Claude Opus 4.7移行ガイド：7つのワークフローリスクを先に潰す

Claude Opus 4.7への移行で本当に危ないのは、プロンプトが一斉に壊れることではありません。むしろ、旧ワークフローの中に埋め込まれた「暗黙の制御」です。たとえば、古いAPIパラメータ、古いtoken見積もり、曖昧なtool useの判断、agentの予算管理がそのまま残ると、品質・コスト・遅延のどこかで想定外が起きやすくなります。

Anthropicの移行ガイドでは、Opus 4.7はOpus 4.6の主要なプラットフォーム機能を引き継ぐ一方で、thinking configuration、sampling-parameter removal、task budgets、tokenizationなどを確認する必要があるとされています。

この記事は、Anthropicの文書で明示されているClaude Opus 4.6からClaude Opus 4.7への移行を前提にしています。さらに古いClaudeモデルから移る場合も出発点としては使えますが、元のモデルとの差分は別途確認してください。

まず、自分のClaudeワークフローを分類する

移行作業の重さは、Claudeをどう使っているかで大きく変わります。手動チャットや文書ドラフトなら、主にプロンプトの回帰テストで足ります。一方、API、RAG（検索拡張生成）、agent、coding、visionを含むワークフローでは、パラメータ、tool policy、コストモデルまで見直す必要があります。

利用パターン	アップグレード前に見るべき場所
手動チャット、文書ドラフト、知識作業	よく使うプロンプト、文体、出力形式、引用、tool useのルール
Messages API / SDK	model ID、thinking設定、samplingパラメータ、token counting、エラー処理
Tool use / RAG / web search	いつツールを使うか、いつ推測を禁止するか、ツール失敗時のfallback
長時間agent / coding agent	effort、task budget、token budget、遅延、regression eval
画像、スクリーンショット、PDF、computer-use	画像解像度、downsample方針、tokenコスト、視覚認識品質

1. 最初のbreaking change：extended thinkingをadaptive thinkingへ移す

最初に触るべきなのは、プロンプト本文よりもAPI設定です。Anthropicは、開発者がClaude API経由でclaude-opus-4-7を利用できるとしています。アプリケーション側でmodel IDを直書きしている場合は、まず小流量テストやshadow evalに入れるのが安全です。

より重要なのがthinking設定です。Anthropicのmigration guideは、Claude Opus 4.7以降では旧式extended thinkingのbudget_tokens設定がサポートされず、400エラーを返すと明記しています。移行先はadaptive thinkingです。

実務では、まず次の3点を確認します。

• コード、SDK wrapper、prompt runner、社内プラットフォーム設定からbudget_tokensを検索する。
• 旧式extended thinking設定を削除し、利用中のAPIまたはproviderがサポートするadaptive thinking設定へ移す。
• 固定のthinking token budgetを主な制御手段にしない。代わりに、文書でサポートされているeffort、task budget、プロンプト制約、evalでタスクの深さを調整する。

Anthropicのprompting best practicesも、Opus 4.6からOpus 4.7へ移行する際に見るべきAPI変更として、effort levels、task budgets、thinking configuration、sampling-parameter removal、tokenizationを挙げています。

2. samplingパラメータに頼っていた制御を、promptとevalへ戻す

旧ワークフローがtemperature、top_p、top_kで創造性、安定性、出力のばらつきを調整していたなら、移行時に設計を見直す必要があります。Anthropicのprompting文書はsampling-parameter removalをOpus 4.7移行時の注意点として挙げており、OpenRouterのClaude 4.7 migration guideもsampling parameters removed、adaptive-only thinking、provider-specific effort behaviorを列挙しています。

影響を受けやすいのは、次のようなタスクです。

• クリエイティブライティングやマーケティング文案：以前は高めのsamplingで発散した案を作っていたケース。
• カスタマーサポート、コンプライアンス、データ抽出：以前は低めのsamplingで安定性を狙っていたケース。
• バッチ生成：samplingパラメータで出力の多様性を調整していたケース。

移行後は、ルールをプロンプトとevalに寄せるほうが管理しやすくなります。文体、禁止事項、出力形式、成功条件を明示する。few-shot例でスタイルを固定する。抽出・分類・レポート生成では構造化出力を指定する。さらに、旧Claudeでのgolden examplesをregression evalにして、Opus 4.7の形式遵守、正確性、コスト、遅延を比較します。

3. Tool useは「いつ使うか」を明文化する

旧ワークフローで「Claudeに大きな目標だけ渡し、ツールを使うかどうかはモデルに任せる」設計をしていた場合、Opus 4.7移行時に最も補強したいのがtool policyです。

