Back to Details

writing-plans

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing Plans

编写计划

Purpose

用途

Create executable, low-ambiguity implementation plans that another engineer can run task-by-task with predictable outcomes.
创建可执行、低歧义的实施计划，可供其他工程师按步骤执行，产出可预测的结果。

When to Use

适用场景

Use this skill when:
  • Requirements/specs exist but implementation has not started
  • Work is multi-step and requires coordination across files and tests
  • A handoff-ready plan is needed for another session or engineer
在以下场景中使用该技能：
  • 已有需求/规格说明，但尚未启动实施
  • 工作内容为多步骤，需要跨文件和跨测试协调
  • 需要为后续会话或其他工程师准备可直接交接的计划

Progress Tracking

进度追踪

Display progress at each planning phase:
[████░░░░░░░░░░░░░░░░] 25% — Phase 1/4: Gathering Context & Constraints
[████████░░░░░░░░░░░░] 50% — Phase 2/4: Decomposing Into Tasks
[████████████░░░░░░░░] 75% — Phase 3/4: Specifying Files & Commands
[████████████████████] 100% — Phase 4/4: Writing & Saving Plan
在每个规划阶段展示进度：
[████░░░░░░░░░░░░░░░░] 25% — Phase 1/4: Gathering Context & Constraints
[████████░░░░░░░░░░░░] 50% — Phase 2/4: Decomposing Into Tasks
[████████████░░░░░░░░] 75% — Phase 3/4: Specifying Files & Commands
[████████████████████] 100% — Phase 4/4: Writing & Saving Plan

Workflow

工作流程

  1. Gather context and constraints
  2. Break work into bite-sized, test-first tasks
  3. Specify exact files, code snippets, and commands
  4. Add validation criteria and expected outputs
  5. Save plan and hand off to 
    executing-plans
  1. 收集上下文信息和约束条件
  2. 将工作拆分为小颗粒度的、测试优先的任务
  3. 明确指定具体文件、代码片段和命令
  4. 添加验证标准和预期输出
  5. 保存计划并移交至
    executing-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原则，频繁提交。
假设执行工程师技术能力合格，但几乎不了解我们的工具集或问题领域，同时不太擅长设计合理的测试用例。
启动时声明： "I'm using the writing-plans skill to create the implementation plan."
上下文说明： 该流程应在专用worktree中运行（由brainstorming技能创建）。
计划保存路径： 
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
所有计划 MUST 以如下头部开头：
markdown
undefined

[Feature Name] Implementation Plan

[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
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

Task Structure

任务结构

markdown
undefined
markdown
undefined

Task N: [Component Name]

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
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
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

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
  • 始终提供准确的文件路径
  • 计划中要包含完整代码（不要只写"add validation"）
  • 提供准确的命令及预期输出
  • 使用@语法引用相关技能
  • 遵循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
保存计划后，提供执行选项：
"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?"
如果选择Subagent-Driven：
  • REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
  • 留在当前会话
  • 每个任务分配新的subagent + 代码评审
如果选择Parallel Session：
  • 引导用户在worktree中开启新会话
  • REQUIRED SUB-SKILL: New session uses superpowers:executing-plans

Critical Rules

核心规则

  • Always include exact paths and exact commands.
  • Always define expected outcomes for test/verification steps.
  • Never leave steps abstract (avoid "implement validation" without concrete code intent).
  • 始终包含准确的路径和命令。
  • 始终为测试/验证步骤定义预期结果。
  • 绝对不要使用抽象的步骤描述（避免没有具体代码实现说明的"implement validation"这类表述）。

Example Usage

用法示例

  1. "Use writing-plans to plan migration from REST to GraphQL."
  2. "Use writing-plans to break down an auth refactor into TDD tasks."
  3. "Use writing-plans to prepare a handoff plan for a new caching layer."
  1. "Use writing-plans to plan migration from REST to GraphQL."
  2. "Use writing-plans to break down an auth refactor into TDD tasks."
  3. "Use writing-plans to prepare a handoff plan for a new caching layer."