將使用者的請求中的程式碼變更,引導到它應該到達的最終位置,並由另一個模型擔任審查者。使用者決定兩次:在解釋器階段決定方法,以及在發送訊息階段決定結果。中間的所有事情都由你處理。
另一個模型是使用者指定的系列中最新且具有指定努力程度的模型,來自 orchestrator_capabilities。相同的模型和努力程度將用於後續的每一次來回、程式碼循環和審查(關鍵決策的辯論除外)。如果系列或努力程度缺失,請要求使用者提供,並且在他們回答之前不要做任何其他事情。
在第 3 步中,由一個 runner 代替你辯護方法(使用 back-and-forth 技能的 runner)。除非使用者指定了一個 runner:使用最新的 Fable 模型(中等努力程度)與另一個模型辯論;對於關鍵決策,使用最新的 Fable 模型(高等努力程度)與最新的 Astra 模型(高等努力程度)辯論,以取代另一個模型。關鍵決策是指 design.md 中的結構性問題觸發了一個條件,並且你可以提出一個答案可能改變方法的問題。當 runner 或其合作夥伴的模型不可用時,請告知使用者,並親自與另一個模型辯護方法。
1. 目的地與規則
確定變更的最終位置:是經過測試的本機變更、已推送的分支、已開啟的 PR、已合併,還是已部署。僅在不明確且答案會改變工作內容時才詢問。說「看到最後」(see it through)並不批准任何推送、PR 或部署;批准權來自發送訊息。
你正在修改的儲存庫的規則,以及使用者指向的任何流程檔案,若與此技能衝突,則以它們為準。
變更已建置。 當使用者說變更已經完成時,已建置的內容就是方法,而發送訊息就是第一次批准:不要發送解釋器,也不要執行來回討論。取代第 2 和第 3 步:
- 釘選基礎:對於未合併的分支,使用其與目標合併分支的合併基礎(取其最後一次合併該分支之後的狀態);一旦合併,則使用變更前的那個提交。不清楚時請詢問。當變更已合併時,目的地是本次運行後續提交將去的地方;不清楚時請詢問。
- 根據使用者的話語以及變更本身所表達的內容(提交訊息、PR 文字)撰寫請求,並標記你推斷的內容。
- 找出在基礎分支的工作目錄上失敗,但在變更上通過的檢查。從變更已有的測試開始(在僅套用變更的測試和測試工具修補程式的基礎分支上執行它們),並僅為那些沒有被證明的承諾行為撰寫一個檢查;對於沒有顯示失敗的變更,例如效能提升或重構,則撰寫一個檢查其承諾的內容。按照第 2 步的方式設定層級。保留的接受基準線(如第 4 步所保留)應為能夠證明變更所承諾的每個行為的最少數量的檢查,並註明哪些是在變更後撰寫的;變更的其他測試則保留給
simplify.md處理。 - 將方法撰寫為一個檔案:說明更改了什麼、
design.md的基礎及其結構性問題的答案(針對已建置的內容),以及第 3 步的失敗檢查。
然後從顯示重現通過繼續執行第 4 步,並將該基礎分支和該檔案提供給程式碼循環作為其 Approach。發送訊息應說明沒有解釋器被批准,並包含任何結構性替代方案以及任何會改變使用者所獲得的發現。
2. 重現
對於錯誤,在撰寫修復程式之前,先在基礎分支上重現它:一個會失敗的測試,並且(當使用者可以看到該錯誤時)一個顯示它的執行中產品,按照 capture.md 的說明手動捕獲(在驗證流程還無法捕獲時)。對於功能,請撰寫使用者應該看到或能夠執行的內容。當你無法重現錯誤時,請在構建修復程式之前告訴使用者,並將你對此所說的任何內容撰寫為「來自程式碼閱讀(未嘗試)」("from reading the code (not tried)")。一個什麼都沒找到的檢查只有在你看過它在有問題時能找到問題才算數。
不要為你尚未重現的失敗路徑建立防護;將其列在解釋器中作為後續事項。
透過儲存庫的 verify 技能進行重現和證明:儲存庫中的 .agents/skills/verify/,或 AGENTS.md 指定的位置。當沒有 verify 技能,或其不涵蓋你需要的流程時,請手動重現,並將使用 make-verifiable 技能建立相關覆蓋範圍納入方法的一部分。
然後設定層級。完整(Full):當變更的行為涉及持久性、並發、授權、遷移、公開契約、破壞性影響或共享狀態所有權,或者當你無法確定變更的程式碼如何被呼叫或測試的覆蓋程度時;根據你找到的呼叫者和狀態寫入者來判斷,而不是根據檔案名稱。輕量(Light):其他情況。如果一次輕量運行出現了上述任何一種情況,則升級為完整。
3. 設計與解釋器
在選擇方法之前,閱讀 design.md 並執行其要求。在完整運行中,與模型來回討論方法(使用 back-and-forth 技能),並將 design.md 中的比例估計作為其 Context 的待檢查前提,以及將較小版本和「不變更」納入選項;在輕量運行中,僅當 design.md 的觸發條件被觸發或強烈方法有實質差異時才這樣做,否則自行撰寫方法。為 runner 提供 Context,包含你的基礎及其參考、你重現的內容和你僅閱讀的內容,以及一個指向 Session 暫存區或臨時資料夾中記錄的路徑;在 Question(由請求撰寫)中,也請詢問變更的落點(包含呼叫者和相關案例)、接受案例,以及留給你處理的部分。當一個設計問題是可以通過運行某些東西來觀察到的事實時,通過在隔離的簽出或暫存資料中進行一次性實驗來解決,而不是詢問使用者;該實驗不會發布任何東西。
然後撰寫失敗檢查:逐一檢查 code-loop 技能簡要標題中的 Conditions,加上依賴於你正在變更的行為的角色,對於每個適用的條件,命名將涵蓋它的測試或你接受的限制。
向使用者發送解釋器(explainer),使用plain語言,按以下順序使用這些標題。每個事項只說一次。
- 問題(The problem): 使用者今天看到什麼,誰遇到它以及頻率(觀察或估計;沒有報告意味著未知,而非罕見),為什麼它很重要,以及你的重現(有的話附帶捕獲);對於功能,說明今天缺少什麼。當使用者要求此變更時,以他們的話語開頭。
- 發生的原因(Why it happens): 原因,用 plain 術語說明;對於功能,說明今天阻礙了什麼。如果沒有阻礙,則對功能省略此標題。
- 變更內容(What changes): 完成後使用者將看到或能夠檢查的內容,以及超出範圍的內容。如果缺少會改變工作的內容,請在此處提出要求。
- 方法(The approach): 程式碼中更改了什麼以及在哪裡更改,你將如何證明它,包括任何
make-verifiable工作以及哪些檢查隨變更一起發布或保留作為證據,發布和維護它的成本,以及為什麼這對於問題(The problem)下的影響範圍和危害是值得的,以及審查者會關心的失敗檢查條目。 - 權衡的替代方案(Alternatives weighed): 每一個強烈的替代方案,其中每當存在一個可信的方案時,
design.md的結構性選項也包含在內,並說明每個方案被否決的原因。 - 審查者可能會問的問題(What a reviewer may ask): 每個可能出現的問題及其答案。
然後停止:在使用者批准之前不要構建任何東西。任何措辭的plain批准都可以讓你開始構建。任何其他內容都會逐字添加到同一個來回討論中,作為進一步的交換(超過其交換限制),並以修改後的解釋器形式返回;再次停止。在沒有來回討論的輕量運行中,自行修改解釋器並再次停止。
批准涵蓋所撰寫的解釋器。當測試、演示或審查改變了使用者獲得的內容、其可見行為、相容性、範圍、你將採取的發布行動,或解釋器接受的權衡時,引用它偽造的句子,與模型一起解決,發送一個說明更改內容的修改後解釋器,然後再次停止。較小的發現,例如使用不同的內部輔助函數,則放入發送訊息中的 "what changed since" 部分。
4. 建置與證明
在更改行為之前,保留重現以及在變更存在之前可以運行的每一個接受檢查:提交解釋器發布的那些,並將其餘的保存(如果沒有要提交的內容,則全部保存為儲存庫外部的修補程式)。它們共同構成接受基準線,並且所有檢查都將在最終候選版本上重新運行:之後對它的任何編輯都將進入程式碼循環和發送訊息,並附帶其差異以及它是否改變了承諾的行為。
按照 design.md 設定的順序建置已批准的方法。當變更更改了 verify 技能涵蓋的流程時,在同一變更中更新該流程。證明第 2 步的重現通過,透過 verify 技能,並在使用者能看到時在執行中的產品中證明。然後按照 simplify.md 的說明簡化差異。然後與模型在完整差異上運行一個程式碼循環(使用 code-loop 技能),將使用者的請求(或代表它的簡要說明)作為 Request,解釋器作為 Approach(有的話包含 runner 的記錄),接受基準線作為 Acceptance,以及層級。
在最終候選版本上,當使用者可以看到或執行變更的內容時,透過 verify 流程捕獲它,如果無法捕獲則使用 make-verifiable 擴展流程;對於錯誤,透過相同的流程捕獲基礎分支上的相同場景,以便前後匹配。按照 capture.md 的說明選擇、製作和審查捕獲內容,並檢查它是否顯示了你將說它顯示的內容。捕獲顯示變更,檢查證明它,因此基礎分支或失敗運行的捕獲永遠不能作為通過。沒有可顯示內容的變更不需要捕獲。
5. 撰寫文件
根據專案的模板草擬 PR、Issue 或發布文字,如果模板有空間則將捕獲內容放入其中,否則放在它們自己的標題下。在 GitHub 上,發布時使用 gh pr create --attach(或 gh pr edit)附加它們,除非儲存庫有自己的工具;當命令以非零狀態退出時,在重試之前檢查 PR 是否已存在。在任何包含事實的公開文字(描述、回覆、狀態更新)發布之前,由模型的新的審查者根據證據、捕獲內容(作為其幀和節奏報告的錄製)以及差異進行檢查:每個聲明都必須為真且有根據,每個勾選的方塊都必須為真。刪除證據不支持的主張;不要添加修飾性語言。
在每次推送之前,重新運行每個勾選方塊和每個聲明背後的檢查,並重新製作每個可能受變更影響的捕獲內容。
6. 發送訊息
向使用者發送:對解釋器的兩三句摘要、自那時以來的變更、證據、捕獲內容、撰寫的文件、差異,以及批准後你將採取的確切行動。當程式碼循環結束時存在未解決的爭議時,以它們開頭:每個主張,每方展示了什麼,以及批准後會發布什麼。在發送之前,重新執行 design.md 的重疊檢查。在使用者批准之前停止。
7. 到達目的地
採取已批准的行動,然後將變更帶到其目的地:
- 在每次推送之前以及在對通知採取行動之前,獲取遠端最新狀態並檢查變更的當前狀態。基於他人的推送進行建置,比較樹而不是提交雜湊;不要用過時的本機版本取代他們的工作。當變更被合併、關閉或被其他人的版本取代時,將到達目的地的內容與你最後驗證的版本和未解決的發現進行比較。報告哪些內容不同或沒有成功送達,但不要重新添加他們有意移除的內容。
- 每個審查發現(內聯或在審查主體中),都需完整閱讀,並得到一個修復或一行原因的解釋;在基礎分支上也發生的發現,按照
code-loop對既有發現的判斷方式處理。改變行為的修復需要進行程式碼循環。 - 當事實證明已發布的文字有誤時,修正該文字。
- 改變範圍或方法的請求將回到第 3 步,並且在建置後進入一個新的發送訊息;影響範圍超出此變更的請求,在收到時通知使用者,並附上其連結:在此處執行不代表在其他地方也執行。
- 對於部署,針對已部署的內容運行 verify 流程。
8. 經驗教訓
當使用者、PR 審查者或發布後的任何事物發現了一個程式碼循環未捕獲的問題,或者程式碼循環發現了一個阻塞點(或應該發現),在你的修改的儲存庫中的 .agents/lessons/log.md 新增一個條目;對於使用者不擁有的儲存庫,則在存放其流程的資料夾中新增。每個條目:日期、變更、被誰發現了什麼、模組、錯誤類別以及原因。
然後閱讀日誌。一個檢查可以捕獲的教訓,如果出現兩次,就變成一個 lint、型別、測試或 verify 檢查;一個需要判斷力的教訓,如果出現兩次,就變成儲存庫中 AGENTS.md 的一行;一個模組中有兩個條目,或任何模組中有兩個相同錯誤類別的條目(例如在 await 期間另一個操作更改的狀態),就變成一個結構性問題,在提出任何重構之前先命名它們的共同原因。在你的最終訊息中將每個列為後續事項;重構作為其自己的 see-it-through 運行。
當變更到達其目的地時,或者當你已報告確切的阻塞點和剩餘事項並且已撰寫(如果需要)經驗教訓條目時,完成。