長時程 agent 程式開發的耐久控制平面

#1 缺口哪裡會失效

問題

對話不適合充當長時程工作的控制平面

一旦工作跨越多個工作階段、經歷多輪審查，還必須能在中斷後恢復，單靠一般對話就不夠用了。真正的缺口主要不在模型能力，而是缺少一個耐久的控制平面。

人類實務

對話式失效模式

有里程碑、可驗證的書面計畫

範圍逐漸漂移；「完成」被宣稱，卻沒有證據支撐。

每個邏輯單元各自成組的變更

一次修改同時混進多個議題，彼此界線不清。

合併前的程式碼審查

寫程式與判斷程式是否正確，最後都由同一個 agent 包辦。

CI / 測試關卡

驗證變成可做可不做，或只剩摘要，甚至可能憑空捏造。

中斷後恢復

一旦發生 context 壓縮，對任務的理解就容易失焦。

誰可以改什麼

規劃者、實作者與審查者之間的界線，最後全都混在同一個工作階段裡。

設計問題： 到底需要一個多小、但足夠可靠的控制平面，才能讓本地 coding agent 保持可恢復、可審查、可治理——不需要雲端編排器、不禁止一般對話中的直接編輯，也不把自由文字當成真相來源？

#2 規則設計原則

設計不變量

這個控制平面必須守住什麼

如果長時程的 agent 工作要能在中斷之後依然保持可恢復、可審查，而且邊界清楚，下面這些不變量就必須被保留下來。

01

耐久、位於對話之外的 canonical state

工作流程狀態必須存在於對話緩衝區之外，放在貼近 repo、機器可讀的檔案中，並且優先於過期的對話摘要。

02

以 slice 為單位執行

工作應拆成邊界清楚的 slices：每個 slice 都要有 acceptance criteria、明確的修改範圍、驗證命令，以及一個 slice 對應一個 commit 的紀律。

03

由程式強制的角色分離

角色邊界必須在程式裡被強制。只有 implementer 可以修改產品程式；reviewer 與 auditor 則必須保持唯讀。

04

結構化輸出契約

角色完成工作時，應以版本化 schema 輸出結果，而不是靠帶有權責意味的自由 markdown。文字可以拿來說明，但不能用來授權狀態轉移。

05

Fail-closed 驗證

模糊的啟動意圖、格式錯誤的報告與缺漏的證據，都應該阻擋進度。系統寧可卡住，也不應默默降級。

06

明確 opt-in

工作流程模式應保持可選。一般對話仍適合快速修改、問答，以及不需要 canonical state 的工作。

#3 拓撲架構

角色調度

一個 driver，一次只調度一個角色

這張圖看的是工作流程由誰在什麼時機接手。主 agent 工作階段是根節點，每次最多只會調度一個專門角色；角色之間不能再巢狀調度。所有流程都在本地、以 repo 為範圍運作。

Bootstrapper Setup

建立或修復控制平面狀態

首次建立 `.agent/` 基本骨架，或在 canonical 檔案缺失、損壞時進行修復。

Regrounder Reconcile

重新對齊 canonical 狀態並選擇 slice

依照 repo 的真實狀態重新對齊 plan 與 active slice；處理 dirty worktree、roadmap 漂移，以及 stop-wave 的重新對齊。

Implementer Execute

修改產品程式並建立 slice commit

唯一可以修改產品程式並建立 slice commit 的角色。落地前必須先執行驗證。

Reviewer Evaluate

逐 slice 的結構化審查

以唯讀方式進行結構化審查：涵蓋契約覆蓋、正確性風險、驗證證據，以及文件與狀態的一致性。

Auditor Evaluate

專案層級稽核

以唯讀方式評估這個 slice 是否仍符合整體任務目標，以及 backlog 是否仍然完整。

Stop-judge Close

最終 stop / no-stop 判斷

獨立且唯讀地判斷工作是否可以停止。預設策略可能要求多個 judge 在當前 HEAD 上一致同意。

角色調度圖

