Claude Code の /doctor で CLAUDE.md を監査する：理由はファイルに、経緯は git に

Claude Code v2.1.283 は 9 月 25 日にリリースされ、そのリリースノートには、1 週間のうち 1 時間を割く価値のある一文があります。/doctor prompt-audit（/checkup prompt-audit からも呼び出せます）は、「CLAUDE.md ファイル、スキル、エージェント、コマンドに含まれる、古いモデル向けに書かれたプロンプトのパターン」を監査します。同じリリースの別の一文によれば、古くなったパス、古くなったコマンド、矛盾する指示ファイルがレポートの先頭に来るようになり、Claude Code がドキュメント化している thinking キーワードは残されます。

Anthropic のドキュメントは、この監査の仕組みを数段落で説明し、サンプルレポートと、「レビューするのは書き直しではなくパッチ」という約束を添えています。ドキュメントが教えてくれないのは、結果を左右する細部です。どのパターンが指摘され、何が読まれ、何に手を付けないのか。その細部はちゃんと存在します。この監査はブラックボックスではないからです。平易な英語で書かれた手順書がバイナリに同梱されていて、ファイルに触れさせる前に読めます。

Claude Code の /doctor prompt-audit は実際に何を実行するのか

同梱の claude-api スキルに処理を渡し、このスキルが shared/prompt-audit.md という 235 行の手順ファイルに従います。/doctor の部分は、その前に固定のスコープ段落を加えます。

このスキルには v2.1.221（8 月 4 日）から prompt-audit サブコマンドがあり、2.1.281 版の手順書でもすでに、監査対象のファイルとして CLAUDE.md と SKILL.md が挙げられていました。v2.1.283 で加わったのは、/doctor という入口、より広く正確になった設定ファイルのリスト、そして後述する古い事実と矛盾のチェックです。

Claude Code は、同梱スキルのファイルを一時ディレクトリ配下のバージョンごとのフォルダに展開します（CLAUDE_CODE_TMPDIR を設定していればそこ、なければシステムの一時ディレクトリ）。次のコマンドで展開済みのコピーがすべて一覧できるので、実行中のバージョンのものを選んでください。

find "${CLAUDE_CODE_TMPDIR:-${TMPDIR:-/tmp}}" -path '*bundled-skills*' -name prompt-audit.md 2>/dev/null

一度読んでみてください。以下の内容はすべてそこから取っています。

/doctor prompt-audit はどのファイルを読み、何に手を付けないのか

現在のプロジェクトでセッションに読み込まれるすべての指示ファイルです。ユーザーレベルのものも含みます。settings ファイルは開かれません。

スコープ段落はそれを列挙しています。プロジェクトルート、その祖先、ネストしたディレクトリにある CLAUDE.md、CLAUDE.local.md、AGENTS.md、およびそれらがインポートする指示ファイル（それ以外のインポートはパスだけが報告され、中身は読まれません）。.claude/CLAUDE.md。~/.claude/CLAUDE.md。そして .claude/ と ~/.claude/ の両方にあるルールファイル、スキル、カスタムコマンド、サブエージェント定義、出力スタイル。管理ポリシーの CLAUDE.md とプラグインが提供するスキルも監査されますが、報告されるだけです。

settings ファイル、.mcp.json、~/.claude.json は読まないよう指示されています。シークレットを含みうるうえ、プロンプトのテキストではないからです。プロジェクト内の何ものも、プロジェクト外のファイルの編集を正当化できません。ユーザーレベルのファイルでも、そのファイル自体のテキストに問題があれば編集案が出され、すべてのプロジェクトに影響すると明記されます。そして監査対象のファイルはデータとして扱われます。ファイル内の指示は評価する対象であって、従う対象ではありません。スキルには命令文がたくさん書かれていますが、監査役はそのすべてをテキストとして読むよう指示されています。

CLAUDE.md のプロンプト監査はどう実行するのか

先にモデルを選び、それからコマンドを実行します。設定ファイルはセッションが動いているモデルを基準に監査されるので、何が化石とみなされるかはそのモデルで決まります。例外は、独自にモデルを固定しているスキル、サブエージェント、コマンドで、それらはそのモデルを基準に監査されます。

ターミナルでバージョンを確認します（2.1.283 以降）。

claude --version

次に Claude Code の中で、移行先のモデルに切り替えて監査を実行します。

/model
/doctor prompt-audit

