CLAUDE.mdは足すより引く。実測が出そろった

2026年8月20日 18:44

Claude Codeの設定ファイルCLAUDE.mdは、書き足すほど言うことを聞いてくれる。ぼくはそう思って育てていました。

この数日で、その直感に反する実測が立て続けに出ています。548KBのCLAUDE.mdを34KBまで削った計測記録。1,350行を丸ごと消して壊れたルールは20個中2個だけだったという対照実験。トークン消費の97.7%がキャッシュ読み込みだったという65稼働日のログ。

発信者は別々で、結論は同じ方向を向いています。効くのは足し算ではなく引き算。

ぼくも自分の環境を測ってみたら、思わぬ場所に「太った索引」が見つかりました。ただし「短ければ短いほどいい」という話でもありません。何を消し、何を残し、何を仕組みに移すのか。一次ソースと自分の環境を照合して答え合わせします。

先に結論を3行で。

・CLAUDE.mdは起動時に、長さに関係なく全文読み込まれる(公式仕様)。@importsで分割しても総量は減らない、と公式が明記
・1,350行を19行+Skillに置き換えた対照実験では、精度は落ちずコストは36%下がった
・引き算を続ける鍵は根性ではなく仕組み。「書いて守らせる」から「機械で検証する」へ、この10日で新作OSSが3本出た

何が起きたか。独立した実測が3日で出そろった

8月16日から18日にかけて、Claude Codeのコンテキスト設計に関する実測が、別々の発信者から相次ぎました。並べます。

548KB→34KB(約94%減)。 ルールパック配布を手がけるアカウントの自社事例(単発のheadless実測・自己申告)ですが、CLAUDE.mdと常駐ルールの総量を測ったところ、タスクが始まる前にキャッシュへ約15万トークンが書き込まれ、その最大の要因が設定ファイルでした。「義務は1つも削らずに」34KBへ。9本の運用手順は、呼ばれたときだけ読み込まれる9個のSkillへ移されました。

1,350行を消して、壊れたのは2ルール。 別の開発者は、機械的に検証できる20ルールを、6構成・計30回(判定は計600チェック)の対照実験にかけました。1,350行のCLAUDE.mdを丸ごと消しても、破られたのはリポジトリの実態と矛盾していた2ルールだけ。さらに19行+Skill構成は、フル版に対して精度100対99、1回あたりコスト$0.696対$1.094。精度は同等のまま、コストはフル版が常に高い(25組の対比較すべて)という結果でした。

AGENTS.mdは読まれない、を実測で確認。 計76回の有効試行を集計した相互運用実験では、ルートのCLAUDE.mdをClaude Codeは9回中9回読む一方、AGENTS.mdだけを置いた場合は3回中0回。サブディレクトリのCLAUDE.mdは12回中7回と確率的でした(公式仕様どおりオンデマンド)。symlinkを張れば両立できることも確認されています。

トークンの97.7%はキャッシュ読み込み。 65稼働日のログを集計した日本語圏の実測では、入力818万・出力7,895万トークンに対し、キャッシュ読みは191億。日次コストの中央値を6月$917から7月$273(約70%減)まで下げた主因は、モデルの切り替えではなく、重い作業を別セッションに切り出して会話を引き延ばさない運用でした。そして8月、習慣が崩れて$903に戻っています。

なぜ足し算が効かないのか。起動時に全部読まれている

種を明かすと、これは書き方の巧拙ではなく、読み込みの仕組みの問題です。

Anthropicの公式ドキュメントは明記しています。カレントディレクトリから上位にあるCLAUDE.mdは、起動時に長さに関係なく全文読み込まれる(推奨は200行以下)。そして@パスでファイルを分割しても「整理には役立つが、コンテキストは減らない」。分割先のファイルも、起動時にそのまま文脈へ入るからです。

つまり「とりあえず書いておけば、必要なときに参照してくれる」は誤解で、実際は書いた分だけ毎回、全部運ばれている。サブエージェントを起動すればそのたびに運ばれるので、量は掛け算で効いてきます。

97.7%がキャッシュ読みだったという実測は、この構造の帰結です。同じ設定と履歴を毎ターン読み直すことが、いちばん大きな費目になる。実際このログでは、安いモデルへの切り替えは集計をほぼ動かしませんでした(下位モデルの比率が4.3%にとどまった上、読み直す量そのものは変わらないため)。効いたのはセッションを短く切ること。読み直す量そのものが減るからです。

