Claude CodeのCLAUDE.mdが太って効かなくなった——8KBまで削って戻した話
CLAUDE.md、いま何行ありますか？
うちは一時期、開くのが億劫になる長さになっていました。そして、そのころがいちばん指示が守られなかった時期です。
書いてあるのに守られない。これ、書いた側からすると相当こたえます。
今日は、その状態から抜けた話を書きます。やったことは1つで、CLAUDE.mdに本文を書くのをやめただけでした。
CLAUDE.mdは「毎回読まれる唯一の場所」
先に前提から。
Claude Code のCLAUDE.mdは、セッションが始まるときに自動で読み込まれます。ここが他のドキュメントと決定的に違うところです。
指示書をいくつ作っても、呼ばれなければ存在しないのと同じです。CLAUDE.mdだけは、呼ばれることが保証されている。
だから、大事なことは全部ここに書きたくなる。私もそうしました。
新しいルールができたら追記する。事故が起きたら、その経緯と対策を追記する。「これは絶対に守ってほしい」と思うたびに追記する。
半年で、手に負えない長さになりました。
太ってから削るまでの、半年の経過
先に、どういう経過をたどったかを時系列で置いておきます。数字が入っているほうが、自分のCLAUDE.mdと比べやすいと思うので。
1ヶ月目は20行くらいでした。起動時にやることと、絶対に人の承認が要ることだけ。このころは守られていました。
2〜3ヶ月目、事故が起きるたびに追記するようになります。ここで初めて「経緯」を書き始めました。なぜこのルールができたのか、いつ誰が決めたのか、何があって決まったのかを、あとから読む人のために残しておこうと思ったからです。親切のつもりでした。
4ヶ月目。100行を超えたあたりから体感が変わります。
指示が通らない回が出てくる。そのたびに「もっとはっきり書こう」と思って、強調と念押しを足しました。太字を増やし、「絶対に」を増やし、同じことを2箇所に書いて確実にしようとした。これが完全に逆でした。
5ヶ月目には250行前後まで来ています。この時期に、さっき書いた「もう有効でない制約」の事故が起きました。対応済みの機能を、指示書に残った古い1行のせいで数ヶ月まるごと使っていなかったやつです。
6ヶ月目で削りました。250行から20行ちょっとへ。
ただし消したのではなくて、本文を別のファイルへ移しただけです。文章の総量はほとんど変わっていません。
いまは上限を8KBに決めて、機械に測らせています。運用して21日、超過は1件だけ。原因は、新しいルールを足すときに本文を正本ファイルへ移し忘れて、索引の1行と一緒に説明まで書いてしまったことでした。
こう並べると分かるんですが、太っていく過程はどの段階も善意なんですよね。親切に書こう、はっきり書こう、忘れないように書こう。全部まっとうです。
まっとうな判断の積み重ねで壊れるので、途中で気づけませんでした。
太ると、なぜ守られなくなるのか
ここが直感に反するところです。
書けば書くほど、守られる確率は下がります。
理由は2つあると思っています。
1つは、単純に読まれる密度の問題です。長い文章の中の1行は、短い文章の中の1行より軽くなる。人間でも同じですよね。就業規則を全部覚えている社員は、たぶんいません。
もう1つのほうが本質的でした。長い指示書には、もう有効でないルールが必ず混ざるからです。
うちの場合、ある機能の制約について「この形式には対応していない」と書いた1行が残っていました。翌月には対応済みになっていたのに、消し忘れていた。
その古い1行を読んだ結果、対応しているはずの機能が、90日以上そのまま使われずに放置されました。しかも誰も気づかない。書いてあるとおりに動いているので、誰も疑わないんです。
正直に言うと、これはかなり効きました。指示書の矛盾は、指示書を読む側ではなく、書く側の責任です。
やったのは「本文を書かない」と決めただけ
直し方は単純でした。それは、
ルールの本文をCLAUDE.mdに書かない
です。
代わりに、こうしました。
ルールの本文は、そのルール専用のファイル1つに書く（1ルール＝正本1箇所）
CLAUDE.mdには、1行の索引だけを置く。「何のルールがあるか」と「本文はどこか」の2つだけ
経緯・実験の記録・過去の裁定は、別の追記用ファイルへ回す
つまりCLAUDE.mdの役割を、目次と受付に限定しました。
やってみて分かったのは、長さの問題ではなかったということです。1つのことが2箇所に書いてある状態が問題でした。2箇所あると、片方だけ直る。直らなかったほうが、あとで嘘になる。
正本を1箇所に決めると、直す場所が自動的に1つに決まります。矛盾が構造的に起きなくなる。
上限を決めて、機械に測らせた
決めただけだと、また太ります。人は必ず追記するので。
だから上限を決めました。CLAUDE.mdは8KB、全体の案内役のファイルは24KBまで。
そしてその上限を、自分で数えないようにしました。 定期監査のスクリプトがサイズを測って、超えていたら不合格として出します。
数値そのものに深い根拠はありません。「いまの分量よりちょっと厳しい」くらいで置いただけです。
大事なのは数字ではなく、超えたときに機械が言ってくれることでした。自分で気をつけるルールは、忙しい日に必ず飛びます。
「これは絶対に守らせたい」と思ったときの分岐
上限を決めると、追記したいときに毎回考えることになります。
そこで作った分岐がこれです。
1回目の指摘 → 該当の正本ファイルを直す。CLAUDE.mdは触らない
2回目の同じ指摘 → 成果物ではなく仕組みのほうを直す
3回目、または機械で判定できる内容 → 文章をやめて、hookにする
3つめが効きました。
hookは、決まった場面で自動的に走る自前の処理です。文章のお願いと違って、hookは読まれなくても動きます。
たとえば「この形式のファイルを直接上書きしない」というルール。文章で書くと、忙しい日に飛びます。ところが、書き込みの直前に割り込んで止める処理を1本置いておくと、その日どれだけ急いでいても、上書きは物理的に起きません。
文章で3回言ったことは、たいてい機械化できます。 そして機械化できたら、その行は指示書から消せます。
指示書が痩せる仕組みを、指示書の中に入れておく。これが今回いちばん効いた設計だったと思っています。
では、CLAUDE.mdに何を残すのか
削る話ばかりしたので、残すもののほうを書きます。うちで最後まで残ったのは4種類でした。
1つめ、起動時にやることの順番。 セッションが始まったら何を最初に読むか。ここが決まっていないと、毎回ちがう前提で仕事が始まります。逆にここさえ効けば、あとは呼ばれた先で詳しく書けます。
2つめ、絶対に人の承認が要ることの一覧。 外部への送信、公開、課金、削除。この4つは1行ずつ書いてあります。取り返しがつかない操作は、判断を分散させてはいけない。
3つめ、正本の場所の索引。 「◯◯のルールは、このファイル」の1行だけ。中身は書きません。
4つめ、太らせないためのルール。 新しいルールの本文をここに書かない、という宣言そのものを、ここに置いています。
逆に、追い出したものはこうです。
何かができるようになった経緯、実験の記録、過去にどう判断したかの理由
特定の作業の手順（呼ばれたときに読めばいい）
もう有効でないかもしれない制約の説明
判断の基準は「毎回のセッションで、着手する前に知っている必要があるか」の一点です。着手してから調べても間に合うことは、全部よそへ出しました。
これで意外なほど減ります。うちの場合、着手する前に本当に知っている必要があったのは、起動の順番が3行、承認が要る操作が4件、正本の場所を指す索引が数行で、合わせて10行ちょっとでした。
「それでも全部読ませたい」と思った人へ
分かります。私も削るとき、いちばん抵抗があったのがそこでした。
消したら守られなくなるんじゃないか、と。
実際にやってみると、逆でした。残った行の守られ方が、はっきり良くなりました。
理由は、たぶん優先順位が伝わるようになったからです。100行の中の1行は、優先順位を持ちません。全部が同じ重さに見える。
20行まで削ると、そこにあること自体が「これは特別だ」という合図になります。
削るのは、諦めることではなくて、順位をつけることなんだと思います。
今日からできる一歩
まず、いまのCLAUDE.mdを開いて、もう有効でない行を探してみてください。
探すコツは、日付が書いてある行、機能の制約について書いてある行、それから「〜には対応していない」という否定形の行です。この3つに、古くなったものが集中します。
うちは、この3つを見ただけで矛盾が1件見つかりました。数ヶ月、静かに効き続けていたやつです。
見つかったら、その1行を消す。それだけで今日は十分だと思います。
今日はこんな話でした。
Claude Code を業務に入れるときの型をまとめています
Claude Code Studio では、Claude Code を実務に組み込むときに私たちが実際に踏んだ事故と、その日のうちに入れた対策をそのまま公開しています。指示書の分け方、承認ゲートの引き方、hookで止める線の決め方までひとまとめにしました。
