task-decomposition

任务分解

适用场景

在以下情况激活此技能：

• 某项功能或目标需要 4 个或更多实施步骤
• 更改涉及后端和前端多个层中的多个文件
• 用户说“拆解一下”“分解”“创建子任务”或“有哪些步骤”
• 需要跨上下文窗口或会话跟踪进度
• 需要将 project-planner 的输出（模块图、风险、验收标准）分解为原子化、可执行的任务
• 需要将工作并行分配给多个 Agent 或开发者

预期输入： 读取 project-planner 生成的 plan.md（或 plan-<feature-name>.md）。该文件包含模块图、风险和验收标准。如果不存在计划文件，则直接接受高层目标并据此开展工作。project-planner 技能负责制定战略计划（哪些模块会受到影响以及原因）。此技能则将该计划转化为有序、可执行的原子化任务，并持续跟踪进度。

请勿在以下情况使用此技能：

• 高层项目规划或功能范围界定（使用 project-planner）
• 架构决策或技术权衡（使用 system-architecture）
• 编写实现代码（使用 python-backend-expert 或 react-frontend-expert）
• 编写测试（使用 pytest-patterns 或 react-testing-patterns）

说明

分解规则

此技能生成的每项任务都必须遵守以下规则：

1. 原子化范围： 每项任务最多涉及 2-3 个文件。如果一项任务需要更改超过 3 个文件，则应进一步拆分。
2. 单一结果： 每项任务都必须有一个明确、可观察的结果。
3. 独立验证： 每项任务都必须包含一条具体的验证命令，用于确认任务已完成（例如：pytest tests/unit/test_user.py -x、npm test -- --grep "Component"）。
4. 明确前置条件： 每项任务都必须列出需要先完成的其他任务，并注明任务 ID。
5. 规模限制： 如果一项任务涉及超过 200 行更改，则应拆分为更小的任务。
6. 无孤立任务： 每项任务要么没有前置条件（根任务），要么依赖计划中的另一项任务。

任务模板

每项任务均使用以下格式：

### Task [N]: [Short descriptive title]
- **Files:** [list of files to create or modify]
- **Preconditions:** [task IDs that must be done first, or "None"]
- **Steps:**
  1. [Specific, unambiguous action]
  2. [Specific, unambiguous action]
- **Done when:** [verification command] → [expected result]
- **Complexity:** [trivial / small / medium / large]

任务规模标准

规模	文件数	更改行数	验证方式	典型耗时
微小	1	<20	快速检查	单个操作
小型	1-2	20-100	单元测试	几个步骤
中型	2-3	100-200	单元测试 + 集成测试	多个步骤
大型	3+	>200	完整测试套件	进一步拆分

如果某项任务被评为“大型”，则必须将其拆解为更小的任务。

优先级顺序

为任务排序时，请遵循以下优先级：

1. 基础设施与配置 — 环境设置、配置更改、依赖安装
2. 数据库与迁移 — 架构更改、Alembic 迁移（必须先于使用新架构的代码）
3. 共享类型与接口 — TypeScript 类型、跨层共享的 Pydantic 架构
4. 后端服务 — 仓储层和服务层实现
5. 后端路由 — API 端点处理程序
6. 前端数据层 — TanStack Query 钩子、API 客户端函数
7. 前端组件 — UI 组件和页面
8. 测试 — 各层的单元测试，然后是集成测试
9. 集成与 E2E — 全栈集成验证

持久化任务文件

创建以下文件，以便在不同上下文窗口间维持状态：

task_plan.md

包含状态跟踪的完整任务列表：

# Task Plan: [Feature Name]

## Status: IN_PROGRESS
## Total Tasks: [N]
## Completed: [M] / [N]

### Task 1: [Title] ✅ DONE
[task details]

### Task 2: [Title] 🔄 IN PROGRESS
[task details]

### Task 3: [Title] ⏳ PENDING
[task details]

