為AI編程代理編寫規範説明書

隨着AI編程代理從單純的問答工具演變為能夠直接編輯倉庫、運行命令、創建分支並請求人工審查的主動執行者，編寫規範説明書的重要性空前提升。這要求我們重新思考提示詞的設計——當代理操作共享代碼庫時，提示詞不再是私人筆記，而是一份公開的任務分配書。

一份良好的編程代理規範不應冗長，但必須清晰傳達五個核心要素：任務背景（為何要做）、需要改變的行為、必須保留的約束、定義正確性的示例或場景，以及審查者應檢查的驗證證據。這五個要素構成了規範驅動開發、行為場景、問題模板、輕量設計文檔等各種方法論的基礎。無論採用何種框架，關鍵在於規範能為代理提供足夠的上下文來行動，同時為團隊提供足夠的結構來審查結果。

規範與提示詞的本質區別在於：提示詞擅長啓動工作，但容易消失在會話歷史中；規範則承載任務，成為團隊持續可見的審查對象。私人提示可能包含縮寫、缺失上下文和未言明的假設，這在小範圍解釋或一次性腳本中尚可接受，但對於團隊工程而言，它們難以與拉取請求對比，也無法幫助後來者理解變更原因。規範則讓任務分配具有可見的形狀，可以在實現前、中、後持續被團隊檢視。

最強有力的規範如同小型行為契約。需求説明系統應做什麼，場景提供具體示例（通常採用Given/When/Then格式），設計説明和任務清單描述技術方案。這種分離是AI輔助工程中最有用的紀律之一。如果意圖與實現過早混合，代理可能誤優化實現細節而忽略真正需要的行為。分配層將三個問題清晰區分：何種行為應改變？哪些約束或示例定義正確性？當前合適的實現路徑是什麼？實現可隨代理閲讀代碼庫而演進，但需求應保持穩定以供審查。

以修復測試為例，一個私人提示“修復不穩定的登錄測試並更新需要修改的地方”過於模糊。更好的規範會縮小範圍：明確觀察到的問題（回調請求到達時會話記錄尚不可見）、期望行為（創建單個會話並重定向）、約束（不削弱認證檢查、不添加sleep）、驗證方式（運行受影響的測試）。這並非去除判斷，而是為代理設定邊界，為審查者提供對照依據。

規範驅動的開發不必然等同於瀑布模型——只要團隊保持規範輕量、可迭代、優先用於已有代碼。規範應隨着實現學習而調整：如果探索發現初始方案錯誤，設計應改變；如果需求過寬，範圍應縮小；如果場景暴露了新邊緣情況，規範應納入該場景。紀律不在於“編碼前寫出完美計劃”，而在於“保持可見的意圖與實現的現實同步演進”。

有了可見的任務分配，審查者的關注點從“這個差異看起來對嗎？”轉變為“這個差異是否滿足我們約定的行為變更，在指定的約束下，並附有可檢查的證據？”這是一個更好的問題。規範不僅幫助代理開始工作，更幫助團隊保持對齊。

AI編程會話是臨時的，但代碼倉庫是永久的。將規範存入倉庫，按功能或變更組織，並隨代碼更新，使其成為對人和代理都有用的持久上下文。代理的上下文容易丟失——聊天記錄被清除、上下文窗口填滿、執行者可能不同——而規範為意圖提供了持久家園。它們不替代代碼、測試或文檔，而是將它們連接起來。

規範最適用於有明確邊界的工作：行為變更、錯誤修復、兼容性更新、小功能、遷移步驟、CI修復或具有清晰約束的窄重構。在這些場景下，團隊可以描述期望的變更並檢查結果是否匹配。隨着AI編程代理能力持續增強，保留代理人應滿足的任務分配變得愈發重要。這一原則超越了任何特定工具：如果代理作用於共享代碼，其規範與結果都應能被團隊審查。