為 Claude Sonnet 5.5 撰寫提示

本指南涵蓋 Claude Sonnet 5.5 專屬的提示模式。關於此模型的 API 變更，請參閱 Claude Sonnet 5.5 的新功能。關於適用於所有目前 Claude 模型的技巧，請參閱提示最佳實踐。

現有的 Claude Sonnet 5 提示應該不需修改就能表現良好，而為 Claude Sonnet 5 撰寫提示中的模式仍是合理的起點。對於最困難的長期工作，Opus 模型是更好的選擇。請從符合您所觀察到情況的章節開始：

• 不確定該使用哪個 effort 等級，或回合執行的時間比在 Claude Sonnet 5 上更長或更短：校準 effort
• 模型在程式設計任務完成前就停下來向您確認，或做了超出您要求的事：引導主動性與範圍
• 您的整合目前在關閉思考的情況下執行：在沒有預先思考的情況下執行
• 對於需要幾個推導步驟的任務，JSON 答案錯誤或無法解析：使用 JSON 輸出的推理任務
• 長時間的代理式回合看起來毫無動靜：面向使用者的進度更新
• 模型根據其訓練知識作答，而搜尋本可以發現已變更的細節：聊天與知識工作中的工具使用
• 使用者在任務進行中傳送的訊息被忽略，或被當作注入的文字：回合中的使用者訊息
• 程式碼變更在沒有執行測試或建置的情況下就被回報為已完成：程式設計任務的驗證
• 模型以錯誤的大小寫呼叫工具，或以稍有不同的名稱傳遞參數：寬容的工具呼叫處理
• 關於密集圖表或技術圖面的回答遺漏細節：用於複雜視覺輸入的工具
• 請求傳回 stop_reason: "refusal"：安全防護拒絕

校準 effort

「Effort」（努力程度）是控制 Claude Sonnet 5.5 思考多少的主要手段，並連帶影響品質、「latency」（延遲）與成本。其等級已重新校準：某個等級產生的思考量，與 Claude Sonnet 5 上相同等級的思考量並不相同。請針對您自己的評估重新進行一輪全面測試，而不是沿用您在 Claude Sonnet 5 上使用的設定。除非您的工作負載是代理式或對延遲敏感的，否則請從 high 開始，這是 Claude API 上的預設值。對於代理式程式設計與多步驟工具使用，規格明確的任務請從 medium 開始，較困難或較長的任務則改用 high。對於聊天及其他對延遲敏感的工作，請從 medium 或 low 開始，因為較高的 effort 意味著回覆開始前需要等待更久。如果品質需要，再提高 effort。

較低的 effort 也會改變模型完成代理式工作的方式。在 low 時，它會讓思考保持簡短，並可能略過對變更的驗證。請參閱程式設計任務的驗證。在 low 與 medium 時，於長時間的代理式任務中，它更有可能在完成前停下來向使用者確認。請參閱引導主動性與範圍。

有三項調整會有幫助：

• 設定 max_tokens 時，為思考與您預期的回覆保留空間。即使思考內容沒有傳回給您，思考仍會計入 max_tokens。針對沒有思考的請求所設定的上限，可能會截斷回覆。對於代理式程式設計，請將 max_tokens 設為 128,000（模型的最大值），並以串流方式接收回應。
• 將 xhigh 與 max 保留給您已量測到品質提升的工作，因為在這些等級下，思考與回覆會變得長得多。在這些等級下不接受 between_tools，因此無法關閉預先思考。
• 若要減少思考，請降低 effort 等級。從 medium 起，模型幾乎在每次回覆前都會簡短思考，即使是打招呼也一樣，這會增加第一個可見 token 出現前的時間。在系統提示中要求它少思考，並不能可靠地減少其思考。在 low 時，它會在大多數簡單請求上略過思考。

在請求之間變更頂層的 effort 值會使提示快取失效。若要以不同等級執行個別回合，請改用逐訊息 effort 變更（beta），這樣可以保留快取。例如，以 low 執行互動式工作階段，並在使用者提交困難問題時將 effort 提高到 high。逐訊息 effort 變更需要「adaptive thinking」（自適應思考）。搭配 between_tools 時，它們會傳回 400 錯誤，如在沒有預先思考的情況下執行所說明。

引導主動性與範圍

