首頁 全景圖 學習路線
namewriting-plans
description (EN)Use when you have a spec or requirements for a multi-step task, before touching code
說明 (繁中)當你有一份多步驟任務的規格或需求，在動任何程式碼之前使用

writing-plans

把定稿的設計拆成一步一步、小到 2–5 分鐘的任務，每個都標好檔案與驗證方式。
附屬文件：plan-document-reviewer-prompt

Writing Plans

撰寫計畫

Overview

總覽

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

撰寫全面的實作計畫，並假設工程師對我們的程式碼庫零上下文、品味存疑。記錄他們需要知道的一切：每個任務要動哪些檔案、程式碼、測試、可能需要查閱的文件、如何測試。把整個計畫拆成小塊任務交給他們。DRY。YAGNI。TDD。頻繁 commit。

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

假設他們是熟練的開發者，但對我們的工具組或問題領域幾乎一無所知。假設他們不太懂好的測試設計。

Announce at start: "I'm using the writing-plans skill to create the implementation plan."

開始時宣告： 「我正使用 writing-plans 技能來建立實作計畫。」

Context: If working in an isolated worktree, it should have been created via the superpowers:using-git-worktrees skill at execution time.

上下文： 如果在隔離的 worktree 中工作，它應該已在執行時透過 superpowers:using-git-worktrees 技能建立。

Save plans to: docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md - (User preferences for plan location override this default)

計畫儲存位置： docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md - （使用者對計畫位置的偏好會覆蓋這個預設）

Scope Check

範圍檢查

If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

如果規格涵蓋多個獨立的子系統，它應該在腦力激盪時被拆成子專案規格。如果沒有，建議把它拆成多份獨立計畫 —— 每個子系統一份。每份計畫應該要能獨立產出可運作、可測試的軟體。

File Structure

檔案結構

Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

在定義任務之前，先規劃哪些檔案會被建立或修改，以及每個檔案負責什麼。分解的決策在這裡鎖定。

  • Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
  • You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
  • Files that change together should live together. Split by responsibility, not by technical layer.
  • In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.
  • 設計邊界清楚、介面定義良好的單元。每個檔案應該有單一清楚的職責。
  • 你對能同時放進上下文的程式碼思考得最好，而檔案越聚焦，你的編輯就越可靠。偏好較小、聚焦的檔案，勝過塞太多事的巨型檔案。
  • 一起變更的檔案應該住在一起。依職責拆分，而不是依技術層拆分。
  • 在既有程式碼庫中，遵循既有模式。如果程式碼庫使用大型檔案，不要單方面重構 —— 但如果你正在修改的檔案已經長到難以掌控，把拆分寫進計畫是合理的。

This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

這個結構支撐任務的分解。每個任務應該產出自足的變更，且可以獨立理解。

Task Right-Sizing

任務尺寸調校

A task is the smallest unit that carries its own test cycle and is worth a fresh reviewer's gate. When drawing task boundaries: fold setup, configuration, scaffolding, and documentation steps into the task whose deliverable needs them; split only where a reviewer could meaningfully reject one task while approving its neighbor. Each task ends with an independently testable deliverable.

一個任務是承載自己的測試循環、並值得一個全新審查者關卡的最小單位。在劃分任務邊界時：把設定、配置、脚手架與文件步驟併入需要這些產物的任務；只有在審查者可以有意義地否決一個任務、同時核准其鄰居任務的地方才拆分。每個任務都以一個可獨立測試的產物結束。

Bite-Sized Task Granularity

小塊任務粒度

Each step is one action (2-5 minutes): - "Write the failing test" - step - "Run it to make sure it fails" - step - "Implement the minimal code to make the test pass" - step - "Run the tests and make sure they pass" - step - "Commit" - step

每個步驟是單一動作（2-5 分鐘）： - 「撰寫失敗的測試」- 步驟 - 「執行它以確認它失敗」- 步驟 - 「撰寫能讓測試通過的最小程式碼」- 步驟 - 「執行測試並確認它們通過」- 步驟 - 「Commit」- 步驟

Plan Document Header

計畫文件標頭

Every plan MUST start with this header:

每份計畫都必須以此標頭開始：

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

## Global Constraints

[The spec's project-wide requirements — version floors, dependency limits,
naming and copy rules, platform requirements — one line each, with exact
values copied verbatim from the spec. Every task's requirements implicitly
include this section.]

---

# [Feature Name] Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

## Global Constraints

[The spec's project-wide requirements — version floors, dependency limits,
naming and copy rules, platform requirements — one line each, with exact
values copied verbatim from the spec. Every task's requirements implicitly
include this section.]

---

Task Structure

任務結構

````markdown

Task N: [Component Name]

Files: - Create: exact/path/to/file.py - Modify: exact/path/to/existing.py:123-145 - Test: tests/exact/path/to/test.py

