planning-and-task-breakdown

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Planning and Task Breakdown

规划与任务拆分

Overview

概述

Decompose work into small, verifiable tasks with explicit acceptance criteria. Good task breakdown is the difference between an agent that completes work reliably and one that produces a tangled mess. Every task should be small enough to implement, test, and verify in a single focused session.

将工作分解为带有明确验收标准的小型、可验证任务。优质的任务拆分是Agent能否可靠完成工作，还是产出混乱成果的关键区别。每个任务都应足够小，以便在一段专注的工作时段内完成实现、测试与验证。

When to Use

适用场景

You have a spec and need to break it into implementable units
A task feels too large or vague to start
Work needs to be parallelized across multiple agents or sessions
You need to communicate scope to a human
The implementation order isn't obvious

When NOT to use: Single-file changes with obvious scope, or when the spec already contains well-defined tasks.

你有规格说明，需要将其拆分为可执行单元
任务规模过大或模糊不清，难以启动
工作需要在多个Agent或工作时段间并行开展
你需要向人员沟通工作范围
实现顺序不明确

不适用场景： 范围明确的单文件修改，或规格说明中已包含定义完善的任务的情况。

The Planning Process

规划流程

Step 1: Enter Plan Mode

步骤1：进入规划模式

Before writing any code, operate in read-only mode:

Read the spec and relevant codebase sections
Identify existing patterns and conventions
Map dependencies between components
Note risks and unknowns

Do NOT write code during planning. The output is a plan document, not implementation.

在编写任何代码之前，进入只读模式：

阅读规格说明及相关代码库部分
识别现有模式与约定
梳理组件间的依赖关系
记录风险与未知项

规划期间请勿编写代码。 输出成果是规划文档，而非实现代码。

Step 2: Identify the Dependency Graph

步骤2：梳理依赖关系图

Map what depends on what:

Database schema
    │
    ├── API models/types
    │       │
    │       ├── API endpoints
    │       │       │
    │       │       └── Frontend API client
    │       │               │
    │       │               └── UI components
    │       │
    │       └── Validation logic
    │
    └── Seed data / migrations

Implementation order follows the dependency graph bottom-up: build foundations first.

明确各部分的依赖关系：

Database schema
    │
    ├── API models/types
    │       │
    │       ├── API endpoints
    │       │       │
    │       │       └── Frontend API client
    │       │               │
    │       │               └── UI components
    │       │
    │       └── Validation logic
    │
    └── Seed data / migrations

实现顺序需遵循依赖关系图自底向上：先构建基础部分。

Step 3: Slice Vertically

步骤3：垂直拆分

Instead of building all the database, then all the API, then all the UI — build one complete feature path at a time:

Bad (horizontal slicing):

Task 1: Build entire database schema
Task 2: Build all API endpoints
Task 3: Build all UI components
Task 4: Connect everything

Good (vertical slicing):

Task 1: User can create an account (schema + API + UI for registration)
Task 2: User can log in (auth schema + API + UI for login)
Task 3: User can create a task (task schema + API + UI for creation)
Task 4: User can view task list (query + API + UI for list view)

Each vertical slice delivers working, testable functionality.

不要先完整构建数据库，再构建所有API，最后构建UI——而是每次构建一条完整的功能路径：

错误示例（水平拆分）：

任务1：构建完整数据库 schema
任务2：构建所有API endpoints
任务3：构建所有UI components
任务4：连接所有模块

正确示例（垂直拆分）：

任务1：用户可创建账户（注册功能的schema + API + UI）
任务2：用户可登录（认证schema + API + 登录UI）
任务3：用户可创建任务（任务schema + API + 创建UI）
任务4：用户可查看任务列表（查询逻辑 + API + 列表视图UI）

每个垂直拆分都能交付可运行、可测试的功能。

Step 4: Write Tasks

步骤4：编写任务

Each task follows this structure:

markdown

undefined

每个任务需遵循以下结构：

