CLAUDE.md、太らせすぎてない？ — Claude 5 世代のコンテキストエンジニアリング新ルール

はじめに

CLAUDE.md が育ちすぎて、どこまで書くべきか・どこから削っていいのか分からない。この記事はそういう人向けです。

先に結論を書きます。CLAUDE.md に残す価値があるのは「ファイルを読んでも分からないこと」だけです。リポジトリの説明は短く済ませ、トークンの大半はハマりどころ（gotchas）に使う。「ハードコードを避けろ」のような当たり前のルールは、今のモデルには要りません。

筆者も CLAUDE.md を育てている側でした。応答スタイル、ワークフロー、git 運用。「AI にちゃんと動いてほしければ、ちゃんと指示を書く」が常識だったので、真面目な運用のつもりでした。

そこに Anthropic からこんな記事が出ました。いわく、Claude Code のシステムプロンプトを80%以上削除したが、コーディング評価で測定可能な性能低下はなかった。

We removed over 80% of Claude Code's system prompt for models like Claude Opus 5 and Claude Fable 5 with no measurable loss on our coding evaluations.

え、あの丁寧に書いたルールたち、要らなかったの？という話です。以下、公式記事の要点を「CLAUDE.md を書く側」の目線に並べ替えたうえで、筆者の CLAUDE.md を実際に監査した手順と結果を載せます。

元記事はこちら: https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models

TL;DR

Claude 5 世代（Opus 5 / Fable 5 など）向けの「Then → Now」は6つ：

Then（これまで）	Now（これから）
ルールを与える	判断力に任せる
例をたくさん見せる	インターフェースを設計する
全部を先頭に書く	段階的開示（progressive disclosure）
大事なことは繰り返す	ツール説明に一度だけ書く
CLAUDE.md に手動でメモ	自動メモリに任せる
Markdown の仕様書	HTML・テスト・実コードなどリッチな参照

CLAUDE.md の書き方も明快で、リポジトリの説明は短く、トークンの大半は「ハマりどころ（gotchas）」に使う。ファイルを見れば分かる当たり前のことは書かない、です。

CLAUDE.md に何を書き、何を書かないか

上の「Then → Now」を、CLAUDE.md を書く手元の判断に落とすとこうなります。この節までは公式記事の要約で、筆者が自分の設定で試した結果は「筆者の CLAUDE.md を新ルールで監査してみた」以降です。

書くもの

ハマりどころ（gotchas）。トークンの大半はここに使う。踏んだ人間しか知らないこと
リポジトリの短い説明。長い概要はコードを読めば分かるので不要
判断の基準。個別ルールの列挙ではなく、迷ったときに使える一文
参照先。Markdown の仕様書より、HTML・テスト・実コードといった実物を指す

書かないもの

ファイルを見れば分かること。ディレクトリ構成、関数の中身、命名規則の説明
細かいルールの列挙。判断の基準に畳めないか先に考える
たくさんの例示。few-shot は探索空間を狭める副作用のほうが目立つ
繰り返しの強調。大事なことは、それが使われる場所（ツール説明）に一度だけ
手動のメモ。自動メモリに任せられる範囲は任せる

「何を書くか」よりも「何を書かないか」のほうが長いのが、この新ルールの性格をよく表しています。

モデルが賢くなったので、縛りが足かせになった

旧世代のモデルは判断力が足りなかったから、細かいルールで縛る必要があった。今のモデルは判断できるので、縛りがむしろ性能を妨げる（hobble する）——これが記事の前提です。

象徴的なのがコードコメントの扱いで、以前は「コメントを書きすぎるな」系の細かいルールが並んでいたのが、今は一文に置き換えられています。

Write code that reads like the surrounding code: match its comment density, naming, and idiom.

個別のルールを列挙する代わりに、判断の基準だけ渡す。指示が重なって矛盾していると、モデルはどれに従うか余計に考え込むので、ルールを減らすこと自体に価値があります。

もうひとつ意外だったのが例示です。few-shot はプロンプトの王道テクだったのに、最新モデルでは例が探索空間を狭める副作用の方が目立つそうです。

