Back to Details

writing-plans

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

编写计划

Writing a Plan

概述

Overview

编写全面的实现计划，假设工程师对我们的代码库零上下文，且品味存疑。记录他们需要知道的一切：每个任务要修改哪些文件、代码、测试、可能需要查阅的文档、如何测试。将整个计划拆成小步骤任务。DRY。YAGNI。TDD。频繁 commit。
假设他们是有经验的开发者，但对我们的工具链和问题领域几乎一无所知。假设他们不太擅长测试设计。
开始时宣布： "我正在使用 writing-plans 技能创建实现计划。"
上下文： 此技能应在专用 worktree 中运行（由 brainstorming 技能创建）。
计划保存位置： 
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
  • （用户对计划位置的偏好优先于此默认值）
Create a comprehensive implementation plan assuming engineers have zero context of our codebase and questionable taste. Document everything they need to know: which files, code, tests to modify for each task, documentation they might need to consult, how to test. Break the entire plan into small step-by-step tasks. DRY. YAGNI. TDD. Frequent commits.
Assume they are experienced developers but know almost nothing about our toolchain and problem domain. Assume they are not very good at test design.
Announce at the start: "I'm using the writing-plans skill to create an implementation plan."
Context: This skill should run in a dedicated worktree (created by the brainstorming skill).
Plan save location: 
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
  • (User preferences for plan location take precedence over this default)

范围检查

Scope Check

如果规格涵盖了多个独立子系统，它应该在头脑风暴阶段就被拆分为子项目规格。如果没有，建议将其拆分为独立的计划——每个子系统一个。每个计划应该能独立产出可工作、可测试的软件。
If the specification covers multiple independent subsystems, it should have been split into sub-project specifications during the brainstorming phase. If not, suggest splitting it into separate plans—one for each subsystem. Each plan should independently produce working, testable software.

文件结构

File Structure

在定义任务之前，先列出将要创建或修改的文件以及每个文件的职责。这是锁定分解决策的地方。
  • 设计边界清晰、接口定义良好的单元。每个文件应有一个明确的职责。
  • 你对能一次放入上下文的代码推理得最好，文件越专注你的编辑越可靠。优先选择小而专注的文件，而非承担过多功能的大文件。
  • 一起变更的文件应放在一起。按职责拆分，而非按技术层级拆分。
  • 在现有代码库中，遵循已有模式。如果代码库使用大文件，不要单方面重构——但如果你正在修改的文件已经变得难以管理，在计划中包含拆分是合理的。
此结构决定了任务分解。每个任务应产出独立的、有意义的变更。
Before defining tasks, list the files that will be created or modified and the responsibility of each file. This is where you lock down decomposition decisions.
  • Design units with clear boundaries and well-defined interfaces. Each file should have a single, clear responsibility.
  • You reason best about code that fits into context at once. The more focused the file, the more reliable your edits will be. Prioritize small, focused files over large files that take on too much functionality.
  • Files that change together should be placed together. Split by responsibility, not by technical layer.
  • In an existing codebase, follow existing patterns. If the codebase uses large files, don't unilaterally refactor—but if the file you're modifying has become unmanageable, it's reasonable to include splitting it in the plan.
This structure determines task decomposition. Each task should produce an independent, meaningful change.

小步骤任务粒度

Small Step Task Granularity

每步是一个操作（2-5 分钟）：
  • "编写失败的测试" - 一步
  • "运行它确认失败" - 一步
  • "实现最少代码让测试通过" - 一步
  • "运行测试确认通过" - 一步
  • "Commit" - 一步
Each step is an action (2-5 minutes):
  • "Write a failing test" - one step
  • "Run it to confirm failure" - one step
  • "Implement the minimal code to make the test pass" - one step
  • "Run the test to confirm pass" - one step
  • "Commit" - one step

计划文档头部

Plan Document Header

每个计划必须以此头部开始：
markdown
undefined
Every plan must start with this header:
markdown
undefined

[功能名称] 实现计划

[Feature Name] Implementation Plan

面向 AI 代理的工作者： 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（
- [ ]
）语法来跟踪进度。
目标： [一句话描述要构建什么]
架构： [2-3 句话描述方案]
技术栈： [关键技术/库]
undefined
For AI Agent Workers: Required sub-skill: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task by task. Use checkbox (
- [ ]
) syntax for steps to track progress.
Goal: [One-sentence description of what to build]
Architecture: [2-3 sentences describing the solution]
Tech Stack: [Key technologies/libraries]
undefined

任务结构

Task Structure

markdown
undefined
markdown
undefined

任务 N：[组件名称]

Task N: [Component Name]

文件：
  • 创建：
    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：Commit
bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
undefined
Files:
  • Create: 
    exact/path/to/file.py
  • Modify: 
    exact/path/to/existing.py:123-145
  • Test: 
    tests/exact/path/to/test.py
  • Step 1: Write a failing test