1,350行実験の含意も面白いところです。消して壊れた2つは「リポジトリの実態と矛盾する指示」だけでした。裏を返すと、コードやリポジトリ自体が語っていることを、CLAUDE.mdに二重に書く必要はない。Claudeはコードも読めるからです。

ぼくの環境にも「太った索引」があった

他人の実測だけでは答え合わせにならないので、自分の環境も測りました。

このリポジトリのCLAUDE.mdは10.4KB・121行。公式推奨の200行以内に収まっていて、一見健全です。

問題は別の場所にありました。記憶のインデックスファイルです。公式仕様では、このファイルが毎セッション自動で読み込まれるのは「先頭200行または25KBまで」で、超えた分は読み込み時に落とされます(書き込み時にAI側へ警告は出ますが、人の目からは見えません)。

うちの索引は31.3KB・105行。行数には余裕があるのに、サイズが上限を超えていて、末尾の記憶は読まれずに落ちていたのです。ファイルサイズはCLAUDE.mdの3倍でした。

仕組みの上では、このファイルは「1つの記憶につき1行のポインタ」のはずでした。それが記事を1本作るたびに1行増え、行はだんだん文になり、文は要約の段落になり、気づけば索引そのものが読み物になっていた。

個別の記憶ファイル95本(合計約216KB)は必要なときだけ開く設計にしてあるのに、索引の1行ずつが太っていくことは、誰もチェックしていなかった。

548KBのCLAUDE.mdを笑えません。足し算は1回ずつは正しいから、誰も気づかないまま積もる。今回の実測群でいちばん刺さったのはここでした。

正直に書いておくと、ここで測れたのは「常駐している文脈の量」までです。索引を削った前後で精度やコストがどう変わるかは、まだ比較できていません。自環境の話は原因の証明ではなく、海外の実測と同じ構造がうちにもあった、という観察です。

もう1つ、身に覚えがあります。「書いておいたのに破られる」問題です。

ぼくの制作パイプラインには「マガジンへの誘導を書かない」というルールがあります(マガジンをまだ作っていないので)。メモに明記してあるのに、同じ違反が3回再発しました。原因はルールの読み落としではなく、参照していたお手本記事に古い誘導文が残っていたこと。直ったのはルールを書き足したからではなく、公開前に別のAIが敵対的にチェックする機械ゲートを挟んでからです。この記事の1本前でも、このゲートが引用の創作を1件検出して、公開前に記事を止めています。

「書いて守らせる」の限界に、この10日で3本のOSSが出た

同じ結論に、コミュニティも収束しつつあります。この10日ほどで公開された3本のツールのうち2本は、指示を書き足すのではなく、破られたら止まる仕組みを作る方向です。

・unlazy(278★): タスクの受け入れ条件をファイルとして置き、未達のままターンを終えることをStop hookでブロック(進捗がないまま6回続くと警告つきで解放する安全弁あり)。判定はファイルスキャンなのでチェックあたりのトークン消費はゼロ
・stop-that-shit(174★): 発端が象徴的で、作者いわく「過度な設計をするな」とAGENTS.mdに書き足し続けたら、指示ファイル自体が肥大化して、過剰生成を始めた。ルールの追記をやめ、モード宣言と実行可能なガードに落とした
・HERO-Anti-OverDefense(209★): こちらはhookではなく、AIの過剰防御を4形態に命名して線を引く「貼るだけの契約ファイル」。ただし作者自身が「長時間の実行では効き目が薄れる」と限界を明記していて、散文の限界は散文側の作者も認めています

並列運用の世界でも同じです。Claude Code・Codex・Gemini CLIを混ぜた64体のエージェントに1つのリポジトリを書かせた実験では、素のGit運用だとマージ64回中57回が衝突。解決したのはプロンプトの改善ではなく、編集範囲を先に登録させて違反コミットを機械的に弾く自作の「関所」でした。著者はこう書いています。「必要なのは、お願いではなく関所」。

サブエージェントのモデル指定が無言で無視される問題への対策も、設定を丁寧に書き直すことではなく、9行のhookで違反する呼び出しを機械的に弾くことでした。

