ai-docs

モデル世代をまたぐ移行 — 何を剥がすか

モデル世代をまたぐ移行 — 何を剥がすか — 結局どうすればいいか

18本を統合する。移行の失敗は「足りない」ではなく「余計なものが残っている」で起きる、というのが横断して見えた最大の発見。

1. 基本方針: 足すより剥がす

4つのモデル別ガイドが独立に同じことを言っている。

最新モデルでは「足す prompting」より 旧世代向けに書いた過剰な指示を剥がす prompting のほうが重要 — claude-prompting-best-practices

If your prompt contains explicit verification instructions (“include a final verification step for any non-trivial task,” “use a subagent to verify”), remove them: instructions like these cause over-verification on Claude Opus 5, and removing them reduces wasted tokens with no loss in quality. — prompting-claude-opus-5

プロンプトに明示的な検証指示（「非自明なタスクには最後に検証ステップを入れよ」「subagent に検証させよ」）が含まれているなら、それを削れ。この種の指示は Claude Opus 5 で過剰な検証を引き起こし、削除すると品質を落とさずに無駄なトークンを減らせる。

Skills developed for prior models are often too prescriptive for Claude Fable 5 and can degrade output quality. — prompting-claude-fable-5

以前のモデル向けに作った skill は、Claude Fable 5 には指示が細かすぎることが多く、出力品質を下げうる。

If you’ve added scaffolding to force interim status messages (“After every 3 tool calls, summarize progress”), try removing it. — prompting-claude-sonnet-5

途中経過のメッセージを強制する scaffolding（「ツール呼び出し3回ごとに進捗を要約せよ」など）を足しているなら、外してみよ。

共通する構造: 旧モデルの限界を回避するために書いた補助輪が、新モデルではそのままコストと害になる。

2. 剥がすべきものの一覧

旧世代で書いていたもの最新モデルでの害出所
CRITICAL: You MUST use this tool when...過剰発火。Use this tool when... に戻すclaude-prompting-best-practices
If in doubt, use [tool]過剰発火同上
Default to using [tool]包括的すぎる。「理解が深まるときに使え」に絞る同上
「最後に検証ステップを入れよ」Opus 5 は指示なしで自己検証する。書き換えではなく削除prompting-claude-opus-5
「ダブルチェックせよ」「返答前に再検証せよ」同上。コストだけ増えて結果は良くならない同上
「3ツール呼び出しごとに進捗を要約せよ」自分で質の高い更新を出すので不要prompting-claude-sonnet-5 / -opus-4-8
「もっと徹底的に」（anti-laziness）過剰発火claude-prompting-best-practices
「思考を見せろ」「推論を説明しろ」Fable 5.1 / Fable 5 / Opus 5.5 / Opus 5 / Sonnet 5.5 で reasoning_extraction 拒否を誘発しうる（Fable 5 では、サーバ側フォールバックはこれを再試行せず、拒否がそのまま返る）。代わりに答えの短い説明か行動の要約を求め、推論は thinking ブロックで読むthinking / prompting-claude-fable-5 / prompting-claude-opus-5
「重大な問題だけ報告せよ」（コードレビュー）忠実に守るので recall が落ちて見える-sonnet-5 / -opus-4-8
単一ファイルのリファクタに限定するルール限界が消えたので不要large-codebases

3. 向きが反転するもの（最も危険）

同じ指示が逆効果になる。 これは1つの文書を読んでいては絶対に見えない。

subagent の傾向必要な prompt
Opus 4.8少なく起こす（推論をツール呼び出しより好む）「こういう場面では委譲せよ」と促す
Opus 5 / Fable 5多く起こす「小さい仕事は自分でやれ」と抑える

Opus 4.8 で必要だったプロンプト:

Do not spawn a subagent for work you can complete directly in a single response.
Spawn multiple subagents in the same turn when fanning out across items or reading multiple files.

Opus 5 で必要なプロンプト（逆向き）:

Delegate to a subagent only for large tasks that are genuinely independent and parallelizable.
Do not delegate work you can finish yourself in a handful of tool calls, and do not use subagents
to verify or double-check your own work. If one subagent can complete the task, use one rather
than several, and keep spawn counts low.

