hdknr blog
戻る

/claude-api prompt-audit とは — 古いモデル向けに書いたプロンプトと CLAUDE.md を棚卸しするコマンド

はじめに

X で「Anthropic のエンジニアが Opus 5.5 向けの最高のトリックを公開した」という投稿が流れてきました。中身は Claude Code で次の 1 行を打つだけ、というものです。

/claude-api prompt-audit

投稿では「スキル・CLAUDE.md・プロンプトを監査し、モデルの足を引っ張るものを全部消し、公式の Opus 5.5 ガイドで書き直す。5 分で終わる」と紹介されていました。

元ネタは Anthropic の Lance Martin 氏の投稿です。ただ、「全部消す」「書き直す」という部分は、コマンドの実際の挙動とはだいぶ違います。結論から言うと、このコマンドが出すのは file:line 付きの監査レポートと提案 diff で、同意なしにファイルを書き換えることはありません。

この記事では、公開されているスキル本体と公式ブログを読み、このコマンドが何をして、何をしないのかを整理します。

出どころと経緯

Claude Code の CHANGELOG では、次の 2 つのバージョンが関係します。

スキル本体はオープンソースで、anthropics/skills の skills/claude-api にあります。手順を定義しているのは shared/prompt-audit.md です。

なぜ「古いプロンプト」が問題になるのか

prompt-audit.md の冒頭には、問題意識がはっきり書かれています。プロンプトやスキルには、古いモデルの弱点を補うための指示が溜まっていきます。たとえば、ツールをなかなか呼ばなかったモデル向けの強調や、計画が苦手だったモデル向けの手順書です。

現行の Claude はそうした指示を、当時のモデルより忠実に、文字どおりに守ります。そのため古い指示は、トークンを無駄にするだけでなく、挙動を積極的に悪くします。必要以上にツールを呼ぶ、必要以上に計画を立てる、判断の余地がある場面でルールを杓子定規に当てはめる、といった具合です。

このファイルは監査の目的を「プロンプトを短くすること」ではなく、「もう合わなくなった具体的な指示を見つけること」と定めています。「合わない」かどうかの基準は、対象モデル、プロジェクトの現状、他の指示ファイルとの整合の 3 つです。

prompt-audit が検出する古いプロンプトのパターン

Martin 氏が挙げた 6 つのアンチパターン

例の列は、9 月 2 日の投稿に書かれている例をそのまま訳したものです。

パターン例何が起きるか
検証の儀式「作業をダブルチェックせよ」「回答前に 2 回確認せよ」文字どおり実行され、作業が重複してトークンを浪費する
徹底・強調ブースター「最大限徹底的に」「CRITICAL: YOU MUST ALWAYS…」冗長な出力や余計なツール呼び出しにつながる
必須手順とスクラッチパッド「スクラッチパッドで段階的に考えよ」モデル組み込みの thinking に定型の思考手順が重なり、トークンを余計に使う
古い few-shot 例旧モデルの失敗に合わせて調整した例不要な場面でも、長い推論を真似させてしまう
矛盾したルール「ポリシー内なら必ず返金」と「エスカレーションなしで返金するな」両方を文字どおり守ろうとして性能が落ちる
古い設定手動の thinking 予算など新しいモデルでは API がリクエストを拒否することがある

スキル本体の 4 グループ

スキル本体は、これより広い範囲を 4 つのグループに整理して走査します。上の 6 パターンのうち、古い設定は Group 4 に、それ以外はおおむね Group 1 に入ります。

CLAUDE.md やスキルしかない設定リポジトリなら、指摘はほぼ Group 1 と 2 に集まります。スキル側も「指摘が 1 グループに偏るのは普通の結果」と明記しています。

「全部消す」わけではない

紹介投稿の「足を引っ張るものを全部消す」は、スキルの設計思想とは正反対です。prompt-audit.md は、むしろ消しすぎを最大のリスクとして扱っています。

成果物は「レポート」と「提案 diff」

監査が出すのは次の 2 つです。

  1. 指摘ごとに場所（file:line）、該当パターン、古くなった理由、確信度を書いた監査レポート
  2. 確信度が高・中の指摘だけを対象にした、提案としての diff

