CLAUDE.mdにルールを書き足していくうちに、気づけば数百行を超えていた。こんな経験のある方は少なくないのではないでしょうか。
コーディング規約、アーキテクチャ方針、命名ルール、テスト方針…。プロジェクトが進むほど「これも書いておこう」と追記が増え、CLAUDE.mdはどんどん長くなっていきます。でもふと気づくと、AIはそこに書いたルールを守ってくれていない。まるで壁に掲げた社訓のように、存在はしているけれど誰も実践していない状態です。
長い社訓は、読まれない
Chroma Researchの調査（"Context Rot"）は、LLMに渡す入力トークン数が増えるだけで出力品質が劣化することを18モデルで確認しています。さらにACL Findings（EMNLP 2025）では、必要な情報がコンテキスト内に正しく存在していても、周囲のトークン量が多ければ推論精度が落ちることが報告されています。
「でも最近のモデルはコンテキストウィンドウが倍増しているから大丈夫では？」と思われるかもしれません。しかし、窓が広くなったことと、窓の中身をきちんと実行することは別の問題です。コンテキストウィンドウの拡大は「より多くの指示を渡せる」ことを意味しますが、「より多くの指示に従える」ことは意味しません。
これは子育てに似ています。毎日「勉強しなさい」と言い続けると、子どもはやがてその言葉を聞き流すようになります。言葉が届いていないのではなく、繰り返される指示が背景ノイズに変わってしまうのです。CLAUDE.mdに積み上げられたルールも同じで、量が増えるほど個々の指示の存在感は薄れていきます。
プランには反映される、でも実装では見ていない
Claude Codeの挙動を観察していると、興味深いパターンが見えてきます。CLAUDE.mdの内容はPlan Modeでのプラン作成時にはしっかり参照されています。しかし、プランが確定して実装フェーズに移ると、AIが実際に参照しているのはCLAUDE.mdそのものではなく、直前に生成されたplansファイルの方です。
これはある意味で合理的な挙動です。実装時に必要なのは「このタスクで具体的に何をすべきか」であり、プロジェクト全体のルール集ではありません。問題は、プラン作成時にCLAUDE.mdの内容が正確にplansファイルへ反映されるとは限らないことです。特にCLAUDE.mdが長くなるほど、プランへの反映漏れが起きやすくなります。
だからこそ、Claude Codeが提案してくるプランは注意深く確認する必要があります。 プランはCLAUDE.mdと実装をつなぐ唯一の橋です。ここでの見落としは、そのまま実装の逸脱につながります。
社訓を「誓約」に変える
CLAUDE.mdが「掲げるだけの社訓」になってしまう根本的な原因は、それが静的な指示リストに過ぎない点にあります。書かれているのは「何をすべきか（what）」だけで、強制力もなければ、AIが自発的に参照する仕組みもありません。
sqlewのConstraint（誓約）機能は、この問題に対するアプローチのひとつです。Constraintは優先度フィールドを持つ独立したエンティティとして管理され、AIエージェントがMCP経由でタスク開始時に自動取得します。CLAUDE.mdのように「全文を読んで該当箇所を探す」のではなく、そのタスクに関連する誓約だけがJust-in-Timeで提供される仕組みです。
たとえば「すべてのAPIエンドポイントは/v2/プレフィックスを使用すること」という誓約を登録しておけば、API関連のタスクが始まるたびにAIがこのルールを取得し、実装に反映します。CLAUDE.mdの片隅に埋もれた一行とは、遵守率が大きく異なります。
CLAUDE.mdを捨てる必要はない
誤解のないように補足すると、sqlewはCLAUDE.mdを置き換えるものではなく、共存するものです。CLAUDE.mdはプロジェクト全体の不変な方針を記述する場として適しています。一方で、確実に守らせたいルールや、プロジェクトの進行に伴って蓄積される設計判断は、構造化された仕組みで管理する方が効果的です。
壁に掲げる社訓と、現場で毎日確認するチェックリストでは、遵守率が違って当然です。あなたのCLAUDE.md、「社訓」のままで終わらせていませんか。
参考文献
- "Context Rot: How Increasing Input Tokens Impacts LLM Performance" — Chroma Research — https://research.trychroma.com/context-rot
- "Context Length Alone Hurts LLM Performance Despite Perfect Retrieval" — ACL Findings (EMNLP 2025) — https://aclanthology.org/2025.findings-emnlp.1264.pdf
- "Agent READMEs: A First Empirical Analysis of Context Files" — Singh et al. (2025) — arXiv:2506.15631
