Claude Opus 4.7 移行ガイド——破壊的変更と対応方法【完全版】

1. この移行ガイドの対象

Claude Opus 4.7 のリリース記事で紹介したとおり、Opus 4.7 は 4.6 の直系後継モデルです。ただし、API レベルでは複数の破壊的変更が同時に入っており、モデル名だけ差し替えると 400 Bad Request で落ちるケースがあります。

この記事は次のような人を対象にしています。

• Anthropic API / SDK を使って claude-opus-4-6 系を呼んでいる開発者
• Bedrock / Vertex AI 経由で Claude を使っているチーム
• Opus 4.5 や 4.1 で止まっていて、一気に 4.7 へジャンプしたい人
• 拡張思考 (thinking: enabled) や temperature を本番で使っている人

Anthropic 公式の移行ガイドを一次情報としつつ、日本の開発現場で詰まりやすいポイントに絞って整理します。なお、公式の情報は platform.claude.com の移行ガイドを参照してください。

2. 3行要約——最短で把握する

時間がない人のための TL;DR です。

1. モデル名を claude-opus-4-6 → claude-opus-4-7 に差し替える（SDK バージョンも最新化）
2. 破壊的変更は大きく3つ: 拡張思考 enabled 廃止 (適応的思考 + effort へ)、temperature/top_p/top_k 廃止、新トークナイザー (同じ文章で最大 1.35 倍のトークン)
3. 代わりに得られるもの: より高いコーディング性能、1M コンテキスト (標準料金)、xhigh という新しい努力レベル

細部は次章以降で詳しく掘り下げます。

3. モデル名の更新

最初にやることは単純です。モデル識別子を差し替えるだけ。

# Before
model = "claude-opus-4-6"

# After
model = "claude-opus-4-7"

環境変数や設定ファイルで管理している場合は、一箇所書き換えるだけで反映できる構造にしておくと、次の移行時も楽になります。

// .env
// CLAUDE_MODEL=claude-opus-4-6
CLAUDE_MODEL=claude-opus-4-7

// app.ts
const model = process.env.CLAUDE_MODEL ?? "claude-opus-4-7";

ただし、モデル名を差し替えただけでは動かないケースが多いのが今回の移行の難しいところです。以下で破壊的変更を1つずつ見ていきます。

4. 破壊的変更1: 拡張思考が廃止、適応的思考へ

Opus 4.6 では、拡張思考 (extended thinking) を有効化する際に thinking: {type: "enabled", budget_tokens: N} を指定していました。4.7 ではこの形式は 400 エラーになります。

代わりに、モデル側が自動で思考量を調整する「適応的思考 (adaptive thinking)」を使います。しかも 4.7 のデフォルトは思考 OFF で、thinking フィールドを省略すると思考なしで動作します。明示的にオンにしないと従来のような深い推論は行われません。

Before (4.6) / After (4.7)

# Before: Opus 4.6
client.messages.create(
    model="claude-opus-4-6",
    max_tokens=64000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    messages=[{"role": "user", "content": "..."}],
)

# After: Opus 4.7
client.messages.create(
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # "max", "xhigh", "high", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

// Before: Opus 4.6
await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 64000,
  thinking: { type: "enabled", budget_tokens: 32000 },
  messages: [{ role: "user", content: "..." }],
});

// After: Opus 4.7
await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 64000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" },
  messages: [{ role: "user", content: "..." }],
});

ポイント

• budget_tokens で「思考量」を直接コントロールする必要はなくなった
• 代わりに output_config.effort で「どの程度真剣に考えるか」を指定する
• thinking フィールド自体を付けないと、思考なしで即応答する (4.6 と挙動が変わる点に注意)

5. 破壊的変更2: サンプリングパラメータ廃止

temperature、top_p、top_k にデフォルト以外の値を渡すと 400 エラーになります。これは「モデルの挙動はプロンプトで指定するべき」という Anthropic の方針の徹底です。

# Before
client.messages.create(
    model="claude-opus-4-6",
    temperature=0.7,
    top_p=0.9,
    top_k=40,
    messages=[...],
)

