結論：モデルIDを変えるだけではなく、8項目をfixtureで再実行する
Claude Opus 5.5への移行では、modelをclaude-opus-5-5へ変える前に、thinking、tool_choice、sampling、prefill、computer use、streamの処理を確認します。thinkingは常時adaptiveで無効化できず、manual budgetも拒否されます。既存コードが通っていても、400エラーと静かな表示変更を別々に検知する回帰テストが必要です。
根拠は公式移行ガイド、公式モデルページ、公式リリースノートです。API移行ガイドはClaude Opus 5、4.8、4.7、4.6以前やSonnet 5からの差分を扱います。Claude Code専用の移行ではなく、Messages APIを使うサービスの判断に限定します。既存のSonnet 5.5移行ガイドとは対象モデルと制限を分けます。
まず固定する公式仕様
| 変更点 | Opus 5.5の条件 | 失敗の見え方 |
|---|---|---|
| thinking | 省略またはadaptive、disabled・manual budgetは不可 | API 400 |
| effort | low・medium・high・xhigh・max、既定medium | token・遅延・品質が変わる |
| tool_choice | autoまたはnone、any・toolは不可 | API 400 |
| sampling | temperature・top_p・top_kは省略または既定値 | 非既定値で拒否 |
| context | 1Mが既定、古いcontext beta headerは不要 | 不要な設定が残る |
| 出力 | thinking blockが先に来る。既定displayは省略 | UIに空白や遅延 |
thinkingが常に走るため、max_tokensはthinkingと本文の合計上限です。thinking tokenも出力tokenとして課金され、出力本文だけを基準にすると容量不足や費用差を見落とします。thinking blockはtool loopで受信したものを編集・並べ替え・削除せず、そのまま返す必要があります。
本番前に行う8手順
- 依存モデルを棚卸しする。Opus 5、Sonnet 5、Bedrockなどの呼び出し元とfallbackを検索します。
- model IDを分けて変更する。APIは
claude-opus-5-5、Bedrock等は各公式IDを確認します。 - thinking設定を検査する。disabledとmanual budgetを削除し、省略またはadaptiveへ移します。
- tool choiceを検査する。any・toolをautoへ置換し、strict tool useやstructured outputsで目的を補います。
- samplingとprefillを確認する。非既定のtemperature等とassistant prefillをfixtureから外します。
- computer useを確認する。Claude APIとGoogle Cloudでは
computer_toolset_20260801を使い、旧computer_20251124を送らない構成を検証します。Bedrockは提供条件が異なるため公式表を読みます。 - content blockを型で処理する。textだけを表示し、thinking、tool_use、tool_resultを捨てずにloopへ返します。
- 費用・監視・ロールバックを承認する。effort別のtoken、400率、tool成功率、表示遅延を比較し、旧モデルへ戻す条件を決めます。
コードの文字列置換だけでは完了しません。stream parserがtext blockの到着だけを待っていないか、空のthinking blockを異常扱いしていないか、会話継続時に署名付きblockを再構成していないかを確認します。画面にthinkingの要約を表示したい時は、表示用設定と内部loop用の完全なblockを分けて扱います。
移行テストの比較マトリクス
| テスト | 成功条件 | 証跡 |
|---|---|---|
| 単発テキスト | textを正しく抽出し、effort別の結果を保存 | request、block型、usage |
| tool loop | thinking blockを変更せず返しtoolが完了 | 全content blockのhash |
| 強制tool | 400を想定し、代替経路へ分岐 | error type、fallback理由 |
| 長文・stream | 空thinkingでもUIが停止しない | 開始からtextまでの時間 |
| computer use | providerごとのtoolsetが一致 | platform、region、tool名 |
テストは代表的な1件だけでなく、短文、長文、toolあり、toolなし、失敗再試行、途中切断を含めます。品質だけを見ず、ユーザーが待つ時間と、課金されるthinking・outputを同じレポートへ入れます。移行を止める条件は「400が出たら戻す」だけでなく、監査ログが欠けた場合、toolの副作用を再実行した場合、表示が誤解を生む場合も定義してください。
公開前チェックリスト
- モデルIDと各providerのIDを公式ページでreadbackした。
- thinking disabled・manual budget・tool_choice any/toolを検索で除外した。
- temperature、top_p、top_k、prefillの非互換設定を確認した。
- max_tokensがthinkingと本文の合計だと運用へ伝えた。
- thinking blockを型で処理し、tool loopで完全に再送した。
- computer useのtoolsetをAPI・Google Cloud・Bedrockごとに分けた。
- effort、token、400率、遅延、tool成功率を旧モデルと比較した。
- ロールバック、変更承認、公式readback日を記録した。
よくある質問
thinkingをdisabledにできますか？
できません。thinkingを省略するか{"type":"adaptive"}を送り、深さはeffortで調整します。disabledやmanual budgetは400エラーになります。
tool_choiceのanyをstrictへ変えれば同じですか？
同じではありません。Opus 5.5ではanyとtoolが拒否されるため、autoとstrict tool use、structured outputsを目的に応じて組み合わせます。
Managed Agentsは同じ移行作業が必要ですか？
公式移行ガイドでは、Managed Agentsはモデル名更新以外の変更は不要とされています。ただし契約・権限・評価は自社の変更管理で確認します。
移行の完了条件は、新モデルで一度成功することではありません。旧モデルと同じ入力、同じtool、同じ停止条件で結果を比較し、失敗した時に人が原因を説明できることです。特にthinkingとtoolの扱いをログへ残せば、400エラー、空表示、費用増の三つを混同せずに復旧できます。
公式手順を自社の変更管理につなぐ
最終的な仕様は公式移行ガイドと公式リリースノートを公開直前に確認してください。認証主体とkeyの設計はAPIキーの種類、Sonnet 5.5の比較はSonnet移行記事も役立ちます。複数providerの変更範囲や監査項目を整理する場合は無料診断をご利用ください。