本文最初發布於 getlockstep.dev。當一個程式碼代理收到修改結帳重試機制的提示詞時,該提示詞可能包含功能需求、貼上的架構文件、兩份事件摘要、完整的風格指南、近期 Slack 訊息,以及昨日的除錯會議記錄。其中一個關鍵限制,是第二份事件摘要中的一行文字:第三次支付嘗試可能導致某供應商重複扣款。
儘管代理擁有的上下文資訊比以往任何時候都多,它仍然可能錯過真正重要的事實。上下文工程並非將所有資訊都塞入上下文視窗,而是選擇最小且最有用的資訊集,為每種上下文提供可靠的歸宿,並在任務需要時進行檢索。
提示詞應該引導代理,而不是成為團隊的整個知識系統。將任務放入提示詞中,提示詞應回答以下問題:我們想要什麼結果?範圍是什麼?目前已知有哪些限制?完成的定義是什麼?代理在行動前應該檢查什麼?
例如:「更新供應商 A 的結帳重試處理。範圍:services/checkout 及其測試。完成條件:重複扣款測試通過,現有供應商 B 的行為不變,且計畫中需指出與已接受支付決策的任何衝突。編輯前:請閱讀支付規則和當前供應商 A 的決策。」不要貼上所有可能相關的文件,而是引導代理指向來源,並在關鍵時刻要求檢索。
將穩定的專案上下文放入檔案中。版本控制的指令檔案適用於團隊在多次會話中會重複使用的資訊,例如:建置和測試指令、儲存庫佈局、程式碼和審查慣例、嚴格的專案邊界,以及指向決策和更深入文件的簡短指標。
例如,關於支付的規則可能包含:「使用 pnpm test payments 執行重點測試。切勿自動重試非冪等(non-idempotent)的扣款。在更改供應商流程前,請閱讀 docs/adr/ 中相符的已接受記錄。」Claude Code 會讀取專案的 CLAUDE.md,並支援 .claude/rules/ 中的路徑範圍檔案。
Cursor 則支援 .cursor/rules 和 AGENTS.md。兩者都建議使用重點明確的指令,而非大量複製的手冊。判斷標準是穩定性,如果某項內容每天都在變化,它就不屬於啟動檔案。
將未完成的工作放入交接檔案。對話歷史記錄包含探索過程,而交接檔案則包含當前狀態。
例如,一個結帳重試交接檔案可能包含:「已完成:重現重複扣款、新增供應商 A 測試夾具。下一步:更改重試分類器、重新執行 pnpm test payments。限制:供應商 B 保持三次重試、當前供應商 A 決策:PAY-18。開放風險:手動恢復路徑沒有整合測試。」
交接檔案應該是暫時性的,任務完成後應關閉或移除,以避免下一個代理遵循過時的步驟。Anthropic 對於長期運行代理的指導也基於同樣原因,建議使用持久的進度產物和乾淨的狀態:一個全新的上下文視窗需要的是先前工作的結果,而不是達到該結果所使用的每個 token。
從即時系統檢索不斷變化的事實。部署狀態、事件狀態、工單歸屬、當前服務健康狀況和客戶配置變化太快,不適合複製到記憶體中。請透過工具或 MCP 連線使用原始來源,並在事實成為行動驅動因素時進行查詢。
一份靜態筆記可能在回滾很久之後仍顯示測試環境運行 v2 版本,而即時部署來源則能回答當前正在運行的版本,並附帶其時間戳和範圍。將檢索指令保留在專案檔案中,並將事實保留在擁有它的系統中。
將已接受的選擇放入團隊記憶體。團隊決策與規則和事實不同。「合併前運行測試」是一條規則。「測試環境運行 v2」是一個當前事實。「在客戶 A 退出舊 API 之前保持雙寫」則是一個決策。
決策記錄應包含:已接受的選擇、理由和限制、被拒絕的選項、所有者和日期、受影響的範圍、狀態,以及替換連結。這可以避免搜尋結果將提案和已接受的答案作為同等上下文呈現。儲存庫的 ADR(架構決策記錄)適用於程式碼庫內部的架構,而跨儲存庫的產品和工程選擇則需要一個所有代理都能查詢的共享系統。
即時載入大型上下文。Anthropic 將上下文描述為一種有限的資源。工具定義、檢索到的文件、對話歷史記錄、指令和輸出都在上下文視窗內競爭。請使用漸進式檢索:載入簡短指令和任務。搜尋索引或來源以查找可能相關的資料。閱讀匹配的記錄。遵循連結以查找當前的替代方案。僅在計畫需要時才提取大型參考資料。這比在代理了解哪個子系統重要之前就載入整個維基百科更可靠。來源:AI 代理的有效上下文工程。
使用子代理保護主要上下文。一個專注的子代理可以檢查大型日誌、儲存庫區域或研究語料庫,並返回相關結果。這將原始資料排除在主要任務的上下文之外。
在以下情況下使用子代理:搜尋空間很大、任務可以明確界定、主要代理需要的是發現結果,而不是每個原始 token。不要將子代理作為所有權的替代品。最終計畫仍需要一個代理或一個人根據當前決策來協調所有發現。
有目的的壓縮。長時間的會話最終會被壓縮。Claude Code 可以自動或透過 /compact 指令進行有重點的摘要。例如,/compact preserve the current checkout plan, failed approaches, Provider A constraint, tests run, and the next exact step。
專案根目錄指令和多個啟動上下文機制在壓縮後會重新載入。僅限對話的細節可能只以摘要形式保留。如果某個限制必須跨會話和人員持續存在,請將其提升到正確的持久儲存位置,而不是僅僅依賴摘要。來源:Claude Code 上下文視窗。
實際任務的上下文預算。以支付重試更改為例:啟動時載入:根專案指令、支付路徑規則、工具名稱(而非完整的工具結果)。提示詞中包含:確切的結果、範圍內的檔案或服務、驗收標準、檢查當前支付決策的指令。
按需檢索:當前供應商 A 決策、匹配的事件詳細資訊、相關程式碼和測試、即時供應商配置。任務期間寫入:任務系統中的計畫和所有權、如果未完成則為交接檔案、如果當前決策必須更改則為新的決策提案。除非需要,否則不載入:不相關的事件、完整的儲存庫維基、舊的會議記錄、所有支付 ADR。
常見錯誤。將提示詞視為長期記憶:下一個會話可能不會收到它。將重複的指令和已接受的選擇移至持久來源。將檔案視為即時事實:靜態副本會過時。查詢擁有變更狀態的來源。
在每個會話中載入所有規則:使用範圍和相關性。過多的指令可能會產生衝突並降低遵守度。使用沒有生命週期欄位的搜尋:相似性找到的是相關文本,而非當前權威。決策需要狀態和替換連結。只儲存輸出而不儲存所有權:沒有所有者的筆記無法告知下一個代理誰可以確認或更改它。
相關指南。關於代理為何會遺忘以及解決此問題的記憶層,請從 AI 程式碼代理記憶指南開始。對於更廣泛的市場,請參閱 AI 程式碼代理上下文的最佳工具。對於儲存邊界,請比較 CLAUDE.md 和代理記憶體。對於即時協議選項,請參閱工程團隊的最佳 MCP 伺服器。對於持久的團隊選擇,請比較產品和工程的最佳決策日誌工具。
Lockstep 的定位。Lockstep 是上下文堆疊中已接受產品和工程決策的共享歸宿。提示詞可以命名任務。檔案可以引導代理。交接檔案可以承載未完成的狀態。MCP 可以檢索即時事實。
當代理即將更改受影響的工作時,Lockstep 提供當前的選擇、理由、被拒絕的選項、所有者、範圍和狀態。良好的上下文工程並非讓單一機制記住所有內容,而是讓代理在正確的時間從正確的來源獲得正確的上下文。