→ 移行時に prompt の向きを反転させる必要がある。そのまま持ち越すと悪化する。

4. API パラメータの破壊的変更

プロンプトより先に、これで落ちる。

世代変更
Claude 4.6 以降prefill が 400 エラー（最後の assistant ターンへの prefill）
Claude 4.7 以降budget_tokens が 400 エラー
Sonnet 5adaptive thinking が既定オン / temperature top_p top_k が 400 / manual extended thinking 削除 / 新トークナイザ
Opus 5thinking 既定オン。xhigh / max では thinking を切れない（400）
Opus 5.5thinking 常時オン（disabled はどの effort でも 400）/ 強制ツール使用（tool_choice の any / tool）が 400 / effort の既定が medium / 会話の前方を変えると過去の thinking が 400（append-only にする）/ Claude API と Google Cloud では computer use が computer_toolset_20260801 のみ（旧 computer_20251124 はエラー） — thinking / effort / thinking-troubleshooting / computer-use-tool
Sonnet 5.5thinking 既定オン。disabled は 400、事前の thinking を切るのは between_tools（effort high 以下のみ）/ 強制ツール使用が 400 / Opus 5.5 と同じ prefix 検査 / API での effort の既定は high（Claude Code では medium）。Sonnet 5 の設定を持ち越さず effort sweep をやり直す / Sonnet 5.5 の thinking ブロックを読める他のモデルは Claude API と Google Cloud 上の Opus 5.5 だけ（そこで Opus 5.5 へ上げる切り替え以外では推論が失われる。building-with-claude-sonnet-5-5 は「他のモデルは読まない」と書いており、食い違いは OVERVIEW §5） — thinking / effort / thinking-troubleshooting / model-config
Fable 5.1 / Mythos 5.1thinking 常時オン（disabled は 400）/ 強制ツール使用が 400（auto + strict tool use か structured outputs へ）/ Fable 5.1 は Opus 5.5 と同じ prefix 検査 — thinking / thinking-troubleshooting
Fable 5 / Mythos 5thinking 常時オン。要約のみ。refusal stop reason

prefill の移行先

旧用途移行先
出力形式の強制（JSON/YAML、分類）Structured Outputs、または enum を持つ tool
前置きの除去system prompt で直接指示。漏れたら後処理
不当な拒否の回避不要。user メッセージ内の明確な prompting で足りる
継続user メッセージに移し、中断した末尾テキストを含める
context の再注入user ターンに入れる、または tool / compaction 時に

トークナイザの変更（見落とされやすい）

Because Claude Sonnet 5 uses a new tokenizer that produces approximately 30% more tokens for the same text, max_tokens limits tuned for Claude Sonnet 4.6 may truncate equivalent output.

Claude Sonnet 5 は同じテキストに対しておよそ30%多いトークンを生成する新しい tokenizer を使うため、Claude Sonnet 4.6 向けに調整した max_tokens では同等の出力が途中で切られる可能性がある。

→ Sonnet 4.6 から移行するなら max_tokens を見直す。

どのモデルが何を蹴るかの正典

上の表は移行で実際に落ちた順に並べたものだが、モデルと thinking.type の対応表そのものは thinking-troubleshooting にある。「蹴る」と書かれていない値は受け付けるという読み方まで原典が定義しているので、移行前の確認はここで足りる。

The table lists what each model supports, what it defaults to, and which thinking.type values it rejects with a 400 error; any value not listed as rejected is accepted. — thinking-troubleshooting

表は、各モデルが何をサポートし、既定が何で、どの thinking.type を 400 で蹴るかを並べている。蹴ると書かれていない値は受け付けられる。

移行の観点で効くのは非推奨と削除の間に1世代あること。

Extended thinking (thinking.type: "enabled" with budget_tokens) is deprecated on the Claude 4.6 models (requests using it still succeed). Claude 4.7 and later models do not support it and reject requests that use it, returning a 400 error. — thinking-troubleshooting

extended thinking（budget_tokens を伴う thinking.type: "enabled"）は Claude 4.6 では非推奨（使ったリクエストは今も通る）。Claude 4.7 以降はサポートせず、使ったリクエストを 400 で蹴る。