# After
client.messages.create(
    model="claude-opus-4-7",
    # temperature / top_p / top_k は完全に削除
    messages=[...],
)

これまで temperature=0.2 で「なるべく安定した出力」を得ていた人は、プロンプト側で「出力は同じ質問に対して可能な限り一貫したものにしてください」と明示するか、JSON スキーマなどの structured outputs を併用することで代替します。

また、temperature=1.2 で「創造的に」と指定していたケースは、プロンプトに「比喩的で意外性のある表現を使ってください」などのトーン指示を盛り込むのが推奨です。

6. 破壊的変更3: 思考コンテンツのデフォルト非表示

4.6 では、思考を有効化するとデフォルトで「要約された思考 (summarized)」がレスポンスストリームに流れてきました。多くのアプリはこれを UI に「考え中...」として表示していました。

4.7 では仕様が静かに変わり、思考ブロックはレスポンスに現れるものの、thinking フィールドは空になります。明示的にオプトインしないと中身は返りません。

症状

UI 側で「考え中です」のインジケータがずっと回りっぱなしになり、回答が始まるまでが異様に長く感じられます。ユーザーから「固まってる？」と言われるのはこのパターンです。

対応

# 4.6 と同じように思考の要約を UI へ流したい場合
client.messages.create(
    model="claude-opus-4-7",
    thinking={
        "type": "adaptive",
        "display": "summarized",  # これを明示する
    },
    output_config={"effort": "high"},
    messages=[...],
)

await client.messages.create({
  model: "claude-opus-4-7",
  thinking: {
    type: "adaptive",
    display: "summarized",
  },
  output_config: { effort: "high" },
  messages: [...],
});

バックエンド処理だけで UI に思考を見せないのであれば、display は付けずにそのまま放っておいて問題ありません。

7. 破壊的変更4: 新トークナイザー (約1.35倍)

Opus 4.7 は内部的に新しいトークナイザーを採用しています。性能向上に寄与している一方、同じ文章に対するトークン数が 4.6 比で約 1.0〜1.35 倍に増えるという副作用があります。

これが何を引き起こすか。

• max_tokens ギリギリで設計していた処理が途中で打ち切られる
• クライアント側で tiktoken 的な見積りをしていた課金・長さチェックが狂う
• /v1/messages/count_tokens の結果が 4.7 / 4.6 で異なる
• 同じプロンプトでもコストとレイテンシが微増する

対応

# Before: 4.6 想定で 16k tokens の出力バッファを確保
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    messages=[...],
)

# After: 1.35倍を目安に余裕を持たせる
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=22000,  # 16000 * 1.35 ≒ 21600 → 切り上げ
    messages=[...],
)

また、4.7 では 1M コンテキストウィンドウが標準 API 料金で利用可能です (長文プレミアム無し)。トークン数が増える側面はあるものの、その分「とりあえず全部入力に放り込む」戦略が取りやすくなった面もあります。

8. 破壊的変更5: プリフィル廃止

4.6 から持ち越された破壊的変更です。assistant メッセージのプリフィル——つまり messages 配列の末尾に {role: "assistant", content: "```json"} のようなメッセージを差し込んで「JSON から始まる応答」を強制する技——は 400 エラーになります。

# Before: プリフィルで JSON 出力を強制
client.messages.create(
    model="claude-opus-4-6",
    messages=[
        {"role": "user", "content": "ユーザー情報を JSON で返して"},
        {"role": "assistant", "content": "```json\n{"},  # プリフィル
    ],
)

# After: structured outputs を使う
client.messages.create(
    model="claude-opus-4-7",
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
            },
        },
    },
    messages=[
        {"role": "user", "content": "ユーザー情報を JSON で返して"},
    ],
)

プリフィルの代替手段は3つあります。

1. Structured outputs (output_config.format) — 出力形式を JSON スキーマで縛る
2. System プロンプトで「JSON だけを返し、マークダウンや前置きは一切書かないこと」と明示する
3. Tool use で関数呼び出しとして受け取る (引数が構造化 JSON になる)