Claude Sonnet 5.5 自行推進的程度取決於 effort 等級與請求內容。在較低的 effort 下，它有時會在程式設計任務完成前向您確認。在較高的 effort 下，或面對開放式請求時，它可能會做超出您要求的事。請透過 effort 等級以及系統提示中的指示來引導它。

將工作貫徹到底。 在 low 與 medium effort 的代理式程式設計任務中，模型有時會在工作完成前向您確認。它可能會暫停以確認計畫、提出它自己就能回答的問題，或在完成多部分任務的其中一部分後停下來詢問是否繼續。請先嘗試較高的 effort 等級。若要在不變更 effort 的情況下讓模型持續工作，請將以下內容加入您的系統提示：

Keep working until everything the user asked for is done, and only stop to ask when you can't go on without the user or before a risky step.

When the work the user asked for is done and checked, stop and report. Don't add features, tests, files, docs or refactors that weren't asked for. If you think one would help, mention it at the end instead of doing it.

使用此提示後，模型在 low 與 medium effort 下會貫徹更多工作，因此這些等級的工作階段會執行得更久、成本也更高。此提示並不能取代您自己關於高風險或不可逆操作的規則。請將這些規則保留在您的系統提示中。

程式設計時未經要求的額外內容。 模型傾向於加入符合您儲存庫慣例的測試、文件與小型輔助檔案，即使您沒有要求。它在每個 effort 等級都會這樣做，effort 越高越明顯。所要求的變更本身則會緊貼您的要求。大多數團隊會樂見這一點。如果您偏好將變更限制在明確要求的範圍內，請只加入該提示的第二段，也就是以「When the work the user asked for is done」開頭的那一段。在 xhigh 與 max effort 下，該段落會減少這些額外內容，並讓整體變更更小。

xhigh 與 max effort 下的徹底程度。 在這些等級下，模型特別徹底。完成任務後，它可能會自行展開多輪審查與驗證，如果您的「harness」（執行框架）提供「subagents」（子代理），有時還會使用子代理。它也可能會順手修正途中注意到的相關問題。這會花費更多時間與 token，因此請以 high 或更低等級執行例行工作，在這些等級下這種情況很少見。如果您確實想要這些 effort 等級帶來的額外徹底程度，但希望將其導向任務本身，請將以下內容加入您的系統提示：

When the work the user asked for is done and its checks pass, stop and report. Don't start extra rounds of review or hardening on your own, and don't launch reviewer sub-agents unless the user asked for a review. If you think a deeper review is worth doing, say so at the end.

在 max effort 的程式設計任務測試中，這阻止了模型啟動審查用的子代理，並將工作階段成本降低約三分之一，且品質沒有變化。它會讓主代理自行發起的審查輪次變少，但不會完全消除。

開放式請求。 當請求是開放式的，例如「show me what you can do with this」，模型可能會開始製作簡報、報告或影片，而您其實只想要一些點子。如果您想先得到點子或計畫，請在請求中說明，或將以下內容加入您的系統提示：

When the user asks for ideas, options or a plan, give them that and stop. Don't start building or changing anything until they say to go ahead.

在沒有預先思考的情況下執行

若要在沒有預先思考的情況下執行 Claude Sonnet 5.5，請傳送 thinking: {"type": "between_tools"}。這是此模型上最低的思考設定，且在 high effort 或更低等級下才會被接受。如果您的整合目前在關閉思考的情況下執行，請將其切換為 between_tools，並檢查以下幾點：

• 在 high effort 或更低等級下傳送 between_tools。 在 xhigh 或 max effort 下，帶有 between_tools 的請求會傳回 400 錯誤。使用 between_tools 時，effort 也無法在對話中途變更：與目前生效等級不同的逐訊息 output_config.effort 會傳回 400 錯誤。若要逐回合變更 effort，請使用自適應思考。使用 between_tools 時，請移除任何要求模型不要思考的指示。這類指示會讓模型更有可能在可見輸出中寫出內部 XML 標籤。
• 依區塊類型讀取回應。 使用自適應思考時，回應可能以 thinking 區塊開頭，在預設的 display: "omitted" 下，其 thinking 欄位為空。使用 between_tools 時，回應可能以進度更新 thinking 區塊開頭。請勿假設第一個內容區塊是文字。
• 原封不動地傳回 thinking 區塊。 使用 between_tools 時，模型在工具呼叫之間寫下的筆記，若長度超過一兩句話，仍會以 thinking 區塊的形式傳回。每個區塊都帶有該筆記的摘要。請將它們連同助理回合的其餘部分原封不動地傳回。您傳回的區塊會讓模型取得它所寫的完整筆記，而不是摘要。
• 對於沒有工具的推理任務，請使用自適應思考。 在沒有工具的請求中，between_tools 意味著模型會不經思考直接作答。對於需要幾個推導步驟的任務，請改用自適應思考。請參閱使用 JSON 輸出的推理任務。

