plan-it 是做什麼的？
將模糊的需求 → 產出可構建的交付套件。 這是規劃
指揮者：生命週期中紀律嚴明的前半段，精確終止於
/build-it 開始之處。它執行 探索（研究實際情況）、規格（撰寫設計文件）
以及 敏捷拆分（PRD、功能主線、測試、共享合約）——
然後進行交接。
/plan-it ─────────────► docs/ + delivery/ ─────────────► /build-it
(探索 → 規格 → 計劃) (可構建的套件) (構建它)
可直接由人類使用，也可由任何接收新需求並必須將其轉化為交付套件、 然後派遣工作者的指揮代理使用。
五條不可協商的規則（請執行這些規則 — 不要只是建議）
這些是從每次成功運行中逆向工程得出的承重規則。 如果你違反任何一條，下游構建將會偏移或默默失敗。
-
在任何並行規劃之前，先凍結共享的 CONTRACT。 CONTRACT 是 法律：規範的實體、結構、API/介面、列舉、儲存庫/分支對應，以及 『已發佈』的定義。團隊依據它來撰寫；任何跨領域的發現都 以帶有日期的修正案形式折回它（v1.0 → v1.1 …）。 沒有凍結合約 → 就沒有並行團隊。
-
將所有僅需人類決策的項目批次處理到一個閘門中。 不要預先決定任何 不可逆轉的事項（儲存庫拓撲、託管方式、產品名稱、架構模式、 自建或採購）。將它們一起提出，每個都附上建議， 然後讓人類按編號回答。這個閘門是人類注入願景的地方，而不僅僅是挑選 選項 — 留出空間讓他們添加你沒有提出的概念。用擁有者 + 日期鎖定每個 答案。
-
驗證每個代理在磁碟上的輸出 — 『空閒中 ≠ 已交付』。 一個團隊進入 空閒狀態並不表示它寫入了檔案。在任何分派之後，檢查實際路徑是否存在且 非空，然後再繼續。如果某個團隊將其輸出保留在訊息中，請指示它
Write到確切的絕對路徑。永遠不要相信『完成』。 -
在凍結之前，根據即時系統而非儲存庫來制定計劃。 對於任何觸及運行中系統的計劃，儲存庫只是一個假設；已部署的 現實才是真相，而且它們會偏移。在凍結 CONTRACT 之前，請根據 實際系統進行驗證，並將觀察結果寫入（而非從儲存庫推導出的猜測）。 經過實戰檢驗：在一個計劃中，每一次中途修正都追溯到一個由儲存庫推斷的 假設與現實相矛盾 — 錯誤的規範識別碼（清單已偏離已部署的目錄）、 一個存在但指向無效主機的配置值、『待構建』的元件其實已部署， 以及一個找到的憑證是錯誤的那個。請參閱第 3 階段的即時接地閘門以了解具體檢查項目。
-
執行機器，而不是文字。 管線的控制流程存在於
machine.json（明確的狀態圖）中，而不是此文件中 — 此文字 解釋了機器。調用時，讀取或初始化.plan-it/state.json（在目標專案中） 並從其state恢復；在每個轉換時寫入它。在每個有守衛的轉換處， 執行守衛對應的子命令（node scripts/gate-check.mjs <check> …）， 並且在非零退出碼時絕不推進 — 修復、重新執行，然後轉換。如果 Node 不可用， 請手動執行相同的檢查並將其記錄在狀態檔案中（降級，絕不中斷）。完整 協定：references/machine.md。
確定性核心（v2）— 為何是機器
以文字形式撰寫的控制流程（『執行步驟 1，絕不跳過閘門』）就是 確定性文獻中所謂的文字控制流程：它依賴模型在一個漫長、 容易摘要化的上下文中的紀律，而有時模型不會遵循它。v2 在適當的 抽象層級上反轉了這一點 — 邊緣的非確定性，核心的確定性：
machine.json— 與 XState v5 相容的管線狀態圖：15 個狀態、 三個人類閘門（meta.gate+meta.human）、有守衛的轉換，以及 在parallelPlanning上的AMENDMENT自迴圈。貼到 stately.ai/viz 上查看。.plan-it/state.json— 持久化的運行：當前狀態、閘門批准 （擁有者 + 日期）、合約版本、已驗證的工件註冊表、歷史記錄。這 使得運行能夠在崩潰或全新會話後存活。scripts/gate-check.mjs— 作為退出碼的守衛：verify（規則 3， 空閒 ≠ 已交付）、freeze（規則 1，無合約 → 無團隊）、handoff（ 可機械化的 playbooks §F 部分）、state（規則 2，閘門已記錄）、adversary（規則 6 / D4 — 失敗模式深度：一個建模的機器必須覆蓋或 放棄五個級聯類別；線性工作流程不適用）。LINT_CLEAN和ADVERSARY_CLEAN轉換（verify → adversaryGate → handoff）閘門作用於 最後兩個。
模糊的階段 — 探索、綜合、規格撰寫、判斷 — 保持
LLM 在節點（在機器中標記為 llmAtTheNode）。不要將其形式化；
建模只有在取代混亂時才是儀式。詳細資料、狀態檔案結構，
以及恢復協定：references/machine.md。
硬性執行（v2.1，僅在 Claude Code 上安裝插件）： 一個 PreToolUse
掛鉤（scripts/hooks/planit-guard.mjs）在運行的合約未凍結時拒絕
對 PRD/功能主線交付物進行 Write/Edit 呼叫 — 規則 1 不再只是一個指令，
而是變成裝配架拒絕的事情。失敗開放：它永遠不會觸及非 plan-it 的工作。
僅技能安裝則依賴規則 5 的紀律。
測試合約 — 品質差異化因素（使其不可協商）
能最大程度提升交付程式碼品質的單一事項：每個 PRD/功能主線結尾時生成
其自己的測試合約 — 最多約 20 個具體的使用案例/場景，用於驗證
實作 — 並且功能在 100% 通過它們之前不算『完成』。
構建代理不能只交付功能；它必須滿足合約，並透過 /iterate 直到綠燈。
這是一個有名且經過驗證的學科：範例規格（Gojko Adzic）+ ATDD/BDD 用於程式碼（具體範例變成可執行的驗收測試和 活動文件），以及評估驅動開發用於技能/LLM 功能 （註冊具有預期輸出的黃金測試，迭代直到它們通過）。在規劃時 撰寫案例是重點 — 它們成為具有約束力的合約，而非事後想法。
測試合約的規則：
- 在規劃時撰寫 — 撰寫每個功能主線/PRD 的最後一步就是其 測試合約。預期輸出現在被註冊（『先設計；預期輸出已註冊』），而非在構建過程中發現。
- 每個功能最多約 20 個高品質案例 — 足以驗證真實行為 + 邊界；不是數千個淺層案例（品質 > 數量 — 自動大量生成 = 『敷衍的內容』， 根據評估文獻）。從真實/可能的失敗模式中提取案例。 每種形狀的計數規則： 大型形狀-1 多團隊計劃持有每個功能主線 ≥10 個案例的底線 （每個功能主線都是一個大型功能）；小型形狀（單一技能/功能，S/M）撰寫 整個套件約 20 個案例（每個功能主線幾個）。永遠不要同時兩者 — 根據形狀選擇， 這樣審查者就不會將一個正確的小型套件標記為測試不足。
- 具有約束力 — 完成定義 = 合約 100% 通過；在此之前，請使用
/iterate。無 部分發佈；無基於模擬的 VERIFIED（一個目標無法觸及的[REAL]案例 → IMPLEMENTED-NOT-VERIFIED，永遠不是假的綠燈）。 - 根據實作選擇測試類型（單元 / 端到端 / 使用案例 / 壓力 測試中的一個或多個）：
| 實作 | 測試類型 | 方式 |
|---|---|---|
| CRUD / REST API | 使用案例（快樂路徑+邊界）+ 端到端 | 每個場景透過 API 和 透過使用 Chrome CDP 的 UI（chrome-cdp-control）執行；對邏輯進行單元測試 |
| 技能 / 提示 / LLM 函數 | 使用案例 + 預期輸出 | 執行它，比較實際與預期 — 封閉式輸出精確匹配，開放式輸出使用評分標準 / LLM 作為評判（make-eval、promptfoo、DeepEval G-Eval） |
| 代理 / 有狀態 / 多步驟 | 壓力場景 + 使用案例 | 六個軸：非同步、分派、升級、人類閘門、遞迴、循環防護（設定/預期/通過） |
| 純邏輯 / 函式庫 | 單元 + 基於屬性 | 列舉案例 + 不變量 |
| 資料管線 / 遷移 | 黃金值 + 端到端 | 手動計算的預期值；冪等性/回滾 |
| 任何有負載/濫用表面的東西 | 壓力 / 對抗性 | 並發、速率、格式錯誤的輸入、紅隊 |
- 執行路徑：
/full-qa執行合約，/iterate將它循環到 100%，chrome-cdp-control驅動 UI 場景。合約是從 plan-it 到 build-it 的橋樑：/build-it的完成定義 = 此合約。
文法與合約標頭格式：references/formats.md（測試合約區塊 + §4–5）。
自主性姿態（引導式自主爆發）
以高努力度自主執行研究與撰寫，但在三個閘門處停止：
| 閘門 | 何時 | 你問什麼 |
|---|---|---|
| G1 — 範圍 | 接收後（第 2 階段） | 在投入精力前確認規模（功能 vs 計劃）+ 編號的完成定義 |
| G2 — 決策 | 規格草擬後（第 7 階段） | 批次處理的『只有你能做的決策』，每個都附有建議 |
| G3 — 交付 | 在敏捷拆分之前（第 8 階段） | 『規格看起來一致 — 繼續進行 PRD/功能主線？』 |
閘門之間的所有事情都在無人值守下運行。建議在一開始使用 /effort xhigh
（你不能自己設定 — 告訴使用者如果他們還沒執行，請執行 /effort xhigh）。
第 0 階段 — 接收
機器優先（規則 5）： 如果目標專案中存在 .plan-it/state.json，
執行 node scripts/gate-check.mjs state .plan-it/state.json 並從列印的狀態恢復
— 不要重新啟動 history 中已有的階段。如果它不存在，
現在就以 intake 狀態創建它（結構在 references/machine.md 中），並在
本次運行剩餘部分的每次轉換中保持更新。
接受以任何形式到達的需求：一個腦力激盪、一個貼上的
逐字稿、一個需求清單，或一句話。預期是指標，而不是內容 —
會話名稱（/read-chat "<name>"）、儲存庫路徑、文件夾。你的工作是去
獲取實際情況，而不是被動接收。
預先捕獲：
- 原始的願景，使用使用者自己的話語（你將在
02 §1中引用它）。 - 指標，指向先前的會話 / 儲存庫 / 文件以供研究。
- 使用案例（自動偵測 — 這將驅動 G1 閘門的封裝形狀）：
- 全新單一應用程式，綠地開發 · 大型現有儲存庫上的功能 · 從頭開始的多子系統計劃 · 多應用平台（許多 PRD） · 重構/遷移/技術債 · 研究探勘（尚未構建） · PM/看板 自動化 · 記錄/稽核一個已構建的系統。
- 研究方法：預設為在 xhigh 使用並行 Claude 團隊。
如果需求真的只是一個模糊的段落，沒有指標和一個現有的儲存庫， 那也沒問題 — 第 3 階段的預先接地會找到目標。
第 1 階段 — 完成定義鎖定
將模糊的文字重組為一個編號、可個別驗證的完成定義
- 一個簡短的陳述假設清單。這是你與使用者針對規劃工作本身的合約。
範例形狀：
本次規劃運行的完成定義：
1. 實際情況調查文件（每個聲明 → 路徑:行號或表格）
2. 解決每個發現/矛盾的願景 + 架構文件
3. 資料/介面合約
4. …（自動調整大小 — 請參閱第 2 階段）
N. 交接：合約已凍結，每個 PRD+功能主線有 ≥10 個測試，啟動提示
假設：<清單>
第 2 階段 — 範圍與形狀管理者 ⏸ 閘門 G1
在投入精力之前，先選擇大小（多少）和 形狀（何種形式）。 與使用者確認兩者。
大小根據工件數量縮放：
| 信號 | 大小 |
|---|---|
| 單一功能，1 個子系統 | S |
| 多功能 / 新子系統，1–2 個儲存庫 | M |
| 從頭開始的計劃 / 許多子系統 | L |
形狀根據使用案例選擇（完整定義 + 使用案例→形狀表在
references/templates.md D 部分）：
- 多文件 +
delivery/（基線）— 從頭開始的計劃，並行團隊。 - 單一檔案 PRD-as-everything — 綠地單一應用程式；CONTRACT 內嵌為 G-規則。
- 研究 → 鎖定架構 → 主體+階段 PRD — 大型現有儲存庫上的功能。
implementation/<name>/與編號的 PRD-NN — 多應用平台，許多 PRD。- 重構/技術債工作流目錄 — 原地棕地開發。 （+ 研究探勘、可執行看板和反向文件模式 — 請參閱 D 部分。）
階段相同 — 只有工件數量和形式變化。不要給一個功能一個 4 團隊的組織；
不要給一個棕地重構一個綠地願景文件。
呈現所選的大小 + 形狀 + 編號的完成定義，並在繼續之前得到同意。
同意後，在 .plan-it/state.json 中記錄 G1 = {approved, owner, date} 加上
所選的大小/形狀 — G1_APPROVED 轉換由 gateRecorded 守衛。
第 3 階段 — 預先接地
在任何分派之前，定位確切目標，以便代理獲得精確的路徑，而不是模糊的指示：
- 如果安裝了會話閱讀技能（
/read-chat或類似功能），則用它解析指標會話； 否則請求相關的逐字稿或摘要。 ls/grep命名的儲存庫；找到docs/、結構檔案、進入點。- 如果儲存庫連接了 wiki（根據其
CLAUDE.md），則讀取 wiki 熱快取/索引。
輸出：一個 {subsystem → 要讀取的確切路徑} 的清單，為研究團隊提供種子。
即時接地閘門（規則 4）— 當計劃觸及一個運行中的系統時
儲存庫告訴你應該是真實的；即時系統告訴你實際上是什麼。在 第 8 階段凍結之前執行此操作，並將發現作為觀察到的事實寫入 CONTRACT：
- 配置可達性，而非存在性。 對於計劃依賴的每個環境/配置槓桿 （基本 URL、API 主機、功能標誌），實際訪問它 — 不要只確認它已設定。一個值 可以被設定為一個已死的主機，並通過『是否存在』檢查，同時默默破壞生產環境。
- 即時註冊表 / 規範識別碼。 重複。
…
[為翻譯而截斷]