9. 努力レベルの選び方 (xhigh新登場)

output_config.effort で指定できる値は次の5段階です。4.7 で xhigh が新登場しました。

4.6 時代は budget_tokens を手で指定していた人も、4.7 では effort を選ぶだけで済むようになります。使い分けの経験則は次のとおり。

• コーディングエージェント (Claude Code的な用途) なら xhigh から始める
• Q&A チャットや RAG の応答なら high が無難
• タグ付け・JSON 抽出・分類の軽量ワーカーは medium or low
• max は「1問だけ金に糸目を付けず深く考えさせたい」時に限定使用

10. 動作変化への対応

API 的には互換でも、プロンプトへの応じ方が 4.6 と変わっている点がいくつかあります。これを知らずに本番投入すると、ユーザーから「なんか素っ気なくなった」と言われます。

10.1 レスポンス長がタスクに適応する

4.7 はタスクの複雑さに応じて応答の長さを自動調整します。「必ず3段落で書け」といった固定の冗長性はありません。逆に言うと、既存の「長さ制御プロンプト」は一度外して挙動を確認するのが推奨です。

10.2 指示をより文字通りに受け取る

特に effort が低いときほど顕著です。「簡潔に」と書けば本当に簡潔に返しますし、「3つ挙げて」と書けば4つ目を勝手に足しません。この性質は便利ですが、曖昧な指示に対して「空気を読んで補ってくれる」4.6 的な振る舞いは減っています。

10.3 トーンが直接的に

「素晴らしい質問ですね！」のような検証フレーズ、装飾的な絵文字、冒頭の挨拶などは減ります。フレンドリーな口調を維持したい場合は、system プロンプトでトーンを明示しましょう。

10.4 進捗更新がエージェント追跡に組み込み済み

エージェント運用で「今から〇〇します」「〇〇しています」といった途中経過を手動で書かせる足場を組んでいた場合、4.7 はこれを内蔵で出すので、重複したスキャフォールディングを外せます。

10.5 サブエージェントとツール呼び出しが控えめに

デフォルトでサブエージェントのスポーン数が減り、ツール呼び出しも減ります。「推論で解ける」と判断すればツールを叩かずに答える傾向が強くなりました。エージェント設計側の期待値をアップデートしてください。

10.6 リアルタイムのサイバーセキュリティ・セーフガード

攻撃的セキュリティ (レッドチーム、脆弱性 PoC など) の正当な業務でも、文脈次第で拒否されるケースがあります。セキュリティ業務が本番ユースケースなら、Anthropic のサイバー検証プログラム (cyber verification program) への申請を検討してください。

10.7 高解像度画像のサポート

最大 2576px までの高解像度画像をそのまま処理できるようになりました。ただしフル解像度画像は 1枚あたり約3倍のトークンを消費します。画像多めのワークロードでは、(a) max_tokens を再配分するか、(b) 送信前にダウンサンプルするかを選んでください。

11. 推奨される変更 (必須ではない)

ここからは「やらなくても動くが、やったほうが得」な項目です。

1. max_tokens の再評価: 新トークナイザーで出力側も膨らむので、既存の値を 1.2〜1.35倍した値から検証し直す
2. クライアント側トークン見積りの監査: 課金計算や長さチェックを自前で実装している場合、count_tokens API に寄せるか係数を見直す
3. task_budgets (beta) の導入: エージェント運用向け。ヘッダー task-budgets-2026-03-13 を付与、最低 20k。これは「ハードキャップ」ではなく「助言的な上限」である点に注意
4. max_tokens を 64k 以上に設定: xhigh/max を使うなら、思考 + 出力の合計で 64k 以上を推奨
5. 画像のダウンサンプル: 高解像度が不要なら送信前に縮小し、トークンとコストを節約

11.1 task_budgets の最小サンプル（公式SDK・Python）

task_budgets はベータ機能のため、client.beta.messages.create エンドポイントを使い、betas 引数を明示する点に注意してください。本番 GA 機能とは呼び出し方が異なります。

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
)

仕様の要点:

