Claude Codeのprompt-auditで古いモデル向けの記述を検出する

prompt-auditはコードでなく指示文を監査する

prompt-auditはclaude-apiスキルの3つのサブコマンドの1つで、v2.1.221以降で使えます。/claude-api prompt-auditと実行すると、コード・スキル・ツールの説明文の中から古いモデル向けに書かれた記述を検出し、修正案を差分(diff)として提案します。

同じスキルのmigrateサブコマンドがSDK呼び出しやモデルID指定といったコードを対象にするのに対し、prompt-auditが見るのは自然文の指示です。システムプロンプト、Skillのdescription、ツールの説明文、CLAUDE.mdに書いた振る舞いの指示など、モデルに向けて書いた文章そのものが対象になります。コードのモデル移行はmigrateで終わっても、プロンプト側の記述が古い世代のモデルを前提にしたままというギャップが起きやすく、prompt-auditはそこを埋めるためのサブコマンドです。

なぜプロンプトは「古くなる」のか

モデルの世代が変わると、同じ指示文でも効き方が変わることがあります。公式のモデル比較表を見ると、その典型例が確認できます。

Opus 5・Sonnet 5・Fable 5は明示的なthinking.type: "enabled"パラメータではなく、Adaptive thinkingという別方式で思考量を扱います。Opus 5自体の仕様と料金はClaude Opus 5の使い方と仕様にまとめています。Opus 4.x世代向けにthinking.type: "enabled"を前提に書かれたコードやプロンプトの指示は、これらの新モデルではそのままでは意図通りに効きません。逆にHaiku 4.5はExtended thinkingに対応する側なので、世代とモデルラインの組み合わせによって「効く指示」と「効かない指示」が入れ替わります。

トークナイザーの変化も見逃しやすいポイントです。Opus 4.7以降の世代で採用されたトークナイザーは、それより前のモデルに比べて同じテキストでもおよそ30%多くのトークンを消費します。「出力は500トークン以内に収めてください」のように具体的なトークン数を指示に埋め込んでいる場合、モデル世代を跨ぐとその数字の意味合いがずれます。モデルIDの指定方法も同様で、Claude 4.6世代以降はモデルIDが日付なし形式でも固定スナップショットとして扱われるようになっており、古い世代の命名規則を前提にしたコードやコメントは実態と合わなくなっていることがあります。

モデルIDと知識カットオフのずれも対象になりうる

古いモデル向けの記述は、思考量の指定だけに現れるわけではありません。公式のモデル比較表の注記によれば、Claude 4.6世代より前のモデルでは日付付きのモデルIDが固定スナップショットとして扱われ、Claude 4.6世代以降は日付なし形式のIDでも同じく固定スナップショットとして扱われるという変更がありました。「日付が入っていないIDは常に最新版を指す」という古い前提でコードやコメントを書いていると、実際の挙動と食い違います。

知識カットオフの差も見落としやすい項目です。同じ世代でもモデルラインによって「reliable knowledge cutoff(信頼できる知識の範囲)」は異なり、たとえばOpus 5とSonnet 5では基準日が数か月単位でずれています。「◯年◯月以降の出来事は知らない前提で回答してください」のように具体的な日付をプロンプトに埋め込んでいる場合、モデルを切り替えるたびにその日付が正しいかどうかを確認し直す必要があります。prompt-auditが拾う「古いモデル向けの記述」には、こうした日付・IDまわりの前提のずれも含まれると考えられます。

実行するとどうなるか

/claude-api prompt-auditを実行すると、Claudeはプロジェクト内のプロンプト・Skillの説明文・ツールの説明文を横断的に読み、古いモデル向けの記述パターンを検出します。検出結果は個別に書き換えるのではなく、修正案を差分として提示する形で返ってきます。実際にコードへ反映するかどうかは、他のClaude Codeの提案と同じく確認してから判断する流れです。

/claude-api prompt-audit

プロジェクト全体を一度に監査するとレビューする差分の量が増えるため、まずは.claude/skills/配下やシステムプロンプトを定義しているファイルなど、モデルへの指示が集中している場所から範囲を絞って走らせるほうが、提案内容を1件ずつ確認しやすくなると考えられます。範囲を絞らずに実行すると、無関係なドキュメントファイルまで巻き込んでレビューが重くなる可能性があるため、最初は影響範囲の狭いディレクトリから試すのが安全そうです。

