task-decomposition

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Task Decomposition

任务分解

When to Use

使用场景

Activate this skill when:

A feature or objective requires 4 or more implementation steps
Changes span multiple files across backend and frontend layers
The user says "break this down", "decompose", "create subtasks", or "what are the steps"
Tracking progress across context windows or sessions is needed
A
```
project-planner
```
output (module map, risks, acceptance criteria) needs to be broken into atomic, executable tasks
Work needs to be parallelized across multiple agents or developers

Expected input: Read

plan.md

(or

plan-<feature-name>.md

) produced by

project-planner

. This file contains the module map, risks, and acceptance criteria. If no plan file exists, accept a high-level objective directly and work from that. The

project-planner

skill produces the strategic plan (what modules are affected and why). This skill turns that plan into ordered, executable atomic tasks with persistent tracking.

Do NOT use this skill for:

High-level project planning or feature scoping (use
```
project-planner
```
)
Architecture decisions or technology trade-offs (use
```
system-architecture
```
)

Writing implementation code (use

python-backend-expert

react-frontend-expert

)

Writing tests (use
```
pytest-patterns
```
or
```
react-testing-patterns
```
)

在以下场景激活此技能：

某个功能或目标需要4步及以上的实现步骤
变更涉及后端和前端层的多个文件
用户提出“拆分这个”、“分解”、“创建子任务”或“步骤有哪些”等需求
需要跨上下文窗口或会话跟踪进度
需要将
```
project-planner
```
的输出（模块图、风险点、验收标准）拆分为原子化、可执行的任务
工作需要在多个Agent或开发者之间并行开展

预期输入： 读取由

project-planner

生成的

plan.md

（或

plan-<功能名称>.md

）文件，该文件包含模块图、风险点和验收标准。如果没有计划文件，则直接接收高级目标并以此为基础开展工作。

project-planner

技能负责生成战略计划（涉及哪些模块及原因），本技能则将该计划转化为有序、可执行的原子化任务，并提供持久化跟踪能力。

请勿在以下场景使用本技能：

高级项目规划或功能范围界定（请使用
```
project-planner
```
）
架构决策或技术选型权衡（请使用
```
system-architecture
```
）

编写实现代码（请使用

python-backend-expert

或

react-frontend-expert

）

编写测试用例（请使用
```
pytest-patterns
```
或
```
react-testing-patterns
```
）

Instructions

操作指南

Decomposition Rules

分解规则

Every task produced by this skill MUST follow these rules:

Atomic scope: Each task touches at most 2-3 files. If a task requires changes to more than 3 files, split it further.
Single outcome: Each task has exactly one clear, observable result.
Independent verification: Each task includes a concrete verification command that confirms completion (e.g.,
```
pytest tests/unit/test_user.py -x
```
,
```
npm test -- --grep "Component"
```
).
Explicit preconditions: Each task lists which other tasks must be completed first, by task ID.
Size limit: If a task involves more than 200 lines of changes, split it into smaller tasks.
No orphans: Every task must either have no preconditions (root task) or depend on another task in the plan.

本技能生成的每个任务必须遵循以下规则：

原子化范围： 每个任务最多涉及2-3个文件。如果某个任务需要修改3个以上文件，必须进一步拆分。
单一结果： 每个任务有且仅有一个清晰、可观察的结果。
可独立验证： 每个任务包含具体的验证命令以确认完成状态（例如：
```
pytest tests/unit/test_user.py -x
```
、
```
npm test -- --grep "Component"
```
）。
明确前置条件： 每个任务列出必须先完成的其他任务ID。
规模限制： 如果某个任务涉及的变更超过200行代码，必须拆分为更小的任务。
无孤立任务： 每个任务要么没有前置条件（根任务），要么依赖于计划中的其他任务。

Task Template

任务模板

Use this format for every task:

markdown

undefined

每个任务请使用以下格式：

markdown

undefined

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]

undefined

文件： [需创建或修改的文件列表]
前置条件： [必须先完成的任务ID，或“无”]
步骤：
1. [具体、明确的操作]
2. [具体、明确的操作]
完成标志： [验证命令] → [预期结果]
复杂度： [极简易 / 小型 / 中型 / 大型]

undefined

Task Sizing Criteria

任务规模判定标准

Size	Files	Lines Changed	Verification	Typical Duration
Trivial	1	<20	Quick check	Single action
Small	1-2	20-100	Unit test	Few steps
Medium	2-3	100-200	Unit + integration	Multiple steps
Large	3+	>200	Full test suite	Split further

