- LLMは状態を保存しない関数であるため、
CLAUDE.md は各セッションごとに Claude にコードベースを紹介する中核ドキュメントとして機能する
- このファイルには、プロジェクトの WHAT（構造）、WHY（目的）、HOW（動作方法） を簡潔に盛り込むべきであり、不要なコマンドの過剰な列挙は性能低下につながる
- Claude はシステムメッセージの指示に従い、
CLAUDE.md の内容を 関連性が低いと判断すると無視することがある
- 効果的なファイルには 短く汎用的に適用できる情報だけを含め、詳細な指針は別文書に分離して Progressive Disclosure 方式で管理すべきである
CLAUDE.md は エージェントハーネスで最も影響の大きいポイントであるため、自動生成ではなく慎重に手作業で作成すべきである
LLMのステートレス性と CLAUDE.md の役割
- LLMは 推論時点で固定された重みを使用し、セッション間で学習や記憶を保持しない
- そのため、モデルがコードベースを理解するには、すべての情報を入力トークンとして与える必要がある
- Claude Code のようなコーディングエージェントはメモリを明示的に管理する必要があり、
CLAUDE.md は すべての会話に自動的に含まれる唯一のファイルである
- このことから、次の3点が必須となる
- セッション開始時点で Claude はコードベースについて何も知らない
- 各セッションごとに必要な情報を再度伝えなければならない
- そのための標準手段が
CLAUDE.md である
コードベースのオンボーディング: WHAT、WHY、HOW
CLAUDE.md は Claude がプロジェクトを理解するのを助ける オンボーディング文書 の役割を果たす
- WHAT: 技術スタック、プロジェクト構造、モノレポ構成など、コードの地図を提供する
- WHY: 各構成要素の目的と機能を説明する
- HOW: ビルド・テスト・型チェックなど、実際の作業の進め方を明記する
- ただし、すべてのコマンドを列挙するのは非効率であり、必要最小限の情報だけを含めるべきである
Claude が CLAUDE.md を無視する理由
良い CLAUDE.md 作成の原則
Less (instructions) is more
- LLM が安定して従える指示は およそ150〜200件である
- 小さいモデルほど性能低下が急激で、多段階タスクには不向きである
- Claude Code のシステムプロンプトには、すでに 約50件の指示 が含まれている
- したがって、
CLAUDE.md には 汎用的で不可欠な指示だけを最小限に含めるべきである
- 指示の数が増えるほど、全体の指示遂行品質が一様に低下する
ファイルの長さと適用範囲
- LLM は 集中していて関連性の高い文脈 でよりよく機能する
CLAUDE.md はすべてのセッションに含まれるため、汎用的に適用可能な情報だけを維持すべきである- 一般的には 300行未満、可能であればさらに短く保つことが推奨される
- HumanLayer のサンプルファイルは 60行未満
Progressive Disclosure
- 大規模プロジェクトでは、すべての情報を1つのファイルに収めるのは難しいため、段階的開示（Progressive Disclosure） 方式が推奨される
- 詳細な指針は
agent_docs/ フォルダ内の別Markdownファイルに分離する
- 例:
building_the_project.md, running_tests.md, code_conventions.md など
CLAUDE.md には、これらのファイルの 一覧と簡単な説明、そして Claude が必要に応じて読むよう促す指示だけを含める- コードスニペットの代わりに
file:line 参照 を使って最新性を保つ
- これは Claude Skills の概念に似ているが、ツール利用よりも指示管理に重点がある
Claude はリンターではない
- コードスタイルのガイドラインを
CLAUDE.md に含めるのは非効率である
- LLM は コストが高く遅いうえに、リンターより非決定的である
- スタイル規則は 既存コードのパターンを通じて自然に学習されるため、別途指示は不要である
- フォーマットは 自動修正可能なリンター（Biome など） を活用し、Claude には修正結果だけを渡す
- 必要に応じて Stop Hook や Slash Command を使い、フォーマットや検証を自動化する
自動生成禁止
/init コマンドや自動生成機能で作られた CLAUDE.md は推奨されない
- このファイルは すべてのセッションと成果物に影響する高レバレッジなポイント だからである
- 誤った1行の指示が コード全体の品質に連鎖的な悪影響 を及ぼしかねない
- したがって、すべての文を慎重に見直し、手作業で作成すべきである
結論
CLAUDE.md は Claude をコードベースにオンボーディングするための文書であり、WHY・WHAT・HOW を明確に定義すべきである- 指示は最小限に抑え、汎用的で簡潔な内容だけを含める
- Progressive Disclosure によって、必要な情報だけを段階的に提供する
- Claude をリンターとして使わず、専用ツールやフック・コマンド機能を併用活用する
- 自動生成ではなく、慎重な手作業による作成でハーネス全体の品質を最大化すべきである
1件のコメント
Hacker Newsの意見
Claudeはしばしば CLAUDE.md の指示を無視する傾向がある
ファイルに特定の作業と関係ない情報が多いほど、Claudeはその指示に従わなくなる
友人がClaudeに自分を「Mr Tinkleberry」と呼ぶように指示していたが、Claudeがそれを忘れるたびに、そのファイルを無視していると分かった
私は以前から Table-of-Contents アプローチ を使ってきた
作業ごとのガイドラインをそれぞれ別の markdown ファイルに分け、CLAUDE.md にはその一覧と簡単な説明だけを入れる
こうすると context window をすっきり保てる
私のサンプルファイルは ここ で見られる
Claudeが他のドキュメントファイルを実際に読むことはほとんどなかった
Claudeには context を与えすぎると、かえって品質が落ちると感じた
そのため、私は常に2つのバージョンのコードを維持している
LLMには最初のバージョンだけを渡す
Compute 対 情報比率 が重要だと思う。計算量には限りがあるからだ
何でも入れる必要はないが、重要な情報 を入れることのROIは高かった
Claudeは一般的なプロジェクトではうまく機能するが、新しいフレームワークやツールではよく混乱する
修正後にコメントと空白を削除するスクリプトを使っているのか聞いてみたい
実は、こうした複雑な設定なしでも解決策はある
それはコードを明確に 文書化(documenting) することだ
各ファイルが何をするのかを簡潔に書けば、それ自体がプロンプトの役割を果たす
README.md を積極的に活用すればよい
LLMはすでに公開情報で学習されているのだから、新しいものを発明する必要はない
単に「コードをきちんと文書化しろ」という助言は、この文脈には合っていない
READMEは有用だが、CLAUDE.md には別の目的がある
たとえば Claude/agents.md には、特定のディレクトリにアクセスしたとき自動的に context に挿入される機能がある
複雑なコードベースでは context 管理 のほうがはるかに重要だ
だから「適切にプロンプトを書け」という助言は核心を外している
READMEに書けば、結局は CLAUDE.md と同じ役割になる
CLAUDE.md の目的は、Claudeが毎回すべての文書を読み直さなくても済むよう 重要な情報を先に与えること だ
人間は記憶できてもClaudeは作業のたびに忘れるため、再オンボーディングを減らす構造が必要になる
正直、ここまで AIインフラをセットアップ しなければならないなら、自分で直接コーディングしたほうがましだと感じる
私は共通ルールとプロジェクト固有ルールを分けて管理している
AIを使わないのは単なる 生産性の損失 だ
設定が一度だけで済むなら、十分に投資する価値がある
「設定が面倒だ」というのは、デバッガ設定を避ける人たちの言い訳に似ている
私は必要なコードを コピーしてチャット欄に貼り付け、会話するように使っているだけだ
最近はモデルがかなり改善されていて、.md ファイルがなくてもかなり良い結果を返してくれる
こうしたファイルで多少の改善はあるかもしれないが、生産性100倍の魔法 ではないと思う
ここで議論されているのは、Claudeが 機能全体の実装やバグ修正 を自力で行う場合だ
必要な context だけ与えれば十分うまく動く。少し bikeshedding のように感じる
私はClaudeに CLAUDE.md を直接書かせて いる
「README.md はユーザー向け、CLAUDE.md は君向け」と伝えておけば、
「APIドキュメントを常に確認せよ」のような指示も自動で更新してくれる
魔法のようなプロンプトを知らなくても、結果さえ良ければそれでいい
AIが自分自身を最もうまくプロンプトできる理由は特にないように思える