planning-and-task-breakdown

规划与任务拆解

概述

将工作拆解为小型、可验证的任务，并明确验收标准。良好的任务拆解，是 Agent 能否可靠完成工作、而非产出一团乱麻的关键。每项任务都应足够小，能够在一次专注的工作时段内完成实现、测试和验证。

适用场景

• 你有一份规格说明，需要将其拆解为可实现的单元
• 一项任务感觉太大或太模糊，不知如何着手
• 工作需要由多个 Agent 或工作时段并行完成
• 你需要向他人说明工作范围
• 实现顺序并不明确

不适用场景： 范围明确的单文件变更，或规格说明已包含定义清晰的任务。

规划流程

第 1 步：进入规划模式

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

• 阅读规格说明和相关代码库部分
• 找出现有模式和惯例
• 梳理组件之间的依赖关系
• 记录风险和未知事项

规划期间不要编写代码。 输出应为保存到 tasks/plan.md 的计划文档，以及记录在任务列表目标（参见“输出文件”；默认是 tasks/todo.md）中的任务列表，而非实现代码。

第 2 步：确定依赖关系图

梳理各项内容之间的依赖关系：

Database schema
    │
    ├── API models/types
    │       │
    │       ├── API endpoints
    │       │       │
    │       │       └── Frontend API client
    │       │               │
    │       │               └── UI components
    │       │
    │       └── Validation logic
    │
    └── Seed data / migrations

实现顺序应遵循依赖关系图，从底层向上构建：先搭建基础。

第 3 步：纵向拆分

不要先完成所有数据库工作，再完成所有 API 工作，最后再完成所有 UI 工作，而应一次构建一条完整的功能路径：

不佳（横向拆分）：

Task 1: Build entire database schema
Task 2: Build all API endpoints
Task 3: Build all UI components
Task 4: Connect everything

较佳（纵向拆分）：

Task 1: User can create an account (schema + API + UI for registration)
Task 2: User can log in (auth schema + API + UI for login)
Task 3: User can create a task (task schema + API + UI for creation)
Task 4: User can view task list (query + API + UI for list view)

每个纵向切片都能交付可运行、可测试的功能。

第 4 步：编写任务

无论任务写入 Markdown 任务列表，还是作为条目放入外部跟踪工具（参见“输出文件”），每项任务都应遵循以下结构：

## Task [N]: [Short descriptive title]

**Description:** One paragraph explaining what this task accomplishes.

**Acceptance criteria:**
- [ ] [Specific, testable condition]
- [ ] [Specific, testable condition]

