Claude Code の /doctor prompt-audit は、CLAUDE.md・AGENTS.md・スキル・コマンドなどの指示ファイルを Claude に読ませ、古くなった指示や互いに食い違う指示を探して、直し方の案を出させるコマンドです。結果は報告と差分の案だけで、頼むまでファイルは1文字も書き換わりません。/checkup prompt-audit と打っても同じものが動きます。
この記事では、Claude Code の公式ドキュメント（How Claude remembers your project の「Audit your instruction files」節・Commands・Skills）と CHANGELOG の原文、それに Claude Code に同梱されている点検の手順書をもとに、何を点検し、どう使い、結果をどう扱えばよいかを整理します。仕様の説明は2026年10月3日時点の原文で確かめたものです。あわせて、このサイトの指示ファイルに実際にかけた結果（指摘9件のうち7件を適用）と、使って分かった注意点を7章・8章にまとめました。
先に結論——/doctor prompt-audit の要点
出典: Claude Code 公式ドキュメント「How Claude remembers your project」「Commands」（2026年10月3日確認）
何をする
指示ファイルの点検
古いモデル向けの書き方、存在しないファイルやコマンドへの言及、食い違う指示を探す。
結果
報告と差分の案
頼むまでファイルは変わらない。適用するかは1件ずつ自分で決める。
対象
CLAUDE.md・スキルなど
AGENTS.md・ルール・コマンド・サブエージェントも。パスを渡せば1か所だけ。
必要な版
v2.1.283 以降
セッションの中で打つ。ターミナルの claude doctor とは別物。
目次
1. /doctor prompt-audit とは——指示ファイルの古さと食い違いを探す
Claude Code は、起動のたびに CLAUDE.md などの指示ファイルを読み込みます。指示ファイルは使ううちに書き足され、昔のモデルのために書いた強い言い回し、もう存在しないファイルやコマンドの名前、別のファイルと食い違う規則がたまっていきます。/doctor prompt-audit は、それを Claude に探させるコマンドです。
公式ドキュメントの説明を要約すると、次のとおりです。
- 探すもの：古いモデル向けに書かれた指示、存在しないファイルやコマンドへの言及、互いに矛盾するファイル。
- 返すもの：見つかった問題の報告と、直し方の案（差分）。Claude に適用を頼むまで、ファイルは何も変わらない。
- 仕組み：Claude Code に同梱の
/claude-apiスキルを通して動く。そのため、設定でこのスキルを止めている（skillOverridesで無効にした、disableBundledSkillsを有効にした）と使えない。 - 必要な版：Claude Code v2.1.283 以降。
/checkup prompt-auditも同じもの。
CHANGELOG の v2.1.283 には、「CLAUDE.md・スキル・エージェント・コマンドを、古いモデル向けのプロンプトの書き方について点検する /doctor prompt-audit（/checkup prompt-audit も）を追加」とあります。同じ版で、古いパス・古いコマンド・食い違う指示ファイルを報告の先頭に出すように改良され、Claude Code が公式に扱う「think」のような考える深さの語は残すようになりました。
なぜ「古い指示」が問題になるのかについて、同梱の手順書は次のように説明しています。いまのモデルは、昔のモデルより指示に近く、文字どおりに従う。そのため、昔のモデルが指示を見落とさないように付けた「CRITICAL」「必ず」の重ね掛けが、いまは効きすぎて、必要のない場面でも規則を当てはめたり、融通の利かない動きになったりする。点検の目的は「指示を短くすること」ではなく、いまのモデル・いまのプロジェクト・ほかの指示と合わなくなった指示を見つけることだ、と手順書ははっきり書いています。
2. 使い方——打つだけで、範囲はパスで絞れる
Claude Code のセッションの中で、次のように打つだけです。
/doctor prompt-audit何も渡さないと、公式ドキュメントによれば次のファイルが対象になります。
| 種類 | 中身 |
|---|---|
| 指示ファイル | CLAUDE.md・CLAUDE.local.md・AGENTS.md |
.claude/ と ~/.claude/ の下 | ルール（rules）・スキル・コマンド・サブエージェント・出力スタイル（output styles） |
1つのファイルやフォルダだけを点検したいときは、パスを渡します。公式ドキュメントの例は次のとおりです。
/doctor prompt-audit .claude/skills/deploy同梱の手順書によると、点検は途中で質問せずに最後まで走る作りです。範囲と「どのモデルに合わせて点検するか」は依頼と手元のファイルから自分で決め、その前提を報告の冒頭に書きます。前提が違っていたら、範囲を絞って打ち直せば直せます。指示ファイルの点検では、ふつうはいま点検を走らせているモデルが基準になります（スキルやサブエージェントが自分でモデルを指定していれば、そのモデル）。
なお、手順書は Claude Code の設定ファイル（.claude/settings*.json）や MCP の設定（.mcp.json）は読まないと決めています。秘密の値が入っていることがあるためです。権限やフックの設定の問題は、この点検の対象外です（6章の /doctor が担当します）。
3. 何を「古い」と判定するのか
点検の中身は、Claude Code に同梱されている手順書（/claude-api スキルの中の prompt-audit の手順）に書かれています。筆者が v2.1.286 の同梱ファイルを読んだところ、点検は4つのグループに分かれていました。指示ファイルの点検で主に効くのは、最初の2つです。
| グループ | 主な中身 | 例 |
|---|---|---|
| 1. 古い書き方の指示 | 強すぎる言い回し、いまは不要な考え方の指定、手順の細かすぎる指定、昔のモデルの不具合への手当てが残ったもの | 「CRITICAL: 必ず〜」の連発、「段階的に考えて」、「STEP 1… STEP 2…」で判断の仕事を縛る |
| 2. 壊れやすい設定ファイル | 存在しないパス・コマンド、ファイル同士の食い違い、事故の経緯の書き込み、1回のつまずきを恒久の規則にしたもの、日付つきの条件 | 消したスクリプトの名前、2つのファイルで逆の規則、「◯月◯日にこう失敗したので」 |
| 3. ツールの説明文 | API でツールを定義するときの説明文（短すぎる説明は足す方向で指摘） | 1行だけの説明、説明文の中の「必ずこのツールを使え」 |
| 4. API の呼び出し側の設定 | いまのモデルではエラーになる・非推奨になったパラメータ、キャッシュを壊す並び順など | アプリのコードがある場合だけ（指示ファイルだけのプロジェクトでは対象外） |
グループ2の「存在しないパス・コマンド」は、手順書の中でも扱いが強い項目です。指示ファイルに書かれたパスがプロジェクトの中に実在するか、コマンドやフラグがスクリプトや設定に定義されているかを、コマンドを実行せずに、ファイルを読んで確かめます。プロジェクトの実物と食い違う記述は「確かさ：高」の指摘になります。
ファイル同士の食い違いでは、どちらが新しいかを git blame（どの行をいつ誰が書いたかの記録）で決め、古いほうを新しいほうに合わせる案を出します。ただし、片方が禁止や安全の規則で、直すとそれが緩む場合や、どちらが新しいか履歴で分からない場合は、直す案を出さずに「ユーザーが決めること」として報告するだけにする、と手順書は決めています。
4. 消さないもの——「短くする点検」ではない
この点検で筆者がいちばん良いと感じたのは、消してはいけないものの一覧が手順書にはっきり書かれていることです。手順書は「何でも消す点検は、真面目に従う人ほど損をする」として、次のようなものは文字列が引っかかっても残すと決めています。
- 書いた人しか知らない文脈——読者・製品・環境の事実・品質の基準・制約と、その理由。手順書は「文脈は決して無駄ではない」と書いている。
- 長さそのもの——字数だけを理由に消さない。害があるのは古い指示であって、量ではない。
- 壊れやすい作業の正確な手順——削除のコマンドや認証の流れなど、安全な手順が1通りしかない作業は、細かい指定のままでよい。
- いまも実際に起きる失敗への禁止——その失敗がいまのモデルでも再現するなら残す。
- うまく働いている重複——同じ内容が2か所にあっても、食い違っていなければ整理の好みの問題で、点検の対象ではない。
逆の方向もあります。いまのモデル向けに指示を足したほうがよい場合は、足す案も出します。そして、何も見つからなければ何も変えないのが正しい結果だ、とも書かれています。
5. 結果の読み方——報告と差分の案
結果は2つ出ます。点検の報告と、直し方の案（差分）です。報告は指摘ごとに次の6項目で書かれます。
| 項目 | 中身 |
|---|---|
| 場所 | ファイル名と行番号 |
| 証拠 | 問題の文をそのまま引用 |
| 型 | 3章のどの型に当たるか |
| 古い理由 | いまのモデルの振る舞い、またはプロジェクトの実物の何と食い違うか |
| 確かさ | 高（公式の記述やプロジェクトの実物と矛盾）・中（広く観察される振る舞い）・低（言い回しからの推測） |
| 対応 | 削除・書き換え（新しい文つき）・移動（移す先つき）・追加・指摘のみ |
差分の案に入るのは、確かさが高と中の指摘だけです。低の指摘は報告に載るだけで、差分には入りません。差分は1件の指摘につき1か所に分けてあるので、受け入れたいものだけを選んで適用できます。
適用するときは、Claude に「1・3・4番を適用して」のように頼みます。手順書は、ファイル同士の食い違いと「実物と合わない記述」の書き換えについて、「全部きれいにして」のようなまとめての依頼では適用しないとも決めています。新しいほうの記述も実物も、リポジトリに書き込める人なら誰でも変えられるため、1件ずつ人が確かめる前提です。
6. /doctor・/claude-api prompt-audit・claude doctor との違い
名前の似たものが4つあります。公式ドキュメント（Commands・Skills）と CHANGELOG の記述で比べると、次のとおりです。
| コマンド | 何をするか | ファイルを変えるか | 必要な版 |
|---|---|---|---|
/doctor prompt-audit | 指示ファイル（CLAUDE.md・スキルなど）の古い指示・食い違いを点検 | 報告と案だけ（頼めば適用） | v2.1.283 以降 |
/doctor（別名 /checkup） | 環境の健康診断（インストールの重複・PATH・壊れた設定、使っていないスキルや MCP、遅いフック、新しい版の有無）と、CLAUDE.md からコードを見れば分かる内容を削る提案・常に読む指示をスキルや入れ子の CLAUDE.md に移す提案 | 先に報告し、確認してから直す | （CLAUDE.md を削る提案は v2.1.206 以降） |
/claude-api prompt-audit | Claude API を使うアプリのプロンプトやツールの説明文を、古いモデル向けの書き方について点検 | 差分の案を出す | v2.1.221 以降 |
claude doctor（ターミナル） | セッションを始めずに、インストールの状態を表示するだけ | 変えない（読み取りのみ） | — |
ややこしいのは、/doctor 自体も CLAUDE.md を扱う点です。違いは目的にあります。/doctor は常に読み込まれる量を減らす方向（重複を消す・コードから分かることを削る・必要なときだけ読む場所へ移す）、/doctor prompt-audit は中身が古くなっていないか・食い違っていないかを見ます。ターミナルの claude doctor は prompt-audit を走らせません。
Claude が指示を守らないとき、原因がそもそも読み込まれていないことにあるなら、この点検では直りません。読み込みの確かめ方は「AIがルールを無視する原因と対応策」に、指示ファイルが会話の容量をどれだけ使っているかの測り方は「Claude Codeのコンテキストは何に食われているのか」にまとめています。
7. 実際に使ってみた——このサイトの指示ファイルで
2026年10月3日、このサイトの開発で使っている指示ファイルに /doctor prompt-audit をかけました。実行したのは Claude Code のデスクトップアプリ（同梱の Claude Code 2.1.286、モデルは Opus 5.5）です。このサイトの指示ファイルは、Claude Code と Codex で共用する AGENTS.md（ルールの本体）と、それを取り込む CLAUDE.md（Claude Code だけの事情）の2つで、合わせて約1万700字ありました。.claude/ の下にルール・スキル・コマンドは置いていません。
1回かけた結果
出典: 筆者の実測（2026年10月3日・/doctor prompt-audit・CLAUDE.md と AGENTS.md）
指摘の数
9件
確かめて適用
7件
見送り（確かさ：低）
2件
まず意外だったのは、古いモデル向けの書き方はほとんど見つからなかったことです。「段階的に考えて」のような指定や、手順の逐一の指定は1つもありませんでした。指摘の中心は、3章のグループ2（壊れやすい設定ファイル）でした。
| 確かさ | 件数 | 中身 | 筆者の対応 |
|---|---|---|---|
| 高 | 1件 | その日に点検の道具を2本足したのに、説明の括弧書きが「どちらも」のままで、足した2本の説明と合っていなかった | 適用（足した道具の分まで説明を書き分けた） |
| 中 | 5件 | 指示ファイルに残る日付・回数つきの事故の記録（同じファイルの「起点のファイルに事故の記録を積まない」という規則と食い違う） | 適用（ただし消さずに、別の記録用ファイルへ移した） |
| 中 | 1件 | 見出しの「(CRITICAL)」に理由が添えられていない | 適用（外した） |
| 低 | 2件 | 手元で動かないコマンドの列挙、日付つきの見出し | 見送り（どちらも理由のある記述で、手順書でも低は「指摘のみ」） |
確かさ「高」の1件は、本物のずれでした。点検の道具を足したときに一覧には名前を足したものの、その横の説明を書き直し忘れていたものです。読み込むたびに Claude が「どちらも」の意味を取り違えかねない状態で、人の目では見落としていました。
報告には、指示ファイルに出てくるパス・道具の名前・参照先のメモがすべて実在することを確かめた、という記録もありました。PHP の版（Docker の設定と一致）や、手順の項目数（別のファイルの一覧と一致）まで突き合わせていました。
適用は、Claude の差分の案をそのまま受け入れたのではなく、1件ずつ元のファイルで確かめてから行いました。いちばん判断が要ったのは中の5件です。案は「事故の記録を消す」でしたが、記録そのものは後から同じ失敗を防ぐ根拠なので、消さずに移すことにしました。日付と回数がすでに別のファイルに残っているものは指示ファイルから外すだけにし、どこにも残っていなかった2件は記録用のファイルへ書き写しました。結果として、指示ファイルの合計は約1万700字から約40字減っただけです。量はほとんど変わらず、食い違いだけが消えたことになります。
ただし、これは1つのプロジェクトに1回かけた結果です。点検の文章はモデルが書くので、同じファイルにかけても指摘の数や言い回しが変わることがあります。.claude/ の下にスキルやコマンドを多く置いているプロジェクトでは、指摘の中身もかなり違うはずです。
8. デメリットと注意点
使ってみて、また公式ドキュメントと手順書を読んで分かった注意点は次の5つです。
- 利用枠を使う——セッションの中で Claude が指示ファイルを読んで点検するので、ほかの作業と同じく利用枠から減る。専用の料金は公式ドキュメントに書かれていない。
- 指摘をそのまま適用しない——Claude は「なぜその規則を書いたか」までは知らないことがある。今回も「事故の記録を消す」案をそのまま受けていたら、同じ失敗を防ぐ根拠を失っていた。
- 結果は毎回同じではない——点検を書くのはモデルなので、件数や表現は回によって変わりうる。1回の結果を「このファイルは問題なし」の証明にしない。
- 設定ファイルは見ない——
settings.jsonや.mcp.jsonは読まないので、権限・フック・MCP の問題は映らない。そちらは/doctorで見る。 - 中身の正しさの保証ではない——実在しないパスや食い違いは見つかるが、指示が正しい方針かどうかは判断しない。方針を決めるのは自分。
手順書自身も、削除は「結論ではなく仮説」だと書いています。指示を消したら、その指示が守らせていた振る舞いが崩れていないかを、実際の作業で確かめるのが前提です。
9. いつかけるとよいか
手順書は「プロンプトはモデルごとの成果物で、ある世代で必要だった行が次の世代では無駄になる」として、新しいモデルが出るたびに点検し直すことを勧めています。筆者の判断としては、次の3つの場面が向いていると感じました。
- 使うモデルを新しい世代に替えたとき——昔のモデルのために付けた強い言い回しや手当てが残っていないかを見る
- 指示ファイルを大きく書き換えたとき——今回のように、足した規則と古い説明の食い違いが出やすい
- Claude Code と Codex など複数の道具で指示ファイルを共用しているとき——AGENTS.md と CLAUDE.md の食い違いを見つけやすい
逆に、指示ファイルが短く、ほとんど書き換えていないプロジェクトでは、急いでかける必要はありません。手順書にも、何も見つからないのは正しい結果だと書かれています。
まとめ
/doctor prompt-audit は、CLAUDE.md・AGENTS.md・スキルなどの指示ファイルから、古いモデル向けの書き方・存在しないパスやコマンド・食い違う規則を探し、報告と差分の案を出すコマンドです。Claude Code v2.1.283 以降で使え、頼むまでファイルは変わりません。
点検の手順書は、文脈・理由・いまも起きる失敗への禁止を「消さないもの」として守り、「短くする点検」にならないように作られています。このサイトの指示ファイルにかけたところ、古いモデル向けの書き方はほとんど無く、代わりに規則を足したときの説明の書き直し忘れという本物のずれが見つかりました。
指摘は1件ずつ元のファイルで確かめ、理由のある記述は消さずに移すのが安全です。新しいモデルに替えたときや、指示ファイルを大きく書き換えたときに1回かけると、人の目で見落としていた食い違いを拾えます。
FAQ
Q. /doctor prompt-audit をかけると、CLAUDE.md が勝手に書き換わりますか？
A. 書き換わりません。公式ドキュメントは、報告と直し方の案を返し、Claude に適用を頼むまでファイルは何も変わらないと書いています。適用するときも、案ごとに選べます。
Q. /checkup prompt-audit と何が違いますか？
A. 同じものです。/checkup は /doctor の別名で、CHANGELOG の v2.1.283 にも「/doctor prompt-audit（/checkup prompt-audit も）」と書かれています。
Q. Codex 用の AGENTS.md も点検されますか？
A. されます。公式ドキュメントは、何も渡さないときの対象に CLAUDE.md・CLAUDE.local.md と並べて AGENTS.md を挙げています。2つのファイルを共用しているなら、食い違いを見つけるのにも向いています。
Q. 打っても点検が始まりません。
A. まず版を確かめます。/doctor prompt-audit は v2.1.283 以降が必要です。版が新しいのに動かないときは、設定で同梱の /claude-api スキルを止めていないか（skillOverrides・disableBundledSkills）を確かめます。なお、ターミナルで打つ claude doctor はインストールの診断だけで、この点検は走りません。
Q. API で作ったアプリのシステムプロンプトも点検できますか？
A. できますが、そちらは /claude-api prompt-audit を使います（v2.1.221 以降）。プロンプト・ツールの説明文・API を呼ぶコードを、古いモデル向けの書き方について点検し、差分の案を出します。
出典
- Claude Code 公式ドキュメント：How Claude remembers your project（「Audit your instruction files」節）
- Claude Code 公式ドキュメント：Commands（
/doctor・/claude-apiの行） - Claude Code 公式ドキュメント：Skills（同梱スキル
/claude-apiのサブコマンドと必要な版） - Claude Code：CHANGELOG（v2.1.283）
- Claude Code v2.1.286 に同梱の
/claude-apiスキルの prompt-audit の手順書（筆者の端末で確認）
いずれも2026年10月3日に原文を確認しました。同梱の手順書は Claude Code の版ごとに更新されるので、点検の中身は版によって変わることがあります。
