Claude Codeのprompt-auditで古いモデル向けの記述を検出する
/claude-api prompt-auditと/doctor prompt-auditは、CLAUDE.md・Skillなどに残った古いモデル向けの記述を検出するコマンドです。2つの違いと使い分けをまとめます。
prompt-auditは古いモデル向けの指示文を検出するコマンド
prompt-auditは、CLAUDE.md・Skillのdescription・ツールの説明文・システムプロンプトといった「モデルに向けて書いた指示文」の中から、古いモデル世代を前提にした記述を検出するコマンドです。実行すると、書き換えが必要そうな箇所を一覧またはdiff形式で提示します。対象はコードではなく、あくまで自然文の指示です。
呼び出し方は2種類あります。/claude-apiスキルのサブコマンドとして使う/claude-api prompt-audit(v2.1.221以降)と、doctorスキルのサブコマンドとして使う/doctor prompt-audit(エイリアス/checkup prompt-audit、v2.1.283以降)です。名前は似ていますが監査対象と結果の出し方が異なり、使い分けは後述の節にまとめます。手元のバージョンがそれぞれの追加バージョンより前だとサブコマンド自体が認識されません。
同じclaude-apiスキルのmigrateサブコマンドがSDK呼び出しやモデルID指定といったコードを対象にするのに対し、prompt-audit系のコマンドが見るのは自然文の指示です。コードのモデル移行はmigrateで終わっても、プロンプト側の記述が古い世代のモデルを前提にしたままというギャップが起きやすく、prompt-auditはそこを埋めるためのコマンドです。
なぜプロンプトは「古くなる」のか
モデルの世代が変わると、同じ指示文でも効き方が変わることがあります。公式のモデル比較表を見ると、その典型例が確認できます。
| 項目 | Claude Opus 5.5 / Sonnet 5.5 / Sonnet 5 / Fable 5.1 | Claude Haiku 4.5 |
|---|---|---|
Extended thinking(thinking.type: "enabled") | Claude Opus 5.5 / Sonnet 5.5 / Sonnet 5 / Fable 5.1非対応 | Claude Haiku 4.5対応 |
| Adaptive thinking | Claude Opus 5.5 / Sonnet 5.5 / Sonnet 5 / Fable 5.1対応(Opus 5.5・Fable 5.1は常時オンで無効化不可。Sonnet 5.5はdisabledが400になり、between_toolsで事前の思考を止める) | Claude Haiku 4.5非対応 |
Claude Codeが使うOpus 5.5・Sonnet 5.5・Sonnet 5・Fable 5.1は、明示的なthinking.type: "enabled"パラメータを使いません。Adaptive thinkingという別方式で思考量を扱います。Opus 4.x世代向けにthinking.type: "enabled"を前提に組んだ設定や、それを前提に書いた指示文は、これらの新モデルではそのままでは効きません。逆にHaiku 4.5はExtended thinkingに対応する側なので、世代とモデルラインの組み合わせで「効く指示」と「効かない指示」が入れ替わります。
トークナイザーの変化も見逃しやすいポイントです。Opus 4.7で導入されたトークナイザーは、Opus 4.7より前のモデルに比べて同じテキストで最大1.35倍程度のトークンを使うことがあります(Sonnet 5はSonnet 4.6比でおよそ30%増。Sonnet 5.5のトークナイザーはSonnet 5と同じです)。「出力は500トークン以内に収めてください」のように具体的なトークン数を指示に埋め込んでいる場合、モデル世代を跨ぐとその数字の意味合いがずれます。
モデルIDの指定方法も見直しの対象です。Claude 4.6世代以降はモデルIDが日付なし形式でも固定スナップショットとして扱われるようになりました。「日付が入っていないIDは常に最新版を指す」という古い前提でコードやコメントを書いていると、実際の挙動と食い違います。
知識カットオフの差も、プロンプトに埋め込みがちな前提の1つです。同じ世代でもモデルラインによって「reliable knowledge cutoff(信頼できる知識の範囲)」は異なります。たとえばFable 5.1・Opus 5.5・Sonnet 5.5はいずれも2026年6月ですが、Sonnet 5は2026年1月で、基準日が数か月単位でずれています。「◯年◯月以降の出来事は知らない前提で回答してください」のように具体的な日付をプロンプトに埋め込んでいる場合、モデルを切り替えるたびにその日付が正しいかどうかを人手で確認し直す必要があります。
どちらのprompt-auditを使うか
prompt-auditは2つの入り口から実行できます。どちらも「古いモデル向けの記述を検出する」という目的は共通ですが、監査対象と結果の出し方が異なります。
2つの入り口の違い
/claude-api prompt-audit
出発点はclaude-apiスキルで、Claude APIやAnthropic SDKを使うプロジェクト向けです。監査対象はプロジェクト内のプロンプト・Skillのdescription・ツールの説明文全般。結果は修正案の差分(diff)で返ります。
/doctor prompt-audit
出発点はdoctorスキル(エイリアス/checkup)で、Claude Code自体のセットアップ点検です。監査対象はCLAUDE.md・skills・agents・commandsに絞られます。結果は古いパス・古いコマンド・矛盾する指示ファイルを上位に並べたレポートです。
監査対象が重なるのはskillsなど一部です。claude-api側はコードでanthropicや@anthropic-ai/sdkをインポートしているプロジェクトで自動的に有効になり、SDK呼び出しのモデル移行(migrate)と地続きで使えます。/doctor側はAPI/SDKを使わないプロジェクト、たとえばClaude Codeの設定だけを管理しているリポジトリでも使えます。/doctorの点検とは別に、/doctor prompt-auditで古い前提のプロンプトだけを洗い出せる点と、Claude Codeが案内しているthinkingキーワードを古い記述と誤判定しない点は、v2.1.283で加わった改善です。
実行するとどうなるか
どちらの入り口も、コードへ自動で書き込むのではなく、結果を返して判断を委ねます。
/claude-api prompt-auditプロジェクト全体を一度に監査すると差分の量が増えるため、まずは.claude/skills/配下などモデルへの指示が集中している場所から確認すると判断しやすくなります。絞り込みには/doctor側の/doctor prompt-audit <path>のようにパスを渡す構文があります(公式の構文は/doctor [prompt-audit [path]])。/claude-api prompt-audit側にパス引数の記載は見当たりません。
/doctor prompt-audit(/checkup prompt-audit)の入力例です。
/doctor prompt-audit/doctorの点検(checkup)は、所見を先に報告し、変更前に確認を求める仕様です。prompt-auditの結果は差分もレポートも、内容を確かめてから反映するかどうかを決めます。
手元のバージョンで実行できるか先に確かめる
prompt-auditはスラッシュコマンドなので、セッションの中で入力する機能です。シェルからclaude prompt-auditと打つものではありません。v2.1.285のヘルプを見ると、シェル側にあるdoctorは次の説明です。
$ claude --version
2.1.285 (Claude Code)
$ claude doctor --help
Usage: claude doctor [options]
Check the health of your Claude Code installation. Reads settings files in the
current directory without a trust prompt. For a full checkup that can also fix
issues, run /doctor in a session.シェルのclaude doctorはインストール状態の確認までで、修正まで含む全体点検は「セッション内の/doctor」と案内されています。/doctor prompt-auditを試すときは、claudeでセッションを開いてから入力する必要があります。claude --helpには--disable-slash-commands(Disable all skills)というオプションもあります。このオプションで起動したセッションではスキルが無効になるため、claude-apiやdoctorのサブコマンドは使えないと考えられます(この組み合わせ自体は実行していません)。
実行の前後の流れは次の4段階です。
prompt-auditを回す前後の流れ
- 1
バージョンを確認する
claude --version(または/status)で、使いたい入り口の追加バージョン(v2.1.221またはv2.1.283)以上かを見ます。 - 2
セッションを開いてコマンドを入力する
コード側のモデル移行が済んでいれば、対象に合わせて
/claude-api prompt-auditか/doctor prompt-audit(必要なら<path>付き)を入力します。 - 3
差分またはレポートを読む
差分は1件ずつ、レポートは上位の項目から判断します。
- 4
反映を決める
差分もレポートも、内容を確かめてから反映します。
リポジトリの外にある指示文は対象になりにくい
prompt-auditが確実に監査できるのは、ファイルとして手元にある指示文です。Managed Agentsのシステムプロンプトを管理コンソール側だけで設定している場合や、別チームが管理する社内プラットフォームにプロンプトを直接貼り付けて運用している場合は、そのプロンプトはリポジトリ内のファイルとして存在しないため、どちらのprompt-auditも監査のしようがありません。エージェント設計をUIやダッシュボード側で完結させている組織ほど、この抜け漏れが起きやすくなります。
対策はシンプルで、モデルへの指示文をなるべくリポジトリ内のファイルとして管理することです。システムプロンプトやツールの説明文を.claude/配下やSkillのdescriptionに落とし込んでおけば、prompt-auditの監査対象に自然と含まれます。prompt-auditをきっかけに「指示文がどこに散らばっているか」を洗い出すこと自体が、エージェント運用全体の棚卸しにもつながります。
prompt-auditが効くのはデフォルトモデルの切り替え直後
prompt-auditが最も効くのは、デフォルトモデルが切り替わった直後です。直近では、Pro・Team Standardプランの既定モデルがv2.1.280でSonnetからOpusへ変わり、同じリリースでOpus自体もOpus 5からOpus 5.5へ置き換わりました。単価・破壊的変更はClaude Opus 5.5とはにまとめています。こうした切り替えのたびに、Adaptive thinkingの扱いやeffortの既定値が変わり、旧世代を前提にしたプロンプトの前提が崩れます。新しいモデルがデフォルトになったニュースを見た時点で、コードのmigrateと合わせてprompt-audit(/claude-api prompt-auditまたは/doctor prompt-audit)を走らせておくと、指示文側の見落としを早めに拾えます。
長く運用しているSkillやツール定義ほど、過去のモデル世代を前提にした注釈が本文中に残りがちです。「念のため一歩ずつ考えてから答えてください」のような、当時のモデルの推論能力を補うために足した指示は、Adaptive thinkingのような機構が標準搭載された後のモデルでは冗長になることがあります。こうした記述は動作を壊さないため気づきにくく、prompt-auditのような機械的な棚卸しが向いている領域です。Skillのdescriptionやfrontmatterの書き方自体はClaude Code Skills完全ガイドを参照してください。
まとめ
prompt-auditは、CLAUDE.md・Skill・ツール説明文の中から古いモデル向けの記述を検出するコマンドです。入り口は2つあります。claude-apiスキルの/claude-api prompt-audit(v2.1.221以降、修正案を差分として提示)と、doctorスキルの/doctor prompt-audit(/checkup prompt-audit、v2.1.283以降、CLAUDE.md・skills・agents・commandsに絞ったレポートを返す)です。Extended thinkingとAdaptive thinkingの違いやトークナイザーの変化のように、モデル世代が変わると指示文の効き方そのものが変わる場面があり、こうした変化はコードを見ているだけでは気づきにくいものです。既定モデルが切り替わった直後に、コード側のmigrateと合わせてどちらかのprompt-auditを走らせておくと、プロンプト側の棚卸し漏れを防げます。