planning-and-task-breakdown

name	planning-and-task-breakdown
description	将工作分解为有序任务。当你有一个规格或明确需求，需要将工作分解为可实现的 task 时使用。当一个 task 感觉太大无法开始时、需要估算范围时，或并行工作可行时使用。

规划与任务分解

概述

将工作分解为具有显式验收条件的小型、可验证的 task。良好的任务分解是让智能体可靠完成工作与产生一团乱麻的区别。每个 task 应该足够小，以至于可以在一次专注的会话中实现、测试和验证。

何时使用

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

何时不使用： 范围明显的单文件变更，或规格已经包含明确定义的 task。

规划流程

步骤 1：进入规划模式

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

• 阅读规格和相关的代码库部分
• 识别现有模式和约定
• 绘制组件之间的依赖关系图
• 记录风险和未知因素

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

步骤 2：识别依赖关系图

绘制什么依赖什么的图：

存储引擎数据布局 / 核心数据结构
    │
    ├── 协议定义与类型（protobuf / IDL）
    │       │
    │       ├── RPC service 实现
    │       │       │
    │       │       └── 客户端 SDK / 调用方库
    │       │               │
    │       │               └── 集成测试
    │       │
    │       └── 输入校验逻辑
    │
    └── 测试数据 / 迁移脚本

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

步骤 3：垂直切片

而不是先构建所有存储层，然后是所有 RPC，然后是所有客户端——一次构建一个完整的功能路径：

坏（水平切片）：

任务 1：构建整个数据模型
任务 2：构建所有 RPC 端点
任务 3：构建所有服务端模块
任务 4：连接所有内容

好（垂直切片）：

任务 1：客户端可以创建资源（写入路径的 Schema + RPC + 存储）
任务 2：客户端可以读取资源（读取路径的索引 + RPC + 存储）
任务 3：客户端可以列出资源（列表查询的索引 + RPC + 分页）
任务 4：客户端可以删除资源（删除路径的 RPC + 墓碑 + GC）

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

步骤 4：编写任务

每个任务遵循此结构：

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

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

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

**验证：**
- [ ] 测试通过：`go test ./... -run TestFeatureName` 或 `cargo test feature_name`
- [ ] 构建成功：`go build ./...` 或 `cargo build`
- [ ] 手动检查：[描述要验证什么]

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

**可能涉及的文件：**
- `internal/service/task.go` 或 `src/service/task.rs`
- `internal/service/task_test.go` 或 `src/service/task_test.rs`

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

步骤 5：排序和检查点

安排任务使：

1. 依赖项被满足（先构建基础）
2. 每个任务让系统保持在工作状态
3. 验证检查点每 2-3 个任务出现一次
4. 高风险任务排在早期（快速失败）

添加显式检查点：

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

任务规模指南

大小	文件数	范围	示例
XS	1	单个函数或配置变更	添加验证规则
S	1-2	一个模块或 RPC 端点	添加新 RPC 端点
M	3-5	一个功能切片	资源 CRUD 流程
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。