文章のルールは、読まれないことがある。読まれても、長いセッションでは薄れていく。unlazyの作者はこれを一言で言い切っています。proseはproseを強制できない。

今日からできる引き算。消す・移す・切る・強制する

消す。 CLAUDE.mdを1行ずつ見て「これはコードやリポジトリ自体が語っていることか?」と問う。テストの起動方法、ディレクトリ構成、命名規則。実態と一致している説明は、消しても壊れません。壊れた2ルールは、実態と矛盾していた指示だけでした。

移す。 手順書・チェックリスト・作業レシピはSkillへ。呼ばれたときだけ読み込まれるので、常駐コストが消えます。@importsでの分割は整理には有効ですが、削減にはならない(公式明記)ことだけ覚えておく。

切る。 話題が変わったらセッションを切る。97.7%問題への、いちばん効く介入です。ただし実測が示すとおり、これは習慣に依存して8月にリバウンドしています。「新しい話題は新セッション」を儀式にするか、自動化するのが現実的です。

強制する。 何度も破られるルールは、書き直すのではなくゲートにする。文字数・禁止語・出典の有無のように機械的に判定できるものはスクリプトで(ぼくは公開前チェックをFAIL 0まで通すことを必須にしています)。判定に文脈が要るものは、別のAIに敵対的にレビューさせる。

引き算とゲート化は、同じ原理の表と裏です。AIに守らせたいことを、AIの記憶力ではなく仕組みに置く。

まとめると、CLAUDE.mdを見直すときは各行に4つだけ問えば足ります。

・コードやリポジトリ自体が語っていないか。語っているなら消す
・特定の作業でしか使わないか。ならSkillへ移す
・何度書いても破られるか。ならゲートにする
・話題が変わっていないか。ならセッションを切る

残す理由を説明できない常駐文脈は、いったん削減候補に置く。ここから始めるのが安全です。

最後に1つ。削ること自体が目的になると、今度は必要な文脈まで失います。基準はあくまで実測です。測って、消して、また測る。今週の記事群が信用できるのは、全員がこの往復をやっているからでした。

コメントで教えてください。あなたのCLAUDE.md(またはAGENTS.md)、いま何行ですか?

①200行以内に収まっている ②気づいたら肥大化していた ③測ったことがなかった

参考リンク(一次ソース)

Rulestack「We cut our CLAUDE.md from 548KB to 34KB: what loads when, measured…」(2026-08-18):
https://dev.to/rulestack/we-cut-our-claudemd-from-548kb-to-34kb-what-loads-when-measured-and-the-commit-gate-that-keeps-1kpk

Mayank Kaul「I deleted a 1,350-line CLAUDE.md. Two rules broke.」(2026-08-16):
https://dev.to/mayankkaul/i-deleted-a-1350-line-claudemd-two-rules-broke-post-404k

Jangwook Kim「AGENTS.md vs CLAUDE.md loading across 76 runs」(2026-08-16):
https://dev.to/jangwook_kim_e31e7291ad98/agentsmd-vs-claudemd-loading-across-76-runs-2of7

trh「AIコーディングの消費、97.7%はキャッシュ読み込みだった…65稼働日の実測ログ」(2026-08-18):
https://zenn.dev/trh/articles/540b2f9424c2ab

Anthropic公式ドキュメント「Manage Claude's memory」:
https://code.claude.com/docs/en/memory

たつはら(tacyan)「AIエージェント64体に1つのリポジトリを書かせたら、マージの57/64が衝突した。0にするまでの話」(2026-08-17):
https://zenn.dev/tacyan/articles/75d3ead8130533

Leonxlnx/unlazy(GitHub・2026-08-09公開):
https://github.com/Leonxlnx/unlazy

wanshuiyin/HERO-Anti-OverDefense(GitHub・2026-08-11公開):
https://github.com/wanshuiyin/HERO-Anti-OverDefense

lennney/stop-that-shit(GitHub・2026-08-11公開):
https://github.com/lennney/stop-that-shit

Thomas Witt「How I stopped my Claude Code subagents from secretly running on Fable instead of Sonnet」(2026-08-16 HN投稿):
https://thomas-witt.com/blog/blog-subagent-model-pin/