writing-plans

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Plans

编写实施计划

Write implementation plans that let a skilled engineer work safely with almost no prior context. A plan names the exact files, interfaces, behavior, tests, documentation, and commands needed for each independently verifiable task. Plans are durable repository artifacts, not chat-only checklists. Each task also ends with a compile, diff review, and conventional commit gate.

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: If working in an isolated worktree, use the repository's worktree workflow at execution time. Do not make the plan depend on chat history.

Save plans to:

.agents/plans/YYYY-MM-DD-<feature-name>.md

Every plan is Markdown with YAML frontmatter. The frontmatter is the machine-readable index for cross-session tracking:

yaml

---
id: YYYY-MM-DD-<feature-name>
name: <Feature Name> implementation plan
kind: plan
category: implementation
status: pending
description: <one-sentence purpose>
---

Use these statuses:

Status	Meaning	Transition
`draft`	Plan is being written or self-reviewed	→ `pending` , `blocked`
`pending`	Plan is complete and ready to implement	→ `running` , `superseded`
`running`	Implementation has started	→ `blocked` , `done` , `superseded`
`blocked`	A documented decision or missing input prevents progress	→ `pending` , `running` , `superseded`
`done`	Implementation and verification are complete	terminal
`superseded`	Replaced by a newer plan; link the replacement	terminal

Start as

draft

, change to

pending

only after self-review, and change to

running

when implementation begins. Change to

done

only after verification. Use

blocked

for a concrete missing decision or input and

superseded

when a newer plan replaces it. Update the same plan file; never create a second status file.

To track plans:

bash

find .agents/plans -maxdepth 1 -type f -name '*.md' -print | sort
rg -n '^status:' .agents/plans
rg -l '^status: (pending|running|blocked)$' .agents/plans

Use

delegation-mode

when work must survive a worker, session, or context boundary. Use

code-review-axes-and-quality

after implementation when a complete quality review is needed. Keep these as separate stages: planning defines the contract, implementation proves it, and review checks the result.

编写的实施计划应能让资深工程师在几乎不了解前置背景的情况下安全开展工作。计划中需明确列出每个可独立验证任务所需的具体文件、接口、行为、测试、文档和命令。计划是持久化的仓库工件，而非仅存在于聊天中的清单。每个任务还需以编译、差异评审和规范提交作为收尾环节。

假设执行者是资深开发者，但几乎不了解我们的工具集或问题领域，且不太熟悉良好的测试设计方法。

开始时声明： "我正在使用writing-plans技能创建实施计划。"

上下文说明： 如果在独立工作树中开展工作，执行时需遵循仓库的工作树工作流。不要让计划依赖聊天历史。

计划保存路径：

.agents/plans/YYYY-MM-DD-<feature-name>.md

每份计划都是带有YAML前置元数据的Markdown文件。前置元数据是用于跨会话跟踪的机器可读索引：

yaml

---
id: YYYY-MM-DD-<feature-name>
name: <Feature Name> implementation plan
kind: plan
category: implementation
status: pending
description: <one-sentence purpose>
---

使用以下状态值：

状态	含义	流转方向
`draft`	计划正在编写或自我审核中	→ `pending` , `blocked`
`pending`	计划已完成，准备开始实施	→ `running` , `superseded`
`running`	已开始实施	→ `blocked` , `done` , `superseded`
`blocked`	存在已记录的决策缺失或输入缺失，阻碍进度	→ `pending` , `running` , `superseded`
`done`	实施和验证已完成	终止状态
`superseded`	被更新的计划替代；需链接替代计划	终止状态

初始状态为

draft

，仅在自我审核完成后改为

pending

，开始实施时改为

running

，验证完成后改为

done

。当存在明确的决策或输入缺失时使用

blocked

，当计划被新版本替代时使用

superseded

。更新同一计划文件，切勿创建第二个状态文件。

跟踪计划的命令：

bash

find .agents/plans -maxdepth 1 -type f -name '*.md' -print | sort
rg -n '^status:' .agents/plans
rg -l '^status: (pending|running|blocked)$' .agents/plans

当工作需要跨执行者、会话或上下文边界延续时，使用

delegation-mode

。实施完成后需要全面质量评审时，使用

code-review-axes-and-quality

。将这些作为独立阶段：规划定义契约，实施验证契约，评审检查结果。

Scope Check

范围检查

If the spec covers multiple independent subsystems, split it into separate plans. Each plan must produce a working, testable increment on its own. Do not hide unrelated cleanup inside an implementation plan.

如果规格说明书涵盖多个独立子系统，需将其拆分为多个独立计划。每个计划必须能独立产出可运行、可测试的增量成果。不要在实施计划中隐藏无关的清理工作。

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.

在定义任务前，先梳理清楚将创建或修改哪些文件，以及每个文件的职责。这是确定分解方案的关键环节。