使用 JSON 輸出的推理任務

本節適用於您要求 Claude Sonnet 5.5 針對需要幾個推導步驟的任務提供 JSON 答案的情況。例如加總文件中的數字、套用規則，或為項目排序。在這類任務上，模型經常不經思考就直接作答，尤其是在 low 與 medium effort 下。有效的做法取決於您請求 JSON 的方式。在可用的情況下，請使用「structured outputs」（結構化輸出）。如此一來，回應文字就是符合您結構描述的 JSON，無需另行解析。

使用結構化輸出時，回應文字只包含 JSON，因此模型只能在思考中推導問題。當它略過思考時，在這些任務上的準確度可能會降低。以下變更有助於維持高準確度。

要求模型先思考。 使用自適應思考時，請在系統提示的結尾加入這一行：

Think the problem through before you answer.

加入這一行後，模型會更常在作答前思考。在 high effort 下，這一行能讓準確度接近模型在 xhigh 下的水準，而輸出 token 只會適度增加。在 low 與 medium effort 下，它能提高準確度，但達不到模型在 high 下的水準，且輸出 token 的增加幅度較大。

或使用 xhigh effort。 使用自適應思考時，即使沒有這一行，xhigh 在這些任務上也能提供最高的準確度。它使用的輸出 token 比 high 多。

使用自適應思考，而非 between_tools。 在沒有工具的請求中，模型在 between_tools 下不會在作答前思考。這一行在那裡沒有作用，且這些任務的準確度較低。請對這些請求使用自適應思考，並搭配本節中的步驟。在測試中，將請求拆成兩個（一個請求取得答案，另一個請求取得 JSON），能帶來高答案準確度與 JSON 合規性，但成本與延遲非常高。

在 low 與 medium effort 下使用結構化輸出時，模型偶爾會持續思考直到達到 max_tokens。在 high effort 及以上，這幾乎不會發生。請將任何 stop_reason 為 "max_tokens" 的回應視為失敗，即使其文字包含有效的 JSON，並重試。請將 max_tokens 設得足以容納思考與 JSON，如校準 effort 所述，但不要高於您願意為單次嘗試花費的額度。

如果您無法使用結構化輸出，請改為在提示中要求 JSON。此時模型通常會在回應文字中推導問題，並在結尾寫出 JSON。JSON 通常包含正確答案，但預期整個回應都是 JSON 的解析器會失敗。有兩件事會有幫助：

