CLAUDE.mdの書き方完全ガイド ── AIを思い通りに動かす設定ファイル
Claude Codeを使っていて、こんな経験はないでしょうか。
- 「日本語で書いて」と毎回言い直す
- せっかく決めたコーディングルールをAIが守ってくれない
- プロジェクト固有のフレームワークの使い方を何度も一から説明する
こういう「毎回同じことを言う問題」を一発で解決してくれるのがCLAUDE.mdです。プロジェクトのフォルダに1つファイルを置くだけで、Claude Codeが毎回セッション開始時に自動で読んでくれる「AIへの取扱説明書」として機能します。
この記事では、CLAUDE.mdの仕組みから、効果的な書き方、そのまま使えるテンプレート、やりがちな失敗パターンまで、CLAUDE.mdを使いこなすためのすべてを説明します。
CLAUDE.mdとは何か
CLAUDE.mdは、Claude Codeが毎回のセッション開始時に自動で読み込むファイルです。「こういうルールで作業してね」と書いておくと、毎回口で言わなくてもAIがそのルールに従って動いてくれます。つまり、一度書くだけで毎回有効になる「AIへの指示書」のようなものです。
毎回「日本語で書いて」と指示
→ AIが英語のコメントを書いちゃう
→ 「違う、日本語で」とやり直し
→ ファイル構成も勝手に変えられる
→ 作業時間の30%がやり直しに消える
一度ルールを書けば毎回自動で適用
→ 最初から日本語でコメントしてくれる
→ ファイル構成も守ってくれる
→ コーディングスタイルが統一される
→ 指示は本題だけに集中できる
CLAUDE.mdの仕組み
プロジェクトフォルダ/
├── CLAUDE.md ← Claude Codeが自動で読んでくれるファイル
├── src/
├── package.json
└── ...Claude Codeを起動すると、まず今いるフォルダとその上の階層からCLAUDE.mdを探して読み込みます。その内容がセッション全体に適用されるので、一度書いておけば毎回有効になるというわけです。
CLAUDE.mdの置き場所と優先順位
CLAUDE.mdは置く場所によって「どの範囲に効くか」が変わります。
| 置き場所 | どこに効く？ | こういうことを書く |
|---|---|---|
~/.claude/CLAUDE.md | すべてのプロジェクトに共通 | 「日本語で書いて」などの共通ルール |
プロジェクトのルート ./CLAUDE.md | そのプロジェクトだけ | 技術スタック、コーディング規約 |
サブフォルダ ./src/CLAUDE.md | そのフォルダの中だけ | フォルダ固有のルール |
.claude/rules/*.md | ファイルの種類で切り分け | 特定のファイルタイプ向けルール |
おすすめの使い分け
「日本語で書いて」「コミットメッセージは日本語で」のような全プロジェクト共通のルールは ~/.claude/CLAUDE.md に、そのプロジェクトだけのルールはプロジェクトのルートに書くのがベストです。
.claude/rules/ フォルダ ── ルールを分割して整理
CLAUDE.mdが長くなりすぎたときは、.claude/rules/ というフォルダにファイルを分けて整理できます。
.claude/
└── rules/
├── typescript.md ← TypeScript関連のルール
├── testing.md ← テスト関連のルール
└── api-routes.md ← API関連のルールさらに、ファイル名のパターンを使って「このフォルダのファイルを編集するときだけ、このルールを適用する」ということもできます。
.claude/
└── rules/
├── src__components__*.md ← src/components/ の中のファイルだけに適用
└── *.test.ts.md ← テストファイルだけに適用効果的なCLAUDE.mdの書き方 ── 3つのポイント
ポイント1: 短くまとめる（200行以内が目安）
CLAUDE.mdは毎回のセッションで読み込まれるので、長すぎると逆に効果が薄れます。AIが一度に覚えておける情報量には限りがあるので、長いCLAUDE.mdだとその枠を無駄に使ってしまい、大事なルールが埋もれてしまうんです。
公式ドキュメントでも、「この行を消したら、AIが間違いを犯すか？」と自問して、そうでなければ消すべきだと言っています。
# 良い例：短くて具体的
- 2スペースインデント
- コンポーネントは src/components/ に配置
- テストは __tests__/ に配置
# 悪い例：ふわっとしていて意味がない
- コードは読みやすく、適切にフォーマットしてください
- ファイルは適切な場所に配置してください
- テストはしっかり書いてくださいポイント2: 具体的に書く
「きれいに書いて」と言われても、AIには「きれい」の定義がわかりません。「2スペースインデント、シングルクォート、セミコロンなし」のように、はっきりと具体的に書きましょう。
- きれいなコードを書く
- テストを書く
- 適切なエラーハンドリング- 2スペースインデント、セミコロンなし
- 変更したファイルにはVitestでテスト作成
- try-catchでエラーをキャッチし、console.errorでログ出力ポイント3: 「なぜ・何を・どうやって」で構成する
効果的なCLAUDE.mdは、この3つのパートで書くとうまくいきます。
# プロジェクトの概要（なぜ？ ── このプロジェクトの目的）
旅行メディアサイト。SEO重視で、読者に実用的な情報を届ける。
# 技術スタック（何を使う？）
- Astro v6 + Tailwind CSS v4
- TypeScript
- Cloudflare Pages
# ルール（どうやって？ ── 具体的な決まりごと）
- 記事はMDXで src/content/posts/ に配置
- コンポーネントは src/components/ に配置
- 画像はpublic/images/ に保存
- コミットメッセージは日本語そのまま使えるテンプレート集
Webサイトプロジェクト用
# プロジェクト概要
コーヒー情報メディアサイト（coffee-explorer.net）
## 技術スタック
- Astro v6 + Tailwind CSS v4 + TypeScript
- MDX（記事用）、Cloudflare Pages（サイトの公開先）
## ビルドコマンド
- npm run dev: 開発サーバー起動（localhost:4321で確認できる）
- npm run build: 本番用にビルド
- npm run preview: ビルド結果をプレビュー
## コーディングルール
- コメントやコミットメッセージは日本語で書く
- コンポーネント: src/components/（ファイル名はPascalCase.astro）
- 記事: src/content/posts/（ファイル名はkebab-case.mdx）
- 画像: public/images/（WebP形式を推奨）
- スタイリングはTailwindのユーティリティクラス優先
## やってはいけないこと
- 既存のファイル構成を勝手に変えない
- node_modulesやdistフォルダをコミットしない
- .envファイル（環境設定の秘密情報）をコミットしない
- 外部サイトの画像を直接リンクしないAPIサーバープロジェクト用
# プロジェクト概要
社内向けREST APIサーバー
## 技術スタック
- Node.js v22 + Express + TypeScript
- PostgreSQL + Prisma ORM（データベース操作ツール）
- Jest（テスト用）
## ビルド・実行
- npm run dev: 開発サーバー起動（ファイルを変えると自動で反映）
- npm run build: TypeScriptをコンパイル
- npm test: テスト実行
- npm run migrate: データベースの構造を更新
## ルール
- APIのエンドポイントは src/routes/ に配置
- ビジネスロジック（実際の処理）は src/services/ に分離
- 入力チェックは zod スキーマで定義
- エラーレスポンスは { error: string, code: number } の形式で統一
- 新しいエンドポイントには必ずテストを書く
## データベース操作
- Prismaスキーマ: prisma/schema.prisma
- データベースの構造を変えたあとは prisma generate を実行する個人設定用（~/.claude/CLAUDE.md）── 全プロジェクト共通
# 共通ルール
- 日本語で応答する
- コミットメッセージは日本語で書く
- ファイルの文字コードはUTF-8
- 不要なコメントは追加しない
- 既存のコードスタイルに合わせる
# 禁止事項
- .envファイルをコミットしない
- 確認なしにパッケージを削除しない
- mainブランチに直接pushしない/initコマンドで自動生成する
既存のプロジェクトで「CLAUDE.mdをゼロから書くのは面倒だな…」というときは、/init コマンドを使えばAIがプロジェクトを分析して自動で作ってくれます。
cd my-project
claude
> /initClaudeがプロジェクトのファイル構成やpackage.json、既存のコードを読み取って、そのプロジェクトに合ったCLAUDE.mdを提案してくれます。提案内容をチェックして、必要に応じて修正してから保存しましょう。
/initはあくまでスタート地点
自動生成されたCLAUDE.mdはたたき台として便利ですが、「ここはこう書いてほしい」「これはやらないで」といったプロジェクト固有の注意点は自分で書き足しましょう。使いながら気づいたことを少しずつ追加していくのが一番効果的です。
情報の出し分け ── 全部を1ファイルに詰め込まない
CLAUDE.mdにあらゆる情報を詰め込む必要はありません。詳しい内容は別ファイルに書いておいて、必要なときだけ見てもらうというテクニックが使えます。つまり、CLAUDE.mdには「目次」だけ書いて、中身は別の場所に置いておくイメージです。
プロジェクト概要・ビルドコマンド・基本ルール
docs/api.md
API仕様の詳細
docs/db-schema.md
データベース構造
docs/deploy.md
デプロイ手順
CLAUDE.mdには「ここを見てね」という案内だけ書いておきます。
## 詳細ドキュメント
- APIエンドポイント一覧: docs/api.md を参照
- DBスキーマ: prisma/schema.prisma を参照
- デプロイ手順: docs/deploy.md を参照こうすることで、CLAUDE.mdは軽く保ちつつ、必要な情報にはいつでもアクセスできるようになります。
よくある失敗パターン
1. CLAUDE.mdが長すぎる
CLAUDE.mdが500行を超えると、大事なルールが埋もれて効果が薄れます。200行以内を目安にして、詳しい内容は別ファイルに分けましょう。
2. 指示があいまい
「コードをきれいに書いて」「ちゃんとテストして」は効果がありません。AIは「きれい」や「ちゃんと」の意味がわからないからです。「2スペースインデント」「Vitestでテスト作成」のように、誰が読んでも同じ意味にとれる書き方をしましょう。
3. 指示が矛盾している
「短いコードを書いて」と「コメントを詳しく書いて」のように矛盾する指示があると、AIの出力が不安定になります。どちらが優先かを明記しましょう。
4. CLAUDE.mdを更新し忘れる
プロジェクトの技術スタックやルールが変わったのにCLAUDE.mdをそのままにしておくと、古いルールに従い続けてしまいます。大きな変更があったら、CLAUDE.mdも一緒に見直しましょう。
5. CLAUDE.mdに書くべきでないもの
| 書くべきでないもの | その理由 |
|---|---|
| APIキーやパスワード | セキュリティ上、危険すぎる |
| しょっちゅう変わるデータ | すぐ古くなって逆に混乱する |
| 一般的なプログラミングの知識 | AIは最初から知っている |
| 具体的なコードの実装内容 | コードの中に直接書くべき |
チーム開発でのCLAUDE.md
チームでClaude Codeを使う場合は、CLAUDE.mdをGit（ファイルの変更履歴を管理する仕組み）にコミットしてチーム全員で共有すると効果的です。
# チームルール
- PRはレビュー後にマージ（直接pushしないこと）
- コミットメッセージは Conventional Commits 形式で書く
- feat: 新機能、fix: バグ修正、docs: ドキュメント
- テストカバレッジ80%以上を維持する
- 外部パッケージを追加するときはチームで相談してからチーム共通のルールはプロジェクトのCLAUDE.mdに、個人の好み（エディタの設定など）は ~/.claude/CLAUDE.md に書き分けると、チーム全体の統一感を保ちつつ、個人の使いやすさも確保できます。
まとめ ── CLAUDE.mdを育てよう
CLAUDE.mdは「一度書いたら終わり」ではなく、プロジェクトと一緒に育てていくものです。
今日からやってみること:
- プロジェクトのフォルダに
CLAUDE.mdを作る（/initで自動生成してもOK） - まずは技術スタック・ビルドコマンド・基本ルールだけ書く
- 使いながら「こう書いてほしかったのに」と思ったら、そのルールを追記する
- 長くなってきたら
.claude/rules/に分割する - 全プロジェクト共通のルールは
~/.claude/CLAUDE.mdに移す
最初は10行でもOKです。使いながらちょっとずつ育てていけば、あなたのプロジェクトにぴったり合ったCLAUDE.mdが自然にできあがりますよ。
