CLAUDE.md に書くのは「モデルが自力で分からないこと」だけ。.NET ブログの選別基準を手元のファイルに当てた

.NET のブログに「Instructions Hygiene: What Frontier Models Still Need You to Say」という記事が出ました(Wendy Breiding、2026-08-12 公開、2026-08-21 取得)。copilot-instructions.md や AGENTS.md、CLAUDE.md のような、エージェントに毎回読ませる指示ファイルをどう手入れするか、という話です。

エージェントハーネスを使っていて、指示ファイルが育ちすぎた覚えのある人向けです。先に要点だけ:

• 指示ファイルに残す基準は「モデルが自分で発見も推論も取得もできないこと」かどうか。短さは目標ではなく、この基準で選んだ結果として出てくる
• 手入れは1行ずつ keep / remove / move / verify の4択で判定する。手元の CLAUDE.md 13項目に当てたら keep 10・verify 1・remove 1・move 1。別の共通ファイル(15項目)では remove が 6 出た
• 消しやすいのは「丁寧に」「step by step で」のような一般論と、lint が既に強制している規則。残すのはコードから読み取れない境界の意図と、動くことを確かめたコマンド

何が書かれているか

以下はすべて上記 URL、2026-08-21 取得。

問いの立て方を変えろ、というのが記事の軸です。「モデルに何を伝えられるか」ではなく、「モデルが自力で発見・推論・取得できないものは何か」を問う。目標は「結果を確実に変える、高信号の情報の最小集合を保つこと」だとしています。

書くべきものとして挙げているのは5種類です。

• システムについての自明でない事実。例として、Billing.Api と Billing.Worker の境界、legacy/ ディレクトリがまだ本番で使われていること、src/Clients/Generated は手で編集しないこと
• 検証までの最短経路。ただし「動くことを確かめたコマンドだけ残す。自信ありげに繰り返される間違ったコマンドは、無いより悪い」
• コードベースだけでは決まらない選択。テストフレームワーク、API スタイル、エラーの返し方など、複数の案からチームが選んだもの
• 絶対的な制約と高くつく失敗。always / never / must は本当に絶対のものにだけ使う
• 正本の所在。詳細はリンク先に置き、必要なときだけ読ませる

消すべきものは6種類です。「古い指示ファイルを改善する最速の方法は、たいてい引き算である」としています。

• 一般的なソフトウェア工学の助言(「きれいで保守しやすいコードを書け」)
• リポジトリの網羅的な目録
• ツールが既に強制している情報。20個のフォーマット設定を列挙する代わりに dotnet format --verify-no-changes を走らせろ、と書く
• 既存ドキュメントの複製
• プロンプトの民間伝承とモデルへのおだて。「深呼吸して」「step by step で考えて」「世界最高のシニアエンジニアとして振る舞え」「完璧になるまで止まるな」
• 過去の失敗の日記

手入れの手順は、1行ずつ4択で判定するレビューです。

判定	条件
keep	まだ真で、結果に影響し、推論で得にくい
remove	モデルが既にこなせる、ツールが強制している、曖昧、古い
move	有用だが、パス限定の指示ファイルかリンク先の文書に属する
verify	コマンド・回避策・バージョン・依存関係を記述していて、変わっているかもしれない

レビューの契機は4つ。明らかに能力の高いモデルを採用したとき、ビルド系を変えたとき、リポジトリを再編したとき、エージェントが同じ指示を繰り返し無視するのに気づいたとき。

新しいモデルと古い足場の関係については、こう書いています。「新しいモデルが古い足場なしで成功したら、足場を消す。リポジトリの知識が欠けていて失敗したら、モデル固有の儀式を処方するのではなく、その知識を文書化する」。

行数についても一言あります。「30行でコマンドが間違っているファイルは、100行でモノレポの境界が必要なだけ書いてあるファイルより悪い。コンパクトさは関連性の結果であって、恣意的な目標ではない」。

手元の CLAUDE.md に当てた

このブログのリポジトリにある CLAUDE.md(40行、空行と表の罫線を除いて13項目)に、上の4択を1項目ずつ当てました。判定は私の手作業で、記事が勧めている「モデルに重複・曖昧・矛盾を挙げさせてから人が確かめる」手順は踏んでいません。

