planning-and-task-breakdown

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：排序与检查点

按以下原则排列任务：

1. 先满足依赖（基础先建）
2. 每个任务完成后系统处于可工作状态
3. 每 2-3 个任务后设置验证检查点
4. 高风险任务放前面（尽早暴露问题）

显式定义检查点：

## 检查点: 任务 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 尺寸
• 任务之间没有检查点
• 没有考虑依赖顺序

验证清单

开始实施前，确认：

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

保存

将计划保存到 docs/features/[功能名称]/plan.md（与 spec 同目录）。计划文档已包含完整的任务列表（checkbox 格式），无需单独的 todo 文件。保存前与用户确认路径。