With our newest models, we've found that giving examples actually constrains them to a certain exploration space.

代わりに、ツールのパラメータを pending / in_progress / completed のような列挙型で定義するなど、インターフェース自体で使い方を伝えることが推奨されています。例文で教えるのではなく、型で伝える。プログラマには馴染み深い考え方ですね。

筆者の CLAUDE.md を新ルールで監査してみた

ここからは筆者の手元の話です。やったことは単純で、新ルールを次の3つの問いに畳んで、1行ずつ当てていきました。

これはファイルを読めば分かることか？ → 削除候補
これは踏んだ人間しか知らないことか？ → 残す gotcha
これはルールの列挙か、判断の基準か？ → 列挙なら基準に書き換えられないか考える

対象は筆者のグローバル CLAUDE.md 39行と rules 23行。軽量な部類だと思っていましたが、新ルールの目で読み返すと「当たり前のこと」系がしっかり混ざっていました。

問い1で引っかかった行（削除候補）

- Avoid hard-coding values unless absolutely necessary.
- Follow existing patterns in the codebase before introducing new ones.

書いた当時は真面目な指示のつもりでしたが、ハードコードを避けろなんて今の Claude は言われなくてもやります。2行目の「既存のパターンに合わせろ」もコードを読めば分かる話なので、同じく問い1に引っかかります。削除候補です。

問い2で残す価値を確信した行（gotcha）

筆者の環境には「cmux 経由の Claude Code は .zshrc を読まないので、環境変数は .zshenv に置く」という一行があります。ファイルシステムをいくら眺めても分からない、踏んだ人間だけが知っている情報。トークンを使うべき gotcha はこういうやつです。

なお CLAUDE.md はセッションの初期ロードに乗り、以後のターンでコンテキストに残り続けます。削る話がそのままトークンの話でもある理由は Claude Code のトークン、どこに消えてる？に書きました。

gotcha は運用しているうちに増えていく

実は記事を書いた前日、これを地で行く出来事がありました。ブログのデプロイ時に velite --watch がビルドと並走して本番が一瞬404になる罠を踏み、その場でデプロイ手順のスキルに「デプロイ前に watch を止める」と追記したんです。CLAUDE.md やスキルはこういう傷の記録になっていくのが正しい姿なんだと腑に落ちました。

スキルファイルを書きっぱなしにせず「生きたドキュメント」として運用する考え方は、Anthropic 社内の Claude Tag 運用の記事でも同じことが言われています。CLAUDE.md も同じ扱いでいいはずです。

なお、記事では CLAUDE.md とスキルの「右サイズ化」を手伝う /doctor コマンドも紹介されています。ターミナルの claude doctor はインストール診断のみで、右サイズ化はセッション内の /doctor が本命のようです。実際に整理を実行したら続報を書きます。

所感

少し前に書いた auto mode の記事と構図が同じだと思いました。あちらは「権限プロンプトの97%を人間は読まずに承認していた」でしたが、今回も、丁寧にルールを書いて安心していたのは人間の側で、モデルの役には立っていなかった可能性がある。

とはいえ書く仕事がなくなったわけではなく、判断基準は渡す、ハマりどころは書く、実物を見せる。教育係からオンボーディング設計者に役割が変わった、というのが筆者の理解です。

まとめ

Claude Code のシステムプロンプトを80%以上削除しても、コーディング評価で性能低下なし
CLAUDE.md に書くのは「ハマりどころ＋短い概要＋判断基準＋実物への参照」。ファイルを見れば分かることは書かない
ルールの列挙をやめて判断基準を渡す。例示は探索空間を狭めるので、型・列挙・パラメータ名で伝える
監査は3つの問いで足りる: ①読めば分かるか ②踏んだ人しか知らないか ③列挙か基準か
筆者の監査結果: 「ハードコード避けろ」系は削除候補、「.zshenv に環境変数」系の gotcha は残す
セッション内の /doctor が右サイズ化を支援してくれる（試したら続報）

しばらくは CLAUDE.md の断捨離がはかどりそうです。ではまた！