planning-and-task-breakdown

# 任务规划与拆解 ## 概述 将工作分解为小的、可验证的任务，每个任务附带明确的验收标准。好的任务拆解是 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：撰写任务 每个任务按以下结构编写： ```markdown ## 任务 [N]: [简短标题] **描述:** 一句话说明此任务完成什么。 **验收标准:** - [ ] [具体的、可测试的条件] - [ ] [具体的、可测试的条件] **验证方法:** - [ ] 测试通过: `npm test -- --grep "功能名"` - [ ] 构建成功: `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. 高风险任务放前面（尽早暴露问题） 显式定义检查点： ```markdown ## 检查点: 任务 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） - 任务标题里出现"和"字——通常意味着是两个任务 ## 计划文档模板 ```markdown # 实施计划: [功能/项目名称] ## 概述 [一句话——要构建什么] ## 架构决策 - [关键决策 1 及理由] - [关键决策 2 及理由] ## 任务列表 ### 阶段 1: 基础 - [ ] 任务 1: ... - [ ] 任务 2: ... ### 检查点: 基础完成 - [ ] 测试通过，构建正常 ### 阶段 2: 核心功能 - [ ] 任务 3: ... - [ ] 任务 4: ... ### 检查点: 核心功能 - [ ] 端到端流程可用 ### 阶段 3: 收尾 - [ ] 任务 5: ... - [ ] 任务 6: ... ### 检查点: 全部完成 - [ ] 所有验收标准达成 - [ ] 可提交 review ## 风险与缓解 | 风险 | 影响 | 缓解策略 | |------|------|---------| | [风险] | [高/中/低] | [策略] | ## 待确认问题 - [需要人类决策的问题] ``` ## 并行化机会 多 agent 或多 session 可用时： - **可安全并行：** 独立的功能切片、已完成功能的测试、文档 - **必须串行：** 数据库迁移、共享状态变更、依赖链 - **需协调：** 共享 API 契约的功能（先定契约，再并行） ## 常见借口 | 借口 | 真相 | |------|------| | "边走边看就行" | 这样做出来的代码一定是一团乱麻。10 分钟规划省几小时返工。 | | "任务很明显" | 写下来。显式任务才能暴露隐藏的依赖和被遗忘的边界情况。 | | "规划是额外开销" | 规划就是任务本身。没有计划的实现只是在打字。 | | "我能全记在脑子里" | 上下文窗口是有限的。书面计划能跨越 session 边界，不随会话压缩丢失。 | ## 红旗信号 - 没有书面任务列表就开始实施 - 任务描述是"实现功能"却没有验收标准 - 计划中没有验证步骤 - 所有任务都是 XL 尺寸 - 任务之间没有检查点 - 没有考虑依赖顺序 ## 验证清单 开始实施前，确认： - [ ] 每个任务都有验收标准 - [ ] 每个任务都有验证方法 - [ ] 任务依赖已识别且排序正确 - [ ] 没有任务涉及超过约 5 个文件 - [ ] 主要阶段之间有检查点 - [ ] 人类已审阅并批准计划 ## 保存 将计划保存到 `docs/features/[功能名称]/plan.md`（与 spec 同目录）。计划文档已包含完整的任务列表（checkbox 格式），无需单独的 todo 文件。保存前与用户确认路径。