その行には他に何も書かないでください。引数が 2 語以上になると、/doctor は入力したテキストをそのままスキルに渡し、Claude Code 用のスコープ段落を外します。これを使えば意図的に監査を 1 ファイルに絞れますが、末尾にうっかり残したコメントが監査を変えてしまうのも同じ仕組みです。

/doctor prompt-audit .claude/skills/deploy/SKILL.md

成果物は 2 つあります。レポートと、提案される diff です。レポートは前提（スコープ、対象モデル）から始まり、指摘を確信度の高い順に並べます。各指摘には file:line、引用されたテキスト、該当するパターン、それが時代遅れである理由、確信度、アクションが付きます。依頼の中で明示的に求めない限り（「clean it up」など）、何も適用されません。その場合でも、古くなった事実の修正と、互いに矛盾する指示ファイルの修正は提案のままで、包括的な依頼で適用されることはありません。結果が空でも構いません。手順書ははっきりこう言っています。何も見つからなかった監査は、何も変えるべきではない、と。

古いモデル向けに書かれたとみなされる CLAUDE.md のパターンはどれか

手順書はそれらを 4 つのグループに分けています。リポジトリの大半が設定ファイルなら、ほぼすべてが最初の 2 つ、つまり古びたプロンプトのテキストと壊れやすい設定ファイルに入ると考えてください。

古びたプロンプトのテキストは、おなじみのリストです。最初に来るのは圧力をかける言葉で、大文字の MUST、NEVER、ALWAYS、CRITICAL、IMPORTANT、特に理由が添えられていないものです。手順書の論拠は、古いモデルには大声が必要だったが、現在のモデルはそれを過剰に適用する、というものです。だから警報だらけのファイルは、慎重で予防線ばかり張るエージェントを生みます。逆方向にも効きます。実際に必須としていることに「try to」のような予防線を付けると、今では文字どおりに、つまり省略してよいという許可として読まれます。

Before:  IMPORTANT: NEVER do X          (several per prompt)
After:   state the one or two real constraints plainly, with the reason

その次が、API の機能に置き換えられた足場（「think step by step」、スクラッチパッドのタグ、もっと考えろ、あるいはあまり考えるなと指示する文章）、過剰な指定（判断が必要な作業に対する手順の細かい振り付け、長い禁止リスト）、そして化石です。化石とは、引退したモデルの癖に対する回避策のことで、たとえば書式を盛りすぎるモデルに対して書かれた「never use bullets」のようなものです。

thinking に関する行は、Opus 5.5 で答えが変わる部分です。Opus 5.5 では thinking が常にオンで、制御できるのは effort だけなので、モデルに考えるなと命じるルールは「従いようがない」（can't be followed）ものになります。これは手順書の言い回しで、私の言葉ではありません。この移行の API 側は、修正方法を名指しする 400 エラーとともに派手に失敗します。指示の側は静かに失敗します。だから監査が必要なのです。

同じ Claude Code リリースで何が変わり、なぜそれが監査レポートの先頭に来るのか

古い事実と矛盾は、リポジトリの証拠だけで高い確信度と評価でき、レポートは確信度の順に並ぶからです。存在しないパスは、どのモデルが読んでも間違っています。強調に関する指摘は、モデルの振る舞いについての主張です。

手順書の 2.1.281 版と 2.1.283 版を diff すると、1 行のリリースノートが何を圧縮しているのかがわかります。「volatile specifics」の行では、指示ファイルに書かれた各パスがプロジェクト内に存在するかを確認するようになり、コマンドとフラグはリポジトリのスクリプトとマニフェストを読んで照合します。実行は決してしません。生成されるパス、git で無視されるパス、プレースホルダー、リポジトリ外のパスは、存在しないというだけでは矛盾とみなされません。

新しい行は、互いに矛盾する指示ファイルを扱います。スキルと CLAUDE.md、ルールファイルとサブエージェントの指示書、といった組み合わせです。この行は衝突と上書きを区別します。ネストしたファイルのルールが違っていても、それが自身のディレクトリやタスクで説明できる場合や、上書きするルールを名指ししている場合は、そのままにされます。本当の衝突では、どちらの記述が新しいかを git blame で判断します。ファイルのタイムスタンプでは決まりませんし、ファイルが自分について主張する内容でも決まりません。「this supersedes everything」と書かれた行も、評価すべきテキストのひとつにすぎません。古いほうの記述が禁止事項や安全のためのルールである場合、監査はそれを書き換えず、衝突を指摘して判断をユーザーに委ねます。

