writing-plans

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Plans

编写计划

Write step-by-step implementation plans for agentic execution. Each task should be a complete unit of work that one agent handles entirely.

Clarify ambiguity upfront: If the plan has unclear requirements or meaningful tradeoffs, use

AskUserQuestion

before writing the plan. Present options with descriptions explaining the tradeoffs. Use

multiSelect: true

for independent features that can be combined; use single-select for mutually exclusive choices. Don't guess when the user can clarify in 10 seconds.

Save to:

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

为Agent执行编写分步实施计划。每个任务都应该是一个由单个Agent全权处理的完整工作单元。

提前明确模糊点: 如果计划存在不明确的需求或重大权衡，在编写计划前使用

AskUserQuestion

。提供带有权衡说明的选项。对于可组合的独立功能，使用

multiSelect: true

；对于互斥选项，使用单选。当用户可以在10秒内澄清时，不要自行猜测。

保存至:

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

Plan Template

计划模板

markdown

undefined

markdown

undefined

[Feature Name] Implementation Plan

[功能名称] 实施计划

Status: DRAFT | APPROVED | IN_PROGRESS | COMPLETED

状态: DRAFT | APPROVED | IN_PROGRESS | COMPLETED

Specification

规格说明

Problem: [What's broken, missing, or needed. Describe the current state and why it's insufficient. Be specific enough that someone unfamiliar with the codebase understands the issue.]

Goal: [What the end state looks like after this work is done. Describe the user/developer experience, not the implementation.]

Scope: [What's in and what's out. Explicit boundaries prevent scope creep.]

Success Criteria:

Criterion 1 (measurable/verifiable)
Criterion 2

问题: [现有问题、缺失功能或需求。描述当前状态及其不足之处。内容需足够具体，让不熟悉代码库的人也能理解问题。]

目标: [完成此项工作后的最终状态。描述用户/开发者体验，而非具体实现细节。]

范围: [包含与排除的内容。明确的边界可防止范围蔓延。]

成功标准:

标准1（可衡量/可验证）
标准2

Context Loading

上下文加载

Run before starting:

bash

read src/relevant/file.ts
glob src/feature/**/*.ts

开始前执行:

bash

read src/relevant/file.ts
glob src/feature/**/*.ts

Tasks

任务

Task 1: [Complete Feature Unit]

任务1: [完整功能单元]

Context:

src/auth/

tests/auth/

Steps:

Create
```
src/auth/login.ts
```
with authentication logic
Add tests in
```
tests/auth/login.test.ts
```
Export from
```
src/auth/index.ts
```

Verify:

npm test -- tests/auth/

上下文:

src/auth/

tests/auth/

步骤:

创建
```
src/auth/login.ts
```
并编写认证逻辑
在
```
tests/auth/login.test.ts
```
中添加测试用例
从
```
src/auth/index.ts
```
导出模块

验证:

npm test -- tests/auth/

Task 2: [Another Complete Unit]

任务2: [另一个完整单元]

Context:

src/billing/

Steps:

Verify:

npm test -- tests/billing/

undefined

上下文:

src/billing/

步骤:

验证:

npm test -- tests/billing/

undefined

Task Sizing

任务规模

A task includes everything to complete one logical unit:

Implementation + tests + types + exports
All steps a single agent should do together

Right-sized: "Add user authentication" - one agent does model, service, tests, types Wrong: Separate tasks for model, service, tests - these should be one task

Bundle trivial items: Group small related changes (add export, update config, rename) into one task.

一个任务应包含完成一个逻辑单元所需的全部内容:

实现 + 测试 + 类型定义 + 导出
单个Agent应完成的所有步骤

合理规模: "添加用户认证" - 单个Agent负责模型、服务、测试、类型定义 不合理: 将模型、服务、测试拆分为单独任务 - 这些应合并为一个任务

合并琐碎项: 将小型相关变更（添加导出、更新配置、重命名）合并为一个任务。

Parallelization & Grouping

并行化与分组

During execution, tasks are grouped by subsystem to share agent context. Structure your plan to make grouping clear:

markdown

undefined

在执行过程中，任务会按子系统分组以共享Agent上下文。计划的结构应清晰体现分组：

markdown

undefined

Authentication Tasks ← These will run in one agent

认证任务 ← 这些将在同一个Agent中执行

Task 1: Add login

任务1: 添加登录功能

