CLAUDE.mdは書き直すたびに痩せる —— 消えた削除手順をfile-historyで突き止め、ルールをgit管理のrules/とcommit-msgフックに移した

シリーズ: NASの重複整理

• 前提1: Windows機の D:\SynologyDrive(NAS と双方向同期)から、重複ファイル194件・190.90GiB を7バッチで消しました。この整理作業を「P22」と呼んでいます
• 前提2: 実行は Claude Code、承認は私です。作業のルールは、司令塔にしたフォルダの CLAUDE.md に書いていました
• 前提3: 消し方の全体は Synology Driveの双方向同期で190GiBの重複削除を事故ゼロで終えた に書きました

結論: ルールの本文を CLAUDE.md から外し、CLAUDE.md は索引だけにしました

7バッチの削除を終えた直後、CLAUDE.md に書いてあった「削除バッチの4手順」の節が消えているのに気づきました。Claude Code が「現在地」を更新するために CLAUDE.md を書き直したとき、一緒に落ちていたのです。

そこで次のようにしました。

変えたこと	中身
ルールの置き場所	git 管理のリポジトリの p22/rules/(00〜05 の6ファイル)
CLAUDE.md	「現在地」と「参照先の索引」だけ。ルールの本文は書かない
変更の規則	rules/ を変えるコミットには 変更理由: の行が必須。節や項目の削除には PM承認: の行も必須
機械の検査	上の規則を commit-msg フックで検査し、満たさないコミットは中止する

エージェントが自分で書き直す文書にルールの本文を置くと、要約されるたびに項目が静かに消えます。 ルールは git 管理のファイルに移し、項目の削除を機械で止めるのが、今回の結論です。

何が起きたか: 4手順の節が消え、書き戻した版も5項目欠けていた

削除のバッチは、plan → execute → 同期完了を待って verify → 記録、の4手順を必ずこの順で行うことにしていました。CLAUDE.md にはその手順と、細かい条件が書いてありました。

フェーズ2の締め作業で「次のアクション」を書き直したときに、この節が丸ごと消えました。気づいて書き戻しましたが、書き戻した版を元の版と突き合わせると、19項目のうち5項目が欠けていました。

欠けていた項目	種類
4手順は(PM条件)	出典
同期完了の判定は(B3 で改善)	経緯
「サーバーの確認」とは、Server echo または source: server の削除イベントのこと	定義
ログを5分前から読むのは、Windows の時計が1〜2秒遅れるため	理由
データスクラブの日は、追加の削除操作をしない	例外

どれも、手順の本体ではなく、本体に付いている短い付記です。

なぜ消えるのか

CLAUDE.md には、性質の違う2つのものが混ざっていました。

• 現在地: どのバッチまで終わったか、次に何をするか。作業のたびに変わる
• ルール: 削除の手順、禁止事項。めったに変わらない

現在地を更新するたびに、Claude Code はファイル全体を読み直して書き直します。そのとき、長くなった文書は少しずつ要約されます。要約で最初に落ちるのは「理由」「出典」「定義」「例外」のような短い付記です。本体の文は残るので、読んでも欠けに気づきにくいのが厄介です。

付記が消えると、ルールは「なぜそうするのか」を失います。理由のないルールは、次の書き直しで「不要」と判断されやすくなります。

git 管理外の文書を、どう突き合わせたか

CLAUDE.md は git 管理の外にあったので、履歴から差分を取れません。使ったのは、Claude Code が編集のたびに残している file-history でした。CLAUDE.md の版が v2〜v13 まで残っていました。

版	時刻	状態
v9	08:18:36	4手順の記述がある最後の版
v10	08:33:57	節が消えた最初の版(締め作業で「次のアクション」を書き直した)
v13	−	書き戻したあとの版(移行の直前)

v9 の該当部分を19項目の文言に分け、v13 と移行後のファイルに同じ文言(または言い換え)があるかを文字列で検査しました。

移行の方法: 1行も落とさない