• 解析回應中的最後一個 JSON 值。 只讀取 text 區塊，並將 stop_reason 為 "max_tokens" 的回應視為失敗。從每個 { 或 [ 開始，嘗試解析一個 JSON 值。當某個值解析成功時，從該值的結尾繼續，這樣巢狀於其中的值就不會被單獨計算。保留找到的最後一個值。不要擷取從第一個 { 到最後一個 } 的所有內容。模型偶爾會在最終 JSON 之前寫出草稿，而該範圍會同時包含兩者。如果您的答案是連續的多個 JSON 值，例如每行一筆記錄，請保留最後一段僅以空格、逗號或換行分隔的連續值。檢查結果是否包含您預期的欄位，若沒有則重試一次。在測試中，這讓幾乎每個回應都可使用，且不會改變其準確度。
• 也可考慮搭配自適應思考使用 xhigh effort。 此時模型會在思考中推導問題，且幾乎總是只傳回 JSON。總輸出 token 與 high 時大致相同，因為推導過程從回應文字移到了思考中。

面向使用者的進度更新

在工具呼叫之間，Claude Sonnet 5.5 會寫下面向使用者的筆記，說明它剛發現了什麼以及接下來要做什麼。長度超過一兩句話的筆記會以進度更新 thinking 區塊的形式傳回。較短的說明則維持為 text。在預設的 thinking.display 下，進度更新區塊的文字為空，因此只呈現 text 區塊的用戶端在長時間的代理式回合中可能看起來毫無動靜。這在聊天介面以及使用者即時追蹤模型工作的其他產品中最為重要。

若要顯示這些筆記，請設定 display: "updates"（beta，thinking-display-updates-2026-08-18 標頭）。使用 between_tools 時，筆記會連同其摘要文字一起傳回，因此不需要 display 欄位。between_tools 不接受其他欄位：與其一起傳送的 display、budget_tokens 或 block_binding 會傳回 400 錯誤。遷移指南說明了如何呈現這些筆記。有時模型需要在長回合進行到一半時向使用者顯示確切的文字，例如程式碼片段或需要使用者回答的問題。針對這種情況，請提供它一個用來傳送訊息給使用者的簡單工具。告訴模型只在這類內容時使用該工具。請在工作階段的第一個請求中宣告該工具，這樣 tools 清單之後就不會變更。

接著，移除較舊的指示，例如「hold all findings for the final response」。如果您接著希望在可預期的時間點取得更新，例如在第一次工具呼叫前用一行說明模型即將做什麼，並在結尾提供簡短回顧，請在系統提示中說明。模型會遵循這類指示。在固定時間點提供更新，對「human-in-the-loop」（人機協作）工作最有幫助。

如果長時間的工具呼叫回合仍然沉默得比您希望的更久，您的 harness 可以提示模型提供更新。讓它計算連續幾個沒有向使用者傳送任何文字或進度更新的工具呼叫步驟。在連續數次之後（例如五次），於最新的工具結果之後附加一則單回合提醒。請以回合範圍的系統訊息（beta）傳送，文字類似如下：

The user hasn't heard from you in a while — say in a few words what you're doing, then continue.

如果回合仍然沉默，請在第二或第三次提醒後停止傳送。在工具結果之後頻繁出現的 harness 文字，可能會讓模型懷疑是提示注入，如回合中的使用者訊息所說明。請在後續請求中將每則提醒保留在 messages 中。由於提醒是附加上去的，而不是插入後再刪除，因此提示快取與保留的思考都能保持完整。在 high effort 下，若有可用來傳送訊息給使用者的工具，提醒會讓模型更常向使用者更新進度，並縮短其最長的沉默時段，且任務品質沒有可量測的變化。

聊天與知識工作中的工具使用

在聊天與知識工作任務中，Claude Sonnet 5.5 有時會根據其訓練知識作答，而網路搜尋本可以發現已變更的細節。例如哪些事項是允許的、必要的，或需要收費的。

首先，檢查您的提示中是否有不鼓勵工具使用的措辭，例如「only use tools when strictly necessary」或「minimize tool calls」，並將其移除。接著，如果您的產品為模型提供了搜尋工具，請將以下內容加入您的系統提示：

Use the search tool to check specifics that may have changed since your training, such as what is allowed, required or charged, even when you feel confident. For researched work such as a report or a comparison, gather current sources rather than writing from your training knowledge.

這對研究與支援類產品最為重要，因為這些產品的答案取決於最新的細節。

回合中的使用者訊息

Claude Sonnet 5.5 經過訓練，能抵禦「indirect prompt injection」（間接提示注入），也就是透過工具結果及其在任務期間讀取的其他內容所傳入的惡意指示。有時它會將真正的使用者訊息視為可能的注入。假設使用者在任務進行中輸入的訊息，以緊接在工具結果之後的對話中途系統訊息形式，或在 tool_result 區塊內傳達給模型。此時模型可能會告訴使用者，工具結果中包含冒充使用者訊息的文字，並忽略該訊息或要求使用者確認。

您的 harness 在每個工具結果之後加入的 token 倒數計時可能會導致這種情況。允許使用者在模型進行多步驟回合的途中傳送訊息，或讓您的 harness 在每個步驟的工具結果之後加入指示或上下文，也可能導致這種情況。在每種情況下，文字都會緊接在工具結果之後出現。若使用倒數計時或逐步驟指示，這可能在每次工具呼叫時都發生。偶爾出現的單回合提醒，例如面向使用者的進度更新中的提醒，出現頻率則低得多。如果您看到模型對您自己的提醒產生這種反應，請降低提醒的傳送頻率。若要避免這種誤判：

• 絕對不要將使用者文字放在 tool_result 區塊內。模型最常誤判這種放置方式。
• 以使用者回合傳遞回合中的使用者輸入。將使用者的話語作為文字區塊，附加在承載 tool_result 區塊的使用者訊息中，並放在最後一個 tool_result 之後。
• 將 harness 通知（例如提醒）放在使用者話語之後的獨立對話中途系統訊息中。絕對不要將通知與使用者的話語放在同一個區塊中。
• 在使用者可以於回合中途輸入的互動式工作階段中，不要在工具結果之後加入您自己的 token 或預算倒數計時。「Task budgets」（任務預算）（beta）會加入類似的倒數計時，但尚未觀察到它們導致這種誤判。如果您在設定了任務預算時看到這種誤判，請嘗試在不使用任務預算的情況下執行工作階段。

程式設計任務的驗證

在代理式程式設計任務中，Claude Sonnet 5.5 通常會在回報變更完成前檢查其工作。不過在 low effort 下，它有時會在沒有執行能實際測試該變更的檢查的情況下，就回報變更已完成。例如，它可能因為專案的相依套件尚未安裝而略過專案的測試。

如果您看到變更被回報為已完成，但對話紀錄中沒有測試或建置輸出，請將以下段落（或類似的段落）加入系統提示。在 low effort 下，它能讓略過或流於表面的檢查變得罕見，任務品質沒有可量測的變化，每項任務的成本也只略微增加：

When you change code that can be run, built, or type-checked, run a real check that exercises the change before reporting it done: the project's tests, type-checker, or build, or the changed command itself. A syntax-only check, or a check command that failed to start, does not count; if all that is missing is the project's declared dependencies, install them with its own package manager and lockfile (e.g. npm install, pip install -r requirements.txt), never via sudo or the system package manager, unless told not to. Only if no real check can run here, say which one you did not run and why instead of reporting the change as done.

寬容的工具呼叫處理

Claude Sonnet 5.5 偶爾會以僅大小寫不同的名稱呼叫已宣告的工具，例如以 bash 呼叫 Bash。它也可能以稍有不同的名稱傳遞已知參數。與其將這類呼叫視為致命錯誤，不如讓您的 harness 以下列兩種方式之一處理：

• 當比對結果明確無歧義時，即使大小寫錯誤也接受該呼叫。
• 傳回帶有 is_error: true 的 tool_result，並註明確切的預期名稱。模型通常會在下一個回合修正呼叫。請參閱使用 is_error 處理錯誤。

用於複雜視覺輸入的工具

對於密集的圖表與技術圖面，請為 Claude Sonnet 5.5 提供裁切、縮放或對圖片執行程式碼的方法。有了這類工具，模型讀取這些輸入的準確度會明顯提高。在圖表上，這些工具在每個 effort 等級都有幫助。在技術圖面上，它們只有從 high effort 起才有幫助，且在 xhigh 與 max 時幫助最大。對於圖表，加入工具比提高 effort 更有幫助：在測試中，於 high effort 下使用工具時，模型讀取圖表的準確度高於在 max effort 下不使用工具，而成本只有其一小部分。裁切工具範例提供了可運作的工具定義。

安全防護拒絕

Claude Sonnet 5.5 會執行可能拒絕請求的安全分類器。拒絕會以帶有 stop_reason: "refusal" 的一般回應形式傳回，而 stop_details.category 會指出拒絕類別：

• cyber：該請求可能促成網路危害，例如惡意軟體或漏洞利用程式的開發。允許在原始碼中尋找漏洞。不允許高風險的軍民兩用網路安全工作。
• bio：該請求可能促成生物危害，例如危險的實驗室方法。日常健康與教育性問題不受影響。
• frontier_llm：該請求可能協助開發競爭性的 AI 模型。
• reasoning_extraction：該請求要求模型在回應文字中重現其內部推理。
• general_harms：該請求屬於其他使用政策領域。無害的工作也可能觸發此類別。

如果 bio 分類器阻擋了您組織的生命科學工作，您可以申請生命科學驗證計畫。

如果您開啟伺服器端備援（beta），它會在 Claude Sonnet 5 上重試 cyber 與 frontier_llm 拒絕。它不會重試 bio、reasoning_extraction 或 general_harms 拒絕。請參閱拒絕、備援與計費。

如果您的提示要求模型在回應中包含其推理，請移除這些指示，因為它們會招致 reasoning_extraction 拒絕。使用自適應思考時，請改為從摘要思考區塊（display: "summarized"）讀取推理。