Back to Details

planning-documentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
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."
Context: This should be run in a dedicated worktree (created by brainstorming skill).
Save plans to: 
docs/plans/YYYY-MM-DD-<feature-name>.md
假设工程师对我们的代码库完全不了解，且缺乏良好的编码品味，编写全面的实施计划。记录他们需要了解的所有信息：每个任务需要修改哪些文件、可能需要查阅的代码、测试和文档，以及如何进行测试。将整个计划拆分为粒度极细的任务。遵循DRY、YAGNI、TDD原则，频繁提交代码。
假设他们是熟练的开发者，但对我们的工具集或问题领域几乎一无所知，且不太了解良好的测试设计方法。
开头需声明： "我正在使用writing-plans技能创建实施计划。"
上下文： 应在专用工作区（由brainstorming技能创建的worktree）中执行此操作。
计划保存路径： 
docs/plans/YYYY-MM-DD-<feature-name>.md

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分钟）：
  • "编写失败测试用例" - 步骤
  • "运行测试以确认其失败" - 步骤
  • "编写最小化代码使测试通过" - 步骤
  • "运行测试以确认其通过" - 步骤
  • "提交代码" - 步骤

Plan Document Header

计划文档头部

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

[Feature Name] Implementation Plan

[功能名称] 实施计划

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: [One sentence describing what this builds]
Architecture: [2-3 sentences about approach]
Tech Stack: [Key technologies/libraries]
undefined
致Claude： 必备子技能：使用superpowers:executing-plans逐步执行此计划。
目标： [一句话描述此计划要实现的内容]
架构： [2-3句话说明实现思路]
技术栈： [核心技术/库]
undefined

Task Structure

任务结构

markdown
undefined
markdown
undefined

Task N: [Component Name]

任务N：[组件名称]

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 the failing test
python
def test_specific_behavior():
    result = function(input)
    assert result == expected
Step 2: Run test to verify it fails
Run: 
pytest tests/path/test.py::test_name -v
Expected: FAIL with "function not defined"
Step 3: Write minimal implementation
python
def function(input):
    return expected
Step 4: Run test to verify it passes
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
文件：
  • 创建：
    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：运行测试以验证其失败
Run: 
pytest tests/path/test.py::test_name -v
Expected: FAIL with "function not defined"
步骤3：编写最小化实现代码
python
def function(input):
    return expected
步骤4：运行测试以验证其通过
Run: 
pytest tests/path/test.py::test_name -v
Expected: PASS
步骤5：提交代码
bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
undefined

Remember

注意事项

  • Exact file paths always
  • Complete code in plan (not "add validation")
  • Exact commands with expected output
  • Reference relevant skills with @ syntax
  • DRY, YAGNI, TDD, frequent commits
  • 始终使用精确的文件路径
  • 计划中包含完整代码（而非仅描述"添加验证"）
  • 提供精确的命令及预期输出
  • 使用@语法引用相关技能
  • 遵循DRY、YAGNI、TDD原则，频繁提交代码

Execution Handoff

执行交接

After saving the plan, offer execution choice:
"Plan complete and saved to 
docs/plans/<filename>.md
. Two execution options:
1. Subagent-Driven (this session) - I dispatch fresh subagent per task, review between tasks, fast iteration
2. Parallel Session (separate) - Open new session with executing-plans, batch execution with checkpoints
Which approach?"
If Subagent-Driven chosen:
  • REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
  • Stay in this session
  • Fresh subagent per task + code review
If Parallel Session chosen:
  • Guide them to open new session in worktree
  • REQUIRED SUB-SKILL: New session uses superpowers:executing-plans
保存计划后，提供执行选项：
"计划已完成并保存至
docs/plans/<filename>.md
。提供两种执行方式：
1. 子代理驱动（当前会话） - 我为每个任务分配新的子代理，在任务间进行审核，实现快速迭代
2. 并行会话（独立会话） - 打开新会话并使用executing-plans技能，批量执行并设置检查点
选择哪种方式？"
若选择子代理驱动：
  • 必备子技能： 使用superpowers:subagent-driven-development
  • 保留在当前会话中
  • 为每个任务分配新的子代理并进行代码审核
若选择并行会话：
  • 引导用户在工作区中打开新会话
  • 必备子技能： 新会话需使用superpowers:executing-plans