4.6 で「動いているから大丈夫」は 4.7 で通らない。 逆向きの移行（4.5 以前へ戻す）でも同じ形で落ちる。Opus 4.5 / Haiku 4.5 / Sonnet 4.5 は "adaptive" の方を 400 で蹴る。

Sonnet 5.5 への移行

5つの設定が 400 を返す —— thinking budget、temperature / top_p / top_k の既定以外、assistant の prefill、強制ツール使用（tool_choice の any / tool）、thinking: {"type": "disabled"}（sonnet-5-5-migration-guide）。強制ツール使用は auto と strict: true に（Bedrock では structured outputs が使えないので auto だけ）、事前の thinking を切るのは between_tools（high 以下）。この5つは基本のリクエストから外す設定で、破壊的変更のすべてではない —— computer use は Claude API と Google Cloud で computer_toolset_20260801 だけ（computer_20251124 は 400、toolset と一緒の fine-grained-tool-streaming-2025-05-14 ヘッダも 400）、advisor の相手は Opus 5 / Opus 5.5 / Sonnet 5.5 / Fable / Mythos だけ（Opus 4.8 などは 400）。thinking ブロックは会話とアカウントに結びつき、一定の日以降に作ったアカウントでは前の履歴を編集して送り返すと 400 になるので、会話は追記だけに保つ。

prompt は Sonnet 5 のものがそのまま動くが、effort は較正し直されたので sweep をやり直す（prompting-claude-sonnet-5-5）。低い effort では途中で確認しに来たり検証を飛ばしたりし、高い effort では頼んでいない追加や自前のレビューに走る —— どちらも system prompt の一文で寄せられる。Sonnet 5 の回避策（拒否の誘導、ツール呼び出しの再試行の shim、「do not be lazy」）は外してから eval を回す（building-with-claude-sonnet-5-5）。

Sonnet 5.5 か Opus 5.5 か —— 明確な仕様と結果を確かめる手段があるなら Sonnet 5.5、慎重な判断が要る複雑な作業と長時間の作業は Opus 5.5（building-with-claude-sonnet-5-5）。Opus 5.5 は返答の前に必ず考えるので、「think carefully」の行は消す（getting-the-most-out-of-opus-5-5）。

5. effort と thinking の整理

混同が最も多い2つ。別の軸である。

何を制御するか
thinkingthinking ブロックで考えるかどうか
effort応答全体（テキスト + ツール呼び出し + thinking）にどれだけ労力を割くか

adaptive を effort の値として渡してはいけない（thinking のモードであって effort のレベルではない）。

世代をまたぐと「既定」が動く

モデルを替えると effort の既定も変わりうる。 Claude Code の既定は high だが、 Opus 5.5 と Sonnet 5.5 は medium、Opus 4.7 は xhigh。しかも目盛りそのものがモデルごとに 較正されているので、同じレベル名を移しても同じ実体にはならない。

The effort scale is calibrated per model, so the same level name does not represent the same underlying value across models.

effort の目盛りはモデルごとに較正されているので、同じレベル名がモデル間で同じ実体を表すわけではない。 — model-config

Opus 5 → Opus 5.5 では、原典がレベルの持ち越しをはっきり止めている。

In Anthropic’s testing, Opus 5.5 at medium matches or exceeds Opus 5 at high on coding and knowledge-work evaluations. At a given level, Opus 5.5 tends to think more per turn than Opus 5. When you move from Opus 5 to Opus 5.5, start at medium rather than carrying over the level you used on Opus 5.

Anthropic の試験では、Opus 5.5 の medium は、コーディングと知識労働の評価で Opus 5 の high に並ぶか上回る。 同じレベルなら、Opus 5.5 は Opus 5 より1ターンあたり多く考える傾向がある。Opus 5 から Opus 5.5 に移るときは、Opus 5 で使っていたレベルを持ち越さず medium から始めよ。 — model-config

