ce-plan

建立技術計畫

注意：目前年份為 2026 年。 在計畫中標註日期以及搜尋最新文件時請以此為準。

ce-brainstorm 透過建立僅包含需求的統一計畫來定義要建構什麼（WHAT）。ce-plan 則在同一個產出物中補充要如何建構（HOW）。ce-work 負責執行已具備實作條件的計畫。先前進行的 brainstorm 雖然能提供有用的背景資訊，但並非必要條件 —— ce-plan 可以處理任何輸入：僅包含需求的統一計畫、舊版需求文件、Bug 報告、功能構想或粗略的描述。

直接呼叫時，務必執行規劃。 絕不要將直接呼叫判定為「非規劃任務」而放棄工作流程。若輸入內容不明確，請提出澄清問題或使用規劃啟動流程（Phase 0.4）來建立足夠的背景資訊 —— 但始終保持在規劃工作流程中。

此工作流程會產生一份可持續使用的實作計畫。它不會撰寫程式碼、執行測試或從執行時期的結果中學習。若解答取決於修改程式碼並觀察結果，那屬於 ce-work 的範疇，而非本 Skill。

強制完成合約

所有會產生計畫產出物或檢查點的正常互動式 ce-plan 分支，在展示其對應的交接問題之前都不算完成。對於跨越 Phase 0.1b 的軟體實作計畫執行流程，該邊界為 Phase 5.4 的生成後交接選單。非軟體類的計畫尋求與做法層級分支，應使用其所路由至的參考工作流程中的終端交接；當這些分支被指示跳過後續階段後，請勿強迫它們通過 Phase 5.4。解答尋求分支是例外：它可以在提供解答後結束，除非通用規劃參考指引要求提供儲存/分享選項。

對於軟體實作計畫的執行，寫入計畫檔案、執行信心檢查以及執行或跳過 ce-doc-review 都只是中間的里程碑，並不代表完成。即使使用者的 Prompt 僅寫著「建立計畫」、「撰寫文件」、「執行 ce-doc-review」或類似要求時也是如此。唯一的例外是 Pipeline 模式（LFG 或任何 disable-model-invocation 的上下文），此時呼叫端會在計畫檔案、信心檢查與無頭文件審查完成後接管下一步。

在任何可能結束軟體實作計畫執行的回應之前，請確認計畫路徑已知、無頭審查狀態或已記錄的跳過狀態已完成摘要，並已詢問使用者：「Plan ready at <absolute path to plan>. What would you like to do next?」若選單適合平台的阻塞式提問工具，請使用該工具提問；否則在對話中繪製編號交接選項並等待。若使用者選擇了某項操作，請先執行該選擇對應的 Phase 5.4 路由，再將此 Skill 視為完成。

互動方式

向使用者提出問題時，請使用平台的阻塞式提問工具：Claude Code 中的 AskUserQuestion（若其 schema 未載入，請先使用 select:AskUserQuestion 呼叫 ToolSearch）、Codex 中的 request_user_input、Antigravity CLI（agy）中的 ask_question、Pi 中的 ask_user（需要 pi-ask-user 擴充套件）。僅當工具環境（harness）中不存在阻塞式工具或呼叫發生錯誤時（例如 Codex 編輯模式），才退回使用對話中的編號選項 —— 切勿因為需要載入 schema 就退回。絕不可默默跳過問題。

一次只問一個問題。當有自然合理的選項時，優先使用簡潔的單選題。

功能描述

**功能描述（Feature description）**是呼叫此 Skill 時傳入的輸入 —— 即要規劃的內容，包含在當前的 Prompt 或對話中，無論是使用者直接提供，或是由呼叫端 Skill 所傳遞（例如在 mode:pipeline 下的 lfg）。

若未提供功能描述，請詢問使用者：「What would you like to plan? Describe the task, goal, or project you have in mind.」（您想規劃什麼？請描述您心中的任務、目標或專案。）然後等待其回應再繼續。

若已提供輸入但內容不明確或規格不足，請勿放棄 —— 可提出一到兩個澄清問題，或直接進入 Phase 0.4 的規劃啟動流程以建立足夠背景資訊。目標始終是協助使用者進行規劃，絕非退出工作流程。

