Back to Details

writing-plans

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Writing Plans

编写方案

Overview

概述

Create implementation plans for an engineer with zero codebase context.
Each plan includes:
  • Exact file paths for every operation
  • Complete code (not "add validation here")
  • Test-first approach with verification commands
  • Bite-sized steps (2-5 min each)
Principles: DRY, YAGNI, TDD, frequent commits.
Announce at start: "I'm using the 
writing-plans
skill to create the implementation plan."
Context: Run in dedicated worktree. If none exists, use 
using-git-worktrees
skill first.
Save plans to: 
docs/plans/YYYY-MM-DD-<feature-name>.md
为完全不了解代码库上下文的工程师创建实施方案。
每个方案包含：
  • 所有操作对应的准确文件路径
  • 完整代码（而非类似“在此处添加校验”的描述）
  • 测试先行的方法，附带验证命令
  • 极小粒度的步骤（每个步骤耗时2-5分钟）
原则：DRY, YAGNI, TDD, 高频提交。
开篇声明： "我将使用
writing-plans
技能来创建实施方案。"
上下文要求： 在专属工作树中运行。如果不存在，先使用
using-git-worktrees
技能。
方案保存路径： 
docs/plans/YYYY-MM-DD-<feature-name>.md

Before Writing

编写前准备

  1. Read spec/requirements completely
  2. Explore project structure (
    view .
    )
  3. Identify tech stack (package.json, pyproject.toml, etc.)
  4. Note existing patterns in similar files
  5. Check docs/ for existing conventions
  1. 完整阅读功能规格/需求文档
  2. 梳理项目结构（
    view .
    ）
  3. 确认技术栈（package.json、pyproject.toml等文件）
  4. 记录同类文件中的现有代码模式
  5. 检查docs/目录下的现有开发规范

Bite-Sized Task Granularity

极小粒度任务拆分

Each step is one action (2-5 minutes), independently verifiable:
  • "Write the failing test" — step
  • "Run it to confirm failure" — step
  • "Implement minimal code to pass" — step
  • "Run tests to confirm pass" — step
  • "Commit" — step
每个步骤仅对应一个操作（2-5分钟完成），可独立验证：
  • "编写失败测试用例" —— 步骤
  • "运行用例确认失败" —— 步骤
  • "编写最小可运行代码通过测试" —— 步骤
  • "运行测试确认通过" —— 步骤
  • "提交代码" —— 步骤

Plan Document Header

方案文档头部

Every plan MUST start with this header:
markdown
undefined
所有方案必须以下面的头部开头：
markdown
undefined

[Feature Name] Implementation Plan

[功能名称] 实施方案

Goal: [One sentence describing what this builds]
Architecture: [2-3 sentences about approach]
Tech Stack: [Key technologies/libraries]
undefined
目标： [用一句话描述本次开发的内容]
架构设计： [用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：运行测试确认用例失败
运行：
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"
undefined

Before Handoff

交付前检查

Verify plan completeness:
  • Every file path exists or will be created
  • Every command can be run exactly as written
  • No TODO/placeholder text remains
  • Tests cover all acceptance criteria from spec
  • Include exact test code, not descriptions
验证方案完整性：
  • 所有文件路径已存在或者会被创建
  • 所有命令可原样直接运行
  • 没有遗留TODO/占位符文本
  • 测试覆盖了规格文档中的所有验收标准
  • 包含完整的测试代码，而非描述性内容

Execution Handoff

执行交付

After saving plan, present:
"Plan saved to 
docs/plans/<filename>.md
. Choose execution mode:
  1. Subagent-Driven — same session, fresh subagent per task, fast iteration
  2. Parallel Session — new session, batched execution with checkpoints
Which approach?"
保存方案后，给出如下提示：
"方案已保存到
docs/plans/<filename>.md
，请选择执行模式：
  1. Subagent驱动 —— 同一会话，每个任务启用全新Subagent，迭代速度快
  2. 并行会话 —— 全新会话，带检查点的批量执行
请问选择哪种方式？"

If Subagent-Driven chosen

若选择Subagent驱动

  • Stay in this session
  • REQUIRED SUB-SKILL: 
    subagent-driven-development
  • Fresh subagent per task + two-stage review
  • 保持在当前会话
  • 必需子技能： 
    subagent-driven-development
  • 每个任务启用全新Subagent + 两阶段评审

If Parallel Session chosen

若选择并行会话

  • Guide user to open new session in worktree
  • REQUIRED SUB-SKILL: New session uses 
    executing-plans
  • 引导用户在工作树中打开新会话
  • 必需子技能： 新会话使用
    executing-plans