python
def test_specific_behavior():
    result = function(input)
    assert result == expected
  • Step 2: Run test to verify failure
Run: 
pytest tests/path/test.py::test_name -v
Expected: FAIL, error message "function not defined"
  • Step 3: Write minimal implementation code
python
def function(input):
    return expected
  • Step 4: Run test to verify pass
Run: 
pytest tests/path/test.py::test_name -v
Expected: PASS
  • Step 5: Commit
bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
undefined

禁止占位符

No Placeholders

每个步骤都必须包含工程师需要的实际内容。以下是计划缺陷——绝不要写出来：
  • "待定"、"TODO"、"后续实现"、"补充细节"
  • "添加适当的错误处理" / "添加验证" / "处理边界情况"
  • "为上述代码编写测试"（没有实际测试代码）
  • "类似任务 N"（重复代码——工程师可能不按顺序阅读任务）
  • 只描述做什么而不展示怎么做的步骤（代码步骤必须有代码块）
  • 引用了未在任何任务中定义的类型、函数或方法
Every step must contain the actual content engineers need. The following are plan defects—never write them:
  • "TBD", "TODO", "Implement later", "Add details"
  • "Add proper error handling" / "Add validation" / "Handle edge cases"
  • "Write tests for the above code" (no actual test code)
  • "Similar to Task N" (duplicate code—engineers may not read tasks in order)
  • Steps that only describe what to do without showing how (code steps must have code blocks)
  • References to types, functions, or methods not defined in any task

注意事项

Notes

  • 始终使用精确的文件路径
  • 每个步骤都包含完整代码——如果步骤涉及代码变更，就展示代码
  • 精确的命令和预期输出
  • DRY、YAGNI、TDD、频繁 commit
  • Always use precise file paths
  • Every step includes complete code—if a step involves code changes, show the code
  • Precise commands and expected output
  • DRY, YAGNI, TDD, frequent commits

自检

Self-Check

编写完整计划后，以全新视角审视规格并对照检查计划。这是你自己执行的检查清单——不是子代理调度。
1. 规格覆盖度： 浏览规格中的每个章节/需求。你能指出实现它的任务吗？列出所有遗漏。
2. 占位符扫描： 搜索计划中的红旗——上方"禁止占位符"章节中的任何模式。修复它们。
3. 类型一致性： 后续任务中使用的类型、方法签名和属性名是否与前面任务中定义的一致？任务 3 中叫 
clearLayers()
但任务 7 中叫 
clearFullLayers()
就是 bug。
如果发现问题，直接内联修复。无需重新审查——修好继续推进。如果发现规格中的需求没有对应任务，就添加任务。
After writing the complete plan, review the specification from a fresh perspective and cross-check against the plan. This is your own checklist to execute—not a sub-agent dispatch.
1. Specification Coverage: Go through each section/requirement in the specification. Can you point to the task that implements it? List all omissions.
2. Placeholder Scan: Search for red flags in the plan—any patterns from the "No Placeholders" section above. Fix them.
3. Type Consistency: Are the types, method signatures, and property names used in later tasks consistent with those defined in earlier tasks? A bug would be calling 
clearLayers()
in Task 3 but 
clearFullLayers()
in Task 7.
If issues are found, fix them inline. No need for re-review—fix and proceed. If requirements in the specification have no corresponding tasks, add tasks.

执行交接

Execution Handover

保存计划后，提供执行选项：
"计划已完成并保存到 
docs/superpowers/plans/<filename>.md
。两种执行方式：
1. 子代理驱动（推荐） - 每个任务调度一个新的子代理，任务间进行审查，快速迭代
2. 内联执行 - 在当前会话中使用 executing-plans 执行任务，批量执行并设有检查点
选哪种方式？"
如果选择子代理驱动：
  • 必需子技能： 使用 superpowers:subagent-driven-development
  • 每个任务一个新子代理 + 两阶段审查
如果选择内联执行：
  • 必需子技能： 使用 superpowers:executing-plans
  • 批量执行并设有检查点供审查
After saving the plan, provide execution options:
"Plan completed and saved to 
docs/superpowers/plans/<filename>.md
. Two execution options:
1. Sub-agent Driven (Recommended) - Dispatch a new sub-agent for each task, with reviews between tasks for rapid iteration
2. Inline Execution - Use executing-plans to perform tasks in the current session, with batch execution and checkpoints
Which one to choose?"
If choosing Sub-agent Driven:
  • Required Sub-skill: Use superpowers:subagent-driven-development
  • One new sub-agent per task + two-stage review
If choosing Inline Execution:
  • Required Sub-skill: Use superpowers:executing-plans
  • Batch execution with checkpoints for review