Claude Code v2.1.283（2026年9月25日リリース）で追加された /doctor prompt-audit（別名 /checkup prompt-audit）は、CLAUDE.md・Skill・エージェント定義・スラッシュコマンドを横断して「古いモデル向けのプロンプティングパターンが残っていないか」を洗い出す監査コマンドだ。
先日、この機能を検証した記事を読んだ。著者はSKILL.mdを持つディレクトリが49本ある環境で、1回目の実行ではプロジェクト内18ファイルしか対象にならず、Skillもサブエージェントも1つも見なかった。--add-dir ~/.claude を付けた2回目でようやくSkill45本・サブエージェント286個を認識したが、全文を読んだのはSkill3ファイルとサブエージェント2個だけで、残りはgrepの流し見だったという。
私も複数のカスタムSkillとエージェント定義を長期運用している身として、これが自分の構成でどう動くのか気になった。この記事は、自分の環境で実際に手を動かして確認した結果と、そこから見えた見落としパターンの記録である。
まず自分の構成を数えた
検証の前に、自分がどれだけの定義ファイルを抱えているかを数えた。
# トップレベルのSkill数
find skills -maxdepth 1 -name "*.md" | wc -l
# => 6
# skills/media-profiles/ は「Skillそのもの」ではなく
# write-blog Skillが内部で読むデータファイル
ls skills/media-profiles/
# => _template.md note.md qiita.md
# エージェント定義（ルート直下＋部門サブディレクトリ）
ls agents/*.md | wc -l # => 19
find agents -mindepth 2 -name "*.md" | wc -l # => 5（secretary/cfo/cmo/dev配下）
ルート直下のエージェント定義19本＋部門サブディレクトリ（agents/secretary/・agents/cfo/・agents/cmo/・agents/dev/）配下の専門エージェント5本で、合計24本のエージェント定義を運用している。Skillは6本だが、skills/media-profiles/ には媒体プロファイルとして3ファイルが別に存在する。ここで最初の学びがあった。「Skillの本数」を単純に.mdの数で数えると、写経元記事が抱えていた「49本のはずが実際のカウントは48→45とズレる」問題を、自分の構成でも即座に再現できる。media-profilesはwrite-blogSkillが参照する設定ファイルであって独立したSkillではないので、数え方の定義次第で本数がぶれる。
実行しようとして、実行できなかった
元記事を追試する形で /doctor prompt-audit を非対話実行しようとしたが、私の環境では手前でつまずいた。
$ claude --version
Error: claude native binary not installed.
Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).
CLIのネイティブバイナリが入っていないため claude -p すら起動できない状態だった。元記事の著者も1回目の実行を claude -p の非対話セッションで行っており、ユーザー階層（~/.claude）への権限が下りずスコープが狭まったと報告している。私の場合はそれ以前の環境問題で足止めを食らった形だが、裏を返せば「監査コマンドを当てにする前に、そもそも実行環境が対話セッションと同じ権限・同じスコープで動くかを確認する」という同じ論点に行き着く。
実行できない以上、コマンドの出力そのものは検証できない。そこで、元記事が明らかにした「監査コマンドがどこを見て、どこを見ないか」の境界線を、自分のリポジトリ構造に当てはめて手動で洗い出すことにした。
可視範囲チートシート
元記事の実測（1回目=プロジェクト内18ファイルのみ・2回目=--add-dirで45Skill/286サブエージェント認識）から逆算すると、監査コマンドの可視範囲は次の3層に分かれる。
| 実行方法 | 見える範囲 | 自分の環境での該当箇所 |
|---|---|---|
| プロジェクト内で素実行 | カレントプロジェクトのCLAUDE.md・.claude/配下のみ |
ルートCLAUDE.md1本＋agents/24本＋skills/6本 |
--add-dir ~/.claude 併用 |
ユーザー階層のSkill・サブエージェント定義も追加 | 個人設定側のカスタム定義（プロジェクトと別スコープ） |
| 対象外（自分で個別に回すしかない） | 別プロジェクト・サブリポジトリのCLAUDE.md |
projects/配下の子リポジトリ・worktree |
3列目は自分で洗い出して初めて気づいた点だ。試しに数えてみたところ、リポジトリ内には独立したCLAUDE.mdが11本、別々のディレクトリに散らばっていた（子リポジトリ7本、worktree系2本、tools/配下1本、ルート1本）。監査コマンドを1回実行しただけでは、これらは対象に入らない。プロジェクトごとに個別に/doctor prompt-auditを回す必要があり、「1回実行して終わり」にすると11分の1しかカバーできない計算になる。
実際にやった代替検証：誤検知も1件見つかった
構造の洗い出しと合わせて、「監査コマンドが指摘しそうな『使われなくなった参照』が実際に残っていないか」もgrepで確認した。
# 過去に廃止したSkill名が、他のエージェント定義に
# 「生きている参照」として残っていないか確認
grep -rl "polish-content\|upgrade-automation\|generate-cover" agents/ skills/
# => agents/publisher-agent.md
1件ヒットした。中身を見ると、該当箇所は「このSkillは過去に廃止済み・再度必要になったら作り直す」という注記付きの記述で、実際に壊れた参照ではなく意図的に残した履歴コメントだった。監査コマンドが「stale paths, stale commands and contradicting instruction files」を優先的に報告する仕様である以上、こうした注記付きの意図的な廃止記録を機械的に「古い参照」として拾ってしまう可能性はある。人間が見て初めて「これは事故ではなく記録だ」と判断できるケースがあることは、実際に手を動かして初めて分かった。
CLAUDE.mdや各種定義ファイルを増やしてきた過程では、以前Hooks機能でファイル変更のたびにESLintとJestを自動実行する仕組みを組み込んだことがある。ついでにkillスイッチ用のPreToolUseフックも導入したところ、構文エラーやテスト失敗の見逃しがゼロになった。今回のように定義ファイルが何十本にも増えると、「どこに何を書いたか」を人間の記憶だけで管理するのは早々に限界が来る。あのときHooksで「AIの行動に自動チェックポイントを設ける」仕組みを入れたのと同じで、定義ファイル自体も「書いたら終わり」ではなく定期的に検証する対象として扱う必要がある。
見落としパターン対応表
自分の環境で確認できた範囲を、トラブルシューティング表としてまとめる。
| 見落としパターン | 原因 | 対策 |
|---|---|---|
| Skill・エージェントが0件扱いになる | 非対話セッションでユーザー階層への権限が下りない |
--add-dir ~/.claude を明示的に付ける |
| Skillの本数が資料と食い違う | データ用ファイル（プロファイル等）を独立Skillとしてカウントしてしまう | Skill本体とSkillが参照する設定ファイルをディレクトリで分けておく |
| サブリポジトリ・worktreeのCLAUDE.mdが対象外になる | 監査は実行時のカレントプロジェクトだけを見る | 子リポジトリごとに個別実行するか、対象パス一覧を台帳化しておく |
| 大量のファイルは全文でなく grep の流し見になる | 数十〜数百本規模だと全文読み込みのコストが高い | 優先度の高いCLAUDE.md・頻用Skillだけでも個別に全文レビューする運用を残す |
| 廃止済みの参照が「古い記述」として拾われる | 廃止記録の注記か、本当に壊れた参照かは機械では区別しづらい | 廃止時は「いつ・なぜ廃止したか」を1行コメントで残し、指摘が出たら人間が最終判断する |
まとめ
実際に手を動かして分かったのは、/doctor prompt-auditという名前がついていても、その実態は「設定ファイルの内容そのものの良し悪し」より先に「そもそもどこまで見えているか」という実行スコープの問題にぶつかるということだった。私の環境ではコマンド自体を動かすところで止まってしまったが、構造を自分の目で数え直しただけでも、Skillのカウント基準のブレやサブリポジトリの取りこぼしといった、監査コマンドが実際に指摘しそうな穴を先に見つけられた。結局のところ、監査コマンドは「代わりに全部やってくれる道具」ではなく、「どこを見ていないかを教えてくれる道具」として使うのが実態に近いと感じている。
この記事の要点だけ持ち帰るなら、監査コマンドを実行する前に、自分のSkill・エージェント定義が何本あり、どこに散らばっているかを一度自分で数えておく、という一点だけ覚えておけば十分です。
自分の環境で試すときのメモ代わりに ストック しておくと、必要になったときにすぐ引けます。