caohaotiantian/三迴圈工作流程

三迴圈工作流程 是做什麼的？

規劃 → 建置 → 結案，深度根據風險程度選擇。

負責指定的實作：其規劃、變更、證據、審查與修復。 實作者可以是上層或指定的執行者。 當存在協調者時，將任務分配、相依性、共用介面與整合所有權留給它。 向該協調者請求必要的角色或排程變更。不要遞迴地協調其他任務。 透過協調者傳遞使用者決策請求。 若無協調者，直接管理變更與必要的角色。 實作深度與執行模式是分開的。直接執行並不會免除必要的審查。

硬性限制，唯一不是預設值的規則：

1. 超過 Direct 的變更必須由未參與撰寫的 context 審查；只有在沒有可用的 context 時，交接文件才需說明此情況（第 5 節）。
2. 執行專案的檢查。未能執行的檢查不等於通過的檢查。
3. 交接文件報告的是觀察到的情況，而非預期結果。
4. 變更誰可以存取什麼（驗證、授權、密碼、未受信任輸入的新路徑）永遠不能使用 Direct 深度。
5. 儲存庫外無法復原的操作必須等待使用者：推送至共用分支、部署、寫入真實資料、發送任何內容。

其他一切都是預設值： 只有在有明確理由時才偏離預設值。專案指南優先於任何預設值，而實現方法由你決定。

閱讀專案指南（例如 AGENTS.md、CLAUDE.md）以了解其檢查命令以及視為合約的檔案；若未指定，則從儲存庫中推斷並說明你的推斷依據。檢查來自建置設定與 CI；合約是此儲存庫外部消耗或持久化的內容：公開 API、結構描述、CLI、線路格式、儲存資料。

將 references/writing.md 中的文字類型、語言與視覺規則套用至此任務的書寫。

1. 深度

選擇最適合的較淺深度。

• Direct： 明顯的小幅度編輯，其正確性顯而易見或已被現有檢查涵蓋。非瑣碎的行為變更（即使有測試）應使用 Standard 或 Deep。打字錯誤修正可以使用 Direct。變更預設值則不可以。直接進行變更並執行檢查。無需規劃或審查者。在一行內報告變更、檢查、結果及無審查的情況。

• Standard： 行為變更的預設值。

• Deep： 僅在觸發條件發生時使用：

  1. 對此儲存庫外部消耗的合約進行破壞性變更。
  2. 儲存庫外部的不可逆影響：遷移持久化資料、金錢、發送給第三方的任何內容。
  3. 在專案視為合約的檔案中變更規則。
  4. 有不同結構的替代方案。

  然後閱讀 references/deep.md。

只有單一風險角落會提升其自身深度，整個變更的深度不會因此提升。由你自行提升深度，包括在建置過程發現觸發條件時；只有使用者可以降低深度。在降低深度前，建議你認為合適的深度。對於剛接觸此工作流程的人，說明此變更會跳過哪些步驟以及可能遺漏的失敗情況。如果他們堅持，請遵循他們的決定，但不得違反硬性限制。

2. 規劃

在 Standard 和 Deep 深度下，進行第一次編輯前，撰寫目標、你曾考慮過的非目標以及驗收標準（第 4 節）作為證據。

根據變更規模調整規劃與審查的範圍。

僅在真正需要做出決策的分岔點新增決策：列出選項（包括較簡單的選項），並說明為何選擇最終方案。

將規劃寫入 .agent/<task>/plan.md，每個任務一個目錄，並將檔案與變更一起提交，除非專案有自己的慣例。如果 .agent 已在 .gitignore 中，則保留該條目，不要強制加入這些檔案。

對於指派的工作，使用提供的規劃路徑，並參考共用範圍與驗收標準。 將實作細節保留在此處。將全域任務記錄留給協調者。 保留現有的正式任務目錄。對於委派的規劃，預設使用 .agent/<task>/tasks/<slice-id>/plan.md。

當請求的兩種解讀方式需要不同的工作時，在目標中說明你的解讀，將其與驗收標準一同顯示給使用者並等待；如果無人能回答，則依你的解讀繼續進行，並在交接文件中標記為未經確認。關於實際產品、範圍或風險的決策，應提供選項、建議與理由後再詢問使用者，切勿自行決定；將答案記錄在規劃中。

當缺陷的原因未知時，找出原因本身就是任務：其驗收標準是能夠重現問題；在找出原因後再規劃修復方案。

3. 建置

• 每一行變更都必須追溯到目標或某項決策。不需要無人需要的抽象化、可配置性或錯誤處理。
• 如果程式碼或修正與規劃衝突，請停止並公開修正規劃，而不是在最後才處理。
• 保持在指定的檔案與介面範圍內。如果需要變更這些範圍，請暫停受影響的工作並請求更新指派。
• 平行閱讀，隔離寫作。 為每個同時進行的寫作者使用獨立的工作目錄（references/parallel.md）。
• 對於整合工作，根據合併後的變更執行檢查與審查。通過部分檢查並不代表整合驗收完成。
• 如果文件中引用了命令產生的數據，請在數據旁標明命令來源，或安排檢查重新計算該數據。

對於持久性工作，將檢查結果儲存在規劃旁的 evidence/checks.md 中。 記錄標準、命令、修訂、結果、證據連結以及失效條件。 將發現、分類、審查者身份與修復輪次儲存在 evidence/review.md 中。

4. 證據