リポジトリの外にある指示文は対象になりにくい

prompt-auditが扱うのは、Claude Codeが開いているプロジェクトの中にあるファイルが基本だと考えられます。Managed Agentsのシステムプロンプトを、コードとして管理せず管理コンソール側だけで設定している場合や、別チームが管理する社内プラットフォームにプロンプトを直接貼り付けて運用している場合は、prompt-auditの視界に入りにくいはずです。エージェント設計をコードで管理せず、UIやダッシュボード側で完結させている組織ほど、この抜け漏れが起きやすくなります。

対策はシンプルで、モデルへの指示文をなるべくリポジトリ内のファイルとして管理することです。システムプロンプトやツールの説明文をコードとして.claude/配下やSkillのdescriptionに落とし込んでおけば、prompt-auditの監査対象に自然と含まれます。逆に言えば、prompt-auditをきっかけに「モデルへの指示文がどこに散らばっているか」を洗い出すこと自体が、エージェント運用全体の棚卸しにもつながります。

いつ棚卸しをすべきか

prompt-auditが最も効くのは、デフォルトモデルが切り替わった直後です。Claude Codeのclaude-apiスキル自体も、Opus 4.8対応の追加、Opus 4.8を基準にしたエージェント設計ガイダンスの拡張、Managed Agentsの取り込み、Opus 5をデフォルトにした更新という順で中身が更新されてきました。この更新の節目は、そのままユーザー側のプロジェクトでプロンプトが古くなりやすいタイミングとも重なります。新しいモデルがデフォルトになったニュースを見た時点で、コードのmigrateと合わせてprompt-auditを走らせておくと、指示文側の見落としを早めに拾えます。

長く運用しているSkillやツール定義ほど、過去のモデル世代を前提にした注釈が本文中に残りがちです。「念のため一歩ずつ考えてから答えてください」のような、当時のモデルの推論能力を補うために足した指示は、Adaptive thinkingのような機構が標準搭載された後のモデルでは冗長になっている可能性があります。こうした記述は動作を壊すわけではないため気づきにくく、prompt-auditのような機械的な棚卸しが向いている領域です。Skillのdescriptionやfrontmatterの書き方自体はClaude Code Skills完全ガイドを参照してください。

よくある質問

prompt-auditは自動でファイルを書き換えますか

いいえ。検出した記述に対する修正案を差分として提示する形式で、適用するかどうかは提示された内容を見てから判断します。

v2.1.221より前のバージョンでは使えませんか

prompt-auditサブコマンド自体がv2.1.221で追加されているため、それより前のバージョンでは/claude-apiに渡しても認識されません。バージョンを確認するには/statusまたはclaude --versionを使います。古いバージョンのまま/claude-api prompt-auditと打つと、サブコマンド自体が存在しないものとして扱われるため、まずアップデートを済ませてから試すのが確実です。

コードだけ新しいモデルに変えれば十分ではないですか

コードのモデルID指定を変えるだけでは、プロンプトやSkillの説明文に残った古い世代向けの前提までは直りません。動作は継続するため見落としに気づきにくく、これがprompt-auditを別サブコマンドとして用意している理由です。

Managed Agentsの設定コンソール側に書いたプロンプトも監査されますか

基本的にはされないと考えられます。prompt-auditが扱うのはClaude Codeが開いているプロジェクト内のファイルです。管理コンソールやダッシュボード側だけで完結しているプロンプトは、いったんコードとして取り込むかコピーして手元に置かない限り監査対象に入りにくいはずです。社内で複数チームがそれぞれ別のダッシュボードにプロンプトを持っている場合は、まずそれらをリポジトリへ集約するところから始めると、以降の棚卸しがprompt-auditだけで完結するようになります。

まとめ

prompt-auditはclaude-apiスキルのサブコマンドの1つで、コード・スキル・ツール説明文の中から古いモデル向けの記述を検出し、修正案を差分として提案します。Extended thinkingとAdaptive thinkingの違いやトークナイザーの変化のように、モデル世代が変わると指示文の効き方そのものが変わる場面があり、こうした変化はコードを見ているだけでは気づきにくいものです。デフォルトモデルが切り替わったタイミングで、コード側のmigrateと合わせてprompt-auditを走らせておくと、プロンプト側の棚卸し漏れを防げます。