Claude のモデル移行は ID 差し替えだけでは終わらない

要点

要点まとめ

この guide の一番大事な点は、モデル移行を『名前の差し替え』ではなく『答え方、監視の見方、コスト見積もりが変わる変更』として扱っていることだ。
とくに自前アプリから Messages API を直接たたいている場合、長い会話履歴の再利用、拒否応答の判定、古い思考設定の残り方まで点検しないと、エラーなしで品質だけずれることがある。
逆に、公式も Managed Agents については model 名更新だけで済むケースがあると明記しており、全部の Claude 利用形態に同じ重さの移行作業が必要だと言っているわけではない。
つまり読むべき論点は、『うちの実装はどの層で Claude を使っていて、どこが静かに変わりうるのか』を先に切り分けることだ。

読解

何が変わったのか

原典はまず適用範囲を分けています。Managed Agents は model 名更新だけで済む寄りですが、Messages API のコードパスでは追加確認が要ります。ここで `thinking` はモデルが途中で使う思考用ブロック、`conversation replay` は過去の会話履歴を次のモデルへ渡して続ける処理です。そのうえで `claude-fable-5` では adaptive thinking が常時有効で、旧来の `thinking: {type: "disabled"}` は使えません。深さ調整は `effort` に寄ります。また model をまたぐ replay では prior assistant turns から `thinking` と `redacted_thinking` を外すよう求めています。さらに `stop_reason: "refusal"` は HTTP 200 の成功レスポンスで返りえます。新しいのは、モデル差分そのものより『同じ監視と同じ履歴処理のままで流用できるとは限らない』と明文化した点です。

日本の文脈

なぜ重要か

日本の導入現場では、model migration が config 差し替え作業として軽く扱われがちです。しかし実際には、thinking 表示、履歴互換、latency、token 課金、refusal handling がまとまって変わるため、移行を release engineering として扱わないと事故になります。この guide は、新モデルを試す前に『壊れる API は何か』『静かに変わる挙動は何か』『再測定が必要な費目は何か』を棚卸しする視点をくれます。とくに agent や coding workflow のように長い会話と自動 retry を使う運用では、移行差分の見落としが目立ちやすいです。

技術ポイント

技術的ポイント

`claude-fable-5` では adaptive thinking が常時有効で、`thinking: {type: "disabled"}` は使えない。深さ調整は `effort` で行う。
`budget_tokens` に直接の置き換えはなく、以前の manual extended thinking を使っていた code path は整理が必要だ。
assistant prefill を前提にした実装は新しい系列で通らない箇所がある。system prompt や structured output 側へ寄せる確認が要る。
conversation replay 時は `thinking` と `redacted_thinking` blocks を model 跨ぎでそのまま流さない前提になる。履歴整形処理の有無が品質差になる。
`stop_reason: "refusal"` は HTTP 200 で返りうる。監視、retry、fallback の判定条件を status code 以外にも広げる必要がある。
guide 自体が自分の workload で token、latency、behavior を re-baseline するよう求めており、概算互換と実運用コストは別問題だ。

用語

英日キーワード

英語	日本語	補足
adaptive thinking	適応的思考	モデルが必要な思考量を都度決める仕組み。固定の深さ前提で運用すると挙動差分を見落としやすい。
effort parameter	effort パラメータ	思考の深さや重さを調整する設定。旧来の thinking 設定の代替として読む必要がある。
conversation replay	会話再生	過去の会話履歴を次のモデルへ渡して続けること。モデル跨ぎでは履歴整形が必要になる。
refusal stop reason	refusal 停止理由	安全上の拒否で応答を止めたことを示す完了理由。HTTP エラーではなく成功レスポンス内で返る場合がある。
assistant prefill	assistant 事前埋め込み	assistant 側の返答を先に埋める古い誘導方法。新しいモデル系列ではそのまま通らないことがある。

試す

試すなら

まず現行コードで `budget_tokens`、`thinking`、assistant prefill、`stop_reason` 判定を grep し、移行影響箇所を洗い出す。
次に同じ入力で旧 model と新 model の token、latency、refusal、履歴継続を比較し、差分を数字で記録する。
自動 retry や cross-model fallback を使うなら、`thinking` block の strip 条件と HTTP 200 refusal の扱いを先にテストで固定する。

注意

注意点

この guide は Messages API migration を主に扱っており、Managed Agents まで同じ重さで読むと過剰対応になる。
公式 docs page 上に公開日は明示されていない。日付証跡が要るなら別の release source と突き合わせるべきだ。