任务完成后更新状态标记：

• ⏳ PENDING — 尚未开始
• 🔄 IN PROGRESS — 正在进行
• ✅ DONE — 已完成并验证
• ❌ BLOCKED — 无法继续（列出原因）

progress.md

用于在上下文窗口重置后恢复工作的当前状态：

# Progress: [Feature Name]

## Current State
- **Last completed task:** Task [N]: [Title]
- **Current task:** Task [M]: [Title]
- **Next task:** Task [P]: [Title]

## What's Been Done
- [Summary of completed work]

## What's Next
- [Immediate next steps]

## Blockers
- [Any issues preventing progress]

findings.md

工作过程中记录的笔记、决策和发现：

# Findings: [Feature Name]

## Decisions Made
- [Decision 1: context and rationale]

## Discoveries
- [Unexpected finding 1]

## Blockers Encountered
- [Blocker 1: description and resolution]

依赖图

分解后，生成一个基于文本的依赖图，展示任务顺序：

Task 1 (migration) ──→ Task 2 (schema)
                                ↓
Task 3 (service) ──→ Task 4 (route) ──→ Task 6 (frontend)
                                ↓
                        Task 5 (tests)

确认不存在循环依赖。如果发现循环依赖，请重新组织任务以打破循环。

分解工作流

按照以下步骤分解任何目标：

1. 阅读目标 — 理解需要完成的全部工作
2. 识别层级 — 哪些后端模块、前端组件、共享类型和测试会受到影响
3. 创建根任务 — 没有前置条件的任务（通常是基础设施、配置或迁移）
4. 串联依赖任务 — 逐层构建依赖图
5. 验证原子性 — 根据分解规则检查每项任务
6. 检查规模 — 确保没有任务超过“大型”阈值；如有需要则拆分
7. 编写持久化文件 — 创建 task_plan.md、progress.md 和 findings.md
8. 呈现计划 — 向用户展示任务列表和依赖图

示例

请参阅 references/decomposition-examples.md，了解完整的演示示例，包括：

• 添加用户身份验证（8 项任务）
• 添加全文搜索（6 项任务）
• 添加使用 S3 存储的文件上传（7 项任务）

快速示例：添加电子邮件验证

目标： 为用户注册添加电子邮件验证。

Task 1: Add email_verified field to User model + migration
Task 2: Create email verification token schema and service
Task 3: Add /verify-email endpoint
Task 4: Modify registration to send verification email
Task 5: Add frontend verification page
Task 6: Write tests for verification flow

依赖图：

Task 1 ──→ Task 2 ──→ Task 3 ──→ Task 4 ──→ Task 6
                                    ↓
                              Task 5 ──→ Task 6

边缘情况

• 循环依赖： 如果任务 A 需要任务 B，而任务 B 又需要任务 A，请通过提取二者共享的依赖项来重新组织任务，将其设为新的任务 C，并让二者都依赖于任务 C。

• 难以单独验证的任务： 添加一个轻量级集成测试作为验证步骤。如果无法进行自动化测试，请记录手动验证流程。

• 上下文窗口即将耗尽： 在窗口重置前立即将当前状态保存到 progress.md。内容包括：最后完成的任务、当前任务状态、任何进行中的更改，以及恢复时要执行的下一步。

• 分解过程中范围扩大： 如果分解发现功能规模超出预期，请标记这一情况。考虑拆分为多个阶段并制定独立的任务计划，而不是创建一个难以管理的单一计划。

• 跨领域关注点： 如果任务会影响横向层（身份验证中间件、日志记录、错误处理），请将其设为所有后续任务都依赖的根任务。不要将跨领域更改分散到多个任务中。

• 恢复时任务仅部分完成： 从 progress.md 恢复时，请验证当前任务的“完成条件”。如果条件满足，则标记为完成并进入下一项任务；如果未满足，则按照进度记录中的说明继续。