markdown

undefined

Task [N]: [Short descriptive title]

任务[N]：[简短描述性标题]

Description: One paragraph explaining what this task accomplishes.

Acceptance criteria:

[Specific, testable condition]
[Specific, testable condition]

Verification:

Tests pass:
```
npm test -- --grep "feature-name"
```
Build succeeds:
```
npm run build
```
Manual check: [description of what to verify]

Dependencies: [Task numbers this depends on, or "None"]

Files likely touched:

```
src/path/to/file.ts
```
```
tests/path/to/test.ts
```

Estimated scope: [Small: 1-2 files | Medium: 3-5 files | Large: 5+ files]

undefined

描述： 一段文字说明该任务的完成目标。

验收标准：

[具体、可测试的条件]
[具体、可测试的条件]

验证方式：

测试通过：
```
npm test -- --grep "feature-name"
```
构建成功：
```
npm run build
```
人工检查：[需验证内容的描述]

依赖项： [依赖的任务编号，或“无”]

可能涉及的文件：

```
src/path/to/file.ts
```
```
tests/path/to/test.ts
```

预估范围： [小型：1-2个文件 | 中型：3-5个文件 | 大型：5个以上文件]

undefined

Step 5: Order and Checkpoint

步骤5：排序与设置检查点

Arrange tasks so that:

Dependencies are satisfied (build foundation first)
Each task leaves the system in a working state
Verification checkpoints occur after every 2-3 tasks
High-risk tasks are early (fail fast)

Add explicit checkpoints:

markdown

undefined

任务排序需满足：

依赖项已被满足（先构建基础）
每个任务完成后，系统处于可运行状态
每完成2-3个任务后设置验证检查点
高风险任务优先执行（快速失败）

添加明确的检查点：

markdown

undefined

Checkpoint: After Tasks 1-3

检查点：完成任务1-3后

All tests pass
Application builds without errors
Core user flow works end-to-end
Review with human before proceeding

undefined

所有测试通过
应用构建无错误
核心用户流程端到端可用
推进前与人员进行评审

undefined

Task Sizing Guidelines

任务规模指南

Size	Files	Scope	Example
XS	1	Single function or config change	Add a validation rule
S	1-2	One component or endpoint	Add a new API endpoint
M	3-5	One feature slice	User registration flow
L	5-8	Multi-component feature	Search with filtering and pagination
XL	8+	Too large — break it down further	—

If a task is L or larger, it should be broken into smaller tasks. An agent performs best on S and M tasks.

规模	涉及文件数	范围	示例
XS	1	单个函数或配置变更	添加一条验证规则
S	1-2	单个组件或接口	添加新的API endpoint
M	3-5	单个功能切片	用户注册流程
L	5-8	多组件功能	带筛选与分页的搜索功能
XL	8+	规模过大——需进一步拆分	—

如果任务规模为L或更大，必须拆分为更小的任务。Agent在处理S和M规模的任务时表现最佳。

Plan Document Template

规划文档模板

markdown

undefined

markdown

undefined

Implementation Plan: [Feature/Project Name]

实施规划：[功能/项目名称]

Overview

概述