• keep: 記事を書くときは /blog-write を使う。規律はスキルにある。正本の所在
• verify: ビルドとゲートのコマンド2行。コマンドなので。実行結果は下に載せる。通ったので keep
• keep: hugo が見つからないときは /opt/homebrew/bin/hugo を試す。環境の自明でない事実。2026-07-29 に which hugo が空を返したが実体はそこにあった。経緯ではなく「ここを試せ」という規則の形で書いてあるので、失敗の日記には当たらないと判断
• keep: 記事の正本は blog-site/content/posts/ だけ。チームが選んだ決定
• remove(後半の句だけ): 種の置き場。「2026-08-16 にカタログから移した」。移した経緯は結果に影響しない。場所だけ残す
• keep: ゲートのスクリプトの場所と、CI では PR が触った記事だけ検査すること。検証経路
• keep: docs/ と posts/ はサイトに出ない。Hugo は blog-site/ の中しか見ない。ディレクトリ名から推論できない
• keep: 太字と em ダッシュを使わない。太字の数を見るゲートは無い。コードでは決まらない選択。ツールが強制していないことまで明記してある
• keep: 日本語の ** は Goldmark の flanking 規則で静かに壊れる。高くつく失敗。ソースを読んでも気づけない
• keep: 新規記事に url: と aliases: を書かない。既存記事が持っている理由を書いておかないと、真似されるだろう
• keep: ゲートが緑でも「何を検査したか」を読む。対象0件でも exit 0 になる。ツールの穴の明示
• keep: カタログの規律をここに持ち込まない。絶対的な制約
• move: カタログ側の文書3つへの参照表。同じ参照がスキル本文に既にある。重複

keep 10、verify 1、remove 1、move 1 でした。verify の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件を検査しています。

ほとんど残った理由は、このファイルが最初から「ゲートが捕まえないものだけ書く」という方針で書かれていたからで、記事の「ツールが強制している情報は消す」と同じ向きです。逆に言うと、この方針で書いていないファイルに当てれば remove はもっと出ます。

同じ手を、全プロジェクト共通で毎回読み込んでいる別のファイルに当てると、様子が変わりました。RTK.md という、シェルコマンドの出力を圧縮するツール(rtk)の使い方メモで、空行と囲みを除くと15項目あります。

• keep: ツールの一行説明。何のためのフックかが分からないと、挙動の違いを不具合と誤解する
• keep: フックの対象外で直接打つコマンド4つ(rtk gain 等)。推論では分からない
• remove: 導入確認の手順3行(rtk --version、which rtk 等)。導入時に一度やれば済む。毎セッション読ませる理由が無い
• remove: 同名の別ツールと衝突する注意書き。導入時の話。今は衝突していない
• keep: 他のコマンドはフックが自動で書き換える、という説明2行。自明でない仕組み
• remove: 「詳細は CLAUDE.md を参照」。参照先に該当する節が無い。古い

15項目中、keep 9、remove 6 でした。

今回は判定だけで、ファイルの編集まではしていません。記事が勧めている「消したあとで実タスクを走らせ、失敗が再発するかを見る」ところも未実施です。

手元にどう効きそうか

ここからは見立てです。

指示ファイルの適正な大きさは、モデルが賢くなるほど縮むはずです。記事の言う「新しいモデルが古い足場なしで成功したら足場を消す」は、モデルを替えるたびにファイルを見直す理由になります。これまで「前のモデルで効いたから」という理由で残してきた行は、verify の対象です。

4択の中でいちばん見落とすのは verify だと思います。keep か remove かは読めば判断できますが、コマンドが今も動くかは実行しないと分かりません。記事の「自信ありげに繰り返される間違ったコマンドは、無いより悪い」は、エージェントがそのコマンドを疑わずに何度も打つ場面を想像すると納得できます。

「過去の失敗の日記」は、私にとっていちばん耳が痛い分類です。失敗した経緯を書いておくと次は防げる気がしますが、エージェントが必要としているのは経緯ではなく、その結果として決まった規則のほうです。経緯は別の場所(コミットメッセージや設計文書)に追い出せます。

まとめ

• 指示ファイルの1行ごとに「モデルはこれを自力で分かるか」と聞く。分かるなら消す
• 「丁寧に」「step by step で」のような一般論と、lint やフォーマッタが既に強制している規則は消してよい
• コマンドを書いた行は、消すか残すかの前に、今も動くかを実行して確かめる
• 残すのは、コードから読み取れない境界の意図、チームが複数案から選んだ決定、ツールが捕まえない失敗の3つ
• 行数は目標にしない。短くなるかどうかは、元のファイルがどう書かれていたかで決まる