planning-and-task-breakdown

计划与任务拆分

概述

将工作分解为小的、可验证的任务，并附带明确的验收标准。好的任务拆分是 Agent 可靠完成工作和产出混乱之间的区别。每个任务应该小到可以在单次聚焦 session 中实现、测试和验证。

何时使用

• 你有一个 spec 需要拆分为可实施的单元
• 某个任务感觉太大或太模糊而无法开始
• 工作需要在多个 Agent 或 session 之间并行化
• 你需要向人类传达范围
• 实现顺序不明显

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

规划流程

第 1 步：进入 Plan Mode

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

• 阅读 spec 和相关代码库部分
• 识别现有模式和约定
• 绘制组件间的依赖关系
• 标注风险和未知因素

在规划期间不要写代码。 输出是一个计划文档，不是实现。

第 2 步：识别依赖图

绘制什么依赖什么：

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

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

第 3 步：纵向切片

与其先构建所有数据库、然后所有 API、然后所有 UI——不如一次构建一条完整的功能路径：

错误（横向切片）：

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

正确（纵向切片）：

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

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

第 4 步：编写任务

每个任务遵循以下结构：

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

**描述：** 一段话解释这个任务完成什么。

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

**验证方式：**
- [ ] 测试通过：运行项目测试套件
- [ ] 构建成功：运行项目构建命令
- [ ] 手动检查：[描述要验证什么]

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

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

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

第 5 步：排序与检查点

安排任务顺序使：

1. 依赖得到满足（先构建基础）
2. 每个任务使系统保持在工作状态
3. 每 2-3 个任务后有验证检查点
4. 高风险任务靠前（快速失败）

添加明确检查点：

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

计划文档模板

# 实现计划: [功能/项目名称]

## 概述
[一段话总结我们正在构建什么]

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

## 任务列表

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

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

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

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

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

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

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

## 待定问题
- [需要人类输入的问题]

警告信号

• 没有书面任务列表就开始实现
• 任务只写"实现功能"而没有验收标准
• 任务之间没有检查点
• 任务涉及超过 8 个文件（需进一步分解）

验证

开始实现之前，确认：

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