重要提示：計畫文件中的所有檔案參照都必須使用相對於儲存庫的相對路徑（例如 src/models/user.rb），絕不可使用絕對路徑（例如 /Users/name/Code/project/src/models/user.rb）。這適用於所有地方 —— 實作單元的檔案清單、範式（pattern）參照、原始文件連結以及內文提及。絕對路徑會破壞在不同機器、工作樹（worktree）及團隊成員之間的可攜性。

產出物根目錄

本 Skill 會在 <root>/plans/ 下寫入計畫，並在 <root>/solutions/ 下讀取經驗學習（learnings）。請在首次組合 <root>/ 路徑時（依據下文區塊）解析 <root>，切勿過早解析。寫入 <root>/... 與讀取 <root>/solutions/ 均視為組合 <root>/ 路徑，因此任一操作皆會觸發解析；只有完全不碰觸任何 <root>/ 路徑的執行（如僅使用暫存區或無 Repo 的流程）才能跳過；請將解析後的路徑傳遞給任何子 Agent，而非傳遞設定檔。

<!-- ce-docs-root:start -->
在組合任何產出物路徑之前，請先解析 CE 產出物根目錄 <root>。

• 從 <repo-root>/.compound-engineering/config.local.yaml 讀取 docs_root，若無則讀取 config.yaml；以第一個非空值為準（<repo-root> = git rev-parse --show-toplevel）。若未設定 -> <root> 預設為 docs，與先前完全一致。
• 驗證已設定的值：必須為相對於 Repo 的目錄，且經符號連結解析後的真實路徑需維持在 Repo 內部，既不能是 Repo 根目錄，也不能在 .git/ 底下。否則請停止執行並回報包含 docs_root 與該值的錯誤 —— 絕不要退回使用 docs。
• 使用 <root> 作為唯一的產出物位置：若不存在則建立，並將每個路徑組合為 <root>/<subdir>（搭配本 Skill 專屬的子目錄），切勿同時讀取 docs。
  <!-- ce-docs-root:end -->

核心原則

1. 以產品合約（Product Contract）作為唯一事實來源 - 若 ce-brainstorm 產出了僅包含需求的統一計畫，規劃階段應在原處加以豐富完善，而非重新發明行為或建立第二份產出物。
2. 注重決策而非程式碼 - 紀錄做法、邊界、檔案、相依性、風險與測試情境。不要預先撰寫實作程式碼或 Shell 命令編排。當偽程式碼（pseudo-code）草稿或 DSL 語法有助於審查者驗證方向時，歡迎用來溝通高階技術設計 —— 但必須明確將其定位為方向性指引，而非實作規格。
3. 先研究再建構結構 - 在敲定計畫之前，視需要先探索程式碼庫、組織內部經驗學習（institutional learnings）與外部指引。
4. 適度調整產出物規模 - 小型工作使用精簡計畫，大型工作則需要更完整的結構。無論深度如何，核心理念保持一致。
5. 切割規劃階段與執行階段的探索 - 在此處解決規劃時期的疑問。將執行時期的未知事項明確延後至實作階段處理。
6. 保持計畫的可攜性 - 計畫應能作為動態文件、審查產出物或 Issue 正文使用，而不嵌入特定工具的執行指令。
7. 在關鍵時刻輕量傳達執行方向 - 若需求、原始文件或 Repo 背景明確隱含了測試先行驗證（test-first proof）、特性覆蓋（characterization coverage）、冒煙優先驗證（smoke-first verification）或其他非預設的執行方向，請在計畫中以輕量化的自然語言標記體現。切勿將其編碼為固定列舉（enum）或將計畫變成一步步的執行步驟編排。
8. 尊重使用者指定的名詞與資源 - 當使用者指定特定資源 —— 例如 CLI、MCP 伺服器、URL、檔案、文件連結或先前的產出物 —— 請將其視為權威輸入，而非建議。若不熟悉該資源，請先進行探索（command -v、fetch、read），切勿直接假設其不可用。優先使用該資源替代通用方案。若執行失敗或資源不存在，請明確說明，而非默默替換。

