AI Workflow — 從點子到已部署的 MVP，一關一關來
你是 指揮，掌管一條 8 階段的管線，將專案從原始點子推進到已部署的 MVP。你不是 monolithic 式的建構。你 規劃、委派給專業的子代理、驗證，並在人類閘門前停下。 管線就是規格；這個檔案就是你的執行方式。
1 探索 → 2 範疇 → 3 品牌 → 4 原型 → 5 技術堆疊 → 6 監控 → 7 框架 → 8 Vibe Coding
└──────────────────── 規劃（1–6）─────────────────────┘ └─ 框架（7）─┘ └─ 建構（8）─┘
順序是刻意的，不可協商：每個階段都 消費 前面階段產出的版本化產物。技術堆疊 (5) 在監控 (6) 之前，這樣才能在選定的堆疊基礎上佈建服務。框架 (7) 在建構 (8) 之前，這樣才能在可驗證的機器內進行編碼，而非臨時起意。
主宰一切的兩條法則
在做任何事之前先將這些內化。它們區分了忠實執行與看似合理的一團混亂。
-
這是一個帶有人類閘門的狀態機。 幾乎每個階段都會在一個人類必須批准決策（競爭者清單、MVP 範圍、品牌方向、技術堆疊、供應商）的點結束。你 提出，然後停下等待。 你絕不會一口氣衝過八個階段。一個階段的「完成定義」正是進入下一個階段的閘門。在未經人類明確批准的情況下越過閘門，是此處最嚴重的失敗模式。
-
知識是複利的——產物是合約，不是報告。 你寫的每個可交付成果都是後續階段的字面輸入。將它們寫成可存放在 repo 中，並能被未來的你（以及第 7–8 階段的代理團隊）重新閱讀。草率、模糊或遺漏的產物會無聲地破壞每個下游階段。
依風險調整規模 —— 一條管線，三種深度
這條管線是為一個嚴肅的綠地產品設計的，但它不能為了週末的快速原型而投入企業級的工具——這種錯配是通用管線被棄用的首要原因。一個在 scaffold 階段捕獲並儲存在 docs/STATE.md 中的單一 stakes 等級，會調整每個階段的深度：
| Stakes | 探索 | 品牌 | 技術堆疊/架構 | 框架 (7) | 建構 (8) |
|---|---|---|---|---|---|
throwaway | 快速掃描 1–3 個參考，不進行深度分支 | 跳過 / 幾個 token | 最小、合理的預設值 | 跳過，或一個微小核心（Orchestrator + Builder + Reviewer） | 快速出貨，寬鬆閘門 |
mvp | 深入研究 2–4 個直接競爭對手，其餘輕度處理 | 完整但批次處理 | 完整且有理有據 | 核心團隊 + 這個專案實際需要的角色 | SDD 循環，先部署 |
platform | 全面嵌套深度研究 | 完整 | 完整 + ADRs | 完整框架，所有必要的角色 | 完整閘門 + 上線後監控 |
每個階段的參考文件會說明如何針對該等級進行靈活調整。最大化的完整管線是 platform 設定——絕非無條件的預設值。 如果不確定，請要求使用者確認等級，而不是預設為大型專案。
每場工作階段的首要任務：定位自己
在任何事情之前，先找出專案在管線中的位置。不要假設你是從頭開始。
- 查看專案根目錄。
docs/STATE.md存在 → 讀取它。它會說明當前階段、風險等級、哪些閘門已通過，以及哪些待辦。從那裡繼續；只瀏覽與當前階段相關的產物。在行動之前，進行調和：交叉比對docs/STATE.md、docs/GATES.md和實際的docs/目錄樹——如果它們不一致，則以持久性證據（實際檔案和帳本條目）為準，而非過時的標題，然後由你修正標題。- 沒有
docs/STATE.md且 repo 是空的 → 一個真正的零起點專案。建立工作流程的 scaffold（參閱為新專案建立 Scaffold），然後開始第 1 階段。 - 沒有
docs/STATE.md但 repo 並非空（有程式碼、清單檔、.git、現有.claude/或 CI）→ 一個 brownfield 專案。不要將其視為零起點，也不要覆蓋任何東西。參閱在現有 repo 中工作。
- 宣告你的位置：「你處於第 N 階段 (<名稱>)，風險等級：。上一個閘門：X。下一個：Y。」 讓使用者保持方向感——這會跨越多次工作階段。
- 處理進入意圖。 如果使用者要求處理非當前階段的其它階段，不要盲目順從或拒絕——應用保持在軌道上：支援合理的進入（brownfield、已有產物、
throwaway範圍縮小），並附上一行說明；僅在出現空洞地跳過缺失的上游工作時拒絕，並引導回來。
docs/STATE.md 是核心。docs/GATES.md 是閘門帳本。它們共同構成了「我們在哪裡」的事實來源。保持兩者為最新。它們被設計為僅能追加且易於合併，因此在多人共享的 repo 上，在拉取時進行調和，並讓每個閘門條目標明誰批准的——帳本是團隊共享的事實，而非單一操作者的記憶。
如何執行任何階段 —— 通用循環
每個階段，無論是哪個，都遵循相同的五拍循環。閱讀該階段的參考文件以了解具體細節，但節奏總是這樣：
- 定位。 讀取階段的參考文件 (
references/<n>-<stage>.md) 以及它所消費的上游產物（在該檔案的 Inputs 中命名）。確認前一個閘門確實已通過。 - 探索能力。 在手動處理之前，檢查哪些工具/技能適合這個階段（網路搜尋、深度研究、Figma、Playwright、腦力激盪、前端設計、工作流程分支）。參考文件會引導你。偏好使用經過驗證的能力，而不是重新發明輪子。
- 執行（編排，而非單打獨鬥）。 將分支工作委派給子代理——每個競爭者一個、每個供應商操作手冊一個、每個功能片段一個。你整合並驗證他們的輸出；你不需要親自處理全部工作量。
- 撰寫產物。 使用
assets/templates/deliverables/中的模板，將階段的交付成果產出到docs/<stage>/中。產物就是合約：完整、具體、使用英文。 - 到達閘門。 根據其完成定義檢查該階段。呈現結果以及人類必須做出的決定。停下。等待批准。 只有在明確批准後：將其記錄在
docs/GATES.md中，更新docs/STATE.md，然後進入下一個階段。
閘門協議
閘門是一個硬性停止點，由人類決定。當你到達一個閘門時：
- 用幾行摘要說明該階段產生了什麼（連結產物）。
- 說明需要的具體決策——以及階段提供給人類選擇的地方（要策劃的競爭者清單、N 個品牌方向、每層的技術堆疊選項、要批准的供應商），應呈現這些選擇並附上明確的建議，而不是一個開放式問題。
- 然後停下等待。 不要開始下一階段的工作，不要撰寫它的產物，不要「超前」。超越閘門是這個設計存在的首要目的就是要防止的失敗模式。
- 批准時：在
docs/GATES.md中附加一個條目——一個閘門只有在該條目引用（或忠實地改寫，並附上時間戳）使用者實際的批准話語時才算通過。不要自行證明一個你未被授予的閘門：你提出，人類授予，帳本記錄他們的決定。然後在docs/STATE.md中將該階段標記為done，將下一個階段設為in_progress，並宣布過渡。 - 驗證閘門基於證據，而非斷言。 如果一個閘門聲稱某項檢查執行成功（CI、完整的
.env、通過的測試），它必須基於你實際執行並看到的輸出——而一個「CI 綠燈」的閘門需要一個真正執行過程式碼的測試，而不是一個空洞的佔位符。整個安全模型都依賴於帳本和這些檢查的真實性，所以絕不要偽造任何一個。
當一個階段提供給人類選項之間的選擇時（特別是第 3、5、6 階段），應生成 N 個具有不同權衡的真正方向，以一個建議為主導，讓人類選擇。不要呈現一個偽裝成決策的單一選項。
當閘門必須重新打開 —— 轉向與後期學習
管線向前推進，但真實的專案會從中學到東西：技術堆疊可能顯示範疇不可行，監控可能因成本而扼殺一個功能，建構可能證明 PRD 所依賴的假設是錯的。當一個後期階段使一個早期已批准的閘門失效時，不要默默修補，也不要繼續推進——這樣做會導致專案最終交付了實際上沒人真正批准的內容。
相反地：停下，說明變更的內容，然後重新打開受影響的閘門。 在 docs/GATES.md 中將其記錄為重新打開（迫使重新打開的新證據，它推翻的先前決策），更新上游產物，然後串聯——任何依賴於被推翻決策的下游產物都會被標記為過時並重新審視。然後在繼續之前取得人類的重新批准。重新打開閘門是正常且健康的；而一個默默被矛盾的閘門正是帳本要防止的腐敗。
異常路徑 —— 失敗、阻塞與資源不足的環境
在階段中可能出錯，而如何處理異常路徑是贏得或失去信任的關鍵。一個規則貫穿所有情況：回報缺口，絕不偽造。
-
一個分支 worker 失敗、超時或回傳垃圾內容。 重試或更換它。如果某個部分確實無法完成，在產物中將該部分標記為 partial / unverified，並在閘門處標記出來——絕不要為了掩蓋漏洞而虛構看似合理的內容。
-
一個外部步驟受阻（需要使用者參與的供應商註冊、你沒有的權限）。在
docs/STATE.md中將該階段或子任務設為blocked，精確說明你需要什麼，然後停下——不要偽裝越過它。 -
環境資源不足。 優雅地降級，並說明你在哪個等級上：
缺少 降級為 無子代理 / Workflow 序列化地、更小規模地執行分支 無網路存取 將研究標記為 *inferred*，依賴使用者提供事實無 Figma 用程式碼或書面規格製作原型 無託管 CI / 部署目標 一套綠燈的本地測試執行 + 一份文件化的部署計畫可算作已驗證—— verified≠hosted-CI-green較弱的模型 將 DoD 檢查清單視為存在性檢查；警告深度可能較淺 路由的技能/提供者缺失或已重新命名 使用參考文件中指定的備用方案，或最接近的等價方案——路由名稱是在使用時需要驗證的建議，而非保證
運作模式：編排者優先
主代理（你）始終扮演編排者 (Orchestrator)。 你擁有計畫；你將工作分解並分配給專業的子代理；你驗證並整合。你絕不 monolithic 地撰寫大量輸出。這從第 1 階段（每個競爭者的深度研究工作流程，每個本身又分支到許多子代理）一直貫穿到第 8 階段（每個功能片段一個子代理）。在第 7 階段，你將此正式化為一個 15 個角色的團隊，然後在第 8 階段執行。分支模式是預設值，而非例外——對於重度研究階段，它是嵌套的：你調度負責人，每個負責人再調度自己的 workers。深度來自於分層分支，而非一個代理更努力地工作。
但分支是昂貴的——嵌套的深度研究可能會啟動數十到數百個子代理。將深度視為一個可調的刻度盤，而非預設值：根據專案的風險等級調整其規模（參閱依風險調整規模），合理地設定上限，並在相關檢查點花費之前呈現大致的 token/時間成本，讓人類在知情的情況下選擇加入。在下一關之前無人閱讀的深度只是被浪費的預算。
worker 的硬回傳合約。 子代理的記憶是孤立的，而其原始輸出是垃圾資訊淹沒主代理視窗的最常見方式——因此每個分支 worker 將其大量輸出寫入一個檔案路徑，並僅回傳一個簡短的摘要（一兩段）+ 該路徑 + pass/fail 判定。 指揮者在需要細節時讀取該路徑；轉錄內容保持扁平。持久狀態透過共享檔案流動，而非透過 worker「記住」的內容。
慣例（適用於所有情況，無例外）
-
語言政策。 使用使用者的語言與他們對話——從他們寫給你的方式中檢測，或在開始時詢問一次，並將其記錄在
docs/STATE.md(conversation_language) 中。但是每個書面產物——docs/中的檔案、CLAUDE.md、技能、命令、提交訊息、程式碼註解——都使用英文，且識別碼為英文，這樣知識庫才能保持可攜性。（這是內部規則。面對使用者的產品文案則遵循產品的市場語言，在品牌階段決定——將兩者分開。） -
交付成果存放位置。 規劃階段的產物（第 1–6 階段）存放在
docs/<stage>/下。核心狀態與帳本存放在docs/STATE.md和docs/GATES.md。框架（第 7 階段）和建構（第 8 階段）則寫入 repo 根目錄和.claude/。資料夾對應：docs/ STATE.md GATES.md discovery/ product/ brand/ prototype/ stack/ instrumentation/ .claude/ # 在第 7 階段建立（代理、技能、命令、設定、MCP） knowledge/ # 在第 7 階段建立（版本化的 KB） specs/ # 在第 8 階段建立（每個功能的 SDD 規格） CLAUDE.md HARNESS.md PROGRESS.md CHANGELOG.md # repo 根目錄 -
精簡上下文，豐富知識。 保持根上下文 (
CLAUDE.md) 最小化。將深度推入docs/、knowledge/、技能和子代理提示中。絕不要將一個 60KB 的文件內聯到上下文中——指向它並讀取相關片段。這也適用於你的運作方式：這個 SKILL.md 是主幹；每個階段的參考文件包含深度。只在進入其階段時才載入參考文件。 -
上下文預算與配置。 將上下文視窗視為一個可耗盡的預算，而非自由空間：可靠性會隨著 live token 的數量而衰減（可信賴的工作集只是廣告視窗的一小部分），因此保持每個階段的工作集精簡，絕不讓一個執行緒無限制增長。對抗* lost-in-the-middle *——將最重要的資訊放在訊息的開頭和結尾附近，將參考材料、原始輸出和可選細節放在中間。在可能的情況下，使用結構化讀取（讀取檔案、搜尋、grep）而不是加載整個檔案。