CLAUDE.mdの書き方——AIに\"文脈を積み上げる\"ディレクトリ設計の実践

CLAUDE.mdとは、Claude Codeがセッション開始時に自動で読み込み、AIへの指示と作業文脈を与える設定ファイルです。 作業ディレクトリから上位階層へ遡って探索されるため、フォルダの階層ごとに置けば文脈が自動で積み上がります。私たちは現在、ホームディレクトリ配下で14枚のCLAUDE.mdを「ルート・エリア・案件」の3層で運用しています。この記事では、その実物の設計と、進捗を直書きして記述を腐らせた失敗から得た配置ルールを、実体験ベースで公開します。

CLAUDE.mdとは——階層自動探索という仕組み

Claude Codeは起動すると、カレントディレクトリから上位に向かってCLAUDE.mdを探し、見つけたものをすべてプロンプトに取り込みます（公式ドキュメント: メモリ管理）。つまり深い階層で起動するほど、上位の文脈が自動で「積み上がって」渡されます。

この性質が設計の出発点です。Anthropicの公式ベストプラクティスも、"CLAUDE.mdはClaudeのプロンプトの一部になるため、頻繁に使うプロンプトと同じように磨き込むべき"（Anthropic・Claude Code開発元）としています。書けば書くほど良いのではなく、毎回注入されるコストを払う価値がある情報だけを、適切な階層に置くのが要点です。

なぜ1枚の巨大CLAUDE.mdは失敗するのか

私たちも最初はルートの1枚に全部を書いていました。実際に起きた問題は2つです。

• 無関係な文脈が常時注入される — 副業プロダクトの作業中にも、本業や学習メモの記述が毎回プロンプトに載る。コンテキストを浪費し、AIの判断のノイズになります
• 更新が追いつかず、記述が現実と乖離する — 最悪だったのは進捗の直書きです。あるプロダクトの欄に「現在ベータ準備中」と書いたところ、数週間後にはとっくに公開済みなのに記述はそのまま。AIが古いフェーズを根拠に的外れな提案をするようになりました

「書いてあることが信用できないファイル」になった時点で、CLAUDE.mdは機能を失います。分割と委譲のルール化は、この失敗の後始末から始まりました。

実例：ルート・エリア・案件の3層で粒度を変える

現在の構造の抜粋です。ホームを本業・前職・副業・私用の4ドメインに分け、各層にCLAUDE.mdを置いています。

~/CLAUDE.md            ← ルート: プロフィール+全域ルール
├── CurrentJob/CLAUDE.md   ← エリア: 本業の方針と案件索引
├── Side/CLAUDE.md         ← エリア: 副業の方針と案件索引
│   └── JurisCodeAI/projects/xxx/CLAUDE.md ← 案件: 目的+現在地への参照
└── Personal/CLAUDE.md     ← エリア: 私用

書く粒度は層ごとに変えます。

1. ルート — 書き手のプロフィール、フォルダ全体の地図、全域に効くルールだけ
2. エリア — そのエリアの目的と、配下案件の1行索引。個別の詳細は書かない
3. 案件 — 目的・関係者・技術構成。変わりやすい現在地は別ファイルへの参照に留める

原則は「下の層には上の層との差分だけを書く」です。上位の内容は自動で積み上がるので、重複させると更新時に二重管理になり、必ずどちらかが腐ります。

置く場所・置かない場所の判断基準

運用の中で固まった判断基準は次の4つです。

1. Claudeが知るべき固有情報がある場所にだけ置く — 「1つのまとまった目的・主題」を持つフォルダが単位
2. 収納フォルダには置かない — assets/、downloads/、inbox/、archive/ のような「入れ物」に置いても、固有の文脈がないため注入コストだけ増える
3. 同種を束ねただけの親フォルダにも置かない — 索引が必要なら上位のエリア層に1行書けば足りる
4. 案件完了時はCLAUDE.mdごとarchive/へ移す — 削除せず履歴として残すと、過去の意思決定を後から辿れる

陳腐化を防ぐ「変わりやすい情報の委譲」パターン

前述の失敗から作った、いちばん効果があったルールです。フェーズ・進捗・バージョンなど変わりやすい情報はCLAUDE.mdに直書きせず、`logs/status.md` のような専用ファイルへ委譲します。 CLAUDE.md側には「現在地の正は logs/status.md」と参照だけを書きます。

ツールのバージョンも同様で、「バージョンは claude --version で確認（固定値を書かない）」のように、確認コマンドを書いて値は書きません。この委譲を徹底した結果、CLAUDE.md本体の更新頻度が下がり、「書いてあることは常に正しい」状態を維持できるようになりました。静的な方針と動的な状態を分離するのが本質です。

アンチパターン集

失敗を一般化すると、避けるべきは次の3つに集約されます。

• 全部盛り — ルート1枚に全プロジェクトの詳細を書く。無関係な文脈の常時注入でコンテキストを浪費する
• 上位との重複記述 — 同じ情報を複数層に書く。更新漏れで矛盾が生まれ、AIがどちらを信じるべきか判断できなくなる
• 進捗・フェーズの直書き — 「現在〜中」は書いた瞬間から腐り始める。状態は専用ファイルへ委譲する

なお、CLAUDE.mdはこの記事で扱った「文脈の設計」の土台であり、その上で開発全体をエージェントに任せる構成は Claude Codeで個人開発を完全自動化する構成 で解説しています。

よくある質問

CLAUDE.mdとREADME.mdは何が違いますか？

READMEは人間の読者に向けたプロジェクト説明で、CLAUDE.mdはAIに毎セッション注入される指示書です。READMEには経緯や網羅的な説明を書けますが、CLAUDE.mdは注入コストがかかるため「AIの判断を変える情報」だけに絞ります。両方置いて役割を分けるのが実用的です。

1枚あたりどのくらいの長さが適切ですか？

私たちの運用ではルートが最も長く、案件層は短いもので数十行です。長さそのものより「毎回読み込ませる価値があるか」で判断します。迷ったら、変わりやすい部分を別ファイルへ委譲して本体を短く保つ方が安全です。

小さなプロジェクトにも置くべきですか？

固有の文脈（目的・技術選定・制約）が1つでもあるなら置く価値があります。逆に、上位のCLAUDE.mdで1行説明すれば足りる規模なら不要です。「書くことが差分として存在するか」が判断基準になります。

いつ更新すべきですか？

方針や構造が変わったときだけです。日々の進捗で更新が必要になっているなら、それは委譲すべき情報をCLAUDE.mdに書いてしまっているサインです。私たちは変更のたびに決定事項ログへ1行追記し、本体の書き換えは最小限にしています。