ファイルへの適用は、ユーザーの同意があるまで行いません。スキルには「同意なしに編集を適用しない」と書かれています。適用されるのは、「clean it up」のように依頼文が適用を明示的に求めた場合だけです。その場合でも、確信度の低い指摘や、ファイル間の矛盾の解消などは適用対象から外れます。

「キープリスト」がある

スキルには「フラグを立てない」ものの一覧があり、パターン表と同じ拘束力を持つとされています。主なものは次のとおりです。

さらに「何も見つからなかった監査は何も変えるべきでない」とも書かれています。空の diff は、無理に作った diff より良い、という立場です。

「公式ガイドで書き直す」でもない

対象モデルは監査の最初に決まります。依頼文でモデルを指定すれば、そのモデルが基準です。指定がない場合、CLAUDE.md などの Claude Code の設定ファイルは、監査を実行しているモデルが基準になります。API を呼ぶアプリケーションのプロンプトは、リポジトリが記録している移行先や、コードが指している最新モデルなどから決まります。

つまり Opus 5.5 で走らせれば、設定ファイルは Opus 5.5 基準で監査されます。「Opus 5.5 向けのトリック」というのはこの意味です。ただし、やることは指摘と提案です。ガイドに沿ってプロンプトを丸ごと書き直すわけではありません。

公式ベンチマーク：Opus 5.5 でのコストと正答率の変化

公式ブログでは、カスタマーサポート用のベンチマークで効果を測っています（Martin 氏の投稿では社内ベンチマークと説明されています）。

まず、きれいなプロンプトにアンチパターンを 1 つずつ仕込んだ 6 本の「レガシープロンプト」を用意しました。仕込んだのは、廃止された thinking 設定、矛盾した返金ルール、手動スクラッチパッド、「2 回確認せよ」、「最大限徹底的に」、必須の 6 段階手順です。これを 3 つの条件で比べています（数値は 6 本の平均）。

条件コスト正答率
Opus 4.8基準基準
Opus 5.5（モデル ID のみ差し替え）約 18% 減（記載なし）
Opus 5.5 + 各プロンプトに prompt-audit を 1 回さらに約 9% 減約 2 ポイント向上

個別の失敗例も具体的です。

いずれも、アンチパターンを意図的に仕込んだプロンプトでの数字です。自分のプロンプトで同じ改善幅が出るとは限りません。

prompt-audit の使い方と監査の対象範囲

Claude Code の中で実行します。

/claude-api prompt-audit

依頼文でファイルやディレクトリを指定すれば、そこが対象になります。指定しなければ、作業ディレクトリ内でプロンプトとして読まれるファイル全般が対象です。主に次のものが含まれます。

~/.claude/ のような作業ディレクトリ外のファイルは、依頼で名指ししない限り対象外です。また、.claude/settings*.json、.mcp.json、認証情報ファイルは、秘密情報を含みうるため読まないと明記されています。

監査は非対話で進むよう設計されていて、途中で確認を求めません。スコープと対象モデルの前提はレポートの冒頭に書かれます。前提が違っていれば、範囲を絞って再実行します。

/doctor prompt-audit との違い

v2.1.283 で追加された /doctor prompt-audit（別名 /checkup prompt-audit）は、CHANGELOG の説明では CLAUDE.md・スキル・エージェント・コマンドが対象です。Claude Code の設定だけを見たいときはこちらが手軽です。API を呼ぶアプリケーションのコードまで含めて見たいときは /claude-api prompt-audit を使います。

結果の受け止め方

スキル自身が最後のステップで、削除は結論ではなく仮説だと強調しています。

このブログのリポジトリで実際に走らせた結果

この記事を書いている hdknr/blogs で、Claude Code（v2.1.294 同梱のスキル）から /claude-api prompt-audit を実際に実行しました。依頼文には何も足していないので、スコープは作業ディレクトリ全体、対象モデルは実行中の Opus 5.5 です。

監査の対象になったもの

.claude/settings*.json は読まれていません。~/.claude/CLAUDE.md のようなユーザーレベルの設定も、名指ししていないので対象外でした。