If any task is sized "large", it MUST be decomposed into smaller tasks.

规模	文件数	变更行数	验证方式	典型耗时
极简易	1	<20	快速检查	单次操作
小型	1-2	20-100	单元测试	少量步骤
中型	2-3	100-200	单元+集成测试	多步操作
大型	3+	>200	完整测试套件	必须进一步拆分

如果任何任务被判定为“大型”，必须将其拆分为更小的任务。

Prioritization Order

优先级排序

When ordering tasks, follow this priority sequence:

Infrastructure & configuration — Environment setup, config changes, dependency installation
Database & migrations — Schema changes, Alembic migrations (must precede code that uses new schema)
Shared types & interfaces — TypeScript types, Pydantic schemas shared across layers
Backend services — Repository and service layer implementations
Backend routes — API endpoint handlers
Frontend data layer — TanStack Query hooks, API client functions
Frontend components — UI components and pages
Tests — Unit tests for each layer, then integration tests
Integration & E2E — Full-stack integration verification

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

基础设施与配置 —— 环境搭建、配置变更、依赖安装
数据库与迁移 —— schema变更、Alembic迁移（必须优先于使用新schema的代码）
共享类型与接口 —— TypeScript类型、跨层共享的Pydantic schema
后端服务 —— 仓储层和服务层实现
后端路由 —— API端点处理器
前端数据层 —— TanStack Query钩子、API客户端函数
前端组件 —— UI组件和页面
测试用例 —— 各层单元测试，然后是集成测试
集成与端到端测试 —— 全栈集成验证

Persistent Task Files

持久化任务文件

Create these files to maintain state across context windows:

创建以下文件以跨上下文窗口维护状态：

task_plan.md

The complete task list with status tracking:

markdown

undefined

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

markdown

undefined

Task Plan: [Feature Name]

任务计划：[功能名称]

Status: IN_PROGRESS

状态：进行中

Total Tasks: [N]

任务总数：[N]

Completed: [M] / [N]

已完成：[M] / [N]

Task 1: [Title] ✅ DONE

任务1：[标题] ✅ 已完成

[task details]

[任务详情]

Task 2: [Title] 🔄 IN PROGRESS

任务2：[标题] 🔄 进行中

[task details]

[任务详情]

Task 3: [Title] ⏳ PENDING

任务3：[标题] ⏳ 待开始

[task details]


Update status markers as tasks complete:
- `⏳ PENDING` — Not yet started
- `🔄 IN PROGRESS` — Currently being worked on
- `✅ DONE` — Completed and verified
- `❌ BLOCKED` — Cannot proceed (list reason)

[任务详情]


任务完成时更新状态标记：
- `⏳ 待开始` —— 尚未启动
- `🔄 进行中` —— 当前正在处理
- `✅ 已完成` —— 已完成并验证
- `❌ 阻塞` —— 无法继续（请列出原因）

progress.md

Current state for resuming after context window reset:

markdown

undefined

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

markdown

undefined

Progress: [Feature Name]

进度：[功能名称]

Current State

当前状态

Last completed task: Task [N]: [Title]
Current task: Task [M]: [Title]
Next task: Task [P]: [Title]

最后完成的任务： 任务[N]：[标题]
当前任务： 任务[M]：[标题]
下一个任务： 任务[P]：[标题]

What's Been Done

已完成工作

[Summary of completed work]

[已完成工作摘要]

What's Next

下一步计划

[Immediate next steps]

[即将开展的步骤]

Blockers

阻塞点

[Any issues preventing progress]

undefined

[任何阻碍进度的问题]

undefined

findings.md

Notes, decisions, and discoveries made during work:

markdown

undefined

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

markdown

undefined

Findings: [Feature Name]

发现：[功能名称]

Decisions Made

已做出的决策

[Decision 1: context and rationale]

[决策1：背景和理由]

Discoveries

新发现

[Unexpected finding 1]

[意外发现1]

Blockers Encountered

遇到的阻塞点

[Blocker 1: description and resolution]

undefined

[阻塞点1：描述和解决方案]

undefined

Dependency Graph

依赖关系图

After decomposing, produce a text-based dependency graph showing task ordering:

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

Verify there are no circular dependencies. If found, restructure tasks to break the cycle.

分解完成后，生成基于文本的依赖关系图以展示任务顺序：

任务1（迁移） ──→ 任务2（schema）
                                ↓
