架構優先規劃 是做什麼的？
規劃首先要回答兩個問題：有哪些元件，它們如何連接（圖表），以及它們之間的確切合約是什麼（介面）。任務清單是次要的；優秀的實作者可以從好的介面推導出任務清單。
計畫是本機且個人化的：~/plans/<YYYY-MM-DD>-<slug>/。Markdown 檔案是唯一真相來源。Artifact 則是它的檢視畫面。
1. 理解需求
- 用一兩句話重新陳述目標，以及明確排除在範圍外的內容。
- 如果需求不明確，請提問（參見下方的提問技巧）。只詢問會影響設計的問題。如果答案開啟了新的分支，則再進行一輪。
- 當好的預設值取決於程式碼現有的內容時，先快速執行步驟 2，這樣你的建議才會基於儲存庫的實際情況，而非猜測。
提問技巧
對使用者的每個提問（在此步驟、辯論後以及迭代過程中）都必須透過 AskUserQuestion 工具進行，絕不能在聊天中以清單形式提出。使用者應能透過點擊來回答大多數問題：
- 預先填寫建議。 將你選擇的選項放在第一個，並在其標籤結尾加上
(推薦)。根據程式碼庫現有的模式、AGENTS.md以及能讓設計最簡潔的原則來決定。 - 每個問題提供 2–4 個具體選項，每個選項都必須是真實的選擇，並附有說明該選擇對設計的影響（例如「新增遷移」、「重複使用
useCursorFeed」）。不要添加「其他」選項：工具會自動提供一個用於輸入自由文字的選項。 - 自包含。 使用者可能只看到對話框，因此每個問題都應指明功能名稱和正在決策的事項，並簡短說明你發現了什麼（如果這是驅動問題的原因）。
- 每次呼叫最多 4 個問題，每個問題帶有一個簡短的
header標籤（≤12 個字元，例如「儲存」、「驗證」、「範圍」）。將相關問題分組；其餘問題則進行另一次呼叫。 - 僅在選項不互斥時（例如「哪些表面會套用此功能？」）使用
multiSelect。在比較具體的成品（如介面草稿、Schema、ASCII 佈局）時使用preview。 - 如果你有明確的答案且該選擇很容易撤銷，則不要提問：直接決定，並記錄在決策表中。
2. 收集上下文
在 phave-ng（主要檢出目錄或堆疊的工作樹）中：
- 首先閱讀
CLAUDE.md、AGENTS.md和.claude/rules/*。它們包含了你不能牴觸的決策。 - 找出既有的內容：功能會觸及或可重複使用的型別、服務、路由、資料表、工作與元件。若要廣泛掃描，請對每個區域並行執行
Explore代理，並僅保留它們的結論。 - 記下你將擴充的每個現有介面，包含其
path:line。
3. 評估規模
| 小型 | 大型 | |
|---|---|---|
| 徵兆 | 僅涉及程式碼庫的一個區域，大約一個 PR（少於 ~400 行），無遷移或只有瑣碎的遷移 | 涉及多個區域、Schema 變更、新的背景工作、超過一個 PR，或需要多人或多個 Session |
| 產出 | 僅 plan.md | plan.md 加上 slices/01-<name>.md、slices/02-<name>.md…… |
不要切割小型工作。 對一個 PR 就能完成的變更增加儀式感是浪費時間。
對於大型工作，進行垂直切片：每個切片本身可合併、讓主線保持可運作，並交付可測試的內容。僅 Schema 的「切片」或「前端切片」不是真正的切片。按依賴關係排序切片，並讓每個切片大致相當於一個 PR。
4. 撰寫計畫
~/plans/<date>-<slug>/plan.md：
# <標題>
**狀態：** 草稿 | 已核准 | 進行中 | 已完成
**規模：** 小型 | 大型 (N 個切片)
**儲存庫 / 基底：** phave-ng @ <提交>
## 目標
<2–3 句話> · **範圍外：** <項目符號>
## 架構
### 元件
<Mermaid 流程圖：現有元件使用一般樣式，新元件使用突顯樣式，變更的元件加上標記>
### 主要流程
<為每個重要流程繪製 Mermaid 循序圖，包含主要的錯誤路徑>
### 資料模型
<如果表格或欄位有變更，使用 Mermaid 實體關係圖；如果事物有生命週期，使用狀態圖>
## 介面
<功能新增或變更的每個合約，以儲存庫語言的實際程式碼呈現。
每個介面標記為 NEW 或 CHANGED，並附上其目標檔案路徑。>
- 型別 / 領域模型
- 函式與服務：完整的簽章，以及它們會拋出的例外
- HTTP / 伺服器動作：方法、路徑、請求和回應型別、驗證方式、錯誤碼
- 資料庫：表格、欄位、索引、列層級安全原則、遷移名稱
- 工作 / 事件：名稱、酬載型別、冪等性、重試機制
- UI 元件：屬性（props），以及用來渲染它們的頁面
## 關鍵設計決策
| 決策 | 考慮的選項 | 選擇的選項 | 原因 |
## 開放問題
- [ ] <問題> — 誰可以回答，以及答案會改變什麼
## 切片 (僅限大型)
| 編號 | 切片 | 交付內容 | 依賴於 | 狀態 |
## 計畫 (僅限小型)
<有序步驟；每個步驟包含：它實作的介面、檔案，以及測試方式>
## 測試策略
<說明哪些部分進行單元測試，哪些部分需要對堆疊進行測試（參閱 `ai-test` / `manual-test`）>
## 風險
每個 slices/0N-<name>.md 包含：目標、來自 plan.md 的它所實作的介面（連結過去，不要複製）、檔案、有序步驟、驗收標準、測試，以及實作筆記（留空，由 implement-plan 填入）。
規則：
- 圖表使用 Mermaid，每個圖表只表達一個概念。如果一個圖表需要超過 ~12 個節點，請將其拆分。
- 介面使用程式碼，而非文字描述。指定實際的檔案名稱。盡可能重複使用現有型別，並加以說明。
- 任何一位合理的工程師可能做出不同選擇的決策，都必須記錄在決策表中。
- 未知事項記錄在開放問題中，每個問題附上你建議的答案。不要暗中猜測。
5. 評論者 / 捍衛者辯論
使用 Agent 工具並行啟動兩個代理。給予每個代理計畫檔案路徑和要讀取的關鍵儲存庫檔案，但不要給予你的結論：
- 評論者：「找出問題所在。設計是否符合目標？介面是否遺漏、有漏洞或與程式碼庫模式不一致？切片是否不是真正的垂直切片？是否有過度設計或規格不足的部分、錯過的重複使用機會、失敗模式、遷移風險、權限缺口？針對每個問題提出具體的修復方案。」
- 捍衛者：「為計畫的選擇提出最有力的論據，特別是在明顯的替代方案被拒絕的地方。指出評論者可能會攻擊的要點，並解釋為什麼目前的設計站得住腳。」
然後進行反駁回合：將另一個代理的輸出發送給每個代理（使用 SendMessage），要求其針對每個要點承認或堅持，並附上理由。
你是裁判。針對每個爭論點：
- 同意變更：將其套用到
plan.md/ 切片檔案中。 - 未解決，且需要使用者介入：將其移至開放問題，並附上你建議的選項。
- 拒絕變更：保留原決策，並在決策表中記錄原因。
在 plan.md 結尾附加一個 ## 辯論摘要：要點 → 評論者 → 捍衛者 → 裁決。
6. 以 Artifact 呈現
載入 artifact-design 與用於圖表的 artifact-diagramming。發佈一個供審閱的頁面，順序如下：
- 標題、狀態、規模，以及一個段落的摘要
- 關鍵設計決策（表格）
- 開放問題：你需要使用者提供的資訊，優先顯示且易於找到
- 架構圖，以渲染後的圖表呈現，而非原始 Mermaid 文字
- 介面，以突顯的程式碼呈現，按層分組，附上 NEW / CHANGED 標籤
- 切片（大型）或步驟（小型）
- 辯論重點：僅列出改變了計畫或仍然懸而未決的觀點
plan.md的本機路徑
在聊天中提供連結。然後使用 AskUserQuestion (參見提問技巧) 提問開放問題，每個問題將評論者與捍衛者的立場作為選項，並將你的建議放在第一個。
7. 迭代直到核准
使用者的答案和意見會先寫入 plan.md：已回答的問題從開放問題移至決策表。在迭代過程中產生的新問題，以相同方式提問，使用 AskUserQuestion 並附上建議選項。然後重新發佈同一個 Artifact（使用相同的檔案路徑，以便 URL 保持不變）。當使用者核准時，設定狀態：已核准，並引導他們使用 implement-plan。
請勿在此技能中撰寫產品程式碼。