**Verification:**
- [ ] Tests pass: [the repository's focused-test command]
- [ ] Build succeeds: [the repository's build command]
- [ ] Manual check: [description of what to verify]

**Dependencies:** [Task numbers this depends on, or "None"]

**Files likely touched:**
- `src/path/to/file.ts`
- `tests/path/to/test.ts`

**Estimated scope:** [Small: 1-2 files | Medium: 3-5 files | Large: 5+ files]

第 5 步：排序并设置检查点

安排任务，确保：

1. 满足依赖关系（先搭建基础）
2. 每项任务完成后，系统都处于可运行状态
3. 每完成 2–3 项任务就设置验证检查点
4. 高风险任务优先处理（快速验证）

在任务列表目标中添加明确的检查点：

## Checkpoint: After Tasks 1-3
- [ ] All tests pass
- [ ] Application builds without errors
- [ ] Core user flow works end-to-end
- [ ] Review with human before proceeding

任务规模指南

规模	文件数	范围	示例
XS	1	单个函数或配置变更	添加一条验证规则
S	1-2	一个组件或端点	添加一个新的 API 端点
M	3-5	一个功能切片	用户注册流程
L	5-8	多组件功能	支持筛选和分页的搜索
XL	8+	过大——应继续拆分	—

如果任务规模为 L 或更大，就应将其拆解为更小的任务。Agent 在处理 S 和 M 规模的任务时表现最佳。

应进一步拆分任务的情形：

• 任务需要超过一个专注的工作时段（大约需要 Agent 工作 2 小时以上）
• 验收标准无法用 3 条或更少的要点描述
• 任务涉及两个或更多相互独立的子系统（例如，身份验证和计费）
• 你发现自己在任务标题中写了“以及”（这通常意味着它包含两项任务）

输出文件

• 计划文档： 将实施计划保存到 tasks/plan.md。这始终是 Markdown 文件——设计决策、风险和未决问题无法清晰地对应到单个跟踪事项。
• 任务列表： 将每项任务记录在任务列表目标中（定义如下）。

如果 tasks/ 目录不存在，请创建它。

绝不要覆盖尚未完成的计划。 在写入 tasks/plan.md 或 tasks/todo.md 之前，检查它们是否已存在且仍包含未勾选的任务：

• 同一项工作正在重新规划（用户要求修订或扩展此计划）→ 就地更新现有文件。
• 不同的工作 → 停止并询问。 未勾选的任务可能正在另一个会话中实施。不要擅自删除、覆盖或重命名现有文件；说明冲突，让用户决定（先完成旧计划、明确放弃旧计划，或告知你新计划应放在哪里）。

同一规则也适用于外部任务列表目标：绝不要为了腾出空间而批量关闭或删除其他计划中未完成的跟踪事项。

任务列表目标

任务列表目标用于记录任务和检查点。它在此处定义；此技能中的其他所有相关说明均以此定义为准。

• 默认： 使用 tasks/todo.md 中采用清单格式的 Markdown 文件。这是 /build 命令和其他下游工具所依赖的惯例，除非项目另有规定，否则请使用它。
• 外部跟踪工具： 如果项目的 Agent 规则（CLAUDE.md、AGENTS.md 等）或用户指定了问题跟踪工具（例如 GitHub Issues、Jira、Linear、bd/beads），则每项任务都创建一个跟踪事项，而不是编写 tasks/todo.md。将第 4 步的结构映射到跟踪工具的字段中：在事项正文中填写验收标准和验证步骤，通过跟踪工具的关联机制（bd dep add、“blocked by”等）设置依赖关系。如果跟踪工具没有合适的对应项，也请将第 5 步的检查点记录为跟踪事项，或在计划文档中以清单形式记录。

使用外部跟踪工具时，请在 tasks/plan.md 中注明（例如“任务在 Linear 项目 FOO 中跟踪”），以便后续步骤和未来会话知道应去哪里查找；同时将计划文档中的“任务列表”部分用作跟踪事项 ID 或链接的有序索引，而不要重复列出清单。

计划文档模板

# Implementation Plan: [Feature/Project Name]

## Overview
[One paragraph summary of what we're building]

## Architecture Decisions
- [Key decision 1 and rationale]
- [Key decision 2 and rationale]

## Task List

### Phase 1: Foundation
- [ ] Task 1: ...
- [ ] Task 2: ...

### Checkpoint: Foundation
- [ ] Tests pass, builds clean

### Phase 2: Core Features
- [ ] Task 3: ...
- [ ] Task 4: ...

### Checkpoint: Core Features
- [ ] End-to-end flow works

### Phase 3: Polish
- [ ] Task 5: ...
- [ ] Task 6: ...

### Checkpoint: Complete
- [ ] All acceptance criteria met
- [ ] Ready for review

## Risks and Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk] | [High/Med/Low] | [Strategy] |

## Open Questions
- [Question needing human input]

任务位于外部跟踪工具时，请将上面的“任务列表”部分保留为跟踪事项 ID 或链接的有序索引，而不要重复列出清单。

并行化机会

有多个 Agent 或会话可用时：

• 可安全并行： 独立的功能切片、针对已实现功能的测试、文档
• 必须按顺序进行： 数据库迁移、共享状态变更、依赖链
• 需要协调： 共用 API 契约的功能（先定义契约，再并行处理）

常见的自我辩解

自我辩解	实际情况
“我边做边想就行”	这样最终只会把事情弄得一团糟，还得返工。花 10 分钟规划，能省下数小时。
“任务都很明显”	还是把它们写下来。明确列出任务有助于发现隐藏的依赖关系和遗漏的边界情况。
“规划是额外负担”	规划本身就是任务。没有计划就开始实施，不过是在敲字。
“我能把所有事情都记在脑子里”	上下文窗口有限。书面计划能跨越会话边界和上下文压缩而保留下来。
“旧的 tasks/plan.md 已经过时了，我直接替换就行”	未勾选的任务可能正在另一个会话中实施。覆盖它们会破坏其他地方没有记录的工作状态。停止并询问。

危险信号

• 未编写任务清单就开始实施
• 未经询问就覆盖仍有其他工作未勾选任务的 tasks/plan.md 或 tasks/todo.md
• 项目指定了外部跟踪工具时仍编写 tasks/todo.md（或将任务分散记录在两处）
• 任务只写“实现该功能”，没有验收标准
• 计划中没有验证步骤
• 所有任务都属于 XL 级别
• 任务之间没有检查点
• 未考虑依赖顺序

验证

开始实施前，请确认：

• 每项任务都有验收标准
• 每项任务都有验证步骤
• 已识别任务依赖，并正确排序
• 任务已记录在任务清单目标位置（默认为 tasks/todo.md）
• 未经用户明确确认，没有覆盖任何预先存在且尚未完成的计划
• 没有任务涉及超过约 5 个文件
• 各主要阶段之间设有检查点
• 人类已审阅并批准计划

另请参阅

验收标准针对单项任务，回答“我们是否构建了正确的东西？”。它们建立在项目范围的完成定义之上；每项任务都必须达到这一长期标准，才能算作完成。请参阅 ../../references/definition-of-done.md。