1. CLI捕獲工具是一個本地腳本，它通過調(diào)用Foundation API來保存會話記錄，而不是作為一個Worker來運行。
   影響程度：高
   如果你希望采用純服務(wù)器less架構(gòu)，請修改這一設(shè)計。

2> 會話記錄的導入是手動進行的，而非自動批量導入。
   影響程度：高
   如果你希望實現(xiàn)自動背景捕獲功能，請修改這一設(shè)置。

3> .jsonl文件名中的會話ID被用作去重鍵。
   影響程度：中等
   如果你的數(shù)據(jù)存儲方案中會話ID的存儲方式不同，請相應(yīng)地調(diào)整代碼。

4> 在當前版本中，不會對會話記錄中的敏感數(shù)據(jù)進行清洗處理。
   影響程度：中等
   如果你的會話記錄包含密碼或密鑰等敏感信息，請修改相關(guān)邏輯。

在讀了這十二個字之后，立刻就有四個決定浮現(xiàn)出來——其中三個決策實際上對建筑設(shè)計產(chǎn)生了直接影響。

第三個假設(shè)（“.jsonl文件中的會話ID就是去重鍵”）很可能會引發(fā)最隱蔽的錯誤。如果代理程序根據(jù)文件名來執(zhí)行去重操作，那么在會話名稱被更改之前，這種機制應(yīng)該是可以正常工作的。而在任何代碼被編寫出來之前，規(guī)范文檔就已經(jīng)發(fā)現(xiàn)了這個問題。

如何閱讀輸出結(jié)果

輸出結(jié)果的閱讀順序應(yīng)該是：首先查找[ASSUMPTION: ...]標簽，然后再閱讀與任務(wù)相關(guān)的內(nèi)容。

閱讀假設(shè)條件

每個[ASSUMPTION: ...]標簽都標志著代理程序在哪些地方根據(jù)用戶未明確指定的內(nèi)容進行了自動填充。你的任務(wù)是仔細閱讀這些假設(shè)條件，并針對每一條做出如下判斷：

• 正確：該假設(shè)條件是正確的，保留原樣即可。

• 需要修改：該假設(shè)條件有誤，需要重新表述假設(shè)內(nèi)容并重新運行測試流程。

• 暫不處理：對于當前迭代來說，這個假設(shè)條件并不重要，可以直接跳過它繼續(xù)下一步。

影響程度的評級會告訴你哪些假設(shè)條件需要在開始編碼之前先進行修正。影響程度較高的假設(shè)條件會影響到系統(tǒng)架構(gòu)或數(shù)據(jù)模型；如果這些假設(shè)有誤，修改它們會導致整個系統(tǒng)需要重新設(shè)計。而影響程度較低的假設(shè)條件則會影響那些日后容易更改的行為細節(jié)。

閱讀驗收標準

以“Given/When/Then”格式編寫的驗收標準是規(guī)范文檔中用于檢測范圍錯誤的最有用部分。閱讀每一條驗收標準后，要問自己：這確實是我想要測試的內(nèi)容嗎？

驗收標準的性質(zhì)本質(zhì)上是二元的。“未認證時返回401狀態(tài)碼”屬于明確的驗收標準，而“運行正常”則不屬于。如果你在閱讀某條驗收標準時覺得“這個標準其實并不明確”，那么這說明這條標準背后隱藏著某種假設(shè)條件，你需要重新表述這條標準。

閱讀任務(wù)內(nèi)容

這些任務(wù)都是按順序排列的，并且每個任務(wù)都能產(chǎn)生可驗證的結(jié)果。在將任何任務(wù)交給代理程序執(zhí)行之前，請先檢查以下兩點：

1. 該任務(wù)是否包含了所有必要的上下文信息？如果任務(wù)要求“遵循現(xiàn)有的認證機制”，但你還沒有向代理程序提供相應(yīng)的認證代碼，那么代理程序就會自行猜測。

2. 該任務(wù)的驗收標準是否與你實際想要測試的內(nèi)容一致？如果驗收標準不夠明確，請在代理程序開始執(zhí)行任務(wù)之前將其細化。

如何將規(guī)范文檔交給代理程序

規(guī)范文檔本身就包含了完成任務(wù)所需的所有上下文信息，它并不需要用戶另行提供提示或說明。當為某個任務(wù)啟動代理程序會話時，請將相關(guān)的規(guī)范內(nèi)容與任務(wù)描述一起提供給代理程序。