default の解決先は版でも動く。 v2.1.280 で Opus 5 から Opus 5.5 に上がり、 それまで Sonnet 5 だった Pro / Team Standard も Opus 5.5 になった（Microsoft Foundry は Sonnet 4.5 のまま）。default を設定に書いたままにしていると、版を上げただけで、 何も変えていないのにモデルが変わる。v2.1.280 以降はプランを替えても default は変わらず、 変えるのはプロバイダ（Foundry）・組織の既定モデル・ANTHROPIC_DEFAULT_MODEL・ANTHROPIC_DEFAULT_OPUS_MODEL・ Default の allowlist 強制・Enterprise でアカウントに記録された既定モデル・deniedModels / availableModelsMatch による版の遮断（model-config）。sonnet も同じで、Anthropic API では v2.1.284 で Sonnet 5.5 に上がった（opusplan の実行フェーズも sonnet）。

Opus 5.5 には、乗り換え時に見落としやすい差が2つある。 ひとつは user settings のトップレベル effortLevel を見ないこと —— 古い形式のキーなので、 Opus 5 やそれ以前には効き続けるのに、Opus 5.5 と、それ以降に出るモデルは 自分の既定（Opus 5.5 なら medium）で始まる。 もうひとつは thinking を切れないこと（MAX_THINKING_TOKENS=0 も効かない。Claude Code では Sonnet 5.5 も同じ）。

⚠️ ultrathink 以外はキーワードではない。 「think hard」「think more」は ただのプロンプト本文として通る（model-config）。世代を移るときに 「呪文が効かなくなった」と誤診しやすい箇所。

費用を縛るもの

You don’t set a thinking token budget. Two controls bound cost:

thinking のトークン予算を自分で設定するのではない。コストを縛るのは次の2つの制御である。

制御性質
max_tokens厳密な上限。thinking + 応答テキストの合計。Claude はこれを超えない
effortソフトな指針。トークン数を保証しない

stop_reason: "max_tokens" が出たときの分岐:

  • その推論が必要だった → max_tokens を上げる
  • 考えすぎだった → effort を下げる

effort レベルの意味

各レベルで thinking がどう振る舞うかは thinking-steering-and-cost の表を見る（ここに写すと原典が変わるたびに2か所を直すことになるので写さない）。移行で効く要点は2つ —— Opus 5.5 の既定は medium、たいていのモデルは high、そしてどのレベルも毎リクエストの思考を保証しない（ツール結果を処理するだけの後続リクエストは xhigh / max でも思考を飛ばしうる）。

モデル別の出発点

モデル出発点
Opus 5.5既定は medium（Opus 5 から替えると、effort を省いたリクエストは1段低く走る）。thinking は常にオンで切れない。持ち越さず eval で sweep する — effort
Opus 5high（既定）から。 要求の厳しいコーディング / agentic で xhigh。品質が保てるなら low / medium を積極的に
Opus 4.8 / 4.7xhigh から（コーディング / agentic）。他は high を最低線に
Sonnet 5high（既定）。最難のタスクで xhigh
Sonnet 4.6medium を推奨既定に。 既定は high なので明示的に設定する（予期しないレイテンシを避ける）
Fable 5high（既定）。低い設定でも旧モデルの xhigh を上回ることが多い

移行時の対応関係（Sonnet の例）:

  • Sonnet 5 の medium ≒ Sonnet 4.6 の high
  • Sonnet 5 の high ≒ Sonnet 4.6 の max

When benchmarking, match by observed thinking length rather than effort name.

ベンチマークを取るときは、effort の名前ではなく、実測した thinking の長さで揃えよ。

そして最も重要な指示:

If you carried effort settings over from an earlier model, run a fresh effort sweep on your evals rather than reusing them.

以前のモデルから effort 設定を引き継いだ場合は、そのまま使い回さず、自分の eval で effort を振り直して測れ。

effort を厳密に守るようになった

Opus 4.7 以降の性質。

Claude Opus 4.7 also respects effort levels more strictly than Claude Opus 4.6. At lower effort levels, the model scopes its work to what was asked rather than doing more than requested.

Claude Opus 4.7 は Claude Opus 4.6 より effort レベルを厳密に尊重する。低い effort では、モデルは求められた以上のことをせず、依頼された範囲に作業を限定する。

