1. 在增加提示詞之前,先選擇模型和工作量
想像一下,POST /pedidos 收到 {"數量": -1} 並返回 201 Created。在這個教學範例中,合約要求數量必須為正,並預期在這種情況下返回 400 Bad Request。我們需要修正驗證邏輯,同時確保有效訂單的建立功能正常運作。
首先,檢查三個不同的項目:
配置:Claude Code 版本,已安裝的程式和可用資源,可在終端機使用 claude --version 檢查。
模型:誰接收並解決任務,可在會話中透過 /model 檢查。
工作量 (Effort):請求的推理和執行所需的工作量,可在會話中透過 /effort status 檢查。
這篇文章的靈感來源強調了一個具體變化:Anthropic 的評估顯示,Opus 5.5 在 medium 工作量下,在程式碼和知識工作方面與 Opus 5 在 high 工作量下表現相當或更優。將舊配置載入新版本可能不再是個好選擇。這並不是我們專案的基準測試。來源:模型和工作量配置。
根據 2026 年 11 月 12 日查閱的文件,opus、sonnet 和 haiku 在 Anthropic 的 API 中解析為 5.5 系列。其他供應商可能使用較舊的版本。Opus 5.5 需要 Claude Code v2.1.280+,Sonnet 5.5 需要 v2.1.284+,Haiku 5.5 需要 v2.1.293+。若要重複比較,請記錄完整的 ID。供應商表格。
模型和工作量不是同一個槓桿。模型定義了能力;工作量影響它在回合中投入多少工作,包括調查和驗證。更高的工作量可能產生更多代幣和等待時間。它沒有設定固定的花費上限。Anthropic 的解釋。
在範例 API 中,我會使用以下初始參考作為測試假設:
情境:提取欄位並定位已知消費者
初始組合:Haiku 5.5, medium
原因:範圍受限的搜尋,易於驗證的結果
情境:使用可重現的測試修正驗證
初始組合:Sonnet 5.5, medium
原因:實作範圍和驗收標準明確
情境:調查具有競爭假設的迴歸
初始組合:Opus 5.5, medium
原因:診斷需要交叉驗證證據
情境:診斷仍無定論
初始組合:比較 Opus 5.5 的 medium 和 high
原因:檢查深入探討是否能改善解決方案
實務上:如果測試已經顯示缺少驗證,Sonnet 在 medium 工作量是我的起點。如果錯誤只在兩個同時請求時出現,我需要調查並發性:那時我會測試 Opus,從 medium 開始。任務的不確定性指導了選擇。
要在終端機中開啟實作會話:claude --model claude-sonnet-5-5 --effort medium。5.5 系列的規模包括 low、medium、high、xhigh 和 max。從預設開始,當調查中出現具體空白時再增加。
若要更改,請使用 /effort high;直接選擇會為該模型儲存偏好設定。CLAUDE_CODE_EFFORT_LEVEL 變數可能會覆蓋此設定,且組織政策可能會限制級別。級別和優先順序。
一個版本細節:在 Claude Code v2.1.311+ 中,ultrathink 有特殊處理,在支援的情況下可以將該回合提升到 xhigh。think 和 think hard 是普通文本。所有這些詞都失去效果的說法已經過時了。當前語義。
2. 給予工作合約和簡短地圖
與其從「深入分析並遵循所有最佳實踐」開始,不如描述需要改變的行為:
任務:POST /pedidos 接受數量 -1 並返回 201。合約規定非正數數量應返回 400;修正驗證。首先,編寫一個重現失敗的測試。限制:保留合約中規定的欄位和狀態。有效訂單應繼續返回 201。不要更改資料庫架構。
這樣,測試在修正前會失敗,修正後會通過;相關驗證會通過,並且可以審查差異。如果缺少合約資訊,請在更改之前提出疑問。這給予代理一個可執行的任務,並允許審閱者檢查結果。若要在沒有現成儲存庫的情況下進行實驗,請將以下檔案儲存為 pedidos_test.go。它包含處理器和測試,並且只使用 Go 的標準函式庫。
完整範例:一個檔案中的處理器和測試
package pedidos
import (
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
)
func novoHandler(criar func()) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
var pedido struct {
Quantidade int json:"quantidade"
}
if err := json.NewDecoder(r.Body).Decode(&pedido); err != nil {
http.Error(w, "JSON 無效", http.StatusBadRequest)
return
}
// 修正:在副作用發生前拒絕。
if pedido.Quantidade <= 0 {
http.Error(w, "數量必須為正", http.StatusBadRequest)
return
}
criar()
w.WriteHeader(http.StatusCreated)
})
}
func TestCriarPedido(t *testing.T) {
casos := []struct {
名稱, 主體 string
狀態, 創建數 int
}{
{"負數", {"數量":-1}, 400, 0},
{"零", {"數量":0}, 400, 0},
{"正數", {"數量":1}, 201, 1},
}
for _, caso := range casos {
t.Run(caso.名稱, func(t *testing.T) {
創建數 := 0
handler := novoHandler(func() {
創建數++
})
req := httptest.NewRequest(http.MethodPost, "/pedidos", strings.NewReader(caso.主體))
req.Header.Set("Content-Type", "application/json")
res := httptest.NewRecorder()
handler.ServeHTTP(res, req)
if res.Code != caso.狀態 {
t.Errorf("狀態:預期 %d,收到 %d", caso.狀態, res.Code)
}
if 創建數 != caso.創建數 {
t.Errorf("創建數:預期 %d,收到 %d", caso.創建數, 創建數)
}
})
}
}
在儲存檔案的目錄中執行:go test -v pedidos_test.go。若要重現錯誤,請暫時移除 if pedido.Quantidade <= 0 區塊並重複指令。負數和零的案例會失敗:收到 201 並建立訂單。恢復驗證並再次執行:三個案例都通過了。測試同時檢查狀態和副作用;在建立訂單後返回 400 並不能解決問題。
我為這篇文章在本地驗證了這個循環:沒有驗證時,兩個案例失敗;有驗證時,三個案例都通過了。這是一個 HTTP 行為的演示,沒有資料庫、身份驗證或生產伺服器。在實際的 API 中,請保持其他欄位有效,以便錯誤因您正在測試的原因而發生。CLAUDE.md 透過專案相關的內容補充了這個請求:測試指令、自訂慣例和規則路徑。
無需重新說明 Go 的運作方式或複製所有文件。官方建議將其保持在 200 行以下。Imports @ 載入內容;使用 imports 分割文件並不會消除其上下文成本。在有意義時使用指標和路徑規則。記憶體和規則。
計畫模式 (Plan Mode) 對於在編輯之前探索廣泛的變更仍然很有用。它控制工作階段和可用工具;它不會增加工作量。對於這個範圍受限的錯誤,我會從測試開始。最佳實踐。
3. 當研究阻礙修正時,將其分開
如果發現消費者需要閱讀數十個檔案,這種探索可能會佔用整個對話。子代理可以在單獨的上下文中進行研究並返回相關證據。對於短暫的搜尋,開啟另一個代理可能會增加協調成本,而不是帶來好處。在 .claude/agents/contratos-api.md 中的一個教學定義:
---
name: contratos-api
description: 調查端點的消費者而不編輯檔案。
tools: Read, Grep, Glob
model: haiku
effort: medium
---
識別所請求端點的欄位、狀態和消費者。返回每個證據的檔案和行號,並聲明空白。請求:「使用 contratos-api 調查此端點的消費者;返回觀察到的合約和未能確認的內容。」
在這種情況下,一個有用的回應是:「合約規定非正數數量應返回 400,有效訂單應返回 201。我找到了網頁消費者,但未能確認行動應用程式的行為。」這是一個說明性回應;在實際執行中,它需要提供證據的檔案和行號。這個空白在審查中應該仍然可見。在這裡,模型的選擇是明確的,工具只允許讀取。
別名伴隨供應商;當需要重現測試時,請固定完整的 ID。子代理也會消耗配額:保留主要對話並不意味著消除這種消耗。子代理配置。
也不要假設工作量會一直被繼承。如果沒有自己的配置,在相同模型中它會跟隨會話的選擇;在另一個模型中,這種選擇不適用。當需要控制此選擇時,請聲明工作量,並在 /tasks 中檢查模型。工作量規則。
4. 讓代理證明它已完成
在我們的 API 中,一個有用的交付成果會顯示三個證據:測試重現了問題,修正後通過了,並且相關驗證已在最終程式碼上執行。「審查兩次」並不能定義這些證明中的任何一個。若要自動繼續直到終止條件,/goal 接受一個目標,例如:
/goal 修正端點並包含迴歸測試。證明:執行專案的驗證並將指令、退出碼和結果摘要帶入對話。保留公共合約和資料庫架構。在 15 個回合後,如果沒有證明,則停止並報告阻塞。/goal 的評估器會讀取對話;它不會自行開啟檔案或執行指令。因此,證明需要出現在歷史記錄中。目標中寫入的回合限制由評估器解釋,而不是嚴格的執行上限。此功能也會消耗代幣,並且不會更改權限。/goal 的運作方式。
在審查中,我會要求:執行的測試名稱、前後結果,以及程式碼在上次執行後是否發生變化。這允許在不接受「現在它有效」作為證明的情況下檢查交付成果。關鍵限制需要除了文本之外的控制。PreToolUse 命令掛鉤可以在執行前以退出碼 2 阻止呼叫,並在 stderr 中解釋原因。它的有效性取決於它能夠識別和攔截的動作;命令過濾器本身並不能保護所有資料庫存取。掛鉤合約。
這是 Birgitta Böckeler 的「線束工程」(harness engineering) 中指南和感測器的實際應用:指令提供指導;控制和驗證提供關於發生了什麼的回饋。
如何檢查消耗而不混淆代幣和帳戶
完成一次嘗試後,開啟 /usage。會話區塊會顯示每個模型的代幣,包括輸入、輸出、快取讀取和寫入,以及持續時間和預估成本。在 Pro 方案中,美元價值不是額外收費:螢幕還會顯示方案限制。對於 API 計費,請檢查供應商。消耗參考。
在比較時,每次嘗試儲存一行:任務 | 模型/版本 | 工作量 | 通過? | 各類代幣 | 預估成本 | 持續時間 | 嘗試次數 | 人工干預。
使用相同的程式碼初始狀態、提示詞、測試、技能和工具。Ab