Interfaces: - Consumes: [what this task uses from earlier tasks — exact signatures] - Produces: [what later tasks rely on — exact function names, parameter and return types. A task's implementer sees only their own task; this block is how they learn the names and types neighboring tasks use.]

  • [ ] Step 1: Write the failing test

```python

````markdown

Task N: [Component Name]

Files: - Create: exact/path/to/file.py - Modify: exact/path/to/existing.py:123-145 - Test: tests/exact/path/to/test.py

Interfaces: - Consumes: [what this task uses from earlier tasks — exact signatures] - Produces: [what later tasks rely on — exact function names, parameter and return types. A task's implementer sees only their own task; this block is how they learn the names and types neighboring tasks use.]

  • [ ] Step 1: Write the failing test

```python

def test_specific_behavior(): result = function(input) assert result == expected ```

def test_specific_behavior(): result = function(input) assert result == expected ```

  • [ ] Step 2: Run test to verify it fails
  • [ ] Step 2: Run test to verify it fails

Run: pytest tests/path/test.py::test_name -v Expected: FAIL with "function not defined"

Run: pytest tests/path/test.py::test_name -v Expected: FAIL with "function not defined"

  • [ ] Step 3: Write minimal implementation
  • [ ] Step 3: Write minimal implementation
def function(input):
    return expected

def function(input):
    return expected
  • [ ] Step 4: Run test to verify it passes
  • [ ] Step 4: Run test to verify it passes

Run: pytest tests/path/test.py::test_name -v Expected: PASS

Run: pytest tests/path/test.py::test_name -v Expected: PASS

  • [ ] Step 5: Commit
  • [ ] Step 5: Commit
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"

git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"

````

No Placeholders

Every step must contain the actual content an engineer needs. These are plan failures — never write them: - "TBD", "TODO", "implement later", "fill in details" - "Add appropriate error handling" / "add validation" / "handle edge cases" - "Write tests for the above" (without actual test code) - "Similar to Task N" (repeat the code — the engineer may be reading tasks out of order) - Steps that describe what to do without showing how (code blocks required for code steps) - References to types, functions, or methods not defined in any task

Self-Review

After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.

1. Spec coverage: Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.

2. Placeholder scan: Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.

3. Type consistency: Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called clearLayers() in Task 3 but clearFullLayers() in Task 7 is a bug.

If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.

Execution Handoff

After saving the plan, offer execution choice:

"Plan complete and saved to docs/superpowers/plans/<filename>.md. Two execution options:

1. Subagent-Driven (recommended) - I dispatch a fresh subagent per task, review between tasks, fast iteration

2. Inline Execution - Execute tasks in this session using executing-plans, batch execution with checkpoints

Which approach?"

If Subagent-Driven chosen: - REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development - Fresh subagent per task + two-stage review

If Inline Execution chosen: - REQUIRED SUB-SKILL: Use superpowers:executing-plans - Batch execution with checkpoints for review

````

禁止占位符

每個步驟都必須包含工程師需要的實際內容。這些都是計畫失敗——絕不允許： - 「TBD」「TODO」「之後再實作」「補上細節」 - 「加入適當的錯誤處理」/「加入驗證」/「處理邊界情況」 - 「為上述撰寫測試」（沒有實際測試程式碼） - 「類似任務 N」（重複程式碼 —— 工程師可能不依順序閱讀任務） - 只描述要做什麼、卻不展示怎麼做的步驟（程式碼步驟需要程式碼區塊） - 引用任何任務中都未定義的型別、函式或方法

自我審查

寫完完整計畫後，以全新眼光看待規格，並據此檢查計畫。這是你自己執行的檢查清單 —— 不是子代理派發。

1. 規格涵蓋： 略讀規格中的每個段落/需求。你能指出實作它的任務嗎？列出任何缺口。

2. 占位符掃描： 搜尋計畫中的紅旗 —— 上方「禁止占位符」一節的任何模式。修正它們。

3. 型別一致性： 你在後續任務中使用的型別、方法簽名與屬性名稱，是否與較早任務中定義的一致？任務 3 中叫 clearLayers()、任務 7 卻叫 clearFullLayers() 的函式就是一個 bug。

如果發現問題，就地修正。不需要重新審查 —— 修好就繼續。如果發現某個規格需求沒有對應任務，就把任務加上去。

執行交接

儲存計畫後，提供執行方式的選擇：

「計畫已完成並儲存至 docs/superpowers/plans/<filename>.md。兩種執行方式：

1. 子代理驅動（建議） - 每個任務派發全新子代理，任務之間進行審查，快速迭代

2. 行內執行 - 使用 executing-plans 在此 session 中執行任務，批次執行並設檢查點

想用哪一種？」

如果選擇子代理驅動： - 必要子技能： 使用 superpowers:subagent-driven-development - 每個任務全新子代理 + 兩階段審查

如果選擇行內執行： - 必要子技能： 使用 superpowers:executing-plans - 批次執行並設審查檢查點