If you observe shallow reasoning on complex problems, raise effort rather than prompting around it.

複雑な問題で推論が浅いと感じたら、プロンプトで回避しようとせず、effort を上げよ。

プロンプトで回避しない。 どうしても低く保つなら:

This task involves multistep reasoning. Think carefully before responding.

キャッシュとの相互作用

effort と thinking の設定はプロンプトにレンダリングされる。

Changing any of them starts a new cache prefix.

いずれかを変更すると、新しい cache prefix が始まる（＝それ以降のキャッシュが効かなくなる）。

運用ルール:

  • 会話ごとに thinking 設定と effort を固定する（per-message effort に対応したモデルなら、role: "system" メッセージで運ぶ effort 変更は接頭辞を壊さない）
  • ターン単位の調整は per-message prompting で（最新の user メッセージへの追記は前方の breakpoint を壊さない）
  • 既定値を明示的に設定するのは省略と等価（キャッシュを壊さない）

6. 世代共通で残る調整点

モデルが変わっても、次の3つは毎回チューニングが要る。

① 応答の長さ

タスクの複雑さに応じて長さを較正するようになったので、固定の冗長さを期待していた製品はずれる。

Opus 5 は特殊:

The effort parameter controls how much the model thinks rather than how much it says: lowering effort can reduce thinking volume without reliably shortening the visible response.

effort パラメータが制御するのは、モデルがどれだけ話すかではなくどれだけ考えるかである。effort を下げれば thinking の量は減りうるが、目に見える応答が確実に短くなるわけではない。

→ 応答長は prompt で明示的に指定するしかない。

効く書き方:

Positive examples showing how Claude can communicate with the appropriate level of concision tend to be more effective than negative examples.

適切な簡潔さで伝える方法を示す肯定的な例のほうが、否定的な例より効果的な傾向がある。

② より字義通りの指示追従

It does not silently generalize an instruction from one item to another, and it does not infer requests you didn’t make.

モデルはある項目への指示を、黙って別の項目へ一般化することはないし、していない依頼を推測することもない。

利点は精度（構造化抽出、予測可能なパイプライン）。対処は「スコープを明示する」:

Apply this formatting to every section, not just the first one.

この性質が生む最大の落とし穴がコードレビュー harness:

When a review prompt says “only report high-severity issues,” “be conservative,” or “don’t nitpick,” the model may follow that instruction more faithfully than earlier models did: it may investigate the code just as thoroughly, identify the bugs, and then not report findings it judges to be below your stated bar.

レビュー用のプロンプトに「重大な問題だけ報告せよ」「保守的に」「細かい指摘はするな」と書くと、モデルは以前のモデルより忠実にその指示に従う可能性がある。コードは同じだけ丹念に調べ、バグも特定したうえで、指定した基準に達しないと判断した指摘を報告しないことがある。

→ precision は上がるが recall が落ちて見える。能力の後退ではない。

直し方は「発見段階の目的はカバレッジ」と明示し、フィルタを別段階に移す:

Report every issue you find, including ones you are uncertain about or consider low-severity.
Do not filter for importance or confidence at this stage - a separate verification step will do that.
Your goal here is coverage. For each finding, include your confidence level and an estimated severity.

③ デザインの既定

開放的なブリーフで一貫した既定スタイルに落ち着く。 Opus 4.8 は具体的に記述されている（クリーム色の背景 ~#F4F1EA、セリフ体、テラコッタのアクセント）。

Generic instructions (“don’t use cream,” “make it clean and minimal”) tend to shift the model to a different fixed palette rather than producing variety.

漠然とした指示（「クリーム色は使うな」「清潔でミニマルに」）は、多様性を生むのではなく、モデルを別の固定パレットへ移すだけになりがちである。

効くのは2つだけ:

  1. 具体的な代替を指定する（色コード、書体、角丸の px まで）
  2. 作る前に選択肢を提案させる — temperature が使えない Sonnet 5 ではこれが推奨手段
Before building, propose 4 distinct visual directions tailored to this brief
(each as: bg hex / accent hex / typeface, plus a one-line rationale).
Ask the user to pick one, then implement only that direction.

7. Fable 5 世代で新しく必要になったこと

