writing-plans

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Plans

编写计划

You are creating a detailed execution plan that breaks work into bite-sized tasks. Each task should be small enough that a fresh subagent with no prior context can execute it correctly.

你需要创建一份详细的执行计划，将工作拆分为易于处理的小任务。每个任务的粒度应足够小，确保没有任何前置上下文的新子Agent也能正确执行。

When to Activate

激活时机

After brainstorming (if it ran) or directly after issue selection for straightforward work
When the developer approves the approach and is ready to plan implementation
NOT for tasks that are already a single atomic change

头脑风暴结束后（若已执行头脑风暴），或在选定问题后直接针对简单工作启动
当开发者认可解决方案并准备规划实现方案时
不适用于已经是单一原子变更的任务

Context Loading

上下文加载

Before writing the plan, gather:

Linear issue details — Description, acceptance criteria, linked docs
Design document — If brainstorming produced one (
```
docs/designs/[issue-id]-*.md
```
)
Project CLAUDE.md — Build commands, test commands, conventions, architecture
Relevant source code — Files that will be modified or referenced
Test patterns — How existing tests are structured in this project

编写计划前，需收集以下信息：

Linear问题详情 — 描述、验收标准、关联文档
设计文档 — 若头脑风暴产出了设计文档（路径为
```
docs/designs/[issue-id]-*.md
```
）
项目CLAUDE.md — 构建命令、测试命令、约定规范、架构说明
相关源代码 — 将要修改或参考的文件
测试模式 — 本项目中现有测试的结构方式

Plan Structure

计划结构

Save the plan to

docs/plans/[issue-id]-plan.md

markdown

undefined

将计划保存至

docs/plans/[issue-id]-plan.md

：

markdown

undefined

Plan: [Issue Title]

计划: [问题标题]

Issue: [ID] — [Title] Branch: [branch-name] Tasks: N (estimated [time])

问题: [ID] — [标题] 分支: [branch-name] 任务数量: N（预计耗时[time]）

Prerequisites

前置条件

[Any setup needed before starting]
[Dependencies that must be in place]

[开始前需完成的任何设置]
[必须就绪的依赖项]

Tasks

任务

Task 1: [Short imperative title]

任务1: [简短的祈使句标题]

Files:

path/to/file.ts

path/to/test.ts

Why: [One sentence — what this accomplishes]

Implementation:

[Exact change to make]
[Exact change to make]

Test:

Write test: [describe the test]
Run:
```
[exact test command]
```
Expected: [what passing looks like]

Verify: [how to confirm this task is done]

文件:

path/to/file.ts

path/to/test.ts

目的: [一句话说明该任务的目标]

实现步骤:

[具体要做的修改]
[具体要做的修改]

测试:

编写测试: [描述测试内容]
运行命令:
```
[精确的测试命令]
```
预期结果: [测试通过的表现]

验证方式: [确认任务完成的方法]

Task 2: [Short imperative title]

任务2: [简短的祈使句标题]

...

Task Dependencies

任务依赖关系

Task 3 depends on Task 1 (needs the interface defined in Task 1)
Tasks 4 and 5 are independent (can run in parallel)

任务3依赖任务1（需要任务1中定义的接口）
任务4和任务5相互独立（可并行执行）

Verification Checklist

验证清单

All tests pass:
```
[test command]
```
Build succeeds:
```
[build command]
```
Lints clean:
```
[lint command]
```
[Issue-specific acceptance criteria]

undefined

所有测试通过:
```
[测试命令]
```
构建成功:
```
[构建命令]
```
代码检查通过:
```
[lint命令]
```
[问题特定的验收标准]

undefined

Task Writing Rules

任务编写规则

Size

粒度要求

Each task should take 2-5 minutes for a focused agent
If a task has more than 5 implementation steps, split it
If a task touches more than 3 files, split it
A task that "adds a REST endpoint" is too big. "Add the route handler", "add the validation schema", "add the test" are right-sized.

每个任务应让专注的Agent耗时2-5分钟完成
若任务包含超过5个实现步骤，需拆分
若任务涉及超过3个文件，需拆分
"添加REST接口"这类任务粒度太大。"添加路由处理器"、"添加验证 schema"、"编写测试"才是合适的粒度。

Self-Contained Context

自包含上下文

Each task must include everything a fresh agent needs:

Exact file paths — no "find the relevant file"
Complete implementation details — not "implement the function" but what the function does, its signature, its behavior
Explicit constraints — from CLAUDE.md conventions (naming, patterns, imports)
Test specification — what to test, how to run it, what success looks like

每个任务必须包含新Agent所需的全部信息：

精确的文件路径 — 不能写"找到相关文件"
完整的实现细节 — 不是"实现函数"，而是明确函数的功能、签名和行为
明确的约束条件 — 来自CLAUDE.md的约定（命名、模式、导入规则）
测试规范 — 测试内容、运行方式、成功的表现

Ordering

任务排序

Tasks that define interfaces/types come before tasks that use them
Tests can be written before or alongside implementation (TDD preference)
Mark independent tasks explicitly — they can be parallelized
Group related tasks but maintain clear boundaries

定义接口/类型的任务需排在使用这些接口/类型的任务之前
测试可在实现前或与实现同步编写（优先采用TDD方式）
明确标记独立任务——它们可并行执行
相关任务可分组，但需保持清晰的边界

Verification Steps

验证步骤

Every task ends with a verification step that is:

Automated — a command that returns pass/fail, not "visually inspect"
Specific —
```
npm test -- --grep "auth"
```
not just "run tests"
From CLAUDE.md — use the project's actual test/build/lint commands

每个任务的结尾都需包含以下验证步骤：

自动化 — 执行返回通过/失败结果的命令，而非"视觉检查"
具体 — 例如
```
npm test -- --grep "auth"
```
，而非仅"运行测试"
遵循CLAUDE.md — 使用项目实际的测试/构建/lint命令

Plan Approval

计划审批

After writing the plan:

Present a summary: task count, estimated complexity, key decisions
Ask: "Does this plan look right? Any tasks to add, remove, or reorder?"
If approved: Plan is ready for execution via the
```
executing-plans
```
skill
If changes requested: Iterate and re-present

编写计划后：

呈现摘要：任务数量、预计复杂度、关键决策
询问："这份计划是否合理？是否需要添加、移除或重新排序任务？"
若获批：计划可通过
```
executing-plans
```
skill执行
若需修改：迭代调整后重新提交审批

Rules

规则

Never write vague tasks. "Set up the database" is bad. "Add Prisma model
```
User
```
with fields
```
id
```
,
```
email
```
,
```
name
```
,
```
createdAt
```
to
```
prisma/schema.prisma
```
" is good.
Include the TDD cycle in task structure: test file changes alongside implementation changes.
If the plan exceeds 12 tasks, suggest splitting into multiple PRs/issues.
Reference
```
_shared/validation-pattern.md
```
for self-checking after plan creation.
Plan files persist across sessions — a new session can pick up where the last left off.

绝不要编写模糊的任务。"设置数据库"是糟糕的示例。"在
```
prisma/schema.prisma
```
中添加包含
```
id
```
、
```
email
```
、
```
name
```
、
```
createdAt
```
字段的Prisma模型
```
User
```
"才是正确的写法。
在任务结构中包含TDD循环：测试文件变更与实现变更同步进行。
若计划包含超过12个任务，建议拆分为多个PR/问题。
计划创建完成后，参考
```
_shared/validation-pattern.md
```
进行自我检查。
计划文件会跨会话保留——新会话可从上次中断的地方继续执行。