Anthropicのprompting best practicesは、最新のClaudeモデルが精密な指示追従を前提に訓練されており、特定ツールの使用を明示すると効果が出やすいと説明しています。同じ文書では、multi-step tool use、complex coding tasks、long-horizon agent loopsのようなagentic workloadにadaptive thinkingを使うことも推奨されています。

たとえば、system promptやワークフローpolicyに次のようなルールを入れます。

• リアルタイム情報、価格、ポリシー、バージョン差分、外部文書に関わる場合は、必ず指定の検索ツールを使う。
• 社内knowledge baseに答えがない場合は、確認できないと明示し、推測で埋めない。
• ツール結果が矛盾する場合は、まず矛盾点を列挙し、そのうえで保守的な結論を出す。
• 最終回答では、ツール結果に基づく情報とモデルの推論を分けて示す。

これは単なるmodel IDの差し替えより重要な場合があります。tool policyは、agentが必要な検索を飛ばすか、情報不足で推測するか、ツール結果が衝突したときに過度に自信を持つかに直結するからです。

4. 長時間agentは、effortとtask budgetでコストを見る

Opus 4.7移行で見落としやすいのが、長時間タスクやagentic workflowの予算管理です。AnthropicのWhat’s new文書はOpus 4.7がtask budgetsを導入したと説明しており、公式文書では、effortパラメータが能力・速度・token spendのトレードオフを調整し、task budgetがタスク全体で使えるtokenの概算をClaudeに与えるものだと説明されています。

coding agent、research agent、browser agent、長時間のデータ処理、多段のtool loopを持つワークフローでは、予算を3層に分けると整理しやすくなります。

• 単一応答のbudget：最終出力に使えるtoken量。
• 推論とツールのbudget：多段タスクで使えるreasoning、tool calls、tool resultsの量。
• タスク全体のbudget：agent loop全体のコストと遅延の上限。

最終出力のmax_tokensだけでagent loop全体のコストを見積もるのは危険です。長時間タスクのコストは、複数回のツール呼び出し、ツール結果の再投入、画像やPDFの解析、リトライ、最終出力から発生します。Opus 4.7のtask budgetsと新tokenizerを踏まえると、ここは再benchmarkが必要です。

5. Token、RAG、cache、batchは再benchmarkする

移行で最も軽く見られがちなのがtoken計測です。Anthropic文書によると、Opus 4.7の新tokenizerは、テキスト処理時に前世代モデルのおよそ1x〜1.35xのtokenを使う可能性があります。また、/v1/messages/count_tokensがOpus 4.7で返すtoken countはOpus 4.6と異なるため、Anthropicはこのendpointで再見積もりすることを勧めています。

アップグレード前に、少なくとも次を再測定してください。

• RAGのchunk sizeとoverlap。
• 長文書の切り捨て閾値。
• conversation memoryの長さ。
• prompt cachingの命中率とコスト見積もり。
• batch jobのコスト上限。
• agent各ターンで再投入するtool resultsのサイズ。
• 画像とPDFの前処理方針。

旧ワークフローがすでにコスト上限やcontext limitに近い場合、過去のtoken見積もりをそのまま使わないほうが安全です。主要プロンプト、長文書サンプル、高トラフィックタスクでtoken benchmarkを取り直し、chunking、切り捨て、cache key設計を調整するか判断します。

6. 画像、スクリーンショット、PDFは前処理ルールを見直す

Opus 4.7文書ではhigh-resolution image supportに触れられています。一方で、追加の画像忠実度が必要ない場合は、Claudeへ送る前に画像をdownsampleしてtoken使用量の増加を避けるべきだとも説明されています。

影響を受けやすいのは、次のようなワークフローです。

• スクリーンショット理解：UI QA、表のスクリーンショット、dashboard分析など。
• 文書画像処理：スキャンPDF、契約書の画像、プレゼン資料ページなど。
• computer-use / browser automation：画面上の位置、ボタン、フォーム、エラーメッセージをモデルが理解する必要があるケース。

Opus 4.6からの移行では、PDFやvisionの能力そのものはAnthropicが挙げる同じ主要プラットフォーム機能の範囲に残っています。再確認すべきなのは、どのサイズの画像を送るか、高解像度が本当に必要か、downsample後も重要な文字やUI要素を認識できるかです。

7. Providerや社内gatewayでは、パラメータmappingを疑う

Anthropic APIを直接呼ばず、OpenRouter、クラウドプラットフォーム、社内gatewayなどを経由してClaudeを使っている場合、フィールド名、無視されるパラメータ、effortの扱いが同じだと仮定しないほうが安全です。OpenRouterのClaude 4.7 migration guideは、sampling parameters removed、adaptive-only thinking、provider-specific effort behaviorを個別に挙げています。

