當你有多步驟任務的規格或需求時使用，在碰觸程式碼之前
撰寫計畫
概述
撰寫全面的實作計畫，假設工程師對我們的程式碼庫一無所知且品味可疑。記錄他們需要知道的一切：每個任務要碰觸哪些檔案、程式碼、測試、可能需要查看的文件、如何測試。把整個計畫拆成一口大小的任務。DRY。YAGNI。TDD。頻繁提交。
假設他們是熟練的開發者，但對我們的工具集或問題領域幾乎一無所知。假設他們不太擅長設計好的測試。
開始時宣告：「我正在使用 writing-plans 技能來建立實作計畫。」
上下文： 如果在隔離的工作樹中工作，該工作樹應已在執行時透過 superpowers:using-git-worktrees 技能建立。
儲存計畫至： docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
- （使用者對計畫位置的偏好會覆蓋此預設值）
範圍檢查
如果規格涵蓋多個獨立子系統，則應在腦力激盪期間將其拆分為子專案規格。如果沒有，建議將其拆分為多個計畫——每個子系統一個。每個計畫應能獨立產出可運作、可測試的軟體。
檔案結構
在定義任務之前，先規劃哪些檔案將被建立或修改，以及每個檔案的職責。這是分解決策被鎖定的地方。
- 設計邊界清晰、介面定義良好的單元。每個檔案應有一個明確的職責。
- 你對能一次掌握在上下文中的程式碼推理最佳，當檔案專注時，你的編輯更可靠。偏好較小、專注的檔案，而非過於龐大的檔案。
- 一起變更的檔案應放在一起。按職責拆分，而非按技術層。
- 在現有程式碼庫中，遵循既有模式。如果程式碼庫使用大型檔案，不要單方面重構——但如果正在修改的檔案變得難以管理，在計畫中包含拆分是合理的。
此結構會影響任務分解。每個任務應產生獨立有意義的、自包含的變更。
一口大小的任務粒度
每個步驟是一個動作（2-5 分鐘）：
- 「撰寫會失敗的測試」- 步驟
- 「執行它以確認它失敗」- 步驟
- 「實作讓測試通過的最小程式碼」- 步驟
- 「執行測試並確認它們通過」- 步驟
- 「提交」- 步驟
計畫文件標頭
每個計畫必須以此標頭開頭：
# [功能名稱] 實作計畫
> **給代理工作者：** 必備子技能：使用 superpowers:subagent-driven-development（建議）或 superpowers:executing-plans 來逐步實作此計畫。步驟使用核取方塊（`- [ ]`）語法來追蹤。
**目標：** [一句話描述此功能建構的內容]
**架構：** [2-3 句關於方法]
**技術棧：** [關鍵技術/函式庫]
---
任務結構
### 任務 N：[元件名稱]
**檔案：**
- 建立：`exact/path/to/file.py`
- 修改：`exact/path/to/existing.py:123-145`
- 測試：`tests/exact/path/to/test.py`
- [ ] **步驟 1：撰寫會失敗的測試**
```python
def test_specific_behavior():
result = function(input)
assert result == expected
```
- [ ] **步驟 2：執行測試以確認它失敗**
執行：`pytest tests/path/test.py::test_name -v`
預期：FAIL 並顯示「function not defined」
- [ ] **步驟 3：撰寫最小實作**
```python
def function(input):
return expected
```
- [ ] **步驟 4：執行測試以確認它通過**
執行：`pytest tests/path/test.py::test_name -v`
預期：PASS
- [ ] **步驟 5：提交**
```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```
無佔位符
每個步驟必須包含工程師實際需要的內容。以下是計畫失敗——永遠不要寫它們：
- 「待定」、「待辦」、「稍後實作」、「填寫細節」
- 「加入適當的錯誤處理」/「加入驗證」/「處理邊界情況」
- 「為上述內容撰寫測試」（沒有實際測試程式碼）
- 「類似於任務 N」（重複程式碼——工程師可能不按順序閱讀任務）
- 描述要做什麼但未展示如何做的步驟（程式碼步驟需要程式碼區塊）
- 引用任何任務中未定義的型別、函式或方法
記住
- 永遠使用確切檔案路徑
- 每個步驟中的完整程式碼——如果步驟變更程式碼，顯示程式碼
- 確切命令與預期輸出
- DRY、YAGNI、TDD、頻繁提交
自我審查
撰寫完整計畫後，以全新眼光檢視規格，並檢查計畫是否符合。這是你自己執行的檢查清單——不是子代理分派。
1. 規格覆蓋率： 瀏覽規格中的每個章節/需求。你能指出哪個任務實作了它？列出任何缺口。
2. 佔位符掃描： 搜尋計畫中的紅旗——上述「無佔位符」章節中的任何模式。修正它們。
3. 型別一致性： 你在後續任務中使用的型別、方法簽名和屬性名稱是否與先前任務中定義的一致？在任務 3 中叫 clearLayers() 但在任務 7 中叫 clearFullLayers() 的函式就是一個錯誤。
如果發現問題，就地修正。無需重新審查——只需修正並繼續。如果發現規格需求沒有對應任務，則加入該任務。
執行交接
儲存計畫後，提供執行選擇：
「計畫完成並儲存至 docs/superpowers/plans/<filename>.md。兩個執行選項：
1. 子代理驅動（建議） - 我為每個任務分派一個全新的子代理，在任務之間進行審查，快速迭代
2. 內聯執行 - 在此對話中執行任務，使用 executing-plans，批次執行並設有檢查點
選擇哪種方式？」
如果選擇子代理驅動：
- 必備子技能： 使用 superpowers:subagent-driven-development
- 每個任務使用全新子代理 + 兩階段審查
如果選擇內聯執行：
- 必備子技能： 使用 superpowers:executing-plans
- 批次執行並設有檢查點以供審查
