CLAUDE.md は何行までにすべきか:長さとトークン消費の目安

CLAUDE.md を書き足していくうちに、どこまで詳しく書いてよいのか分からなくなります。長いほど丁寧に伝わる気がしますが、実際には逆で、長すぎる CLAUDE.md は指示が無視される原因になります。

公式ドキュメントが示す目安は明確です。1 ファイルあたり 200 行未満にしてください。この記事では、その 200 行の意味と、超えたときに「削る」のか「分ける」のかの判断基準を整理します。

200 行は目安、4 MiB が上限

CLAUDE.md の長さについて、公式ドキュメントには性質の違う 2 つの数字が出てきます。混同しやすいので分けて押さえてください。

数字	種類	超えるとどうなるか
200 行	推奨の目安	読み込まれる。ただしコンテキストの消費が増え、指示の遵守率が下がる
4 MiB	実際の上限	ファイルごとスキップされる(まったく読み込まれない)

公式ドキュメントの表現は「1 ファイルあたり 200 行未満を目標にする。長いファイルはコンテキストを多く消費し、遵守率を下げる」というものです。つまり 201 行で急に壊れるわけではなく、長くなるほどじわじわ効いてくる性質のものです。

一方 4 MiB は挙動が変わる境界です。「Claude Code は 4 MiB までの CLAUDE.md を全文読み込み、それより大きいファイルはスキップする」と明記されています。通常のテキストで 4 MiB に到達することはまずありませんが、巨大なログや生成物を貼り付けると起こり得ます。

起動時にどれくらいトークンを使うのか

公式ドキュメントには、セッション開始時に何がどれだけ読み込まれるかを示す対話型のシミュレーションがあります。そこで例として使われている値は次のとおりです。

読み込まれるもの	例として示されているトークン数
システムプロンプト	4,200
プロジェクトの CLAUDE.md	1,800
~/.claude/CLAUDE.md(ユーザー)	320
オートメモリ(MEMORY.md)	680
スキルの説明文	450

これはあくまで例示用の数値で、あなたのファイルの実測値ではありません。ただし規模感は掴めます。200,000 トークンのウィンドウに対してプロジェクトの CLAUDE.md が 1,800 トークン程度、という比率です。

ここで見落としやすいのがサブエージェントの分です。サブエージェントは自分のコンテキストに CLAUDE.md を読み込み直します。公式ドキュメントには「サブエージェントも CLAUDE.md を読み込む。同じファイル、同じ内容だが、あなたのコンテキストではなくサブエージェントのコンテキストを消費する」と書かれています。組み込みの Explore と Plan のエージェントはこれを省略します。サブエージェントを多用する運用では、CLAUDE.md の長さが実質的に掛け算で効きます。

実際の消費量は /context で確認できます。Memory files の欄に、読み込まれているファイルが一覧表示されます。

/context

長くなったときの 3 つの選択肢

200 行を超えたとき、取れる手は 3 つあります。効果が違うので、順番に検討してください。

1. 削る(いちばん効果が大きい)

ベストプラクティスのページは、1 行ずつ次の問いを当てるよう勧めています。「これを消したら Claude はミスをするようになるか」。ならないなら消す、という基準です。そのうえで「肥大化した CLAUDE.md は、本当に守ってほしい指示を無視させる原因になる」と書かれています。

書くべきもの・書かないほうがよいものは、公式ドキュメントで次のように整理されています。

書く	書かない
Claude が推測できない Bash コマンド	コードを読めば分かること
既定と異なるコードスタイルの規則	言語の標準的な慣習
テストの手順と使うテストランナー	詳細な API ドキュメント(リンクで済ませる)
リポジトリの作法(ブランチ名、PR の規約)	頻繁に変わる情報
このプロジェクト固有の設計判断	長い説明やチュートリアル
開発環境の癖(必要な環境変数)	ファイルごとの説明
よくある落とし穴、直感に反する挙動	「きれいなコードを書く」のような自明な心得

チェックイン済みの CLAUDE.md に対しては /doctor が削減案を出します。ディレクトリ構成、依存関係の一覧、アーキテクチャの概要のように「コードから導ける内容」を削り、落とし穴・理由・ツールの既定と異なる規約は残す、という方針です。この削減チェックには Claude Code v2.1.206 以降が必要です。

2. 分ける(トークンは減らない)

@path のインポートで別ファイルに切り出すと、ファイルは読みやすくなります。ただしコンテキストの消費は減りません。公式ドキュメントは「インポートされたファイルも起動時に展開されてコンテキストウィンドウに入る」「分割は整理には役立つが、起動時に読み込まれる以上コンテキストは減らない」と明記しています。

整理目的なら有効な手です。書き方は CLAUDE.md の @ インポート記法 にまとめています。

3. 移す(条件付きで読み込ませる)

実際にトークンを減らせるのはこの方法です。

• paths 付きのルール: .claude/rules/ に置いたルールに paths を指定すると、該当するファイルを Claude が読んだときだけコンテキストに入ります。書き方は .claude/rules/ でファイル種別ごとにルールを分ける を参照してください
• スキル: 呼び出したとき、または Claude が関連すると判断したときにだけ読み込まれます。手順の長い作業はこちらに向きます

公式ドキュメントも「複数ステップの手順、またはコードベースの一部にしか関係しない項目は、スキルか paths 付きのルールに移す」と案内しています。

モノレポで他チームの CLAUDE.md まで読み込まれている場合は、claudeMdExcludes の設定 で除外できます。

行数を増やさずに情報を残す

CLAUDE.md の中のブロックレベルの HTML コメントは、Claude のコンテキストに入る前に取り除かれます。

<!-- このメモは人間のメンテナ向け。Claude のコンテキストには入らない -->

## テスト
- 単体テスト: `pnpm test`

公式ドキュメントには「ブロックレベルの HTML コメントは、内容が Claude のコンテキストに注入される前に削除される。人間のメンテナ向けのメモを、コンテキストのトークンを使わずに残すのに使える」と書かれています。コードブロック内のコメントは保持されます。また Read ツールで直接開いた場合はコメントも見えます。

なお、行数だけを減らしても中身が同じならトークンは減りません。長い 1 行にまとめるのではなく、不要な記述自体を削るのが本筋です。

まとめ

• 目安は 1 ファイル 200 行未満。超えても読み込まれるが、遵守率が下がる
• 読み込まれなくなる境界は 4 MiB。そこを超えるとファイルごとスキップされる
• 「200 行または 25KB」の読み込み制限はオートメモリの MEMORY.md のもので、CLAUDE.md には適用されない
• @ インポートでの分割はコンテキストを減らさない。減らせるのは paths 付きルールとスキルへの移動
• 削る基準は「消したら Claude がミスをするか」。/doctor が削減案を出し、/context で実際の読み込みを確認する