そのため、Anthropicの文書だけでなく、実際に使っているproviderのmigration noteも確認してください。特にmulti-model router、fallback gateway、社内prompt platformでは、上流APIのパラメータを独自フィールドに包んでいることがあります。移行時は、どのフィールドが有効か、どれが無視されるか、どれがエラーになるかを確認します。

大きく変えなくてよい可能性が高いもの

Opus 4.6からOpus 4.7への移行で、プラットフォーム機能が丸ごと入れ替わるわけではありません。Anthropicのmigration guideによると、Opus 4.7はOpus 4.6と同じ主要機能セットをサポートします。これには、1M token context window、128k max output tokens、adaptive thinking、prompt caching、batch processing、Files API、PDF support、vision、server-side / client-side tools一式が含まれます。

つまり、最初に全面刷新すべき対象は通常、次のような基盤ではありません。

• Files APIとファイルアップロードの流れ。
• PDF / vision機能の有無。
• prompt cachingやbatch processingの利用可否。
• ツール呼び出し能力そのもの。
• 長いcontext windowそのもの。

本当に再調整すべきなのは、それらの能力をどう制御するかです。いつツールを使うか、どれだけtokenを使うか、どのeffortを選ぶか、画像をどのサイズで送るか、失敗時にどうfallbackするかを明示する必要があります。

実務用チェックリスト

APIとパラメータ

• model nameをclaude-opus-4-7へ切り替え、小流量テストまたはshadow evalを行う。Anthropicは、開発者がClaude API経由でこのmodel IDを利用できるとしています。
• thinking、budget_tokens、旧式extended thinking wrapperを検索し、adaptive thinkingへ移す。Opus 4.7以降では旧式設定は非対応で、400エラーになります。
• temperature、top_p、top_kなどのsampling制御を検索し、prompt、few-shot、schema、evalで安定性を管理する設計に変える。
• OpenRouterなどの代理層やproviderを使っている場合は、そのproviderのClaude 4.7 migration guideとパラメータmappingを確認する。

Promptとtool use

• いつツールを必ず使うかをsystem promptに書く。Anthropic文書は、最新Claudeモデルが明示的なtool-use指示から恩恵を受けると説明しています。
• いつ推測してはいけないか、情報不足時にどう答えるかを書く。
• ツール結果が矛盾した場合、ツールが失敗した場合、外部情報が足りない場合のfallbackを書く。
• 抽出、分類、レポート生成などでは、構造化出力形式を指定する。

Agentとcoding workflow

• coding agent、research agent、browser agentでは、effortとtask budgetを再調整する。Anthropic文書はadaptive thinkingをmulti-step tool use、complex coding tasks、long-horizon agent loopsと結びつけて説明しています。
• task budgetsを使うか評価する。Opus 4.7文書はtask budgetsを挙げ、token countingが前世代と異なることも説明しています。
• agent loop全体のコストを最終出力上限だけで見積もらない。tool calls、tool results、リトライ、最終出力を含めて見る。
• 旧Claudeで成功していたケースをregression evalにし、Opus 4.7の成功率、形式遵守、遅延、コストを比較する。

Token、文書、画像

• /v1/messages/count_tokensで、主要プロンプト、RAG chunks、長文書、batch tasksのコストを再見積もりする。
• chunk size、切り捨て閾値、conversation memory、prompt caching戦略を再テストする。
• 画像、スクリーンショット、PDFページにはdownsample policyを作る。高い画像忠実度が不要な場合は、token使用量を抑えるため、Claudeへ送る前に解像度を落とす。

安全な移行順序

一度に全面切り替えするより、次の4段階で進めるほうが安全です。

1. 静的スキャン：model ID、thinking、sampling、token counting、image preprocessing、provider-specific parametersを洗い出す。
2. 小流量eval：既存のgolden setで、旧ClaudeとOpus 4.7の出力品質、形式遵守、tool use、コスト、遅延を比較する。
3. 高リスクpromptの改修：tool use、RAG、coding agent、データ抽出、コンプライアンス系タスクを優先する。
4. 段階的な放量：token使用量、tool call回数、エラー率、遅延、人手レビューのフィードバックを監視する。

要するに、Claude Opus 4.7への移行は「プロンプトを全部書き直す」作業ではありません。旧ワークフローに隠れていた制御ロジックを明示する作業です。thinkingはadaptiveへ、sampling制御はpromptとevalへ、長時間agentは予算駆動へ、画像とtokenコストは再benchmarkへ。この順番で進めると、既存ワークフローの制御性を保ちながら移行リスクを下げられます。