CLAUDE.md に指示を足すきっかけはよくありますが、消すきっかけはあまりありません。失敗したときに足した一行を読み直しても、消したらまた同じことになりそうで、結局そのままにしてしまいます。
そこで手元の 2 本を、残す理由まで書き出して読み直しました。ブログ用の 13 項目はほとんど残り、共通のツール説明は 15 項目中 6 項目が削除候補になりました。同じように毎回読ませているファイルでも、中身はずいぶん違いました。今回は判定までで、ファイルは編集していません。
.NET ブログの「Instructions Hygiene: What Frontier Models Still Need You to Say」に、見直す基準が書かれていました(Wendy Breiding、2026-08-12 公開、2026-08-21 取得)。モデルが自分で調べたり推論したりしても分からないことを残す、という考え方です。
コードを読めば分かることまで書いていないか
記事の例では、legacy/ がまだ本番で使われていることや、src/Clients/Generated を手で編集してはいけないことを残します。Billing.Api と Billing.Worker の役割分担など、設計で決めた意図も同じです。名前や配置から推測されて、間違った判断をされると困るものです。
検証用のコマンドは、動くことを確認してから書く。絶対に守る制約には always / never / must を使ってよいが、何でも強い指示にしない。詳しい説明は別の文書に置き、そこへのリンクを示す、という整理です。
消す候補は、一般的な助言、ファイル目録、ツールが調べる設定、ほかの文書のコピーなど。「深呼吸して」「step by step で考えて」といった文句や、過去の失敗を経緯ごと書いたメモも挙がっていました。
フォーマット設定を 20 個書くより、dotnet format --verify-no-changes を走らせる指示を残す。この例なら、自分のファイルでも置き換えられる箇所を探しやすいです。
見直すときは、各行を次の 4 つに分けます。原文では keep / remove / move / verify と呼んでいます。
| 判定 | 判断すること |
|---|---|
| 残す | 今も正しく、結果に影響し、自力では分かりにくいか |
| 消す | 一般論、曖昧な指示、古い情報、ツールが検査する内容ではないか |
| 移す | 特定のパスだけの指示や、別の文書に置く詳細ではないか |
| 確かめる | コマンド、回避策、バージョン、依存関係が今も有効か |
モデルの変更、ビルド方法の変更、リポジトリの再編、同じ指示が繰り返し無視されるときが、見直しの機会だそうです。新しいモデルが指示なしで成功したなら削り、リポジトリ固有の知識が足りずに失敗したなら、その知識を足す。
行数そのものは目標にしない、という説明もありました。コマンドが間違った 30 行より、必要な設計の説明がある 100 行のほうがよい。この基準なら、短くするためだけに削らずに済みます。
ブログの CLAUDE.md は、ほとんど残った
このブログの CLAUDE.md は当時 40 行。空行と表の罫線を除く 13 項目を、私が一つずつ読みました。記事で勧めている、先にモデルへ重複や矛盾を探させる手順は使っていません。
| 内容 | 判定 | 理由 |
|---|---|---|
記事は /blog-write の手順で書く |
残す | 執筆規約を読む場所を示している |
| ビルドと検査のコマンド | 確かめる | 実行して、今も動くかを見る |
hugo が見つからなければ /opt/homebrew/bin/hugo を試す |
残す | 手元の環境で実際に必要だった補足 |
記事本文は blog-site/content/posts/ に置く |
残す | このリポジトリの決め事 |
| 種の置き場と、2026-08-16 に移した経緯 | 経緯だけ消す | 現在の場所が分かれば足りる |
| 検査スクリプトの場所と、CI で見る記事の範囲 | 残す | 検証に必要 |
docs/ と posts/ はサイトに出ない |
残す | ディレクトリ名だけでは分かりにくい |
| 太字と em ダッシュを使わない | 残す | 文体の決め事。太字の数は自動検査していない |
| 日本語の太字が Goldmark の規則で壊れる場合がある | 残す | ソースを読むだけでは気づきにくい |
新規記事に url: と aliases: を書かない |
残す | 古い記事を真似すると間違える |
| 検査が何件を見たか確認する | 残す | 対象 0 件でも exit 0 になる |
| カタログ側の規約をブログへ持ち込まない | 残す | リポジトリ間のルールを区別する必要がある |
| カタログ側の文書 3 つへの参照表 | 移す | スキルにも同じ参照がある |
「残す」10、「確かめる」1、「消す」1、「移す」1 でした。コマンドは実行して確認しました。次は当時の出力です。
$ cd blog-site && hugo --quiet && cd ..
$ perl scripts/check-post-output.pl blog-site/content/posts/2026-08-21-instructions-hygiene.md
OK: blog-site/content/posts/2026-08-21-instructions-hygiene.md（本文 6242 文字, ソースの **=0, 本文 <strong>=0, 生の **=0, em ダッシュ=0）
ビルドと検査はどちらも exit 0。対象の記事 1 件を検査したことも確認し、この項目も残すと判断しました。
たとえば hugo が見つからなければ絶対パスを試す、という行。一般的な使い方の説明に見えますが、手元では実際に必要だった補足です。古い記事にある url: を新規記事には使わない、という規則も、コードを真似するだけでは分かりません。もともと自動検査で捕まえられないことを残していたので、削る箇所は少なくなりました。
共通のツール説明には、導入時のメモが残っていた
もう一つ見たのは、シェル出力を圧縮する RTK の使い方を書いた RTK.md です。全プロジェクトで毎回読ませていました。空行と囲みを除くと 15 項目あります。
残したいのは、何のためのツールかという説明と、フックがコマンドを自動で書き換える仕組み、それにフックの対象外で直接実行する rtk gain などのコマンドです。
削除候補は、rtk --version や which rtk など導入確認の 3 行、同名ツールとの衝突についての注意書き、参照先に該当する節がない「詳細は CLAUDE.md を参照」でした。導入確認は一度済ませればよく、今は名前の衝突もありません。古い参照も毎回読ませる意味がありませんでした。
こちらは「残す」9、「消す」6。導入時には必要だった確認が、その後も毎回読む説明に混ざっていました。
「過去の失敗の日記」は耳が痛いです。経緯を全部書いておくと次は防げる気がしますが、作業に必要なのは、そこから決まった手順だけの場合もあります。経緯はコミットや設計文書で読めればよさそうです。
今回は分類だけなので、消しても困らないかはまだ確認できていません。削った後には、普段の作業で以前の失敗が再発しないかを見ます。ブログの指示がほとんど残ったことにも、それぞれ理由はありました。行数だけ見ていても、その違いは分かりませんでした。