當任務需要在任何人開始建置之前被轉化為計劃時,使用此技能。它是 apw-implement 的上游夥伴,也是 apw-research / apw-brainstorm 的下游消費者:它接收一個模糊的簡報(加上任何文件或先前的產出物),並產出可供實作的持久性規劃文件。它的存在是為了對抗兩種失敗:僅在易失性上下文中持有完整計劃就跳入程式碼——導致步驟被跳過,工作偏離原始要求——以及產出一個失去其應滿足需求線索的計劃。請嚴格依序遵循以下步驟。
輸出風格
當此技能要求產出計劃、報告、摘要、狀態更新或其他面向聊天的輸出時,請優先使用項目符號或編號列表,而非純文字段落。保持每個項目簡潔且承載內容。省略那些僅用於潤飾語氣、重複脈絡或添加不改變意義的「語言糖」的語言。
步驟 1 — 吸收輸入
在形成任何計劃之前,閱讀所有定義任務的內容:
- 簡報 — 給定的任務描述、工單或請求。
- 提供的素材 — 隨附的任何文件、規格、設計或參考資料。
- 先前的產出物 — 如果您的工作項目的
research.md或brainstorm.md產出物已存在(請參閱apw-work-with-work-item-artifacts以了解它們的位置),則計劃建立在它們之上,而不是重做它們的工作。 - 程式碼庫 — 工作將觸及的檔案、模組和慣例,使計劃符合現實而非想像中的架構。
即使任務看起來很小,也不要跳過此步驟。計劃的好壞取決於其背後的理解。
步驟 2 — 陳述您的理解、提問並選擇深度
首先,撰寫一份關於您理解需要完成什麼的簡潔陳述——目標、您所理解的範圍,以及主要的工作項目。這讓使用者在任何文件撰寫之前有具體的內容可以修正。
然後,在同一輪互動中:
- 提出最多 5 個主要問題 — 僅針對會改變計劃的真正模糊之處。跳過任何您可以從步驟 1 中已回答的問題。不要為問而問。
- 詢問要產出哪種文件深度(使用 AskUserQuestion 工具):
- 完整 —
requirements.md+design.md+plan.md。適用於較大或風險較高的工作,其中什麼和如何都應在編寫任何程式碼之前確定。 - 中等 —
design.md+plan.md。當需求已經清晰(或在上游已捕獲),但技術/UI 方法仍需要決定時。 - 純計劃 —
plan.md僅。適用於已經充分理解,只需分解為有序、可檢查步驟的工作。
- 完整 —
在產生任何內容之前,等待使用者的回答和他們的深度選擇。
步驟 3 — 逐一產出並確認產出物
將文件(requirements.md、design.md、plan.md)寫入您工作項目的產出物資料夾——請參閱 apw-work-with-work-item-artifacts 以了解工作項目產出物的位置。
按照依賴順序逐一產出文件——絕不同時全部產出。 在寫完每個產出物後,停下來:告訴使用者它已準備就緒(及其路徑)和一份一兩行的摘要,說明其內容,然後等待他們的審查。使用者可以:
- 批准 → 繼續下一個產出物,或者
- 要求修改 → 修改該產出物並重新提交,重複此過程直到他們批准。
只能在前一個產出物已確認的基礎上建置下一個產出物——在需求被批准之前不得撰寫設計,在設計(和需求)被批准之前不得撰寫計劃。這種排序是重點:後續文件引用早期文件中的 ID,因此每個關卡都能防止下一個文件建立在使用者即將更改的內容之上。
順序取決於在步驟 2 中選擇的深度:
- 完整 →
requirements.md→ 審查 →design.md→ 審查 →plan.md→ 審查 - 中等 →
design.md→ 審查 →plan.md→ 審查 - 純計劃 →
plan.md→ 審查
每份文件都使用此技能資料夾中的模板:
requirements.md(僅完整模式) —REQUIREMENTS_TEMPLATE.md。為每個需求賦予一個穩定 ID(R1、R2、…),以便設計和計劃可以引用它。ID 一經分配不得更改。design.md(完整和中等模式) —DESIGN_TEMPLATE.md。涵蓋技術設計(主要的技術決策、各元件如何組合、哪些方案被拒絕)以及——僅當任務具有使用者可見的介面時——以 ASCII 模擬圖形式呈現的 UI 設計。為每個設計決策賦予一個穩定 ID(D1、D2、…),並將其連結到它所服務的需求。當沒有 UI 時,刪除 UI 部分。plan.md(所有深度) —PLAN_TEMPLATE.md。子任務的有序列表。規則:- 每個子任務都是一個未勾選的核取方塊:
- [ ]。該方塊供實作代理在完成該任務時勾選(- [x])——這是移交給apw-implement的機制。 - 在完整/中等模式下,每個任務都指明其實作了什麼——
(implements: R2, D1)。一個無法追溯到其來源需求和設計的計劃,正是此技能旨在防止的確切偏離。在純計劃深度下,沒有上游文件,因此省略引用並保持每個任務自包含。 - 每個任務具體且可獨立檢查,並附有「完成條件」說明。
- 按依賴關係排序任務;如果工作規模較大,則將其分組為階段。
- 每個子任務都是一個未勾選的核取方塊:
步驟 4 — 揭露衝突
如果在規劃過程中,您發現輸入之間相互矛盾、某個需求無法按所述實現,或者範圍明顯比簡報暗示的要大——停下來告訴使用者。與他們重新定義框架,而不是為錯誤的問題撰寫一個自信且結構良好的計劃。
步驟 5 — 簡潔摘要
每個產出物已在步驟 3 中逐一審查和批准,因此這是一個簡短的最終總結,而不是反對的首次機會。保持聊天簡潔——細節存在於產出物中。僅報告:
- 選擇的深度和所有已撰寫文件的路徑。
- 用一兩行描述計劃的輪廓——階段數量、任務數量、方法的主軸。
然後確認它已準備好移交給 apw-implement,並提供最後一次檢視機會,以防整套文件全部呈現後有任何需要更改之處。