flowchart TB Driver["Workflow driver\n(main session + MCP claim/submit)"] subgraph setup ["Setup 與對齊"] Bootstrapper["Bootstrapper\nscaffolding / repair"] Regrounder["Regrounder\nplan、slice 選擇、對齊"] end subgraph execute ["實作"] Implementer["Implementer\n產品修改 + slice commit"] end subgraph evaluate ["唯讀評估"] Reviewer["Reviewer\nper-slice rubric review"] Auditor["Auditor\n專案層級 audit"] StopJudge["Stop-judge\n最終 stop / no-stop"] end subgraph close ["收束關卡"] StopVerifier["Stop verifier\n.agent/verify_completion_stop.sh"] end Driver -->|"缺少 scaffolding"| Bootstrapper Driver -->|"狀態過期 / 未選 slice / review 後對齊"| Regrounder Bootstrapper --> Regrounder Regrounder -->|"已選 slice、尚未 commit"| Implementer Implementer -->|"slice 已 commit"| Reviewer Reviewer --> Auditor Auditor --> Regrounder Regrounder -->|"所有 slice 完成"| StopJudge StopJudge -->|"仍需更多 judge"| StopJudge StopJudge -->|"stop wave 完成"| StopVerifier StopVerifier --> Regrounder Regrounder --> Driver

調度

調度順序

缺少 scaffolding → bootstrapper
狀態過期或模糊 → regrounder
尚未選定 slice → regrounder
已選 slice、尚未 commit → implementer
已 commit、尚未 review → reviewer
尚未 audit → auditor
review 後重新對齊 → regrounder
所有 slice 完成 → stop-judge（×N）
完成 stop 判斷後 → stop verifier + 最終 regrounder 對齊

#4 層 Canonical State

Repo 本地檔案系統控制平面

貼近 git worktree 的耐久狀態

對本地優先、可檢視的 agent 工作流程來說，用 gitignored 的 `.agent/` 目錄（搭配 JSON 與 JSONL 檔）保存耐久的外部狀態，是一種務實又清楚的做法。

.agent/
  current/
    state.json                  # 工作流程控制器
    startup-brief.json          # 已確認的 intake（不是 plan）
    plan.json                   # Slice backlog + acceptance criteria
    active-slice.json           # 當前實作契約
    slice-history.jsonl         # 僅追加的角色 transcript
    stop-check-history.jsonl    # Stop-judge 判斷
    verification-evidence.json  # 命令結果 + 覆蓋範圍
    tmp/                        # repo 本地暫存
  verify_completion_stop.sh
  verify_completion_control_plane.sh

01

工作流程控制器

`state.json` 會驅動自動化：包含當前階段、continuation policy、下一個強制角色、reground 旗標與 stop-wave epoch。

02

Startup brief ≠ plan

Startup brief 記錄的是已確認的 intake。Regrounder 會在確認後依照 repo 的真實狀態撰寫 slice plan——散文式的任務描述不會默默變成執行契約。

03

Active-slice 契約

其中包含目標、acceptance criteria、implementation surfaces、驗證命令、basis commit 與範圍鎖。只要 plan 與 active slice 發生漂移，驗證器就會 fail closed。

#5 單位 Slice 生命週期

工作單位

一次一個 slice、一個 commit

這張圖看的是單一 slice 從被選中到完成會經過哪些階段。每個 plan 項目都必須具備可驗證的 acceptance criteria；commit 後 active-slice 狀態會停在 `committed`，reviewer 與 auditor 則把 `reviewed` / `audited` 寫入 slice-history，最後由 regrounder 決定 `accepted`（`done`）或 `reopened`。

Slice 生命週期階段

stateDiagram-v2 [*] --> selected: regrounder 選擇 slice selected --> in_progress: implementer 開始 in_progress --> committed: commit + implemented record committed --> done: regrounder accepts committed --> selected: regrounder reopens done --> [*] in_progress --> reground: 發現 roadmap 漂移 committed --> reground: dirty worktree / 對齊 reground --> selected: regrounder 對齊

01

選擇

把一個 backlog 項目正式指定為目前進行中的工作：鎖定 acceptance criteria 與 basis commit，並寫入 active-slice 契約。

02

實作

依照 active-slice 契約完成實作、執行驗證命令，並建立恰好一個 slice commit，讓它進入可評估狀態。

03

評估

active-slice 狀態維持 `committed` 時，reviewer 與 auditor 會把 `reviewed`、`audited` 寫入 slice-history。若未通過，就回到 regrounder 重新對齊與後續處理。

04

對齊

完成評估後，系統會更新 backlog 狀態、處理 dirty worktree，然後決定是挑選下一個 slice，還是進入 stop 評估。

05

收束

只有在所有 slice 都完成、且 stop-judge 與 verifier 都通過後，continuation policy 才能轉為 done。

當 continuation policy 為 continue 時，driver 會自動調度必要角色，而不會在每個 slice 之間反覆詢問「要繼續嗎？」。
進入下一個 slice 之前，tracked worktree 必須保持乾淨。無關變更若安全，可透過可逆的 stash 自動保留。
對符合條件的 regression slice，驗證會在鎖定的 basis commit 上，於 disposable worktree 重新執行——也就是在工作流程層證明這個 bug 在 basis 上確實存在。

