CLAUDE.md を肥大させない — 毎回フルロードされる『常設コンテキスト』の設計術(/doctor の新チェック)

Claude Code の CLAUDE.md は、プロジェクトの永続指示を書く場所です。便利ゆえに膨らみがちですが、ここには見落とされやすいコストがあります——CLAUDE.md は長さに関わらず毎セッション全文がコンテキストに読み込まれる。つまり 1 行ごとに毎ターンのトークンを消費し、しかも長いほど指示の遵守率が下がる。v2.1.206 では /doctor に 「肥大した checked-in CLAUDE.md のトリミング提案」 が追加されました。本記事では、CLAUDE.md を軽く保つ設計術を、コンテキスト規律(定額プランの実践)の続きとして整理します。

到達点

CLAUDE.md が 毎回フルロードされる意味(コスト+遵守率)を理解する
200 行という目安と、長さが効いてくる理由
@path インポートはコンテキストを減らさないという罠
常設コンテキストを実際に削る .claude/rules(paths スコープ)
HTML コメントが無料になる仕組みと、/doctor・claudeMdExcludes

なぜ長さが問題なのか

Claude Code は毎セッション、まっさらなコンテキストから始まります。そこへ CLAUDE.md が読み込まれるのですが、重要なのは MEMORY.md(auto memory)と挙動が違う点です。

	読み込み量
auto memory の `MEMORY.md`	先頭 200 行 / 25KB まで(超過分は非ロード)
CLAUDE.md	長さに関わらず全文(上限なし)

つまり CLAUDE.md には自動的な打ち切りがない。書けば書いた分だけ、毎回・全部がコンテキストに乗ります。これが 2 つのコストを生みます。

トークンコスト:CLAUDE.md の全行が、そのセッションの全ターンで入力トークンに乗り続ける
遵守率の低下:公式も明言するとおり、長いファイルほど Claude の遵守が落ちる。重要な指示が大量の凡例に埋もれる

CLAUDE.md は「システムプロンプト」ではなく、システムプロンプト後のユーザーメッセージとして届く文脈です。強制力はなく、薄く・具体的なほど効く。だから肥大対策は「節約」であると同時に「精度向上」でもあります。

目安は 200 行

公式ガイドは 1 ファイルあたり 200 行未満を目標に挙げています。超えると「コンテキストを食い、遵守率を下げる」。まずこの線を超えていないかを点検するのが出発点です。v2.1.206 の /doctor は、checked-in の CLAUDE.md が肥大していればトリミングを提案するようになりました。定期的に /doctor を回して、肥大を早期に検知できます。

罠:`@path` インポートはコンテキストを減らさない

肥大した CLAUDE.md を「整理」しようとして、多くの人が @path/to/file インポートで分割します。これは構成の整理にはなりますが、コンテキスト削減にはなりません。

インポートされたファイルは、launch 時に展開されて CLAUDE.md と一緒にコンテキストに読み込まれます。分割しても、合計のトークン量は変わらない。

@path は「1 枚の巨大ファイルを複数に分けて見通しを良くする」ためのもので、「常設コンテキストを軽くする」ためのものではない。ここを混同すると、「分割したのにトークンが減らない」と首をかしげることになります(インポートは最大 4 ホップまで再帰。バッククォートで囲めば `@README` はリテラル扱いでインポートされません)。

常設コンテキストを実際に削る:`.claude/rules`(paths スコープ)

トークンを本当に減らす鍵は、「常に読む」から「必要なときだけ読む」への移行です。それを担うのが .claude/rules/ の paths スコープ付きルールです。

---
paths:
  - "src/api/**/*.ts"
---

# API 開発ルール
- すべてのエンドポイントは入力バリデーションを含める
- 標準のエラーレスポンス形式を使う

paths フロントマターを付けたルールは、Claude が該当ファイルを読むときにだけコンテキストに入ります。つまり API を触るときだけ API ルールが載る。全セッションに常駐しない分、常設コンテキストが減る。

置き方	ロード
CLAUDE.md 本体	毎回全文(常設)
`.claude/rules/*.md`(paths なし)	毎回(CLAUDE.md 相当)
*`.claude/rules/.md`(paths あり)**	該当ファイルを触るときだけ
スキル	呼び出し時/関連時のみ

肥大対策の本筋は、「毎回要る核」だけを CLAUDE.md に残し、「特定領域でだけ要る指示」を paths スコープのルールに逃がすこと。多段の手順や一部分でしか使わない知識は、スキルに切り出すのがさらに軽い。

無料になる部分:HTML コメント

地味に効くテクニックがあります。CLAUDE.md 内の ブロックレベル HTML コメント()は、コンテキストに注入される前に除去される——つまりトークンを消費しません(コードブロック内のコメントは保持)。

<!-- メンテナ向けメモ:この節は2026Q3にリファクタ予定。Claude には不要 -->
## ビルド
- `npm run build` で本番ビルド

人間の保守メモ・TODO・背景説明のうち Claude に読ませる必要がないものは、 に入れておけばタダで残せる。可読性を保ちつつコンテキストを食わない、という両立ができます。

モノレポ:`claudeMdExcludes`

CLAUDE.md は作業ディレクトリから上位ディレクトリを遡って全て連結されます(ルート→作業ディレクトリの順)。モノレポでは、他チームの祖先 CLAUDE.mdまで載って肥大しがちです。

// .claude/settings.local.json
{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

claudeMdExcludes で関係ない CLAUDE.md をスキップすれば、自分の作業に不要な文脈を常設から外せます(managed policy の CLAUDE.md は除外不可)。

実務チェックリスト

/doctor を定期的に回す:肥大した checked-in CLAUDE.md を検知・トリミング提案(v2.1.206)
200 行を目安に:超えていたら「常設に本当に必要か」を問う
@path 分割で満足しない:見通しは良くなるがトークンは減らない
領域限定の指示は .claude/rules(paths)へ:常設から外して該当時のみロード
手順・専門知識はスキルへ:呼び出し時だけロード
保守メモは :トークン無料で残す
モノレポは claudeMdExcludes:他チームの文脈を外す
/memory で確認:実際に何がロードされているかを点検

まとめ

CLAUDE.md は MEMORY.md と違って毎セッション全文ロードされ、上限がありません。だから 1 行ごとに毎ターンのトークンを食い、長いほど遵守率も落ちる——肥大対策は節約と精度向上を同時に達成します。v2.1.206 の /doctor は肥大の早期検知に使えます。

設計の勘所は 3 つ — CLAUDE.md 本体は「毎回要る核」だけに絞る(200行目安)、領域限定の指示は .claude/rules の paths スコープで該当時のみロード、@path 分割はトークンを減らさないと理解する。「常に読ませるものを最小化し、必要なときだけ載せる」——この文脈設計が、Claude Code のコストと精度の両方を静かに底上げします。

到達点