Claude Opus 4.7 遷移指南：升級前必查的 7 個 workflow 風險

1. 先修 breaking change：extended thinking 改 adaptive thinking

第一件事不是改 prompt，而是掃 API 設定。Anthropic 表示，開發者可透過 Claude API 使用 claude-opus-4-7；如果你的應用程式直接指定 model ID，先把這一步納入小流量或 shadow eval。^[10]

更關鍵的是 thinking 設定。Anthropic 的 migration guide 明確寫到，Claude Opus 4.7 或之後不再支援舊式 extended thinking 的 budget_tokens 設定，且會回傳 400 error；遷移方向是改用 adaptive thinking。^[15]

實務上，先做三件事：

• 搜尋程式碼、SDK wrapper、prompt runner、內部平台設定中的 budget_tokens。
• 移除舊式 extended thinking 設定，改用你所使用 API 或 provider 支援的 adaptive thinking 設定。^[15]
• 不要再把固定 thinking token budget 當成主要控制器；改用文件支援的 effort、task budget、prompt 約束與 eval 來校準任務深度。^[26][27]

Anthropic 的 prompting best practices 也把 effort levels、task budgets、thinking configuration、sampling-parameter removal 與 tokenization 列為從 Opus 4.6 遷移到 Opus 4.7 時要看的 API 變更。^[26]

2. 把 sampling 參數的控制搬回 prompt 與 eval

如果舊 workflow 依賴 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 行為。^[26][14]

這會影響三種常見任務：

• 創意寫作或行銷文案：過去可能靠較高 sampling 取得更發散的版本。
• 客服、合規、資料抽取：過去可能靠較低 sampling 追求穩定。
• 批次生成：過去可能用 sampling 參數控制多樣性。

升級後，較穩的控制方式是把規則移到 prompt 與 eval：明確定義語氣、格式、禁止事項與成功標準；用 few-shot 範例固定輸出風格；對抽取、分類與報告產生使用結構化輸出要求；把舊版 Claude 的 golden examples 變成 regression eval，逐題比較 Opus 4.7 的格式遵循、正確率、成本與延遲。^[26]

3. Tool use：把「何時查工具」寫成明確 policy

如果舊 workflow 是給 Claude 一個寬鬆目標，讓模型自己判斷何時查工具，升級時最值得補強的是 tool policy。Anthropic 的 prompting best practices 指出，Claude 最新模型受訓於精準遵循指令，且會受益於明確要求使用特定工具；同一份文件也建議將 adaptive thinking 用於 multi-step tool use、complex coding tasks 與 long-horizon agent loops 等 agentic workload。^[1]

可把這類規則直接寫進 system prompt 或工作流 policy：

• 涉及即時資訊、價格、政策、版本差異或外部文件時，必須先使用指定查詢工具。
• 內部 knowledge base 沒有答案時，必須說明無法確認，不得猜測。
• 工具結果彼此矛盾時，先列出衝突，再給出保守結論。
• 最終答案要區分哪些資訊來自工具結果，哪些是模型推論。

這通常比單純替換 model ID 更重要，因為 tool policy 會直接影響 agent 是否漏查資料、是否在資料不足時亂猜，以及工具結果衝突時是否過度自信。^[1]

4. 長任務 agent：用 effort 和 task budget 思考成本

Opus 4.7 的一個遷移重點是長任務與 agentic workflow 的預算控制。Anthropic 的 What’s new 文件指出，Opus 4.7 introduces task budgets；官方文件也說，effort 參數可在能力、速度與 token spend 之間取捨，task budget 則讓 Claude 對整體任務可用 token 有概略估計。^[4][27]

如果你的 workflow 是 coding agent、research agent、browser agent、長時間資料處理或多工具 loop，建議把 budget 分成三層：

• 單次回覆 budget：最終輸出可以用多少 token。
• 推理與工具 budget：多步驟任務中，模型可以投入多少 reasoning、tool calls 與 tool results。
• 任務級 budget：整段 agent loop 的成本與延遲上限。

不要只用最終輸出上限來估整段 agent loop 成本。長任務的成本可能來自多次工具查詢、工具結果回灌、圖片或 PDF 解析、重試與最終輸出；Opus 4.7 的 task budgets 與新 tokenizer 都讓這件事更需要重新 benchmark。^[4][27]

5. Token、RAG、快取與 batch：重跑 benchmark

這是最容易被低估的遷移項。Anthropic 文件指出，Opus 4.7 的新 tokenizer 在處理文字時，可能會比前代模型使用約 1x 到 1.35x 的 token；/v1/messages/count_tokens 對 Opus 4.7 回傳的 token count 也會不同於 Opus 4.6，Anthropic 建議用該 endpoint 重新估算。^[4]

升級前應重測：

• RAG chunk size 與 overlap。
• 長文件截斷門檻。
• conversation memory 長度。
• prompt caching 命中率與成本預估。
• batch job 的成本上限。
• agent 每輪工具結果可回灌的大小。
• 圖片與 PDF 的預處理策略。

如果舊 workflow 已接近成本上限或 context limit，不要直接沿用舊版 token 估算。先用核心 prompt、長文件樣本與高流量任務跑 token benchmark，再決定是否調整 chunking、截斷或 cache key 設計。^[4]