#6 證據驗證

證據，而不是散文

評估、驗證與受治理的收束

驗證證據是耐久且結構化的產物，不是對話裡的一段摘要。所有唯讀評估角色共用一套四維 rubric；每個維度都會得到 pass、concern 或 fail。

01

契約覆蓋

實作是否滿足已鎖定的 acceptance criteria 與宣告的 surfaces？

02

正確性風險

依照目前的證據，哪些地方可能壞掉、回歸，或出現非預期行為？

03

驗證證據

決定性的檢查是否已執行、被記錄，且新鮮到足以支撐判斷？

04

文件 / 狀態一致性

文件、canonical state 與 repo 的真實狀態，是否仍然彼此一致？

Stop wave： 多個彼此獨立的 stop-judge 子程序，可能需要在當前 HEAD 上一��同意，工作才能真正停止。Stop-wave epoch 讓系統在對齊過程改變 canonical 真相、卻沒有產生合成 commit 時，仍然可以重新評估。收束時移除 `.agent/` 是預期行為，不是異常。

#7 選擇兩種模式

工作流程模式與一般對話

以明確 opt-in 保留直接協作

這個設計刻意保留兩種模式。只有在可恢復性、審查軌跡與受治理的收束，真的值得額外成本時，才啟用工作流程模式。

模式

行為

一般對話

快速修改、問答、腦力激盪，以及不需要工作流程開銷的多檔案工作。

允許直接修改 repo。不調度角色，也不載入工作流程協定。

工作流程模式

需要恢復能力的任務、審查 / 稽核回合、canonical state，以及確認優先的邊界。

必須明確進入。系統會以 fail-closed 規則建立啟動狀態、進行角色調度，並在進入停止狀態前持續自動推進。

控制項

Start / resume — 進入工作流程，或從已保存的狀態繼續
Park — 暫停工作流程，改做一般直接編輯；恢復時會強制 reground
Cancel — 關閉已停止或已 park 的工作流程

#8 落地實作

從規格到實作

這套設計如何在 Cursor 中落地

這一頁描述的是抽象層次的控制平面架構；letscook Cursor plugin 則把這套架構變成 Cursor 中可運作的長時程工作流程模式。

設計與實作的關係： 控制平面是架構模型；letscook 是它的一個具體落地版本。核心不變量維持不變，但命令命名、檔案布局與宿主整合細節，仍屬於當前實作選擇。

快速開始

Customize → 匯入 letscook plugin
重新載入 Cursor → 啟用 plugin 與 MCP
/cook add login redirect handling and the missing redirect tests

設計面向

letscook 實作

明確的工作流程入口

受治理的長時程模式應該採用 opt-in，並在啟動前先完成使用者確認。

`/cook` 會解析工作區、合成啟動交接內容，並在 `confirm_cook_handoff`（Start/Cancel；若在 main checkout 則另有隔離關卡）確認後，才進入六角色 MCP 編排迴圈。

恢復、暫停與關閉

生命週期控制應該保持明確，而不是藏在對話慣性裡。

`/cook resume`、`/cook park` 與 `/cook cancel` 讓續跑、暫停與結束都保持明確。

耐久的 canonical state

工作流程狀態必須能跨越 context 壓縮與工作階段重啟，而不是只存在對話記憶裡。

Repo 本地的 `.agent/` 檔案會把 startup brief、plan、active slice、證據與 stop 狀態保存在 worktree 旁邊。

角色分離的執行

實作、評估與收束不應坍縮成單一權責面。

bootstrapper、regrounder、implementer、reviewer、auditor 與 stop-judge 會以分離的完成角色執行，並受到權責邊界約束。

受治理的驗證與收束

完成條件應建立在結構化證據與明確的 stop 條件上，而不是對話中的自信語氣。

內建的控制平面驗證器、stop 驗證器、結構化證據，以及 fail-closed 的審查 / 稽核 / stop 回合，會共同把關完成條件。

角色 Prompt 實作

六個角色 agent 的約束實際寫在哪裡

架構圖呈現的是分工；真正的可編輯範圍、禁止事項、回報格式與交接契約，則寫在 letscook 隨附的角色 prompt 裡。想看完整的權責邊界，請直接讀 full prompt；想快速掌握執行重點，則可看 quick reference。

Bootstrapper

負責建立或修復本地 `.agent/**` 輔助檔與 canonical 狀態，之後交接給 regrounder。不能修改 tracked 產品檔，也不能建立 commit。

