はじめに
Claude Code に同梱の claude-api スキルには、/claude-api prompt-audit というサブコマンドがあります。
同梱ドキュメント（shared/prompt-audit.md）を読んで、要点を整理してみます。
/claude-api prompt-audit は、プロンプト・スキル・ツール説明から「古いモデル向けに書かれ、今のモデルでは逆効果になっている記述」を探し、根拠付きのレポートと修正案の diff を作るコマンドです。
1. なぜ必要なのか
プロンプトは、当時のモデルの弱点を補う指示が継ぎ足されて育ちます。
ところが今の Claude は指示をより忠実に、文字どおりに守るため、昔の大げさな指示が効きすぎてしまいます。
| 古い指示 | 今のモデルで起きること |
|---|---|
MUST / NEVER / CRITICAL の多用 |
過剰発火・融通が利かない |
| 細かすぎる手順書き | モデル自身の計画より質が落ちる |
| 「できれば〜」（本当は必須） | 省略してよい許可と読まれる |
「長いから悪い」わけではありません。
ドキュメントでは、目的は特定の古い指示を見つけることで、短くすることではないと明言されています。
2. 使い方と3つのルール
/claude-api prompt-audit
範囲を絞るなら「src/prompts/ のプロンプトを prompt-audit して」のように自然文で頼みます。
| ルール | 内容 |
|---|---|
| 非対話 | 範囲と対象モデルを質問せずに推定し、前提をレポート冒頭に書く |
| 勝手に適用しない | diff は提案のみで、取り込む部分は自分で選ぶ。 例外は「削除して」と明示的に頼んだときだけ（確度が低い所見は除く。確度は後述） |
| 途中で止まらない | 「続けますか？」と聞かず、レポートと diff の2つを最後まで出す |
3. 内部の流れ
「古い」かどうかはモデル次第なので、最初に基準のモデルを決めるのがポイントです。
中心の問い（③の判定）
4. 何が「古い」とされるのか
| グループ | 例 | なぜ問題か | 直し方 |
|---|---|---|---|
| 1. 古いプロンプト文 | 「CRITICAL: 必ず〜」の連発 | 今のモデルには効きすぎる | 普通の強さで、理由を添えて書く |
| 2. 古くなったスキルファイル | 古いバージョン番号やパス | 実態と食い違う | 今の事実に合わせる |
| 3. ツール説明 | 1行だけの説明 | 使いどころが伝わらない | 詳しく足す |
| 4. API の設定 | 新しいモデルではエラーになる設定値（例: 考える量をトークン数で指定する budget_tokens） |
そもそも動かない | 削除する |
特に分かりやすいのが、API の機能で置き換えられる昔の工夫です。
例えば「応答を必ず JSON で返させる」ために、以前は応答の先頭をこちらで { と書いておき、閉じ括弧が来たら止め、壊れていたらやり直すという力技を使っていました。今は API に JSON の形を指定するだけで済みます。
ツール説明は特に逆向きです。
性能を最も左右するのは詳しい説明で、よくある失敗は説明不足のほうです。
5. 何を「残す」のか
ドキュメントは「削除」だけを言う監査を避けるため、残すべきものの基準も明示しています。
主なものは次のとおりです。
- 文脈（対象読者・製品・環境・品質基準・理由）
- 壊れやすい操作の厳密な手順（破壊的コマンド、認証、コンプライアンス）
- ツールの仕様の詳細（むしろ増えることが多い）
- 今のモデルでも起きる失敗への禁止
- 食い違っていない重複（整理の好みの問題にすぎない）
| 確度 | 基準 | diff に入るか |
|---|---|---|
| High | 公式ドキュメントに記載、または対象モデルでエラー | ✅ |
| Medium | 広く観察されている挙動 | ✅ |
| Low | 言い回しからの推測 | ❌ レポートのみ |
何も見つからなければ、何も変えない。
「作り出した diff より、空の diff のほうが良い」とドキュメントは明言しています。
6. 実際に使ってみた
自作スキル27個のリポジトリで実行しました。
- 所見は 11件（High 2・Medium 5・Low 4）
- 「必ず承認を得る」のような強調は、戻せない操作のゲートで理由もあるため残す判定
- 中心は、古いモデル向けの書き方ではなく、実態と合わなくなった数値と、記述の食い違い
例えば、次のような所見です。
| スキル | 元の行 | 何が問題か | 直し方 |
|---|---|---|---|
| 紹介動画を作るスキル | 「尺は2〜3分に収める」「6〜10枚」 | 尺は 60秒〜6分からユーザーが選ぶ仕様なのに、本文に2〜3分の値が固定で残っていた。長い尺を選んでも2〜3分の分量で作られてしまう | 「1で選んだ尺に収める」「枚数は尺の表に従う」 |
| リリースノートを要約するスキル | 「このフォーマット・粒度を厳守する」 | 例が1つしかないと、個数や長さまで写される。「注目ポイントは1〜5個で可変」という別の指示と逆向きに働く | 揃えるもの（見出し・表の列）と、揃えないもの（注目ポイントの数と長さ）を分けて書く |
監査結果にも誤りが1件ありました。
紹介動画スキルの「テーマを推測で決める」「既定のまま出す」という2つの注意書きを、1つにまとめる提案です。
2つは似ているだけで食い違ってはいないので、上の「何を『残す』のか」で挙げた「食い違っていない重複は残す」に照らすと対象外でした。
AI の監査結果も、ドキュメントの基準で読み直すのが大切です。
7. 複数のモデルを使い分けているとき
Opus 5.5 と Sonnet 5 のように、複数のモデルで同じプロンプトやスキルを使うこともあると思います。
ドキュメントに書かれていること
- 「古い」かどうかは基準のモデルで決まる。 ある世代で必要だった指示が、次の世代では不要になる
- 基準のモデルは依頼文で指定できる。 依頼文にモデル名があれば、それが最優先になる
- 消すかどうかは仮説。 取り込む前後で、実際の挙動を比べて確かめる
- API の設定の中には、モデルによってエラーになるものがある。 例えば、考える処理（thinking）を止める設定や、特定のツールの呼び出しを強制する設定は、Opus 5.5 ではエラーになり、Sonnet 5 では動く
複数のモデルを使い分ける場合について、ドキュメントに直接の記載はありません。
ドキュメントにない部分（考察）
ここからは、上の「基準のモデルで決まる」という考え方から整理したものです。
ある 1 つのモデルを基準にした指摘をそのまま取り込むと、別のモデルでは困ることがありそうです。
ただし、困り方は指摘の種類によって違うと考えています。
| 指摘の種類 | 例 | 扱い方（考察） |
|---|---|---|
| API の設定 | thinking を止める設定、ツールの呼び出しを強制する設定 | 使うモデルのどれか1つでもエラーになるなら直す。基準を別のモデルにすると、この指摘自体が出てこない |
| どのモデルでも間違い | 数字が実態と合わない、記述が食い違う | そのまま直す |
| 特定のモデル向けの文言 | thinking を止めたときの対策として書いた指示（「ツールを使う前に一言添える」など） | 使う各モデルで動かして確かめる |
最後の行の例は、ドキュメントでは Opus 5 で thinking を止めたとき向けの対策とされ、Opus 5.5 では不要になりうると書かれています。
Sonnet 5 を thinking を止めて使うなら、まだ意味が残るかもしれません。
まとめ
| 観点 | ポイント |
|---|---|
| 何をするか | 古くなった指示を見つけ、レポートと diff を作る |
| しないこと | 短くすること自体は目的にしない。勝手に適用しない |
| 判断の軸 | 「モデルはすでにそれを知っているか？」 |
| 使いどころ | 使うモデルを新しいものに切り替えるとき、新モデルのリリース時 |
| 複数のモデルを使うとき | ドキュメントに記載なし。API の設定はどのモデルでもエラーにならない形に、文言はモデルごとに確かめるのがよいと考えている |
プロンプトはモデルごとの成果物です。
新しいモデルが出たら、一度走らせてみると、古いモデル向けの残骸を見つけられるかもしれませんね。