• 驗收標準應指明最便宜且能證明沒有此變更就會失敗的真實證據：現有檢查變為綠色、新的測試或觀察到的結果。說明失敗的情況是什麼。
• 預設情況下不要求新增單元測試。 僅當行為是測試可以低成本驗證的邏輯，且值得防範回歸時才編寫。以下情況不適合使用單元測試：UI 渲染與佈局、接合與膠水程式碼、配置、對外部服務的簡單呼叫、一次性腳本以及散文：應改為觀察結果。
• 當需要實際操作（點擊、輸入或呼叫）時， 應由未參與撰寫變更的 context 來驅動並報告其觀察結果。提供路徑與失敗情況，而非 diff 或你的說明。矛盾即為發現。若無此類 context：親自驅動並貼上你所見。對於禁止觸及的區域，請在安全的地方驅動並說明差距。未驅動即等同未檢查。
• 當輸出是用於閱讀而非執行時（文件、說明文字、規格），證據應由不具備變更背景的讀者對最終檔案進行冷讀：作為產品閱讀，而非作為 diff 閱讀。
• 間歇性失敗本身即為可重現的證據，也是具分辨力的證據。不要為了讓該變更的失敗通過而重新執行，也不要在將其視為可重現證據之前要求確定性的重現方法。非此變更導致的失敗應記錄為後續任務，不在本次變更中修復。
• 在審查前執行檢查，每次修復後執行涵蓋該變更的檢查，並在交接前完整執行一次所有檢查。貼出通過/失敗的行數，而非完整日誌。任何跳過或透過減弱測試換取綠燈的情況，都不算通過。

5. 審查

審查者接收完整的變更（或對於分階段建置的變更，則是完整的階段）、規劃與儲存庫，而不是你的摘要或推理。「完整」意味著變更新增、修改或刪除的每個檔案，包括新的未追蹤檔案；對空 diff 或不完整 diff 的審查不算是通過的審查。Direct 深度無需審查者；Standard 深度需要一位。

無法進行獨立審查或閱讀： 優先使用可用的獨立 context。 對於缺失的角色，檢查上述指定的完整工件，而不是你對工作的記憶。 在一次自我審查中應用缺失角色的簡要說明。 將其標記為「自我審查，非獨立審查」，並報告缺失的獨立角色。 向使用者提供簡要說明，以便在其他地方執行。 此備用方案不會凌駕於使用者、專案或主機的更嚴格要求之上。

逐字提供以下簡要說明：

依據規劃審查此變更。報告每個發現事項，並標註檔案:行號，
標記為阻擋性（錯誤行為、違反合約、超出規劃範圍的工作）
或非阻擋性。請勿修改程式碼。
1.  它在哪裡會出錯？意外的輸入、觸及信任邊界的惡意輸入、
    它所呼叫的失敗、從 diff 外部假設的事實。
2.  現有的測試是否被削弱了？
3.  新行為是否由證據（測試或觀察到的結果）證明，且該證據
    在沒有此變更的情況下會失敗？不要要求更多。
4.  是否有任何內容超出目標或屬於非目標？
5.  規劃本身是否有誤？

分類後再修正。 針對引用的程式碼確認每個發現事項。對誤讀以及要求進行非目標所排除的工作的發現事項，各用一行駁回。除非缺失的測試是為了防止已確認的正確性錯誤，否則預設為非阻擋性。當沒有確認的阻擋性發現事項時，此變更即關閉。

審查他人的變更： 使用相同的簡要說明，並將其描述作為規劃；缺少非目標即為一個發現事項。進行分類，然後將確認的發現事項交給作者；不要自行修復。

6. 修復與停止

• 修復應針對確認發現事項所引用的根本原因進行修補，並涵蓋同一缺陷出現的所有位置。
• 新的機制是新的工作：新的檢查、測試工具、防護措施、抽象化或測試檔案應記錄為後續任務，而非屬於本次修復的一部分。僅為已確認的正確性錯誤新增一個會失敗的測試，並擴展現有的測試檔案。
• 每次修復後，審查者僅重新檢查修復本身：引用的發現事項是否已解決？修復是否引入了新問題？一次修復加上其重新檢查即為一輪。

停止並詢問使用者，當一輪結束後，已確認的發現事項仍未改變時；當修復擴展到規劃未涵蓋的檔案或機制時；或當第三輪後仍有阻擋性發現事項時。請逐字提出未解決的發現事項、已嘗試的方法、出錯位置（附帶實際輸出）、選項（修改規劃、接受已記錄的風險、將項目降級為後續任務、拆分出機制）以及你的建議。切勿默默降低標準。

7. 結案：交接文件

交接文件即最終的變更描述。協調者的 HANDOFF.md 則改為提供恢復指示。 套用 references/writing.md 中的選擇性閱讀與記錄生命週期規則。 若存在協調者，則將有來源的記憶候選項返回，並將共用更新留給它。

在 Standard 和 Deep 深度下，變更描述應包含：

• 目標（使用者現在可以做到的事）以及非目標；
• 驗收標準以及證據實際顯示的內容；
• 無法檢查的項目及其原因；
• 審查者，或「自我審查，非獨立審查」，或未進行審查；同樣地，對於需要實際操作的項目也需要說明；
• 使用者降低過的深度，以及你在他們堅持之前所展示的內容；
• 未修復的非阻擋性發現事項，每項一行；
• 殘留風險；
• 在 Deep 深度下，目前狀態的復原方案。

對於指派的工作，返回工件路徑與修訂版本、證據、審查狀態、未解決的請求以及正在執行或未知的修改命令。 向協調者報告本地的完成狀態。不要聲稱完成了整個任務。

使用者新增的審查、安全或編排工具輔助獨立審查，但永遠不能取代它。