CLAUDE.md と AGENTS.md は設計ドキュメントの復権なのか
誰も読まなかった設計書が、機械が毎回読む文書として戻ってきた、という見方があります。公式ドキュメントの読み込み規則を突き合わせると、復権したのは「毎回読まれる」という性質だけだと分かります。
CLAUDE.md と AGENTS.md は設計ドキュメントの復権ではありません。 設計書と違うのは「毎回読まれる」という 1 点だけで、その代わりに長さの上限と結合の優先順位という制約が付いています。設計書の体裁で書くとかえって効きが落ちる、別の種類の文書です。
この見立ては感想ではなく、両ツールの公式ドキュメントが書いている読み込み規則から出てきます。
KEY POINT
この記事の主張
- 「毎回読まれる」は設計書が持てなかった性質で、ここだけは本当に新しい
- 読まれることと従われることは別で、公式ドキュメントが保証しないと明言している
- 長さの上限があるため、設計書の内容をそのまま載せる使い方には向かない
「毎回読まれる」は設計書になかった性質
設計ドキュメントが読まれなくなる理由は、たいてい「読むきっかけがない」ことでした。CLAUDE.md と AGENTS.md はここが違います。読み込みが仕組みに組み込まれています。
Claude Code 側の記述はこうです。
Claude Code loads
CLAUDE.mdandCLAUDE.local.mdfrom your current working directory and every directory above it.
Codex 側はさらに踏み込んで、キャッシュが無いことまで書いています。
Codex rebuilds the instruction chain on every run (and at the start of each TUI session)
続けて「so there is no cache to clear manually」とあります。つまり古い版が残り続けることがない。設計書が陳腐化する典型的な経路の 1 つが、構造的に塞がれています。
さらに、更新した内容が効き始めるタイミングも規定されています。Claude Code では圧縮をまたいでも生き残る階層があります。
Project-root CLAUDE.md survives compaction: after
/compact, Claude re-reads it from disk and re-injects it into the session. Nested CLAUDE.md files in subdirectories and rules withpaths:frontmatter load again on demand.
会話の中だけで与えた指示は圧縮で消えますが、ファイルに書いたものはディスクから読み直されます。「言ったはずなのに忘れている」が起きる境界が、文書に書いたか否かで引かれているわけです。ファイルの置き場所と階層の違いは CLAUDE.md の書き方 に整理しました。
読まれることは従われることではない
ここが設計書の復権と呼べない最大の理由です。Claude Code の公式ドキュメントは、トラブルシューティングの節で正面から書いています。
CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions.
システムプロンプトではなく、その後ろのユーザーメッセージとして届く。読んで従おうとはするが、厳密な遵守は保証されない。組織向けの運用の節では、強制との線引きがさらに明確です。
Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude's behavior but are not a hard enforcement layer.
同じページは、確実性が要るものの行き先も書いています。「To block an action regardless of what Claude decides, use a PreToolUse hook instead」。
設計書にも同じ性質はありました。「このレイヤーを飛び越えて呼ぶな」と書いてあっても、実際に止めるのはレビューかリンタでした。その構造は変わっていません。変わったのは、守らせる層が設定ファイルとフックという形で用意されたことです。この線引きは allow と deny と hooks を設計する仕事が新しいコードレビューになる で扱いました。
長さの上限が文書の性格を変える
設計書は長くてよい文書でした。context files はそうではありません。
| ツール | 制約 |
|---|---|
| Claude Code | 「target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence」 |
| Codex | 「Codex skips empty files and stops adding files once the combined size reaches the limit defined by」project_doc_max_bytes(既定 32 KiB) |
Claude Code 側は「長いと従われにくくなる」と性能の話として書き、Codex 側は「上限に達したらそれ以降のファイルを追加しない」と打ち切りの話として書いています。方向は違いますが、どちらも長さが内容を殺すという設計です。Codex の上限の効き方は Codex の AGENTS.md は既定で 32 KiB までしか読まれない、Claude Code 側の 200 行の目安は CLAUDE.md の長さは 200 行未満が目安 にまとめてあります。
矛盾への扱いも設計書と違います。公式ドキュメントは「if two instructions contradict each other, Claude may pick one arbitrarily」と書いています。設計書なら、矛盾は読んだ人間が気づいて質問になりました。ここでは気づかれないまま片方が選ばれます。
結合の順序も決まっています。Claude Code は「content is ordered from the filesystem root down to your working directory」で、同じディレクトリ内では CLAUDE.local.md が CLAUDE.md の後に追加されます。Codex も「Codex concatenates files from the root down, joining them with blank lines」です。後に来たものが優先されるという規則があるため、どこに何を書くかが意味を持ちます。ツールごとの読み込み方の違いは CLAUDE.md・AGENTS.md・GEMINI.md の違いは読み込み方だけ に比較表があります。
反論と限界
この主張が成り立たない条件が 4 つあります。
小さなプロジェクトでは制約が効かない。 200 行や 32 KiB に当たらない規模なら、設計書の要約をそのまま置いても実害はありません。この議論が効くのは、モノレポや複数チームの構成で context files が育っていく場合です。
「復権」の定義による。 「読まれる文書が戻ってきた」という意味なら、復権と呼んでよい部分はあります。私が否定しているのは「設計書の内容をそのまま置ける場所が戻ってきた」という読み方です。前者を主張する人と争う点はありません。
仕様は変わりうる。 上に挙げた制約はすべて 2026 年 11 月 20 日時点の公式ドキュメントの記述です。システムプロンプトに入る経路が将来用意されれば、「従われる保証がない」という前提は変わります。実際 Claude Code には --append-system-prompt という、システムプロンプトのレベルに指示を足す手段が別にあります。
機械が書く領域は別に用意されている。 Claude Code には auto memory があり、公式ドキュメントの比較表は「Who writes it」を CLAUDE.md は「You」、auto memory は「Claude」と分けています。「機械が毎回読む文書」という括りだけで見ると、この分担を見落とします。人が書く文書と機械が書く記録は、別の場所に分かれました。
設計書から持ち越せるもの、持ち越せないもの
制約を踏まえると、書き分けははっきりします。
持ち越せるものは、短く書ける決定事項です。命名規則、ブランチ運用、テストの走らせ方、触ってはいけないディレクトリ。いずれも 1 行で書けて、読まれた回数がそのまま効きます。
持ち越せないものは、意思決定の背景です。なぜこのアーキテクチャを選んだか、どの選択肢を却下したか、どんな制約があったか。これらは長く、毎回読ませる必要がなく、読ませると他の指示の遵守率を下げます。従来どおり ADR や設計ドキュメントに置き、CLAUDE.md からは参照だけにするのが筋です。
公式ドキュメントも、範囲が限られる内容の置き場所を用意しています。「Move instructions that matter for only part of the codebase into path-scoped rules, which load only when Claude works with matching files」。全体に効かせるものと、特定のファイルを触るときだけ効かせるものを分ける仕組みです。
つまり設計ドキュメントは消えません。消えたのは「設計書 1 つで足りる」という前提です。
まとめ
- context files が設計書と違うのは「毎回読まれる」1 点。Codex は「there is no cache to clear manually」と明言している
- 読まれることは従われることではない。CLAUDE.md はユーザーメッセージとして届き、厳密な遵守は保証されない
- 長さの上限がある。Claude Code は 200 行で遵守率が落ち、Codex は 32 KiB で打ち切る
- 矛盾した指示は人間に気づかれず、片方が任意に選ばれる
- 短く書ける決定事項は context files へ、意思決定の背景は設計ドキュメントへ。1 つで足りるという前提だけが消えた
よくある質問
- CLAUDE.md に設計書の内容をそのまま載せてよいですか?
- 長さの制約があります。公式ドキュメントは「target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence」と書いており、長いほど従われにくくなります。範囲が限られる内容は path-scoped rules に分けてください。
- CLAUDE.md に書けば確実に守られますか?
- 守られません。公式ドキュメントは「there's no guarantee of strict compliance」と明記しています。確実に止めたい操作は permissions の deny ルールか PreToolUse フックに置きます。
- 設計ドキュメントは不要になるのですか?
- なりません。CLAUDE.md と AGENTS.md は毎回読まれる代わりに長さの上限があり、意思決定の背景や却下した選択肢を書く場所には向きません。役割の違う文書として両方必要です。
参考にした一次情報
この記事は公式ドキュメントを基に AI が下書きを作成し、運営者が内容を確認して公開しています。誤りを見つけた場合は お問い合わせからお知らせください。