planning-and-task-breakdown

规划与任务分解

概述

将工作分解为小的、可验证的任务，并带有明确的验收标准。良好的任务分解是区分一个能可靠完成工作的智能体与一个产生混乱结果的智能体的关键。每个任务都应足够小，以便在单个专注的会话中实现、测试和验证。

何时使用

• 你有规范，需要将其分解为可实施的单元
• 任务感觉太大或太模糊，无法开始
• 工作需要在多个智能体或会话之间并行化
• 你需要向人类传达范围
• 实现顺序不明确

何时不使用： 单文件变更且范围明确，或规范已包含定义良好的任务。

规划过程

步骤 1：进入规划模式

在编写任何代码之前，以只读模式操作：

• 阅读规范和相关的代码库部分
• 识别现有模式和约定
• 映射组件之间的依赖关系
• 注意风险和未知因素

规划期间不要编写代码。 输出是保存到 tasks/plan.md 的计划文档和保存到 tasks/todo.md 的任务列表，而不是实现。

步骤 2：识别依赖图

映射什么依赖于什么：

数据库模式
    │
    ├── API 模型/类型
    │       │
    │       ├── API 端点
    │       │       │
    │       │       └── 前端 API 客户端
    │       │               │
    │       │               └── UI 组件
    │       │
    │       └── 验证逻辑
    │
    └── 种子数据/迁移

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

步骤 3：垂直切片

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

糟糕（水平切片）：

任务 1：构建整个数据库模式
任务 2：构建所有 API 端点
任务 3：构建所有 UI 组件
任务 4：连接所有内容

良好（垂直切片）：

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

每个垂直切片交付可工作、可测试的功能。

步骤 4：编写任务

每个任务遵循以下结构：

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

**描述：** 一段解释此任务完成内容的段落。

**验收标准：**
- [ ] [具体、可测试的条件]
- [ ] [具体、可测试的条件]

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

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

**可能涉及的文件：**
- `src/path/to/file.ts`
- `tests/path/to/test.ts`

**预估范围：** [小：1-2 个文件 | 中：3-5 个文件 | 大：5+ 个文件]

步骤 5：排序和检查点

安排任务，使得：

1. 满足依赖关系（先构建基础）
2. 每个任务使系统保持工作状态
3. 每 2-3 个任务后设置验证检查点
4. 高风险任务尽早处理（快速失败）

添加明确的检查点：

## 检查点：任务 1-3 之后
- [ ] 所有测试通过
- [ ] 应用程序构建无错误
- [ ] 核心用户流程端到端工作
- [ ] 在继续之前与人类评审

任务规模指南

规模	文件数	范围	示例
XS	1	单个函数或配置更改	添加验证规则
S	1-2	一个组件或端点	添加新的 API 端点
M	3-5	一个功能切片	用户注册流程
L	5-8	多组件功能	带筛选和分页的搜索
XL	8+	太大——进一步分解	—

如果任务为 L 或更大，则应分解为更小的任务。智能体在 S 和 M 任务上表现最佳。

何时进一步分解任务：

• 需要超过一个专注的会话（大约 2 小时以上的智能体工作）
• 无法用 3 个或更少的要点描述验收标准
• 涉及两个或更多独立的子系统（例如，认证和计费）
• 发现自己在任务标题中写了“和”（表明这是两个任务）

输出文件

• 计划文档： 将实施计划保存到 tasks/plan.md。
• 任务列表： 将清单式任务列表保存到 tasks/todo.md。

如果 tasks/ 目录不存在，则创建它。这些路径是 /build 命令和其他下游工具期望的约定。

计划文档模板

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

## 概述
[一段总结我们要构建的内容]

## 架构决策
- [关键决策 1 及其理由]
- [关键决策 2 及其理由]

## 任务列表

### 阶段 1：基础
- [ ] 任务 1：...
- [ ] 任务 2：...

### 检查点：基础
- [ ] 测试通过，构建干净

### 阶段 2：核心功能
- [ ] 任务 3：...
- [ ] 任务 4：...

### 检查点：核心功能
- [ ] 端到端流程工作

### 阶段 3：打磨
- [ ] 任务 5：...
- [ ] 任务 6：...

### 检查点：完成
- [ ] 所有验收标准满足
- [ ] 准备评审

## 风险与缓解措施
| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| [风险] | [高/中/低] | [策略] |

## 未解决问题
- [需要人类输入的问题]

并行化机会

当有多个智能体或会话可用时：

• 可安全并行： 独立的功能切片、已实现功能的测试、文档
• 必须顺序执行： 数据库迁移、共享状态更改、依赖链
• 需要协调： 共享 API 契约的功能（先定义契约，然后并行化）

常见合理化

合理化	现实
“我会边做边想”	这就是你最终得到混乱和返工的原因。10 分钟的规划节省数小时。
“任务很明显”	无论如何写下来。明确的任务能揭示隐藏的依赖和被遗忘的边缘情况。
“规划是开销”	规划本身就是任务。没有计划的实现只是打字。
“我可以全部记在脑子里”	上下文窗口是有限的。书面计划能跨越会话边界和压缩。

红旗

• 在没有书面任务列表的情况下开始实现
• 任务说“实现功能”但没有验收标准
• 计划中没有验证步骤
• 所有任务都是 XL 大小
• 任务之间没有检查点
• 未考虑依赖顺序

验证

在开始实现之前，确认：

• [ ] 每个任务都有验收标准
• [ ] 每个任务都有验证步骤
• [ ] 任务依赖关系已识别并正确排序
• [ ] 没有任务涉及超过约 5 个文件
• [ ] 主要阶段之间存在检查点
• [ ] 人类已评审并批准计划

参见

验收标准是针对每个任务的，回答“我们构建了正确的东西吗？”。它们位于项目范围的“完成定义”之上，这是每个任务在算作完成之前必须达到的常设标准。请参阅 references/definition-of-done.md。