完整 Prompt Quick reference

Regrounder

負責依照 repo 真實狀態重新對齊 plan、active slice、工作流程狀態與驗證證據。不能修改 tracked 產品檔，也不能呼叫下游角色或建立 commit。

完整 Prompt Quick reference

Implementer

唯一可以修改 tracked 產品檔、執行 slice 驗證、建立 slice commit，並追加 implementation record 的角色。不能自行決定下一個 slice，也不能默默重寫 roadmap。

完整 Prompt Quick reference

Reviewer

針對單一已提交 slice 進行唯讀的結構化審查，明確給出是否可接受，以及必要時最小的後續 slice。不能寫 canonical state，也不能建立 commit。

完整 Prompt Quick reference

Auditor

從專案層級進行唯讀稽核，檢查剩餘工作、worktree 是否乾淨、backlog 是否仍如實反映現況，以及 canonical state 是否仍與現況一致。不能寫 canonical state，也不能建立 commit。

完整 Prompt Quick reference

Stop-judge

在最終 stop wave 期間，對 current HEAD 做獨立且唯讀的 stop / no-stop 判斷。不能寫 canonical state，也不能建立 commit。

完整 Prompt Quick reference

哪些屬於設計不變量

耐久的外部狀態、slice 化執行、明確的工作流程入口、角色分離，以及 fail-closed 驗證，都是這套設計的核心不變量。它們是架構本體，不只是實作細節。

哪些屬於當前實作選擇

`/cook` 命令、目前的 `.agent/` 檔案布局、Cursor plugin 打包方式，以及 MCP 編排細節，都屬於 letscook 的當前實作選擇，而不是抽象設計本身。

實作導覽

應該先看哪裡

不同讀者適合的入口不同。你可以依照自己是想使用 plugin、檢查協定，還是了解編排細節，選擇對應的實作資料。

如果你想直接使用它

先讀 plugin README。它會說明什麼情況適合使用 `/cook`、工作流程模式和一般對話的差異，以及如何安裝 letscook Cursor plugin。

如果你想看執行期契約

閱讀 completion-protocol 技能文件。裡面記錄 canonical `.agent/**` 狀態、工作流程指令、產生的 verifier 腳本、強制角色派遣，以及 fail-closed 延續規則。

如果你要看編排細節

閱讀 cursor-orchestrator 與 cursor-worktree-cook 技能文件。letscook 透過 MCP、內建 agent 與可選的 worktree 隔離，在 Cursor 中原生執行完整工作流程。

具體細節

這個實作走得比架構圖更遠。

plugin 本身提供命令、MCP 工具、repo 本地 `.agent/` 狀態、產生的 verifier 腳本、內建角色 agent，以及 completion-protocol 技能。它在 Cursor 中以可選的 worktree 隔離原生運作。

查看 GitHub 實作閱讀 plugin README 查看 completion protocol 查看 Cursor 編排文件

#9 誠實取捨

它是什麼、也不是什麼

只有在漂移代價高時，才值得付出額外開銷

工作流程模式會增加延遲、token 開銷與認知負擔。只有當工作跨越多個工作階段、審查軌跡很重要、錯誤的「完成」代價高，或純對話嘗試已經出現任務漂移時，這些成本才值得。

不是雲端編排器

所有東西都在本地、以 repo 為範圍，並由 plugin 管理。

不是對話的替代品

當工作流程開銷沒有必要時，直接實作依然是有效做法。

不是正確性的保證

角色與驗證器可以降低風險與漂移，但無法證明形式上的正確性。

預設不追求跨宿主通用性

具體實作會綁定特定的 agent 執行環境、子程序隔離方式與工具生態。

單一 agent 一路做到底

開銷低，但沒有可恢復的控制平面、權責模糊，而且收束薄弱。

人類 PR 工作流程

審查文化強，但不是 agent-native——沒有自動調度，也不特別處理 context 壓縮後的恢復。

雲端任務佇列

編排能力雖然可擴展，但也帶有外部依賴，而且較不貼近 git。

只靠提示詞的多 agent

角色扮演雖然靈活，但缺乏工具層級的強制與 canonical state 時，角色最終還是會坍縮。

可執行規格

協定行為本身就是發布關卡的一部分，不只是附帶的 CI 衛生工作。

回歸測試套件應涵蓋 schema 一致性、evaluator 校準、stop-wave 語意、dirty worktree 政策、worktree-root 邊界、helper 權責，以及公開文件與執行期行為的一致性。