CLAUDE.mdは削るほど効く

199行のCLAUDE.mdを114行に、120行を52行に削った。モデルが替わるたびに、足場は負債になる。何を残し、何を消したかを書く。

編集部の CLAUDE.md は、全体用が199行、あるプロジェクト用が120行ありました。新しい世代のモデルに替えたのをきっかけに、それぞれ114行と52行に削りました。この記事では、削った基準と、削ったあとに足した仕組みを書きます。

公式の目安は200行以下

Claude Code の公式ドキュメントは、CLAUDE.md を1ファイル200行以下にするよう勧めています。長いファイルは文脈を多く使い、指示に従う度合いを下げる、という理由です（出典：https://code.claude.com/docs/en/memory 、2026-10-16確認）。

この200行は CLAUDE.md の目安です。auto memory の索引 MEMORY.md には、先頭200行か25KBまでしか読まれないという別の上限があります。こちらの設計は「エージェントのメモリ設計」にまとめました。

もう1つ、見落としやすい点があります。@path で別ファイルを読み込んでも、読み込んだファイルは起動時にすべて読まれます。整理はできますが、文脈の量は減りません（同出典）。

手元の行数は、こうして数えます。

wc -l ~/.claude/CLAUDE.md ./CLAUDE.md ./.claude/rules/*.md 2>/dev/null

消したもの

モデルの世代が上がると、昔の弱点を補うために書いた指示が、逆に邪魔になります。編集部が消したのは、次の3種類です。

• 検証の手順の列挙：「テストを走らせたら結果を確認し、失敗したら…」のような手順です。
• 「よく考えて」の類：考える量は effort の設定で決めます。文章ではお願いしません。
• コードを読めば分かること：ディレクトリ構成や依存の一覧です。

公式ドキュメントでも、/doctor の点検は、構成図や依存の一覧のようにコードから分かる内容を削る提案をする、とされています（同出典）。

新しく書く指示には、ゴールと制約だけを書くことにしました。モデル名や effort の値は焼き込みません。次の世代で、また負債になるからです。

残したもの

• コードを読んでも分からない判断の理由
• 踏んだことのある罠
• ツールの既定と違う規約

加えて、「提案しないこと」を書いた行を残しています。過去に却下した案を、新しいセッションが何度も持ち出すのを防ぐためです。

守らせたいことは hook に移す

公式ドキュメントは、CLAUDE.md を「強制される設定ではなく文脈」と説明しています。必ず止めたい操作は PreToolUse hook で止めるように案内しています（同出典）。

編集部では、Git の破壊的な操作は確認を求め、コミットの形式違反は拒否する hook を入れました。CLAUDE.md の該当部分は、「機構を参照」の1行になりました。

ただし、hook も測らないと穴があきます。メモリへの書き込みを見張る hook が、Write と Edit だけを対象にしていました。30日分を数えたら、77件が素通りしていました。auto mode では、操作の約85%が Bash 経由だったからです。matcher は、想像ではなく実際の呼び出しの記録から決めます。

hook の書き方と、素通りを測った結果は「Claude Code hooks実践」にまとめました。

常時読まれる説明文も削る

CLAUDE.md の外にも、毎回読み込まれる文章があります。skill の description です。

使われていない skill は、手動で呼んだときだけ読まれる設定に落とします。何が使われていないかは、感覚ではなく、直近の呼び出しの記録を数えて決めます。

公式ドキュメントも、特定の作業にしか使わない手順は CLAUDE.md から skill に移すよう勧めています。skill は必要なときだけ読み込まれるからです（出典：https://code.claude.com/docs/en/costs 、2026-10-16確認）。

MCP サーバーが文脈に与える負担は「MCPサーバー入門と設計の5原則」で扱っています。

点検はコマンドで

公式ドキュメントによると、/doctor prompt-audit は、古いモデル向けの指示、存在しないファイルへの参照、ファイル同士の矛盾を探して、修正案を出します。ファイルは、頼むまで書き換えません。v2.1.283 以降が必要です（出典：https://code.claude.com/docs/en/memory 、2026-10-16確認）。編集部の検証環境に入れた版は 2.1.301 でした（claude --version、2026-10-16）。

失敗のあとに何を書き足すか（撤退条件・再開条件の残し方）は、「同じ修正を3回させない」にまとめました。

まとめ

• CLAUDE.md は200行以下にする。@ での分割では文脈は減らない。
• モデルが替わったら、手順の列挙と「よく考えて」を消す。
• 必ず守らせたいことは hook に移し、hook の対象は実測で決める。
• skill の description も、使われていないものは常時読み込みから外す。