| name | planning-and-task-breakdown |
| description | 将 spec 或需求拆解为有序、可执行的任务列表。当用户有一份 spec 需要落地、感觉任务太大无从下手、需要评估工作量、或需要编排并行工作时使用。触发词：拆任务、任务拆解、出计划、实施计划、排期、task list、plan。 |
任务规划与拆解
概述
将工作分解为小的、可验证的任务，每个任务附带明确的验收标准。好的任务拆解是 agent 能可靠完成工作而不产出混乱代码的关键。每个任务应足够小，能在单次聚焦 session 中实现、测试和验证。
适用场景
- 有一份 spec 需要分解为可执行单元
- 任务太大或太模糊，无从下手
- 需要在多个 agent 或 session 间并行工作
- 需要向人类沟通工作范围
- 实施顺序不明确
不适用： 范围明显的单文件改动，或 spec 中已包含定义完善的任务。
规划流程
步骤 1：只读分析
在写任何代码之前，先做只读分析：
- 阅读 spec 和相关代码库代码
- 识别已有模式和约定
- 映射组件间的依赖关系
- 标记风险和未知项
规划阶段不要写代码。 产出是计划文档，不是实现。
步骤 2：梳理依赖图
理清谁依赖谁：
数据库表结构
│
├── API 模型/类型
│ │
│ ├── API 接口
│ │ │
│ │ └── 前端 API 封装
│ │ │
│ │ └── UI 组件
│ │
│ └── 校验逻辑
│
└── 种子数据 / 迁移脚本
实施顺序从依赖图底部向上：先建基础。
步骤 3：垂直切片
不要先建完所有数据库、再建所有 API、再建所有 UI。一次完成一个完整的用户路径：
错误（水平切片）：
任务 1: 建全部数据库表
任务 2: 写全部 API
任务 3: 做全部 UI
任务 4: 串联一切
正确（垂直切片）：
任务 1: 用户注册（注册的 schema + API + UI）
任务 2: 用户登录（登录的 auth + API + UI）
任务 3: 创建任务（任务的 schema + API + UI）
任务 4: 查看任务列表（查询 + API + UI）
每个垂直切片交付可运行、可测试的功能。
步骤 4：撰写任务
每个任务按以下结构编写：
## 任务 [N]: [简短标题]
**描述:** 一句话说明此任务完成什么。
**验收标准:**
- [ ] [具体的、可测试的条件]
- [ ] [具体的、可测试的条件]
**验证方法:**
- [ ] 测试通过: `npm test -- --grep "功能名"`
- [ ] 构建成功: `npm run build`
- [ ] 手动验证: [描述要检查什么]
**依赖:** [依赖的任务编号，或"无"]
**涉及文件:**
- `src/path/to/file.ts`
- `tests/path/to/test.ts`
**预估规模:** [小: 1-2文件 | 中: 3-5文件 | 大: 5+文件]
步骤 5：排序与检查点
按以下原则排列任务：
- 先满足依赖（基础先建）
- 每个任务完成后系统处于可工作状态
- 每 2-3 个任务后设置验证检查点
- 高风险任务放前面（尽早暴露问题）
显式定义检查点：
## 检查点: 任务 1-3 完成后
- [ ] 全部测试通过
- [ ] 应用无错误构建
- [ ] 核心用户流程端到端可用
- [ ] 继续前与人类确认
任务规模指南
| 规模 | 文件数 | 范围 | 示例 |
|---|
| XS | 1 | 单个函数或配置变更 | 添加校验规则 |
| S | 1-2 | 一个组件或接口 | 新增一个 API 接口 |
| M | 3-5 | 一个功能切片 | 用户注册流程 |
| L | 5-8 | 多组件功能 | 带筛选和分页的搜索 |
| XL | 8+ | 太大——继续拆 | — |
agent 在 S 和 M 任务上表现最佳。L 及以上的任务应进一步拆分。
需要继续拆的信号：
- 单个 session 做不完（agent 约需 2 小时以上）
- 验收标准 3 条写不下
- 同时涉及两个独立子系统（如 auth 和 billing）
- 任务标题里出现"和"字——通常意味着是两个任务
计划文档模板
# 实施计划: [功能/项目名称]
## 概述
[一句话——要构建什么]
## 架构决策
- [关键决策 1 及理由]
- [关键决策 2 及理由]
## 任务列表
### 阶段 1: 基础
- [ ] 任务 1: ...
- [ ] 任务 2: ...
### 检查点: 基础完成
- [ ] 测试通过，构建正常
### 阶段 2: 核心功能
- [ ] 任务 3: ...
- [ ] 任务 4: ...
### 检查点: 核心功能
- [ ] 端到端流程可用
### 阶段 3: 收尾
- [ ] 任务 5: ...
- [ ] 任务 6: ...
### 检查点: 全部完成
- [ ] 所有验收标准达成
- [ ] 可提交 review
## 风险与缓解
| 风险 | 影响 | 缓解策略 |
|------|------|---------|
| [风险] | [高/中/低] | [策略] |
## 待确认问题
- [需要人类决策的问题]
并行化机会
多 agent 或多 session 可用时：
- 可安全并行： 独立的功能切片、已完成功能的测试、文档
- 必须串行： 数据库迁移、共享状态变更、依赖链
- 需协调： 共享 API 契约的功能（先定契约，再并行）
常见借口
| 借口 | 真相 |
|---|
| "边走边看就行" | 这样做出来的代码一定是一团乱麻。10 分钟规划省几小时返工。 |
| "任务很明显" | 写下来。显式任务才能暴露隐藏的依赖和被遗忘的边界情况。 |
| "规划是额外开销" | 规划就是任务本身。没有计划的实现只是在打字。 |
| "我能全记在脑子里" | 上下文窗口是有限的。书面计划能跨越 session 边界，不随会话压缩丢失。 |
红旗信号
- 没有书面任务列表就开始实施
- 任务描述是"实现功能"却没有验收标准
- 计划中没有验证步骤
- 所有任务都是 XL 尺寸
- 任务之间没有检查点
- 没有考虑依赖顺序
验证清单
开始实施前，确认：
保存
将计划保存到 docs/features/[功能名称]/plan.md（与 spec 同目录）。计划文档已包含完整的任务列表（checkbox 格式），无需单独的 todo 文件。保存前与用户确认路径。