以上面例子中的任務(wù)1為例，你的代理程序會話可能會這樣開啟：

上下文信息：
- 該系統(tǒng)是一個基于Cloudflare Workers、D1和Vectorize構(gòu)建的聯(lián)邦知識庫。
- 會話數(shù)據(jù)以.jsonl文件的格式存儲在~/.claude/projects/目錄下。
- API接口的地址為https://.workers.dev。

規(guī)范內(nèi)容：
[粘貼SPEC和PLAN部分]

任務(wù)內(nèi)容：
[粘貼任務(wù)1的具體要求]

上述示例僅用于說明目的。請將其替換為您自己項目所使用的技術(shù)棧、文件路徑以及API地址。關(guān)鍵在于要讓代理在第一天就能獲得與新團隊成員相同的開發(fā)環(huán)境信息。

現(xiàn)在，代理已經(jīng)掌握了需求信息、架構(gòu)背景，以及一項具有明確驗收標準的具體任務(wù)。由于規(guī)范中已經(jīng)明確了相關(guān)細節(jié)，因此它不可能錯誤地判斷去重鍵的值；同時，由于驗收標準有明確要求，它也不能忽略錯誤處理環(huán)節(jié)。

這就是該規(guī)范所設(shè)計的目的——它并非取代代理的工作，而是將決策權(quán)從代理手中轉(zhuǎn)移到您的手中，在工作開始之前就為所有事項制定明確的規(guī)則。

保存規(guī)范以備后續(xù)使用

如果您希望采用“以規(guī)范為導向的開發(fā)模式”，即讓規(guī)范存儲在代碼倉庫中，那么請將生成的結(jié)果文件保存到項目中的specs/目錄下：

# 創(chuàng)建spec目錄
mkdir -p specs
 
# 保存您的規(guī)范文件
# 將輸出內(nèi)容粘貼到specs/cli-capture.md文件中

當需求發(fā)生變化時，只需更新規(guī)范文件，然后重新讓代理根據(jù)新的規(guī)范來調(diào)整開發(fā)工作。此時，規(guī)范才是權(quán)威依據(jù)，而非代碼注釋。

下一步該怎么做

在編寫任何代碼之前，先在下一個功能開發(fā)項目中嘗試使用這種規(guī)范編寫方式。規(guī)范中指出的那些問題會幫助您發(fā)現(xiàn)一些尚未被意識到的問題——而在將任務(wù)交給代理之前糾正這些高影響性的錯誤，正是這一方法的核心意義。如果跳過這個步驟，就相當于直接讓代理隨意決策。

如果您的項目規(guī)模正在擴大，建議盡快采用“以規(guī)范為導向的開發(fā)模式”。請將所有規(guī)范文件保存在代碼倉庫的specs/目錄下。這樣，當有新成員加入團隊或代理開始新的工作流程時，他們可以直接參考這些規(guī)范來開展工作，而無需花費時間去反推代碼實現(xiàn)細節(jié)。

目前，這種開發(fā)模式面臨的最大挑戰(zhàn)在于有人認為過于詳細的規(guī)范實際上會變成代碼本身。如果您的規(guī)范文件中包含了具體的實現(xiàn)細節(jié)，那就意味著您已經(jīng)越過了合適的界限。應(yīng)該把決策權(quán)保留給自己，只規(guī)定“只有經(jīng)過身份驗證的用戶才能執(zhí)行某項操作”，而將具體實現(xiàn)工作交給代理來完成。規(guī)范的作用應(yīng)該是指出那些代理可能會犯錯的環(huán)節(jié)，而不是詳細描述功能的實現(xiàn)過程。

目前，《Agent Skills》標準已適用于Claude Code、GitHub Copilot、Cursor以及Gemini CLI等工具。規(guī)范編寫工具的代碼倉庫地址為github.com/dannwaneri/spec-writer。

確實，我們在Claude項目中投入了64%的資源來開發(fā)這個工具，但這一努力確實取得了成效——通過這個規(guī)范，我們從一個短短12個字的提示中得出了4項重要的決策。其中第4項關(guān)于去重鍵的假設(shè)，如果處理不當，可能會導致程序出現(xiàn)錯誤，而這種錯誤在會話名稱被更改之前是無法被發(fā)現(xiàn)的。

這不是幻覺，而是代理確實發(fā)揮了它所能發(fā)揮的最大作用。

正是通過規(guī)范，我們才能真正提升“輔助工具”的效用水平。