• 最小値は 20,000 トークン。それ未満は受け付けられません
• max_tokens はリクエストごとのハードキャップ（モデルには非公開）、task_budget はエージェントループ全体の助言的な上限（モデルがカウントダウンを認識）
• 厳密にコストを抑えたいなら max_tokens、品質と効率のバランスを取りたいなら task_budget
• 品質 > 速度 のオープンエンドな作業では task_budget を 設定しない のが推奨（過度に切り上げる傾向が出る）

12. Opus 4.5/4.1 以前からの移行

4.6 を飛ばして 4.5 や 4.1 から一気に 4.7 へ上げる場合、上記に加えて次の対応が必要です。

• サンプリングパラメータの削除: Claude 3.x からの継続ユーザーは temperature を当たり前に使っているはず。完全削除
• beta ヘッダーの整理: effort-2025-11-24、fine-grained-tool-streaming-2025-05-14、interleaved-thinking-2025-05-14 などはすでに本体に取り込まれたので削除
• エンドポイントの切り替え: client.beta.messages.create で呼んでいたコードを client.messages.create に変更
• output_format → output_config.format への移行: キー名が変わっている
• ツール引数のパース: 4.6 以降、JSON エスケープの挙動が以前と異なるケースがある。生の文字列パースではなく JSON.parse / json.loads など正式なパーサーを使うこと

Claude Opus 4.7 そのものの新機能については、前提記事のClaude Opus 4.7 リリース: 新機能とベンチマーク、料金も合わせてどうぞ。

13. 移行チェックリスト (全項目)

印刷してチーム内で配れるよう、全項目を平置きで並べておきます。

13.1 必須 (これをやらないと 400 エラーまたは挙動破壊)

• ☐ モデル名を claude-opus-4-6 → claude-opus-4-7 に更新
• ☐ temperature / top_p / top_k を削除
• ☐ thinking: {type: "enabled", budget_tokens: N} を {type: "adaptive"} + output_config.effort に置換
• ☐ assistant メッセージのプリフィルを削除し、structured outputs / system プロンプトに置換
• ☐ UI に思考を表示している場合は thinking.display: "summarized" を明示設定

13.2 チューニング (コスト・品質の最適化)

• ☐ 新トークナイザーでコストとレイテンシを再ベンチマーク
• ☐ max_tokens を 1.35倍目安で再調整
• ☐ クライアント側のトークン見積り処理を再テスト
• ☐ 画像を送る場合は高解像度分のトークンを再配分
• ☐ xhigh/max を使うなら max_tokens ≥ 64k を設定
• ☐ エージェント用途なら task_budgets (beta) の導入を検討

13.3 プロンプトと運用の見直し

• ☐ 文長適応・文字通り解釈・トーン変化を実プロンプトで確認
• ☐ 既存の長さ制御プロンプトを削除し、ベースラインを再計測
• ☐ セキュリティ業務で拒否される場合はサイバー検証プログラムへ申請
• ☐ エージェントのスキャフォールディング (途中進捗出力など) を簡素化
• ☐ 4.5 以前からの移行時は beta ヘッダー削除と client.messages.create への移行も

14. 自動移行ツール

Claude Code を使っているなら、Anthropic が提供している Claude API スキルで機械的な書き換えを自動化できます。Claude Code のスキル呼び出しで次のように指示するだけです。

/claude-api migrate

プロジェクト全体を Claude Opus 4.6 から 4.7 に移行してください。
- モデル名を差し替える
- temperature / top_p / top_k を削除する
- thinking: enabled を adaptive + effort: high に置換する
- プリフィルが残っていたら structured outputs に置き換える

スキル側がリポジトリを走査し、anthropic SDK を import しているファイルを特定してから変更提案を出します。ただし、プロンプト本文の微調整やベンチマーク再計測は自動化できないので、必ずチェックリストで仕上げてください。

FAQ

この記事は Anthropic 公式の Claude Opus 4.7 移行ガイド (2026年4月時点) をもとに作成しています。API 仕様は変更される可能性があるため、本番投入前に 公式ドキュメントで最新情報を確認してください。