任务3（服务） ──→ 任务4（路由） ──→ 任务6（前端）
                                ↓
                        任务5（测试）

验证是否存在循环依赖，如果发现则重构任务以打破循环。

Decomposition Workflow

分解工作流

Follow these steps to decompose any objective:

Read the objective — Understand the full scope of what needs to be done
Identify layers — Which backend modules, frontend components, shared types, and tests are affected
Create root tasks — Tasks with no preconditions (usually infrastructure, config, or migration)
Chain dependent tasks — Build the dependency graph layer by layer
Verify atomicity — Check each task against the decomposition rules
Size check — Ensure no task exceeds the "large" threshold; split if needed
Write persistent files — Create task_plan.md, progress.md, and findings.md
Present the plan — Show the task list with dependency graph to the user

遵循以下步骤分解任何目标：

读取目标 —— 理解需要完成的全部范围
识别涉及层级 —— 确定受影响的后端模块、前端组件、共享类型和测试用例
创建根任务 —— 无前置条件的任务（通常是基础设施、配置或迁移任务）
链接依赖任务 —— 逐层构建依赖关系图
验证原子性 —— 检查每个任务是否符合分解规则
规模检查 —— 确保没有任务超过“大型”阈值，如有需要则拆分
编写持久化文件 —— 创建task_plan.md、progress.md和findings.md
呈现计划 —— 向用户展示任务列表和依赖关系图

Examples

示例

See

references/decomposition-examples.md

for complete worked examples including:

Adding user authentication (8 tasks)
Adding full-text search (6 tasks)
Adding file upload with S3 storage (7 tasks)

请查看

references/decomposition-examples.md

获取完整的实践示例，包括：

添加用户认证（8个任务）
添加全文搜索（6个任务）
添加基于S3存储的文件上传（7个任务）

Quick Example: Add Email Verification

快速示例：添加邮箱验证

Objective: Add email verification to user registration.

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

Dependency graph:

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

目标： 为用户注册流程添加邮箱验证功能。

任务1：为User模型添加email_verified字段 + 迁移
任务2：创建邮箱验证令牌schema和服务
任务3：添加/verify-email端点
任务4：修改注册流程以发送验证邮件
任务5：添加前端验证页面
任务6：编写验证流程的测试用例

依赖关系图：

任务1 ──→ 任务2 ──→ 任务3 ──→ 任务4 ──→ 任务6
                                    ↓
                              任务5 ──→ 任务6

Edge Cases

边缘情况处理

Circular dependencies: If Task A requires Task B and Task B requires Task A, restructure by extracting the shared dependency into a new Task C that both depend on.
Tasks that are hard to verify in isolation: Add a lightweight integration test as the verification step. If no automated test is possible, document a manual verification procedure.
Context window running out: Immediately save current state to progress.md before the window resets. Include: last completed task, current task state, any in-progress changes, and the next step to take when resuming.
Scope creep during decomposition: If decomposition reveals the feature is larger than expected, flag this. Consider splitting into multiple phases with separate task plans rather than creating an unmanageable single plan.
Cross-cutting concerns: When a task affects a horizontal layer (auth middleware, logging, error handling), make it a root task that all subsequent tasks depend on. Do not scatter cross-cutting changes across multiple tasks.
Partially completed tasks on resume: When resuming from progress.md, verify the current task's "Done when" condition. If it passes, mark as done and move to the next task. If it fails, continue from where the progress notes indicate.

循环依赖： 如果任务A依赖任务B，任务B又依赖任务A，则将共享依赖提取为新的任务C，让A和B都依赖C以打破循环。
难以独立验证的任务： 添加轻量级集成测试作为验证步骤。如果无法实现自动化测试，记录手动验证流程。
上下文窗口即将耗尽： 在窗口重置前立即将当前状态保存到progress.md，包括：最后完成的任务、当前任务状态、任何进行中的变更以及恢复工作的下一步操作。
分解过程中范围蔓延： 如果分解后发现功能规模超出预期，需标记此情况。考虑将功能拆分为多个阶段，每个阶段使用独立的任务计划，而非创建难以管理的单一计划。
横切关注点： 当任务影响横向层级（如认证中间件、日志、错误处理）时，将其设为所有后续任务依赖的根任务，避免将横切变更分散到多个任务中。
恢复时存在部分完成的任务： 从progress.md恢复工作时，验证当前任务的“完成标志”条件。如果通过则标记为已完成并进入下一个任务；如果未通过，则根据进度记录继续执行。