私はこれまでに数多くの Claude Code の設定を試してきました。
出力を本当に変えてくれたのは、CLAUDE.md というたった 60 行のファイルだけです。
このページをブックマークしておいてください 🔖
ここでは、その仕組み、ほとんどの人が完全に見逃してしまう理由、そして今日すぐにコピーできる完全なテンプレートをご紹介します。
Claude Code について誰も教えてくれないこと
最初のプロンプトの前に。たった一行のコードの前に。セッションの中で何かが起こる前に。
Claude は 1 つのファイルだけを読みます。たった 1 つです。
CLAUDE.md。
そして、それをセッション全体の絶対的な真実として扱います。提案としてではありません。他のコンテキストの一つとしてでもありません。すべての判断を導く決定的なブリーフィングとして扱うのです。
だからこそ、このファイルは Claude Code スタック全体の中で最も過小評価されている変数なのです。
ほとんどの人はこのファイルをまったく持っていません。そして持っている人でも、次の 2 つのミスのいずれかを犯しています。ファイルに実質的な内容が空っぽであるか、「ステップバイステップで考える経験豊富なシニアエンジニアであれ」という 300 行の指示であるかです。
どちらも役に立ちません。理由はそれぞれ異なります。
なぜほとんどの CLAUDE.md ファイルが機能しないのか：本当の 3 つの理由
理由 1：長すぎる
Claude は 1 セッションあたり約 150 ～ 200 の指示を確実に従うことができます。これは構造上の制約であり、善意の問題ではありません。
問題点：Claude Code の内部システムプロンプトにはすでに約 50 の指示が含まれています。つまり、あなたの CLAUDE.md には、Claude が指示をドロップし始める前に、実際には 100 ～ 150 の指示スロットしかないということです。
ファイルが 200 行ある場合、Claude はわざとルールを無視しているのではありません。機械的に忘れているのです。あなたにはコンプライアンスの問題ではなく、アテンションバジェットの問題があるのです。
理由 2：内容が悪い
CLAUDE.md ファイルの大半は、Claude が自分で推測できることや、行動を測定可能な形で変えないことで埋め尽くされています。
「シニアエンジニアのように振る舞え」→ Claude はそれが何を意味するかすでに知っており、特定の行動を固定するものではありません。「ステップバイステップで考えろ」→ それはトレーニングに含まれています。行を無駄に使っています。「クリーンで保守可能なコードを書け」→ 具体的な基準がありません。Claude はあなたの特定のコンテキストで「クリーン」が何を意味するのかを知りません。
具体的で明確なエラーを防がない行はすべて、実際に重要な指示から文字通り盗まれた行です。テストは簡単です。この行を削除した場合、Claude は何か具体的に間違えるでしょうか？もし答えが「いいえ」なら、その行はそこにあるべきではありません。
理由 3：階層がゼロ
ほとんどの人は、Claude Code には 3 つのレベルの指示があることを無視し、すべてを同じ場所に詰め込んでいます。
~/.claude/CLAUDE.md→ グローバル（すべてのプロジェクトに適用）.claude/CLAUDE.md→ プロジェクト（チームと共有、git 管理）./CLAUDE.local.md→ ローカル（個人のオーバーライド、git 管理外）
グローバルレベルは、すべてのプロジェクトで繰り返すルールのためのものです。プロジェクトレベルは、あなたのスタックとチームに固有のコンテキストのためのものです。ローカルレベルは、共有する必要のない個人の好みのためのものです。
これら 3 つのレベルを正しく使うことで、各ファイルを短く、集中したものにし、真に効果的にすることができます。すべてを 1 つのファイルに入れることは、重要なルールをノイズの下に溺れさせる漏斗を作るようなものです。
効果的な CLAUDE.md を構成する 5 つのセクション
本番で使われている数十の CLAUDE.md ファイル（オープンソースプロジェクト、Anthropic の公式ドキュメント、コミュニティのベストプラクティスリポジトリ）を調べた結果、すべての効果的なファイルに共通する 5 つのセクションが明らかになりました。
セクション 1：重要なコマンド
Claude は毎回のセッションを、あなたのプロジェクトのビルド方法、テストの実行方法、lint エラーの修正方法を知らずに開始します。推測します。そしてその推測はあなたのターンを無駄にします。
正確に入力すべきものを教えてください：
Commands
- Build:
npm run build - Dev:
npm run dev - Test single file:
npm test -- path/to/file - Full test:
npm test - Lint + fix:
npm run lint:fix - Type check:
npx tsc --noEmit
短く、正確で、すぐに使えるものです。
このセクションがないと、プロジェクトが pnpm vitest で動作しているのに Claude は npm test を試そうとします。決して動作しないコマンドの問題をデバッグするのに 3 ターン費やすことになります。実際の作業に使えたはずの 3 ターンです。
セクション 2：アーキテクチャマップ
Claude は毎回のセッションを、コードベースに関する知識がゼロの状態で開始します。ゼロです。ビジネスロジックがどこにあるのかを知りません。コンポーネントがステートレスであるべきかどうかを知りません。API ルートにビジネスロジックを含めるべきでないことを知りません。
マップを与えてください：
Architecture
- src/lib/services/ → すべてのビジネスロジック
- src/components/ → ステートレスな UI コンポーネントのみ
- src/lib/store/ → グローバルステート（Zustand）
- src/app/api/ → API ルート、ここにビジネスロジックはなし
- DB アクセスは Server Actions または API ルート経由のみ
ツリー構造を網羅的に列挙する必要はありません。Claude がどこに何があるか、そしてさらに重要なことに、どこに配置すべきでないかを知るのに十分な情報だけを提供します。
この「どこに置くか vs. どこに置かないか」の区別こそが、最も頻繁に発生するアーキテクチャエラーを防ぐものです。
セクション 3：ハードルール
これはファイル全体の中で最も重要なセクションです。例外なく。
ここにあるすべてのルールは、単一の質問に答えなければなりません：「この行を削除した場合、Claude は具体的なエラーを犯すか？」
はい → ルールは残す。いいえ → そこにあるべきではない。
価値の高いルールの例：
Rules
- NEVER commit .env files or secrets
- All async calls must be wrapped in a try/catch
- Functional components only, zero class components
- Mandatory commit prefixes: feat:, fix:, docs:, refactor:
- Every PR must pass
npm run verifybefore merge - Static export only, no SSR (deployed on S3)
- IMPORTANT: run type check after every code modification
このリストについて、2 つの注意点があります。
第一に、否定形のルールは肯定形のルールと同じくらい重要です。「.env ファイルを絶対にコミットしない」というルールは、Claude が実際にそれをやってしまうまでは自明にしか見えません。必ず入れてください。
第二に、IMPORTANT や YOU MUST のような強調マーカーは実際に効果があります。
これは逸話的なものではありません。Anthropic は自社のドキュメントで、ルールの前に IMPORTANT や YOU MUST を追加すると、そのルールに対する Claude の遵守が測定可能な形で向上することを確認しています。
これらは控えめに使いましょう。無視された場合に最も深刻な結果をもたらすルールのために取っておいてください。
このセクションのルールは 15 個以下に抑えてください。それを超えると、重要なルールへの注意が薄まります。
セクション 4：ワークフローの好み
あなたも経験したことがあるでしょう。一行直してほしいと頼んだのに、Claude は 3 つのファイルを書き換え、関数名を変更し、あなたの依頼とはまったく関係のないクラスをリファクタリングします。
このセクションはそれを防ぎます：
Workflow
- Ask clarifying questions before starting complex tasks
- Make minimal changes, do not refactor unrelated code
- Run tests after every change, fix failures before continuing
- Create separate commits per logical change, not one giant commit
- In case of uncertainty between two approaches, explain both and let me choose
ここにあるすべての行は、具体的な痛点に対応しています。47 ファイルの巨大コミット。依頼していない完全書き換え。尋ねるべきだったのに Claude が独断で下すアーキテクチャ上の決定。
セクション 5：CLAUDE.md に入れてはいけないもの
このセクションも他のセクションと同じくらい重要です。おそらくそれ以上に。
Do NOT include:
- Personality instructions ("be a senior engineer")
- Formatting rules that your linter already handles
- @ imports that pull entire docs into every session
- Duplicate rules (if global says "run tests", the project doesn't repeat it)
- Anything Claude learns on its own via auto-memory
最後の点は広く過小評価されています。
Claude は ~/.claude/projects/<project>/memory/ に独自のメモを保持しています。セッション内で /memory を実行すると、Claude がすでにあなたのプロジェクトについて学習している内容を確認できます。数回のセッションを経ると、Claude が CLAUDE.md に手書きで書こうとしていた情報をすでに取得していることに気づくことがよくあります。
限られた指示を、Claude が自分で覚えたことに浪費しないでください。
60 行未満の完全なテンプレート、すぐに使える
あなたのプロジェクトに当てはまらないセクションは削除してください。目的はすべてを埋めることではありません。目的は、Claude の行動を測定可能な形で変えるものだけを残すことです。
私の出力に最も大きな影響を与えた行：具体的な結果
数十の設定をテストした結果、最も目に見える違いをもたらした 5 つの行は次のとおりです：
- IMPORTANT: run type check after every code modification → Claude が型を壊したコードを、明示的にチェックするよう促されないと検出せずに納品するのを防ぎます。
- Make minimal changes, do not refactor unrelated code → 依頼されていないファイル全体の完全な書き換えを防ぎます。
- Create separate commits per logical change, not one giant commit → 47 ファイルが混在した読みにくい巨大コミットを防ぎます。
- In case of uncertainty between two approaches, explain both and let me choose → Claude があなたに属するべきアーキテクチャ上の決定を独断で下すのを防ぎます。
- Static export only, no SSR → 静的に S3 にデプロイされるプロジェクトに Claude がサーバーコードを追加するのを防ぎます。
これらの 5 つの行に共通することは、それぞれがデバッグ時間において具体的で、頻繁に発生し、コストのかかるエラーを防ぐことです。
これが、CLAUDE.md のすべての行に対する究極のテストです。
根本的な誤りと、それがこれほど広まっている理由
人々は CLAUDE.md を、願望リストやパーソナリティプロンプトのように扱っています。
「シニアであれ」「徹底的であれ」「専門家のように考えろ」
これはブリーフィングではありません。魔法のような思考です。
CLAUDE.md は技術文書であるべきであり、やる気を起こさせるスピーチではありません。スタック、コマンド、アーキテクチャ、具体的なルール、ワークフロー。それ以外はすべて、実際に重要な指示と競合するノイズです。
ファイルは 80 行未満に抑えてください。Claude が防止できたはずのエラーを犯すたびに、修正してください。
そして何より、このファイルが時間とともに何になるかを理解してください。
最初の 1 ヶ月で優れた CLAUDE.md は、毎回のセッションで時間を節約してくれます。3 ヶ月目までには、あなたの規約とスタックを正確に捉え、Claude はほぼチームメンバーのように動作します。
6 ヶ月目までには、このプロジェクトで Claude がこれまでに犯したすべてのエラーが含まれ、それらを自動的に防止します。
ファイルは資本となります。修正のたびに改善され、徐々にあなたが書いた中で最高のオンボーディングブリーフィングになります。
Claude のためではありません。あなた自身のために。