设计具有清晰边界和明确定义接口的单元。每个文件应仅有一个明确的职责。
你对能一次性理解的代码逻辑判断最准确，且当文件聚焦单一职责时，修改更可靠。优先选择小而聚焦的文件，而非功能繁杂的大文件。
需同步修改的文件应放在一起。按职责拆分，而非按技术层拆分。
在现有代码库中，遵循已有的模式。如果代码库使用大文件，不要单方面重构——但如果你要修改的文件已变得臃肿，在计划中包含拆分步骤是合理的。

该结构为任务分解提供依据。每个任务应产出独立且有意义的变更内容。

Task Right-Sizing

任务规模合理划分

A task is the smallest unit that carries its own test cycle and is worth a fresh reviewer's gate. When drawing task boundaries: fold setup, configuration, scaffolding, and documentation steps into the task whose deliverable needs them; split only where a reviewer could meaningfully reject one task while approving its neighbor. Each task ends with an independently testable deliverable.

任务是最小的单元，需包含完整的测试周期，且值得让新的评审人员进行审核。划分任务边界时：将设置、配置、脚手架和文档步骤融入到需要这些内容的任务中；仅在评审人员可以合理拒绝某个任务同时批准相邻任务的情况下进行拆分。每个任务的结尾需有可独立验证的交付成果。

Bite-Sized Task Granularity

细粒度任务拆分

Each step is one action, normally 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
"Compile the affected project or package" - step
"Inspect the complete diff and run
```
git diff --check
```
" - step
"Commit the verified increment with a conventional message" - step

每个步骤对应一个操作，通常耗时2–5分钟：

"编写失败测试用例" - 步骤
"运行测试以确认其失败" - 步骤
"编写最小化代码使测试通过" - 步骤
"运行测试以确认其通过" - 步骤
"编译受影响的项目或包" - 步骤
"检查完整差异并运行
```
git diff --check
```
" - 步骤
"以规范提交信息提交已验证的增量变更" - 步骤

Plan Document Header

计划文档头部

Every plan MUST start with this frontmatter and header:

markdown

---
id: YYYY-MM-DD-<feature-name>
name: [Feature Name] implementation plan
kind: plan
category: implementation
status: draft
description: [One-sentence purpose]
---

每份计划必须以下面前置元数据和头部内容开头：

markdown

---
id: YYYY-MM-DD-<feature-name>
name: [Feature Name] implementation plan
kind: plan
category: implementation
status: draft
description: [One-sentence purpose]
---

[Feature Name] Implementation Plan

[Feature Name] 实施计划

For agentic workers: Use
delegation-mode
for resumable or multi-worker execution. Steps use checkbox (
- [ ]
) syntax for tracking.

Goal: [One sentence describing what this builds]

Architecture: [2-3 sentences about approach]

Tech Stack: [Key technologies/libraries]

Spec: [path to the spec/design doc this plan implements — the plan argues from the spec, so the spec travels with it; executors read both]

面向智能执行者： 使用
delegation-mode
实现可恢复或多执行者执行。步骤使用复选框(
- [ ]
)语法进行跟踪。

目标： [一句话描述本计划要构建的内容]

架构： [2-3句话描述实现方案]

技术栈： [核心技术/库]

规格说明： [本计划所依据的规格/设计文档路径 — 计划基于规格说明制定，因此需附带该文档；执行者需同时阅读两者]

Global Constraints

全局约束

[The spec's project-wide requirements — version floors, dependency limits, naming and copy rules, platform requirements — one line each, with exact values copied verbatim from the spec. Every task's requirements implicitly include this section.]

undefined

[规格说明中的项目级要求 — 版本下限、依赖限制、命名和文案规则、平台要求 — 每项占一行，直接复制规格说明中的精确内容。所有任务的要求均隐含包含本部分内容。]

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

Interfaces:

Consumes: [what this task uses from earlier tasks — exact paths and signatures]
Produces: [what later tasks rely on — exact paths, names, parameters, and return types. This block is the contract for an implementer who sees only this task.]
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: Compile the affected project or package

Run the narrowest real compile/build command that proves the changed interfaces are valid. Record the exact command and result in the task handoff.

bash

<project compile or build command>

Expected: exit 0 with no compile errors.

Step 6: Review the complete diff

bash

git diff --check
git diff -- <files owned by this task>
git status --short

Confirm there are no unrelated files, generated artifacts, secrets, or unreviewed edits. If the diff is not scoped, fix it before committing.

Step 7: Commit the verified increment

bash

git add tests/path/test.py src/path/file.py
git diff --cached --check
git diff --cached
git commit -m "feat: add specific feature"

Record the commit hash and verification evidence in the task result. Do not mark the task

done

before the compile, diff, and commit gates pass.

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

预期结果：失败，提示"function not defined"

步骤3：编写最小化实现代码

python

def function(input):
    return expected

步骤4：运行测试以确认其通过

运行：

pytest tests/path/test.py::test_name -v

预期结果：通过

