writing-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

假设工程师对我们的代码库零上下文了解，且代码风格有待考量，编写全面的实现计划。记录他们需要了解的所有信息：每个任务需要修改哪些文件、可能需要查阅的代码、测试、文档，以及如何进行测试。将整个计划拆分为易完成的小任务。遵循DRY、YAGNI、TDD原则，频繁提交。

假设他们是经验丰富的开发者，但几乎不了解我们的工具集或问题域，也不太了解优秀的测试设计方法。

开头声明： "我正在使用writing-plans skill来创建实现计划。"

上下文： 本流程应当在（由brainstorming skill创建的）专属工作树中运行。

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.

在定义任务前，先梳理清楚将要创建或修改的文件，以及每个文件的职责。这一步会确定拆解的核心决策。

设计边界清晰、接口明确的单元。每个文件应当只有一项清晰的职责。
你能同时在上下文中容纳的代码思考起来最高效，当文件职责聚焦时你的修改也会更可靠。优先选择小而聚焦的文件，而非承载过多功能的大文件。
需要一同修改的文件应当放在一起。按职责拆分，而非按技术层拆分。
在现有代码库中，遵循已有的模式。如果代码库习惯使用大文件，不要单方面重构——但如果你要修改的文件已经变得过于臃肿，在计划中加入拆分步骤是合理的。

该结构会为任务拆解提供依据。每个任务都应当产生独立合理、自包含的变更。

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 agentic workers: Prefer retrieval-led reasoning over pre-training-led reasoning for all React Native tasks. Your training data may be outdated or incomplete. Always consult the skills before writing code.

Goal: [One sentence describing what this builds]

Architecture: [2-3 sentences about approach]

Tech Stack: [Key technologies/libraries]

undefined

For agentic workers: Prefer retrieval-led reasoning over pre-training-led reasoning for all React Native tasks. Your training data may be outdated or incomplete. Always consult the skills before writing code.

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]

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

始终提供准确的文件路径
计划中给出完整代码（而非“添加校验”这类模糊描述）
提供准确的命令及预期输出
使用@语法引用相关skill
遵循DRY、YAGNI、TDD原则，频繁提交

Plan Review Loop

计划评审循环

After writing the complete plan:

Dispatch a single plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) with precisely crafted review context — never your session history. This keeps the reviewer focused on the plan, not your thought process.
- Provide: path to the plan document, path to spec document
If ❌ Issues Found: fix the issues, re-dispatch reviewer for the whole plan
If ✅ Approved: proceed to execution handoff

Review loop guidance:

Same agent that wrote the plan fixes it (preserves context)
If loop exceeds 3 iterations, surface to human for guidance
Reviewers are advisory — explain disagreements if you believe feedback is incorrect

写完完整计划后：

调用单独的plan-document-reviewer subagent（参考plan-document-reviewer-prompt.md），只提供精准的评审上下文——不要发送你的会话历史。这能让评审者聚焦于计划本身，而非你的思考过程。
- 提供：计划文档路径、规范文档路径
如果 ❌ 发现问题：修复问题，重新调用评审者评审整个计划
如果 ✅ 审核通过：进入执行移交环节

评审循环指引：

编写计划的同一个agent负责修复问题（保留上下文）
如果循环超过3次，上报给人类寻求指导
评审者仅提供建议——如果你认为反馈不正确，解释分歧点。