CLAUDE.mdにルールを足し続けて1か月、やり直しは減らなかった
AIコーディングの運用で、失敗するたびにルールを書き足していく人は多いと思う。私もそうで、プロジェクトの CLAUDE.md は1か月で7回コミットされ、今では8つの節に膨らんだ。
書いているときは効いている気がしていた。ただ、それを確かめたことは一度もなかった。手元に33日ぶんのセッションログが505MBあるので、日付を軸に前後で比べれば測れるはずだと思って集計してみた。
結果は期待とは逆だった。
ルールを足したあと、やり直しの割合は上がった
CLAUDE.md にまとまった量のルールを追加したのは7月25日で、シークレットの取り扱い規約とgitleaksの導入をまとめて入れた日だ。ここを境に、指示に占める「やり直し発言」の割合を出した。
| 期間 | 指示 | やり直し | 割合 |
|---|---|---|---|
| 6/26〜7/24（ルール追加前） | 638 | 20 | 3.1% |
| 7/25〜8/2（ルール追加後） | 176 | 8 | 4.5% |
減るどころか1.4ポイント上がっている。日別に並べても、後半に赤い点（やり直し）が途切れず続いているのが分かる。
図の後半、7月27日以降は指示そのものが少ない日が続く。少ない日に1件でもやり直しが出ると割合は跳ね上がるので、この4.5%という数字は不安定だ。だから「ルールを足したせいで悪化した」とは言えない。言えるのは、足しても改善は観測できなかった、ということだけだ。
なぜ減らないのか、ルールと事故を並べてみた
数字だけ見ていても仕方がないので、追加したルールと、その引き金になった事故を突き合わせてみた。gitのコミット履歴と、そのころのセッションログを照らし合わせるとこうなる。
| 追加日 | 足したルール | 引き金になった出来事 |
|---|---|---|
| 7/1 | 記事を書く前に人気記事をリサーチする | 書いた記事の構成が単調だった |
| 7/2 | モーキャプからのポーズ量産手順を明文化 | 幾何分類を数値だけで判定して誤りに気づかなかった |
| 7/3 | グローバル規約と重複する項目を削除 | ルールが増えすぎて機能していなかった |
| 7/25 | シークレットの取り扱い規約、gitleaks導入 | 決済連携の作業中に認証情報を会話へ露出させかけた |
| 8/1 | worktreeのマージ・デプロイ確認を必須化 | 本命の修正が未マージのまま2日間放置されていた |
| 8/1 | public/ 配下の「別プロジェクトのビルド成果物」対応表 |
ビルド出力を直接編集して、次のビルドで消えた |
並べて気づいたのは、すべてのルールが、起きてしまった事故のあとに書かれているということだ。当たり前といえば当たり前だが、これは「ルールを足せば次の事故が減る」という期待とは噛み合わない。
ルールが防げるのは同じ事故の再発であって、まだ起きていない種類の事故ではない。そして開発が進むにつれて、やることは毎回少しずつ違う。7月上旬は記事とポーズ生成をやっていて、中旬は決済連携、下旬はデプロイ運用をやっていた。守るべき境界が移動していくので、既存のルールが効く範囲から外へ出続けることになる。
つまり CLAUDE.md は事故率を下げる装置ではなく、事故の種類をひとつずつ潰していく装置だ。総量が減らないのは、失敗の分布が入れ替わっているから。
いちばん危なかったのは、いちばん短いセッションだった
プロジェクト別にやり直し率を出すと、もうひとつ面白い偏りが出た。
| プロジェクト | 指示 | やり直し | 割合 |
|---|---|---|---|
| Cloud Functions（決済連携） | 13 | 2 | 15.4% |
| skeleton-check | 200 | 9 | 4.5% |
| kabe-tech（サイト本体） | 237 | 9 | 3.8% |
| bustStudio | 306 | 7 | 2.3% |
指示がたった13件しかないCloud Functionsのプロジェクトが、突出して15.4%。これが7月18〜19日の決済連携の作業で、シークレットを露出させかけた回でもある。
慣れていない領域を、短時間で、外部サービスを相手にやる。この条件が重なると事故率が一気に上がる。逆に300件以上やり取りしたbustStudioは2.3%で最も低い。回数をこなしている領域では、ルールが無くても事故は起きにくい。
ここから素直に読み取れる教訓は、ルールを書く場所は「よくやる作業」ではなく「めったにやらない作業」だということ。私のCLAUDE.mdでいちばん長い節がシークレットの取り扱いになっているのは、結果的には正しかったことになる。
この測り方には無理がある
正直に書くと、この分析には弱いところが多い。
まず母数。やり直しの総数が28件しかなく、期間で割ると20件と8件になる。この規模で割合を比べても統計的な意味はほとんど無い。「上がった」と書いたが、誤差の範囲だと言われたら反論できない。
次に指標そのもの。やり直しの判定は「違う」「ダメ」といった否定の語を含むかどうかで機械的にやっている。前の記事で書いたとおり、実際の差し戻しの多くは疑問形で入るので、この指標は差し戻しの一部しか捉えていない。ルールを足したことで指摘の言葉遣いが変わっただけ、という可能性も消せない。
そして最大の問題は、比較対象が無いこと。CLAUDE.mdを書かなかった世界線のログは存在しない。同じ期間・同じ作業を、ルール無しでもう一度やることはできない。だからこれは厳密には効果測定ではなく、単なる前後比較だ。
測るなら「率」ではなく「再発」
では CLAUDE.md は無駄なのかというと、そうは思わない。測り方が間違っていた、というのが今回の結論だ。
やり直しの総量は下がらない。下がるべきなのは同じ失敗が二度起きる回数のほうで、これは率ではなく個別の事象として追うしかない。実際、上の表に挙げた6件のうち、ルール化したあとに同種の事故が再発したものは今のところ無い。ビルド出力を直接編集して消える事故は8月1日に対応表を書いてから起きていないし、シークレットの露出も7月25日以降は発生していない。
そう考えると、CLAUDE.mdに書くべきなのは一般論ではなく、日付と実例が入った具体的な事故の記録ということになる。私のファイルでルールに （2026-07-29に実際に発生） のような但し書きが付いているのはそのためで、書いた当初は単なるメモのつもりだったが、今回並べてみてこの形式が正解だったと感じている。抽象的な心構えは、読み飛ばされるだけで再発を止めない。
自分のログで同じことをやるなら、必要なのは日付ごとの指示数とやり直し数だけなので、集計は10行くらいのスクリプトで済む。効果が見えなかったとしても、なぜ見えないのかを考える過程のほうに価値があるというのが、1か月やってみての感想だ。