目安は「200行未満」
Claude Code公式ドキュメントは、CLAUDE.mdのサイズについてこう書いています。
“target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.”
（1ファイルあたり200行未満を目安に。長くなるほど文脈を消費し、指示への追従も落ちる）
理由は単純です。CLAUDE.mdは毎回のセッションの最初にまるごと読み込まれます。長ければ長いほど、その分の文脈を食い、しかも肝心なところが埋もれて読み飛ばされやすくなる。トークン消費を減らすコツでも同じ理由からこの数字に触れました。
理屈としては、まったくその通りだと思います。短いに越したことはありません。
でも、本気で開発しているプロジェクトは膨らむ
理屈と現実は、けっこう離れます。
ちゃんと動いているプロジェクトでは、開発が進むほど「前にこれで事故った」が積み上がります。命名を勘違いした、確認を飛ばしてバグを埋め込んだ、デプロイの手順を1つ飛ばして本番を壊しかけた——その一つひとつが、二度目を防ぐためのルールとしてCLAUDE.mdに追記されていきます。放っておくと増える、というより、ちゃんと運用しているからこそ増える。
実際に、管理人が動かしている別プロジェクトのCLAUDE.mdを見てみました（ヴェーダ占星術のアプリで、書けるのにコードを書いていない、というエージェント開発の実例としても登場しているものです）。459行——目安の倍以上でした。中身の具体的な業務ロジックはここには載せません。ただ、増え方そのものは一般的な話として書けるので、そちらを紹介します。
これは「理想の完成形」として見せているものではありません。 本人談として断っておくと、「本来、できるだけコンパクトな方が良い、という前提」があった上での、いまも改善が続いている途中経過です。読みどころは行数ではなく、増え方に見えたパターンのほうです。
増え方のパターン、4つ
1. 本体には書かず、別ファイルに分ける
冒頭の一文がこうなっていました。「このファイルには常時守る鉄則だけを置く。手順・仕様の詳細はdocs/が正本」。
実際、ファイルの末尾には「詳細docの在り処」という索引の表があり、アーキテクチャ・API・デプロイ手順それぞれの正本ドキュメントへのリンクが並んでいるだけでした。行数が増えているように見えて、本文が背負っているのは「鉄則」と「索引」だけ——詳細な手順書は別ファイルに追い出す、という一次対応が、すでに本文の膨張を抑えています。
2. 失敗を、ルールの理由として残す
ルールの多くに「なぜこの決まりがあるか」が、過去の事故と日付つきで添えられていました。「実装を確認せずコードを書いたら本番で落ちた」「命名が曖昧で似た名前を取り違えた」といった調子です。
これは読む側を助けます。ルールだけが並んでいると、読む側（未来のエージェントも、未来の本人も）は「これは本当に守るべきものか、それとも昔の名残か」が判断できません。理由が実際の事故として書いてあると、そのルールが今も生きている根拠になります。
3. 繰り返す間違いは、文章からフックへ
同じ種類の間違いを何度も踏んだルールは、注意書きの文章から機械的な強制に格上げされていました。危険な一括操作（例えばgit add -Aのような、意図しないファイルまで巻き込みうる操作）を検知して実行前に止める仕組みや、特定の書き方をした直後に警告する仕組みです。
「気をつける」は、忘れます。何度も踏んだ罠だけが、こうして仕組み側に移されていました。
4. 複雑な手順は、スキルへ
チェックリストの項目のうち、確認の手順が複数ステップにわたるものは、呼び出せるスキルという形に育っていました。設計に着手する前、PRを作る前、デプロイを確認する前など、場面ごとに6個。CLAUDE.md本体には「どの場面でどれを使うか」の1行対応表だけが残り、手順そのものは別ファイルに委ねられていました。
大事なのは行数ではなく、増え方の質
459行という数字だけを見ると、「目安を大きく超えている、良くない」という話に見えます。ただ中身を追うと、書き殴って伸びたのではなく、増える先が変わりながら伸びていたのが分かります。
- 詳細 → 外部ドキュメントへ
- 理由 → 過去の事故の記録へ
- 繰り返す間違い → フックへ
- 複雑な手順 → スキルへ
CLAUDE.md本体に残るのは、それでも常時読ませておく価値がある、短い鉄則だけという形に近づいていく。これは目安を無視した結果ではなく、目安を意識し続けた結果の膨らみ方だと思います。
とはいえ、これも完成形ではありません。別ファイルに分けきれていない部分、まだ文章のままのルール、古くなって整理が要る箇所は残っています。本気で開発するほどCLAUDE.mdは育つし、育ったものはまた手入れが要る——このあたりは、また別の記事で扱います。