6. 圖片、截圖與 PDF：重設前處理規則

Opus 4.7 文件提到 high-resolution image support；官方文件也提醒，如果不需要額外影像保真度，應在送進 Claude 前先 downsample，以避免 token 使用增加。^[4][27]

這會影響三類工作流：

• 截圖理解：例如 UI QA、表格截圖、dashboard 分析。
• 文件影像處理：例如掃描 PDF、合約截圖、簡報頁面。
• computer-use / browser automation：例如模型需要理解畫面位置、按鈕、表單與錯誤訊息。

從 Opus 4.6 升級時，PDF 與 vision 能力本身仍在 Anthropic 列出的同一組主要平台能力中；真正要重測的是送多大圖片、是否需要高解析度、以及 downsample 後關鍵文字與 UI 元件是否仍可辨識。^[15][27]

7. Provider 或內部 gateway：不要假設參數映射相同

如果你不是直接打 Anthropic API，而是透過 OpenRouter、雲端平台或內部 gateway 呼叫 Claude，不能假設欄位名稱、忽略規則與 effort 行為完全相同。OpenRouter 的 Claude 4.7 migration guide 就單獨列出 sampling parameters removed、adaptive-only thinking 與 provider-specific effort 行為。^[14]

因此，除了 Anthropic 文件，也要查你實際 provider 的 migration note。特別是多模型 router、fallback gateway、內部 prompt 平台，常會把上游 API 參數包成自己的欄位；升級時應確認哪些欄位仍有效、哪些會被忽略、哪些會導致錯誤。^[14]

哪些通常不用大改？

如果你是從 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。^[15]

也就是說，第一優先通常不是重寫這些基礎架構：

• Files API 與文件上傳流程。
• PDF / vision 能力是否存在。
• prompt caching 或 batch processing 是否可用。
• 工具呼叫能力本身。
• 長 context 能力本身。

真正要重校的是你如何控制這些能力：何時用工具、花多少 token、用多高 effort、圖片送多大，以及失敗時如何 fallback。^{[1][4][15][27]}

實際遷移 checklist

把這份清單交給工程、AI platform owner 或負責 Claude workflow 的團隊，可以快速找出高風險點。

API 與參數

• 將模型名稱切換到 claude-opus-4-7，並先做小流量或 shadow eval；Anthropic 表示開發者可透過 Claude API 使用這個 model ID。^[10]
• 搜尋 thinking、budget_tokens 與舊式 extended thinking wrapper，改成 adaptive thinking；Opus 4.7 或之後不支援舊式設定，會回傳 400。^[15]
• 搜尋 temperature、top_p、top_k 等 sampling 控制，改用 prompt、few-shot、schema 與 eval 管理穩定性。^[26]
• 若透過 OpenRouter 或其他代理層使用 Claude，另查該 provider 的 Claude 4.7 migration guide 與參數映射。^[14]

Prompt 與 tool use

• 把何時必須用工具寫進 system prompt；Anthropic 文件指出最新 Claude 模型受益於明確的 tool-use 指示。^[1]
• 把何時不能猜答案、資料不足時如何回答寫清楚。
• 把工具結果衝突、工具失敗、外部資料不足時的 fallback 行為寫清楚。
• 對資料抽取、分類、報告產生等 workflow 加上結構化輸出格式。

Agent 與 coding workflow

• 對 coding agent、research agent、browser agent 重新校準 effort 與任務預算；Anthropic 文件將 adaptive thinking 與 multi-step tool use、complex coding tasks、long-horizon agent loops 連在一起討論。^[1]
• 評估是否使用 task budgets；Opus 4.7 文件列出 task budgets，並提醒 token counting 與前代不同。^[4]
• 不要只用最終輸出上限估整段 agent loop 成本；把工具呼叫、工具結果、重試與最終輸出都納入成本模型。^[4][27]
• 用舊版 Claude 的成功案例建立 regression eval，比較 Opus 4.7 的成功率、格式遵循、延遲與成本。

Token、文件與影像

• 用 /v1/messages/count_tokens 重新估算核心 prompt、RAG chunks、長文件與批次任務成本。^[4]
• 重測 chunk size、截斷門檻、conversation memory 與 prompt caching 策略。^[4]
• 對圖片、截圖與 PDF 頁面建立 downsample policy；不需要高保真時先降低解析度，以控制 token 使用。^[27]

建議升級順序

最穩的升級方式不是一次全面替換，而是分四步：

1. 靜態掃描：找出 model ID、thinking、sampling、token counting、image preprocessing 與 provider-specific 參數。
2. 小流量 eval：用既有 golden set 比較舊版 Claude 與 Opus 4.7 的輸出品質、格式遵循、tool use、成本與延遲。
3. 重寫高風險 prompt：優先處理 tool use、RAG、coding agent、資料抽取與合規任務。
4. 逐步放量：監控 token 使用、工具呼叫次數、錯誤率、延遲與人工回報。

一句話總結：從舊版 Claude 搬到 Opus 4.7，核心不是把 prompt 全部重寫，而是把舊 workflow 裡隱含的控制邏輯顯性化。thinking 改 adaptive，sampling 改 prompt/eval，長任務改預算驅動，圖片與 token 成本重新 benchmark；這樣升級風險最低，也最能保留舊 workflow 的可控性。