「1リクエストが数分〜数時間走る」が最大の実務的インパクト。

Adjust client timeouts, streaming, and user-facing progress indicators before migrating, and consider restructuring harnesses to check on runs asynchronously rather than blocking.

移行の前に、クライアントのタイムアウト・ストリーミング・ユーザー向けの進捗表示を調整せよ。さらに、ブロッキングせずに非同期で実行状況を確認するよう harness を組み替えることも検討せよ。

プロンプト側で新しく要るもの:

課題対処
進捗の捏造ツール結果に照らして各主張を監査させる。「テストが落ちたならその出力とともにそう言え」（実測でほぼ消えた）
稀な早期停止自律パイプラインには system reminder。「最後の段落が計画・質問・約束なら、その作業を今やれ」
context 予算の懸念harness が残トークンのカウントダウンを見せると誘発される。見せないのが最善
verbatim で届けたい内容send_to_user ツールを作る。ツール入力は要約されないので内容がそのまま届く

そして scaffolding 側:

Start at the top of your difficulty range. Pick a task harder than what you’d assign to prior models.

自分が扱う難易度の上限から始めよ。以前のモデルに割り当てていたものより難しいタスクを選ぶ。

Separate, fresh-context verifier subagents tend to outperform self-critique.

まっさらな context を持つ検証用 subagent は、自己批判より良い結果を出す傾向がある。

8. 移行の手順

  1. API パラメータの互換性を確認する（プロンプトより先に落ちる）
    • prefill を使っていないか（4.6+ で 400）
    • budget_tokens を使っていないか（4.7+ で 400）
    • temperature / top_p / top_k を送っていないか（Sonnet 5 で 400）
    • トークナイザ変更で max_tokens が足りるか（Sonnet 5 で約30%増）
    • thinking の既定が変わっていないか
  2. 剥がす（§2 の一覧を上から確認）
    • 検証指示、再確認指示
    • 進捗要約の scaffolding
    • 過剰な発火促進（CRITICAL / MUST / If in doubt）
    • 「思考を見せろ」系（Fable 5.1 / Fable 5 / Opus 5.5 / Opus 5 / Sonnet 5.5 で拒否を誘発）
    • コードレビューの「重大なものだけ」
  3. 向きが反転しているものを直す
    • subagent の prompt を、抑制 ⇄ 促進 のどちらが要るか確認
  4. effort を測り直す
    • 旧モデルの設定を流用しない。eval で sweep をやり直す
    • 会話内では固定する（キャッシュのため）
    • xhigh / max なら max_tokens を 64k から
  5. 世代共通の3点を再調整する
    • 応答の長さ（Opus 5 は effort では変わらない）
    • スコープの明示（字義通りに読むので）
    • デザインの既定（具体指定 or 選択肢提案）
  6. eval で確認する
    • recall が落ちて見えるのは harness 効果かもしれない
    • 「観測される thinking の長さ」で揃えて比較する

9. この文書自体の鮮度

§2〜§7 は陳腐化が最も速い部分。 モデルがもう1世代進んだら真っ先に見直す。

鮮度の起点: whats-new のモデルの既定の推移。

W16 Opus 4.7 → W22 Opus 4.8 → W27 Sonnet 5 → W30 Opus 5 → v2.1.280 Opus 5.5

最後の Opus 5.5 は digest ではなく model-config で確認した（当時のもの。 whats-new の索引の最新は W37 = v2.1.263–269 で、v2.1.280 はまだ載っていない）。

約2ヶ月に1度、既定モデルが変わっている。 つまりこの文書は2ヶ月ごとに点検する必要がある。

原典で確認した。 digest が言う「Opus 5 が Claude Code の既定 Opus に」は choosing-a-model に書かれていなかった。原典が述べているのはeffort の既定が high（Claude Code と Messages API の両方で）であり、既定モデルの話ではない。この「既定 high」は Opus 5.5 には当てはまらない（Opus 5.5 の既定は medium。effort）。以前の取得では、この一文自体が choosing-a-model から消え、「Fable 5.1 と Opus 5 は high、Opus 5.5 は medium から始める」に変わった。

バックリンク