Task 2: Add logout

任务2: 添加登出功能

Billing Tasks ← These will run in another agent (parallel)

计费任务 ← 这些将在另一个Agent中执行（并行）

Task 3: Add billing API

任务3: 添加计费API

Task 4: Add webhooks

任务4: 添加Webhooks

Integration Tasks ← Sequential (depends on above)

集成任务 ← 顺序执行（依赖上述任务）

Task 5: Wire auth + billing

任务5: 关联认证与计费系统


**Execution model:**

- Tasks under same `##` heading → grouped into one agent
- Groups touching different subsystems → run in parallel
- Max 3-4 tasks per group (split larger sections)

Tasks in the **same subsystem** should be sequential or combined into one task.


**执行模型:**

- 同一`##`标题下的任务 → 分组到同一个Agent中
- 涉及不同子系统的组 → 并行执行
- 每个组最多包含3-4个任务（较大的部分需拆分）

同一**子系统**中的任务应按顺序执行或合并为一个任务。

Rules

规则

Explicit paths: Say "create
```
src/utils/helpers.ts
```
" not "create a utility"
Context per task: List files the agent should read first
Verify every task: End with a command that proves it works
One agent per task: All steps in a task are handled by the same agent

明确路径: 写明"创建
```
src/utils/helpers.ts
```
"而非"创建一个工具类"
任务上下文: 列出Agent应优先读取的文件
验证每个任务: 以可证明任务完成的命令结尾
单个Agent处理单个任务: 任务中的所有步骤由同一个Agent完成

Before Presenting

提交前检查

Before presenting the plan to the user, dispatch the

ce:devils-advocate

agent via Task tool to review it:

Pass the full drafted plan text to the agent
Load relevant domain skills based on what the plan involves. Evaluate which of these apply and include them in the agent prompt:
- ```
Skill(ce:architecting-systems)
```
  - system design, module boundaries, dependencies
- ```
Skill(ce:managing-databases)
```
  - database schemas, queries, migrations
- ```
Skill(ce:handling-errors)
```
  - error handling patterns
- ```
Skill(ce:writing-tests)
```
  - test strategy and quality
- ```
Skill(ce:migrating-code)
```
  - code migrations, API versioning
- ```
Skill(ce:optimizing-performance)
```
  - performance-sensitive work
- ```
Skill(ce:refactoring-code)
```
  - structural refactoring
The agent will look for: unstated assumptions, missing edge cases, tasks that are too vague, missing dependencies between tasks, verification gaps
Incorporate valid feedback into the plan
Note what the review caught in a brief "Review notes" comment at the bottom of the plan

Skip this step only if the plan is trivial (< 3 tasks, single subsystem, no architectural decisions).

在将计划提交给用户之前，通过Task工具调度

ce:devils-advocate

Agent进行审核：

将完整的草拟计划文本传递给该Agent
根据计划涉及的内容加载相关领域技能。评估哪些技能适用并将其包含在Agent提示中：
- ```
Skill(ce:architecting-systems)
```
  - 系统设计、模块边界、依赖关系
- ```
Skill(ce:managing-databases)
```
  - 数据库架构、查询、迁移
- ```
Skill(ce:handling-errors)
```
  - 错误处理模式
- ```
Skill(ce:writing-tests)
```
  - 测试策略与质量
- ```
Skill(ce:migrating-code)
```
  - 代码迁移、API版本控制
- ```
Skill(ce:optimizing-performance)
```
  - 性能优化相关工作
- ```
Skill(ce:refactoring-code)
```
  - 结构化重构
该Agent将检查：未阐明的假设、遗漏的边缘情况、过于模糊的任务、任务间缺失的依赖关系、验证环节的漏洞
将有效的反馈整合到计划中
在计划底部的"审核说明"评论中记录审核发现的问题

仅当计划非常简单（<3个任务、单个子系统、无架构决策）时，可跳过此步骤。

Large Plans

大型计划

For plans over ~500 lines, split into phases in a folder:

**/plans/YYYY-MM-DD-feature/
├── README.md           # Overview + phase tracking
├── phase-1-setup.md
└── phase-2-feature.md

对于超过约500行的计划，将其拆分为多个阶段并存放在文件夹中：

**/plans/YYYY-MM-DD-feature/
├── README.md           # 概述 + 阶段跟踪
├── phase-1-setup.md
└── phase-2-feature.md