[One paragraph summary of what we're building]

[一段文字总结我们要构建的内容]

Architecture Decisions

架构决策

[Key decision 1 and rationale]
[Key decision 2 and rationale]

[关键决策1及理由]
[关键决策2及理由]

Task List

任务列表

Phase 1: Foundation

阶段1：基础构建

Task 1: ...
Task 2: ...

任务1：...
任务2：...

Checkpoint: Foundation

检查点：基础构建完成

Tests pass, builds clean

所有测试通过，构建无问题

Phase 2: Core Features

阶段2：核心功能

Task 3: ...
Task 4: ...

任务3：...
任务4：...

Checkpoint: Core Features

检查点：核心功能完成

End-to-end flow works

端到端流程可用

Phase 3: Polish

阶段3：优化完善

Task 5: ...
Task 6: ...

任务5：...
任务6：...

Checkpoint: Complete

检查点：全部完成

All acceptance criteria met
Ready for review

所有验收标准达标
准备好进行评审

Risks and Mitigations

风险与缓解措施

Risk	Impact	Mitigation
[Risk]	[High/Med/Low]	[Strategy]

风险	影响	缓解策略
[风险内容]	[高/中/低]	[应对策略]

Open Questions

待解决问题

[Question needing human input]

undefined

[需要人员提供输入的问题]

undefined

Parallelization Opportunities

并行工作机会

When multiple agents or sessions are available:

Safe to parallelize: Independent feature slices, tests for already-implemented features, documentation
Must be sequential: Database migrations, shared state changes, dependency chains
Needs coordination: Features that share an API contract (define the contract first, then parallelize)

当有多个Agent或工作时段可用时：

可安全并行： 独立的功能切片、已实现功能的测试、文档编写
必须串行： 数据库迁移、共享状态变更、依赖链相关工作
需要协调： 共享API契约的功能（先定义契约，再并行开发）

Common Rationalizations

常见错误认知

Rationalization	Reality
"I'll figure it out as I go"	That's how you end up with a tangled mess and rework. 10 minutes of planning saves hours.
"The tasks are obvious"	Write them down anyway. Explicit tasks surface hidden dependencies and forgotten edge cases.
"Planning is overhead"	Planning is the task. Implementation without a plan is just typing.
"I can hold it all in my head"	Context windows are finite. Written plans survive session boundaries and compaction.

错误认知	实际情况
“我可以边做边想”	这种方式会导致混乱的成果和返工。10分钟的规划能节省数小时的时间。
“任务很明显，不用写下来”	无论如何都要写下来。明确的任务能暴露隐藏的依赖关系和被遗忘的边缘情况。
“规划是额外负担”	规划本身就是任务的一部分。没有规划的实现只是无意义的打字。
“我能把所有内容记在脑子里”	上下文窗口是有限的。书面规划能跨越工作时段，避免信息丢失。

Red Flags

危险信号

Starting implementation without a written task list
Tasks that say "implement the feature" without acceptance criteria
No verification steps in the plan
All tasks are XL-sized
No checkpoints between tasks
Dependency order isn't considered

未编写任务列表就开始实现
任务描述仅为“实现该功能”，无验收标准
规划中没有验证步骤
所有任务都是XL规模
任务之间没有设置检查点
未考虑依赖顺序

planning-and-task-breakdown

Original

Translation

Planning and Task Breakdown

规划与任务拆分

Overview

概述

When to Use

适用场景

The Planning Process

规划流程

Step 1: Enter Plan Mode

步骤1：进入规划模式

Step 2: Identify the Dependency Graph

步骤2：梳理依赖关系图

Step 3: Slice Vertically

步骤3：垂直拆分

Step 4: Write Tasks

步骤4：编写任务

Task [N]: [Short descriptive title]

任务[N]：[简短描述性标题]

Step 5: Order and Checkpoint

步骤5：排序与设置检查点

Checkpoint: After Tasks 1-3

检查点：完成任务1-3后

Task Sizing Guidelines

任务规模指南

Plan Document Template

规划文档模板

Implementation Plan: [Feature/Project Name]

实施规划：[功能/项目名称]

Overview

概述

Architecture Decisions

架构决策

Task List

任务列表

Phase 1: Foundation

阶段1：基础构建

Checkpoint: Foundation

检查点：基础构建完成

Phase 2: Core Features

阶段2：核心功能

Checkpoint: Core Features

检查点：核心功能完成

Phase 3: Polish

阶段3：优化完善

Checkpoint: Complete

检查点：全部完成

Risks and Mitigations

风险与缓解措施

Open Questions

待解决问题

Parallelization Opportunities

并行工作机会

Common Rationalizations

常见错误认知

Red Flags

危险信号

Verification

规划验证