ルールを rules/ に移すこと自体が、また書き直しです。今度は欠けがないことを機械で確かめました。

1. 移行前の CLAUDE.md の、空行以外の全行(192行)を対象にする
2. 各行が、移行後のどこか(新しい CLAUDE.md・rules/・reference/・引き継ぎメモ)に原文のままあるかを調べる(見出しの # の数の違いだけ許す)
3. 初回は13行が欠けていた。CLAUDE.md の側で1行に要約した部分だった → 原文を reference/ に移して解消
4. 最終的に 192/192 行が存在、欠落0件

v9 から落ちていた5項目は、rules/ の中に「書き戻しで落ちていた文言」という節を作って復元し、19/19 になりました。

ルールを守る仕組み

rules/ の README に、変更の規則を5つ書きました。

1. rules/ を変えるコミットには、変更理由: で始まる行を必ず入れる
2. 節(見出し)や項目(番号付き・箇条書き)の削除は承認事項。PM承認: で始まる行(日付と内容)を必ず入れる。言い換えで項目の意味を狭める変更も削除として扱う
3. 項目の追加や明確化は、変更理由があればよい。既存のルールと矛盾するなら承認事項
4. 1〜2 は commit-msg フックで機械的に検査する。フックがなくても規則は有効
5. CLAUDE.md にルールの本文を書き戻さない

フックは、ステージした差分のうち rules/ 配下で「消えた見出し行・項目行」を探し、PM承認: の行がなければコミットを中止します。実際のコミットメッセージはこうなります。

P22 phase2_batch: plan / execute で恒久除外を再判定し、該当行は SKIP_EXCLUDED でスキップ

変更理由: 恒久除外が dry-run 時にしか判定されず、dry-run が古いと実行時に効かない穴を塞ぐため。
PM承認: 2026-10-10 PM指示。項目の削除はなく、rules/02 と rules/03 の1項目ずつの文言を実装に合わせて書き換えた。

同じ構造の失敗: 一時フォルダに置いた明細が消えた

似た失敗がもう1つありました。前のフェーズで作った重複判定の明細が、Windows 側の Claude Code のスクラッチパッド(一時フォルダ)に置かれていて、自動削除で消えていました。再取得はできませんでした。

どちらも「消えてよい場所に、消えてはいけないものを置いた」失敗です。ルールに「作業成果物は一時フォルダに置かず、リポジトリ内に保存してコミットする」を足しました。一時フォルダは、秘密情報を一時的に扱うときなど、コミットしてはいけないものだけに使います。

判断の記録は、決めた直後に1本ずつ

ルールとは別に、判断の記録(決裁メモ)を残しています。複数の選択肢から1つを選んだとき、方針を変えたとき、私の判断を仰いで決まったときに、Claude Code が10行以内のメモを1本書きます。

欄	書くこと
選択肢	比べたもの
採用	選んだもの
理由	なぜそれか
捨てた理由	ほかを選ばなかった理由
注意点・未解決	残ったリスクや宿題

この案件では17本になりました。決めた直後に書くのがポイントです。セッションの終わりにまとめて書こうとすると、終わりは予告なく来るので取りこぼします。このシリーズの「検討したが選ばなかったこと」の表は、すべてこのメモから作りました。

まとめ

やること	理由
「現在地」と「ルール」を別のファイルに分ける	現在地の更新のたびに、ルールまで書き直されないように
ルールは git 管理にする	欠けたときに差分で追える
節や項目の削除を、フックで機械的に止める	要約による欠けは、読んでも気づきにくい
理由・出典・例外は、項目と同じ行に書く	付記は切り離されると最初に落ちる
移行するときは、原文の全行が残っているかを機械で確かめる	移行そのものが書き直しだから
判断は、決めた直後にメモで残す	終わりは予告なく来る

エージェントに長く守らせたいルールほど、エージェント自身が書き直す文書から切り離し、消えたら機械が止める場所に置いてください。