監査そのものは何も変更しなかった

先に結論を書くと、ファイルは 1 つも変更されていません。依頼文が適用を求めていないので、出てきたのはレポートと提案 diff だけです。

見つかったもの: 移行の「消し残し」

指摘は 13 件で、確信度の内訳は High 6 件、Medium 6 件、Low 1 件でした。グループで見ると 13 件すべてが Group 2（スキル・設定ファイルの脆さ）のパターンです。そのうち blog-batch.sh の 1 件は Group 4（リクエスト設定）にも当たり、Low の 1 件は diff を伴わない flag です。Group 1 の古いプロンプト文は 0 件で、Group 3 はツール定義がないので対象外でした。

13 件中 10 件は、2 つの移行の後に取り残された記述です。

  1. Hugo から Astro への移行（2026 年 8 月）
    • /blog スキルのビルド確認が、まだ hugo --source ... --gc を指示していた。一方で CLAUDE.md は「Hugo はもう CI でビルドしない。astro build の後にアセット検査まで行う」と定めていて、正面から矛盾していた
    • /wiki-ingest スキルの hugo --gc、CLAUDE.md の「wiki は layouts/wiki/ のレイアウトを使う」（実際に配信しているのは Astro のルート）も同じ種類
    • サブエージェント 3 本の「Hugo ブログ記事」、slug や画像パスのルールの理由として書かれた「Hugo が〜するから」もこの仲間。ルール自体は正しく、理由だけが古くなっていた
  2. Wiki ingest を /blog から /ship に移したとき（2026 年 7 月）
    • /blog スキルの末尾に、移す前の手順の断片が宙に浮いて残っていた。直前の段落には「/blog は Wiki ingest を行わない」と書いてある
    • blog-batch.sh は、バッチの毎回の実行に「重要: SKILL.md の ‘Post-merge follow-up’ ステップ 3 は実行しないでください」と注入していた。しかし、そのセクションはもう存在しない

どちらも git blame で、古い側の行が移行コミットより前に書かれたことを確かめたうえで、新しい側に合わせる書き換えが提案されています。ほかに、サブエージェント tech-writer の説明文が「技術的正確性の観点で」と書きながら本文では「正誤判断はしない」と書いている矛盾や、CLAUDE.md のエージェント一覧から test-strategist が抜けていることも指摘されました。

残されたもの

MUST や「No exceptions.」のような強い言い回しは、1 件も削除候補になりませんでした。いずれも直後に「&& で連結すると許可パターンに一致しない」のような理由が付いた制約で、キープリストの「制約とその理由は残す」に当たると判断されています。

CLAUDE.md に書いてある「Hugo のショートコードが生のまま表示された記事が 19 本あった」「インデックスが 13MB から 29MB に倍増した」といった経緯の数字は、Group 2 の「経緯の記述」の形をしています。ただ、ルールの根拠を担っているので、Low の flag として報告されるにとどまりました。

提案 diff を適用した

レポートを読んだうえで、flag の 1 件を除く 12 件の提案を、そのまま別の PR（#723）で適用しました。差分は 8 ファイルで、追加 20 行・削除 39 行です。削除のほうが多いのは、取り残された手順の断片と、存在しないセクションへの禁止プロンプトを消したためです。

振る舞いが変わるのは blog-batch.sh だけで、claude -p に渡すプロンプトから 1 段落が消えます。もともと存在しない手順を禁じていた段落なので、実行される手順は変わらないはずです。それでも、スキルの Step 7 が言うとおり削除は仮説なので、次のバッチを --limit 1 で 1 件流して確かめるつもりです。

紹介投稿のイメージとは違い、実際の監査は強調表現を削るより、事実が古くなった箇所を指摘するほうが中心でした。設定ファイルばかりのリポジトリでは、こちらのほうが効き目が大きいように思います。

まとめ

参考

前の記事
ZINE を1部から作る — 少部数に対応したネット印刷サービス4選と選び方
次の記事
要求仕様書作成ループ — コーディングエージェントの開発ハーネスの手前に「要求確定」と「仕様レビュー」のループを置く