2026年9月、Claude Codeのv2.1.283で/doctor prompt-auditが追加されました。CHANGELOGには次のように書いています。
Added
/doctor prompt-audit(also/checkup prompt-audit) to audit your CLAUDE.md files, skills, agents and commands for prompting patterns written for older models
（CLAUDE.md、Skills、エージェント、コマンドに、古いモデル向けに書かれたプロンプトのパターンが残っていないか監査する/doctor prompt-auditを追加）
古いモデル向けの書き方とは具体的に何なのかが気になったので、Opus 5.5の公式ドキュメント、Anthropicのブログ、prompt-auditの手順書の3つから、CLAUDE.mdやSkillsに関わるところを抜き出しました。それぞれを要約したうえで、新しいモデルでアンチパターンになる書き方をまとめ、最後に自分のリポジトリで試した結果を載せようと思います。
この記事でわかること
- Opus 5.5の公式ドキュメントとAnthropicのブログが、外すよう勧めている指示
-
/doctor prompt-auditがCLAUDE.mdやSkillsのどこを見ているか - 新しいモデルでCLAUDE.mdやSkillsに書かなくていいことと、書いておくこと
前提
- 2026年9月時点の情報です
- Claude Code v2.1.283、対象モデルはClaude Opus 5.5
Opus 5.5の公式ドキュメントは、考え方と検証の指示を外すよう書いている
見たのはPrompting Claude Opus 5.5、Prompting best practices、Opus 5.5の移行ガイドです。
前提として、Opus 5のプロンプトはそのままでもよく動くと書いています。
Existing Claude Opus 5 prompts should perform well without changes
（既存のClaude Opus 5のプロンプトは、変更なしでもよく動くはずです）
そのうえで、外すよう書いているのは次のような指示です。
- よく考えてから答えさせる指示：チャット用途のシステムプロンプトについて、考える量はモデルが自分で決め、effortが主な調整手段なので、外すことを検討するよう書いています。考える量を減らしたいときも、プロンプトより先にeffortを下げるほうが確実だと説明しています。
- 推論を回答に書き出させる指示：thinkingが常に有効なので不要で、推論の書き出しを求めると拒否されることもあります。
- 自己検証の指示：Opus 5は指示しなくても自分の作業をよく検証するので、以前のモデル向けの検証の指示は検証のしすぎを招くとしています。Opus 5.5はOpus 5のプロンプトの型を引き継いでいます。
- 進捗報告のリズムの指定：「3回ツールを呼ぶごとに進捗をまとめる」のような指示は外してみるよう勧めています。
- 強い言い方：Opus 4.5の頃から、ツールやSkillsが使われないように強めに書いていた指示は使われすぎを招くので、言い方を弱めるよう勧めています。
Where you might have said "CRITICAL: You MUST use this tool when...", you can use more normal prompting like "Use this tool when...".
（「重要：〜のときは必ずこのツールを使うこと」と書いていたところは、「〜のときはこのツールを使う」のような普通の書き方でよい）
※逆に、無人で長く走らせるエージェントが途中で止まる問題には、止まってほしくないパターンを書き足すことを勧めています。書かなくていいことばかりではありません。
Anthropicのブログは、6つのアンチパターンを挙げている
Anthropicのブログ（2026年9月8日）では、古いモデルの弱点を補うために足した指示が、新しいモデルではコストを増やすとして、次の6つを挙げています。
- 検証の儀式（「double-check your work（作業を見直して）」「verify twice before responding（答える前に2回確認して）」）
- 網羅性や強調のブースター（「Be maximally thorough（できる限り網羅的に）」「CRITICAL: YOU MUST ALWAYS…（重要：必ず常に〜すること）」）
- 固定の手順やスクラッチパッド（「think step by step in a scratchpad（作業メモに1ステップずつ考えを書いて）」）
- 古いモデルの失敗に合わせて作った、回答のお手本（few-shot例）。お手本に「〇〇を確認すると△△なので、結論はXXです」のような考える過程まで書いてあると、必要のない質問でも同じように過程を長く書くようになる
- 矛盾するルール
- 古い設定値（thinkingの予算など）
矛盾するルールについては、新しいモデルほど指示を文字どおりに守るので性能が落ちる、と書いています。対策として/claude-api prompt-auditを紹介していて、対象にはCLAUDE.mdやSkillsのようなClaude Code自身の設定も含まれるとしています。
Opus 4.8からOpus 5.5への移行を題材にした検証では、アンチパターンを取り除くとコストがさらに9%下がり、正答率が約2ポイント上がったそうです。※アンチパターンを1つずつ仕込んだカスタマーサポートの題材での数字です。
prompt-auditは「モデルがもともと知っていることか」で1行ずつ見る
/doctor prompt-auditの中身はclaude-apiスキルのprompt-auditサブコマンドで、手順書が公開されています。判定の軸は1つです。
For each instruction, ask one question: could the model already know this?
（指示ごとに1つだけ問う。モデルはもともとこれを知っているか？）
削る候補は次の2つです。
- 言わなくてもやること：「正確に」「網羅的に」「計画してから」のような指示
- 今のモデルではもう起きない失敗への対策：公式ドキュメントの節で見た、ツールやSkillsを使い渋る、作業を見直さない、途中経過をあまり報告しない、といった以前のモデルの失敗に向けた指示
逆に、読者やプロダクト、実行環境の前提情報、制約の理由のように、作者しか知らないことは残します。手順書では、こうした情報が足りないとモデルは無難な一般論で埋めてしまうので、多すぎるくらい渡してよいと書いています。
CLAUDE.mdやSkillsについて見ているのは、次の2つです。
| グループ | 見ているもの |
|---|---|
| 古い書き方 | 強調語、考え方の指示（「ステップごとに考えて」など）、手順の書きすぎ、過去のモデル向けの対策 |
| 設定ファイルの劣化 | 存在しないパスやコマンド、指示ファイル同士の矛盾 |
ほかに、ツールの説明文やAPIを呼ぶコードも見ます。矛盾については、v2.1.283で「古いパスやコマンド、矛盾する指示ファイルをレポートの先頭に出す」改善も入っています。出てくるのは確度付きのレポートと差分で、勝手には適用しません。矛盾は、どちらを残すかを人に聞く形で返ってきます。
手順書の最後には次のように書いています。
Prompts are per-model artifacts; a line that is load-bearing on one generation is cruft on the next.
（プロンプトはモデルごとの成果物で、ある世代では必要だった1行が、次の世代では不要物になる）
まとめると、新しいモデルでアンチパターンになる書き方はこの5つ
3つの出典を重ねると、CLAUDE.mdやSkillsで書かなくていいことは次のようになります。
| 書き方 | 例 | 代わりにすること |
|---|---|---|
| 強い念押し | 「重要：」「必ず〜すること」「絶対に〜しない」（CRITICAL、MUST、NEVER） | 普通の言い方で書き、なぜそうしてほしいかを1文添える |
| 考え方の指示 | 「よく考えて」「ステップごとに」「計画してから」 | 書かない。考える量はeffortで調整する |
| 検証の念押し | 「ダブルチェックして」 | 書かない。確かめ方（テストや基準）があるならそれを書く |
| 1つの作業の中身を分解した手順 | 「1. 要件を読む 2. 関連ファイルを探す 3. 影響範囲を考える…」 | 目的と制約と確かめ方を書く |
| 出力のリズムや長さの数値指定 | 「3回ごとに進捗を報告」「〇〇字以内」 | 書かない。必要なら「簡潔に」のような言い方にする。ただし「記事は2,000〜4,000字」のように、作るもの自体の決まりなら書く |
どれも、古いモデルが言うことを聞きにくかった頃の対策です。新しいモデルは指示に素直に従うので、同じ文が効きすぎたり、文字どおり二度やったりします。
手順を書くこと自体がだめなわけではありません。手順書でも、番号付きの手順は順番に意味があるところでは残すとしています。たとえば「実装方針を検討する→ブランチを切る→実装→指示者にレビューを仰ぐ→指摘を修正→コミット→テストコードを書く」のようなチームの進め方は、順番そのものが決め事でモデルには分からないので、書いておくものです。手順を間違えると壊れる操作（削除や認証まわり）も同じです。書かなくていいのは、1つの作業の中身を分解した手順のほうです。「1. 要件を読む 2. 関連ファイルを探す 3. 影響範囲を考える」は言われなくてもモデルがやることなので、上の進め方にある「実装方針を検討する」の1ステップで足ります。
残るのは、作者しか知らない文脈とその理由です。書かなくていいことが増えたぶん、書くべきことはそこに絞られてきていると思います。
ルール同士の矛盾は、モデルに関係なく避けるべきものです。ただ、ブログにある通り新しいモデルほど指示を文字どおりに守るので、矛盾があるとどちらに従うかがぶれやすく、影響は大きくなっています。
試しに自分のリポジトリにかけてみたら、多かったのは矛盾でした
実はこの記事も、技術記事を書くためにリポジトリとAIのルール（CLAUDE.mdとSkills）を整備して、Claudeと一緒に書いています。そのリポジトリと~/.claude配下にかけると、古い書き方の指摘は、2026年3月版の公式code-reviewコマンドを持ってきたファイルの3か所（CRITICALやIMPORTANTなど）だけでした。多かったのはルール同士の矛盾で、Claudeに1節を追記してもらったときに、同じことを言っていた古い行が残っていたものです。矛盾はprompt-auditも自動では直さないので、どちらに寄せるかを自分で決めて古い行を書き換えました。
まとめ
新しいモデルでは、強い念押しや、考え方・検証・手順を細かく指示することは書かなくてよくなってきています。そのぶん、CLAUDE.mdやSkillsには作者しか知らない文脈と理由を書き、ルール同士が矛盾していないかを見ることが大事だと思いました。
レビューの指摘をAIのルールに変える仕組みについては、今更聞けない、レビューの指摘をAIのルールに変える仕組みに書きました。
この記事はZennにも投稿しています。