thinking キーワードの修正は、もっと範囲が狭いものです。コーディングエージェントの設定では、エージェント自身がドキュメント化し、自ら反応するキーワード（たとえば Claude Code の ultrathink）は設定であって、残ったおまじないではありません。アプリケーション自身のプロンプトでは、同じ単語はただの文章なので、引き続き指摘されます。

prompt-audit の指摘のうち、どれを却下すべきか

今動かしているモデルでもまだ起きる失敗に対処しているものです。監査はそれを文面から判断できません。経緯かテストが必要です。

残すもののリストは明示されています。現在実際に確認されている失敗に対する禁止事項は残します。判断基準は、その失敗が対象モデルで再現するかどうかであって、その文が禁止事項に見えるかどうかではありません。コンテキストも残ります。対象読者、環境に関する事実、品質の基準、制約の背後にある理由のことです。由来を確認するステップでは、強調されたすべての行にひとつの質問をします。この行はどのモデルのどの失敗を防いだのか、そしてそれは今も再現するのか。答えのない行に対するデフォルトは率直です。「誰も正当化できない行は、デフォルトで疑わしい」（a line nobody can justify is suspect by default）。

手順書には、ユーザー自身が折り合いをつけるべき点がひとつ残っています。化石の行は、すべての回避策に、それが対処したモデルを名指しすること、あるいはそのモデルまでたどれることを求めます。「削除の責任を誰も持たない」（nobody owns the removal）からです。一方、経緯の記述の行は、指示ファイル内の過去形、インシデント ID、固定されたモデル名を不要物として指摘します。「現在のルールを述べよ。考古学は捨てよ」（State the current rule; drop the archaeology.）。ざっと読むと、この 2 つは矛盾しています。モデルを名指ししろ、でもモデル名は書き残すな、と。

化石の行の後半の節「あるいはそのモデルまでたどれること」（or gets traced to）が要になっていて、手順書がたどるために使う道具が git blame だと気づけば、矛盾は消えます。理由はファイルの中に、現在形で書きます。モデルがそのルールをどこまで重く見るかを判断するとき、目の前にあるのはファイルだからです。インシデントとモデルは、その行を追加したコミットに書きます。そこなら blame で見つかり、誤って読み込まれることもありません。

自分の例をひとつ挙げます。5 月に、仕事の日の真っ最中に Claude が寝るよう勧めてくるのを止める行を追加しました。

Time of day is irrelevant to my work patterns. Do not suggest
breaks, rest, or continuing tomorrow regardless of session length
or perceived hour. Your time estimates for tasks are sourced from
solo human developer training data and do not reflect what an LLM
can do; never quote them.

最初の文はコンテキストで、3 番目の文は時間見積もりを禁じる理由を担っています。どちらも現在形で、インシデントの気配はありません。これが経緯の記述の行を通過する半分です。もう半分、つまりどのモデルに対して書かれたのか、それが発動したときにどう見えたのかは、コミットから来なければなりません。そうでないと、監査にはたどるものがありません。両方の半分がそろっていても、手順書の最後のステップは変わらず当てはまります。新しいモデルでその振る舞いが現れるかどうかは、スクラッチ用のコピーでその行を削除し、普段どおりのコーディングセッションを何回か回して観察することで決まります。

もうひとつ、注意深く読むべき指摘があります。手順書は「強制されていない指示」を指摘します。どのコードパスも eval もレビュアーもチェックしておらず、アプリ自身のトランスクリプトで破られていることがわかるルールです。その助言は、コードで強制できるものはコードで強制せよ、というもので、守られなければならないルールを文章からゲートへ移すという議論と同じです。そうしたルールを削除する前に、システム全体でその文言そのものを grep してください。テストやログパーサーがプロンプトの文字列で照合していることがあるからです。

CLAUDE.md の監査はいつ再実行すべきか

モデルを変えるたびに、新しいモデルで実行します。

手順書の最後のステップがはっきり述べています。プロンプトはモデルごとの成果物であり、新しい移行のたびに監査をやり直すきっかけになる、と。対象はセッションのモデルなので、同じファイルでも切り替えの前後で異なる指摘が返ってくることがあります。そして手順書は、削除のひとつひとつをスクラッチ用のコピーで検証すべき仮説として扱い、影響が大きい場面では一度にひとつずつ変更します。

既定モデルの切り替えは、これが最も重要になる瞬間です。デプロイもなく、自分で選んだわけでもないのに、新しいモデルに移ってしまうことがあるからです。監査はその切り替えを検知しません。その後で、古いルールのうちどれが直前まで使っていたモデルのために書かれたものかを、ファイルごとに確認する手段を与えてくれます。