計畫品質標準

每份計畫皆應包含：

• 清晰的背景問題架構與範圍邊界
• 可追溯回需求或原始文件的具體需求追溯性
• 擬議工作的 Repo 相對檔案路徑（絕不可使用絕對路徑 —— 參見規劃規則）
• 包含功能的實作單元之明確測試檔案路徑
• 包含理由依據的決策，而非僅有任務清單
• 可供遵循的現有範式（patterns）或程式碼參照
• 為每個包含功能的單元列舉測試情境，其具體程度需讓實作人員清楚知道要測試什麼，而無需自行捏造測試覆蓋範圍
• 清晰的相依性與執行順序

當實作人員能夠充滿自信地開始工作，且不需要計畫幫他們撰寫程式碼時，計畫即算準備妥當。

任務可見性

在評估階段確定 ce-plan 將執行實質的多階段流程後，若平台支援任務追蹤功能（task-tracking），請利用該功能向使用者展示根據所選路由及剩餘規劃工作所導出的簡短檢視。請追蹤具意義的成果，而非記錄每個階段、工具呼叫或微小步驟；僅在條件觸發門檻時新增條件工作，並在重要過渡點更新檢視。名稱請保持簡短且以成果為導向。若平台無任務追蹤功能，請正常繼續執行，無需在對話中模擬任務清單。

工作流程

Phase 0：復原、來源與範圍

0.0 解析輸出模式

在觸發任何其他階段之前先確定 OUTPUT_FORMAT。輸出模式為互斥的 —— 計畫只能寫入為 Markdown（.md）或 HTML（.html），絕不能兩者兼有。優先順序：Prompt 內的要求 > 使用者先前表達的偏好 > 設定檔 > 預設值（md），且受 Pipeline 模式的硬性覆蓋控制。

讀取設定檔。 執行階段透過 Shell 工具執行 git rev-parse --show-toplevel 來解析 <repo-root>。接著使用原生檔案讀取工具讀取 <repo-root>/.compound-engineering/config.local.yaml。若無法解析根目錄（非 Git 儲存庫）或檔案不存在，則依序降級至下述預設流程。

解析步驟：

1. Prompt 內的要求。 分析使用者本次執行的 Prompt，檢查是否有關於本文件輸出格式的要求，可能表現為 output: 簡寫或自然語言（「將計畫做成網頁」、「我想要 HTML 格式」）。若有明確格式，不分大小寫比對 md/html，並在將 Prompt 其餘部分讀取為功能描述時忽略 output: 簡寫標記。請區分針對文件格式的要求與作為主題名稱的格式：例如「新增 HTML 匯出功能」或「規劃 CSV 匯入器」是指工作內容，而非文件格式要求 —— 切勿據此切換模式。
   • 僅有 output:（無值）→ 不處理，進入步驟 2。
   • output:<unknown>（例如 output:pdf）→ 丟棄該標記，進入步驟 2，並記得在最終解析後於生成後選單上方輸出單行提示：Ignored unknown output: value '<value>' — using <resolved_format> instead.（忽略未知的 output 值 '<value>' — 改用 <resolved_format>）。其中 <resolved_format> 為經歷剩餘優先順序步驟後 OUTPUT_FORMAT 實際解析出的值。請勿在提示中硬編碼 md —— 當設定檔設為 HTML 時這會誤導使用者。
2. 使用者先前表達的偏好。 若本次 Prompt 未包含格式要求，請遵循使用者先前建立的輸出格式偏好（Markdown vs HTML）—— 無論是本階段稍早、您的記憶中，或寫入其作用中指令且已存在於目前上下文的偏好（不分大小寫比對 md/html）。被記住的偏好比鮮少修改的設定檔更即時，因此會覆蓋步驟 3 的設定檔。無需為了尋找偏好而開啟或搜尋指令檔案 —— 僅針對已存在於上下文中的偏好採取行動；若無，則進入設定檔流程。
3. 設定檔。 若步驟 1-2 未能解析出...