步骤5：编译受影响的项目或包

运行最精准的编译/构建命令，以验证变更后的接口有效。在任务交接时记录精确的命令和结果。

bash

<project compile or build command>

预期结果：退出码0，无编译错误。

步骤6：检查完整差异

bash

git diff --check
git diff -- <files owned by this task>
git status --short

确认无无关文件、生成的 artifacts、机密信息或未评审的修改。如果差异范围不符合预期，提交前需修正。

步骤7：提交已验证的增量变更

bash

git add tests/path/test.py src/path/file.py
git diff --cached --check
git diff --cached
git commit -m "feat: add specific feature"

在任务结果中记录提交哈希和验证证据。在通过编译、差异检查和提交环节前，不要标记任务为

done

。未记录编译结果、差异评审和提交哈希的任务视为未完成。

undefined

No Placeholders

禁止使用占位符

Every step must contain the actual content an engineer needs. These are plan failures — never write them:

"TBD", "TODO", "implement later", "fill in details"
"Add appropriate error handling" / "add validation" / "handle edge cases"
"Write tests for the above" (without actual test code)
"Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
Steps that describe what to do without showing how (code blocks required for code steps)
References to types, functions, or methods not defined in any task

每个步骤必须包含工程师所需的实际内容。以下属于计划失误 — 切勿使用：

"TBD"、"TODO"、"后续实现"、"补充细节"
"添加适当的错误处理" / "添加验证逻辑" / "处理边缘情况"
"为上述内容编写测试用例"（未提供实际测试代码）
"与任务N类似"（需重复代码 — 工程师可能会打乱任务顺序阅读）
仅描述操作内容但未展示实现方式的步骤（代码步骤需附带代码块）
引用未在任何任务中定义的类型、函数或方法

Self-Review

自我审核

After writing the complete plan, review it against the spec with fresh eyes. This is a checklist you run yourself, not a subagent dispatch.

1. Spec coverage: Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.

2. Placeholder scan: Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.

3. Type consistency: Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called

clearLayers()

in Task 3 but

clearFullLayers()

in Task 7 is a bug.

If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.

完成计划编写后，以全新视角对照规格说明书进行审核。这是你需自行完成的检查清单，无需委派给其他智能体。

1. 规格覆盖： 浏览规格说明书的每个章节/要求。你能否指出对应的实现任务？列出任何遗漏的内容。

2. 占位符检查： 在计划中搜索红色标记 — 上述「禁止使用占位符」部分中的任何模式。修正这些问题。

3. 类型一致性： 后续任务中使用的类型、方法签名和属性名称是否与前置任务中定义的一致？例如任务3中名为

clearLayers()

的函数在任务7中被称为

clearFullLayers()

，这属于错误。

如果发现问题，直接在计划中修正。无需重新审核 — 修正后即可继续。如果发现规格说明书中的某项要求没有对应的任务，需添加该任务。

Execution Handoff

执行交接

After saving the plan, offer execution choice. Keep the path in the repository's

.agents/plans/

namespace:

"Plan complete and saved to
.agents/plans/<filename>.md
. Two execution options:

1. Delegated execution (recommended) — Dispatch a fresh worker per task, record each result under

.agents/plans/

, and review between tasks.

2. Inline execution — Execute tasks in this session with checkpoints and update the plan status as work progresses.

Which approach?"

For delegated execution, use

delegation-mode

: stable task IDs, one result file per task, explicit resume state, and a final aggregation only after every task is confirmed. For inline execution, keep the same task boundaries and update checkboxes and status in the plan.

Before marking the plan or implementation complete, require fresh evidence: run the relevant compile/build and tests, inspect the full diff, run

git diff --check

, stage only the intended files, inspect the staged diff, and commit the verified increment. Do not mark

done

from intent or an agent's success report alone. A task without a recorded compile result, diff review, and commit hash is incomplete.

保存计划后，提供执行选项。保存路径需位于仓库的

.agents/plans/

命名空间下：

"计划已完成并保存至
.agents/plans/<filename>.md
。提供两种执行选项：

1. 委派执行（推荐） — 为每个任务分配新的执行者，将每个任务的结果记录在

.agents/plans/

下，并在任务间进行评审。

2. 内联执行 — 在本次会话中执行任务，设置检查点，并随工作推进更新计划状态。

选择哪种方式？

对于委派执行，使用

delegation-mode

：稳定的任务ID、每个任务对应一个结果文件、明确的恢复状态，且仅在所有任务完成后进行最终汇总。对于内联执行，保持相同的任务边界，并在计划中更新复选框和状态。

在标记计划或实施完成前，需获取新的验证证据：运行相关的编译/构建和测试、检查完整差异、运行

git diff --check

、仅暂存预期文件、检查暂存的差异，并提交已验证的增量变更。切勿仅根据意图或智能体的成功报告标记为

done

。未记录编译结果、差异评审和提交哈希的任务视为未完成。