---

name: devdocs-dev-tasks description: Break down system design into executable development tasks. Use when users need task breakdown, sprint planning, or development task lists. Triggers on keywords like "dev tasks", "task breakdown", "sprint planning", "implementation tasks". allowed-tools: Read, Write, Glob, Grep, AskUserQuestion, TodoWrite, Bash

开发任务

将系统设计分解为可执行、可追踪的开发任务。

语言规则

• 支持中英文提问
• 统一中文回复
• 使用中文生成文档

触发条件

• 用户已完成系统设计和测试计划
• 用户要求拆分开发任务
• 用户需要迭代/Sprint 规划

前置条件

• 需求文档：docs/devdocs/01-requirements.md
• 系统设计文档：docs/devdocs/02-system-design.md
• 测试用例文档：docs/devdocs/03-test-cases.md（及 03-test-unit.md, 03-test-integration.md, 03-test-e2e.md）
• 如不存在，建议先运行前置阶段

工作流程

1. 读取文档：加载所有前置阶段文档
2. 识别组件：将系统模块映射为任务
3. 定义依赖：建立任务执行顺序
4. 评估范围：确保任务粒度合适
5. 创建任务列表：生成结构化任务文档
6. 用户确认：获得批准
7. 加载到 TodoWrite：可选，添加任务到追踪列表

输出文件

主文件：docs/devdocs/04-dev-tasks.md

文档拆分规则

当满足以下条件时，应拆分文档：

• 任务数量超过 20 个
• 文档超过 300 行
• 涉及多个独立模块

拆分方式：

Copydocs/devdocs/
├── 04-dev-tasks.md              # 主文档：任务概览、依赖图、执行检查清单
├── 04-dev-tasks-infra.md        # 基础设施任务：数据库、配置、部署
├── 04-dev-tasks-core.md         # 核心逻辑任务：Service、Domain 层
├── 04-dev-tasks-api.md          # 接口层任务：Controller、路由、验证
└── 04-dev-tasks-test.md         # 测试任务：单元测试、集成测试、E2E

拆分内容分配：

主文档保留内容：

• 任务总数和执行顺序
• 完整的依赖关系图
• 各子文档的任务范围说明
• 执行检查清单（汇总）

任务归档规则

随着迭代，已完成任务会不断积累。为保持主文档简洁，需定期归档。

归档触发条件（由 /devdocs-sync 自动检测）：

• 主文档超过 300 行
• 已完成任务超过 15 个

主文档保留：

• 所有"待开发"和"进行中"任务
• 最近完成的 5 个任务（保持上下文）
• 执行检查清单（完整）

归档文件：04-dev-tasks-archive.md

归档结构（按功能点分组）：

Copy# 已完成任务归档

## F-001: 用户注册

### T-01: 数据库表设计 ✅
- **完成时间**：2024-01-15
- **关联需求**：F-001, AC-001
- **涉及文件**：`src/db/schema.ts`
- **测试结果**：IT-001 通过

### T-02: 注册接口实现 ✅
- **完成时间**：2024-01-16
- **关联需求**：F-001, AC-002, AC-003
- **涉及文件**：`src/api/auth.ts`, `src/services/user.ts`
- **测试结果**：UT-001~003, IT-002 通过

---

## F-002: 用户登录

### T-05: 登录接口实现 ✅
- **完成时间**：2024-01-20
- **关联需求**：F-002, AC-006
- **涉及文件**：`src/api/auth.ts`
- **测试结果**：UT-010, IT-005 通过

归档内容简化：

• 保留：任务描述、关联需求、涉及文件、完成时间、测试结果
• 移除：详细的验收标准检查项、Review 要点（已通过）

归档操作：

Copy# 由 /devdocs-sync 自动建议
/devdocs-sync
# → 检测到已完成任务过多，是否归档？

# 或手动触发
/devdocs-sync --archive

任务设计原则

每个任务必须满足 TAR 原则：

分层 TDD 模式

采用 分层 TDD（Test-Driven Development）方式，根据任务类型决定测试优先级：

Copy┌─────────────────────────────────────────────────────────────┐
│                      分层 TDD 策略                           │
├─────────────────────────────────────────────────────────────┤
│  核心逻辑层 (Service/Domain)  │  🔴 强制 TDD  │ 测试先行   │
├─────────────────────────────────────────────────────────────┤
│  接口层 (Controller/API)      │  🟡 推荐 TDD  │ 建议测试先行│
├─────────────────────────────────────────────────────────────┤
│  UI 层 (Component/View)       │  🟢 可选 TDD  │ 可实现后补  │
├─────────────────────────────────────────────────────────────┤
│  基础设施层 (DB/Config)       │  ⚪ 不适用    │ 集成测试验证│
└─────────────────────────────────────────────────────────────┘

TDD 循环

Copy┌──────────────────────────────────────┐
│           TDD 红-绿-重构循环          │
│                                      │
│   ┌─────┐    ┌─────┐    ┌─────┐     │
│   │ 红  │ → │ 绿  │ → │重构 │ ──┐  │
│   │写测试│    │写实现│    │优化 │   │  │
│   │(失败)│    │(通过)│    │代码 │   │  │
│   └─────┘    └─────┘    └─────┘   │  │
│       ↑                           │  │
│       └───────────────────────────┘  │
└──────────────────────────────────────┘

为什么分层？

文档模板

Copy# 开发任务：<功能名称>

## 任务概览

- **总任务数**：X 个
- **执行顺序**：按依赖关系

## 任务设计原则

每个任务必须满足 **TAR 原则**：
- **可测试 (Testable)**：有明确的测试方法
- **可验收 (Acceptable)**：有可量化的完成标准
- **可审查 (Reviewable)**：有独立的代码审查点

## 依赖关系图

T-01 ─┬─> T-03 ─> T-05 T-02 ─┘ │ ▼ T-06 ─> T-07

Copy
## 任务列表

### 1. 基础设施 ⚪ 不适用 TDD

#### T-01: <任务名称>

| 属性 | 内容 |
|------|------|
| **描述** | <任务描述> |
| **依赖** | 无 |
| **优先级** | P0 |
| **TDD 模式** | ⚪ 不适用 |
| **关联需求** | F-001, AC-001 |
| **涉及文件** | `src/db/schema.ts` |

**执行步骤**：
1. [ ] 实现基础设施
2. [ ] 运行集成测试验证

**测试用例**（来自 `03-test-*.md`）：
- [ ] IT-001: 验证表结构创建成功

**测试方法**：
- [ ] 运行数据库迁移脚本
- [ ] 执行 IT-001 集成测试

**验收标准**：
- [ ] 迁移脚本执行无错误
- [ ] 数据库表结构与设计文档一致

**Review 要点**：
- [ ] 字段类型是否正确
- [ ] 索引设计是否合理
- [ ] 是否有安全隐患

---

### 2. 核心逻辑 🔴 TDD

#### T-02: <任务名称>

| 属性 | 内容 |
|------|------|
| **描述** | <任务描述> |
| **依赖** | T-01 |
| **优先级** | P0 |
| **TDD 模式** | 🔴 强制 |
| **关联需求** | F-001, AC-002, AC-003 |
| **涉及文件** | `src/services/xxx.ts` |

**TDD 执行步骤**：
1. [ ] 🔴 编写测试 UT-001, UT-002（应失败）
2. [ ] 🟢 编写最小实现（使测试通过）
3. [ ] 🔵 重构代码（保持测试通过）

**测试用例**（来自 `03-test-unit.md`）：
- [ ] UT-001: AC-002 - <测试场景>
- [ ] UT-002: AC-003 - <测试场景>

**编码约束**（参考 `/code-quality`）：
- [ ] 函数不超过 50 行，参数不超过 5 个
- [ ] 依赖通过注入，核心逻辑可单元测试
- [ ] 遵循 MTE 原则

**测试约束**（参考 `/testing-guide`）：
- [ ] 测试覆盖率 >= 80%
- [ ] 禁止弱断言，验证具体值
- [ ] 变异得分 >= 60%（推荐 >= 80%）

**验收标准**：
- [ ] 所有单元测试通过
- [ ] 行覆盖率 >= 80%，分支覆盖率 >= 80%

**Review 要点**：
- [ ] 业务逻辑是否正确
- [ ] 错误处理是否完善
- [ ] 代码是否符合规范
- [ ] 是否遵循 TDD 流程

---

### 3. 接口层 🟡 推荐 TDD

#### T-03: <任务名称>

| 属性 | 内容 |
|------|------|
| **描述** | <任务描述> |
| **依赖** | T-02 |
| **优先级** | P0 |
| **TDD 模式** | 🟡 推荐 |
| **关联需求** | F-001, AC-004 |
| **涉及文件** | `src/api/xxx.ts` |

**TDD 执行步骤**（推荐）：
1. [ ] 🔴 编写接口测试 IT-002（应失败）
2. [ ] 🟢 编写接口实现（使测试通过）

**测试用例**（来自 `03-test-integration.md`）：
- [ ] IT-002: AC-004 - API 接口测试

**测试方法**：
- [ ] API 接口测试（正向/反向）
- [ ] 参数校验测试

**验收标准**：
- [ ] API 响应符合设计文档
- [ ] 错误码返回正确

**Review 要点**：
- [ ] 接口设计是否符合 RESTful 规范
- [ ] 参数校验是否完整
- [ ] 权限控制是否正确

---

### 4. UI 层 🟢 可选 TDD

#### T-04: <任务名称>

| 属性 | 内容 |
|------|------|
| **描述** | <任务描述> |
| **依赖** | T-03 |
| **优先级** | P1 |
| **TDD 模式** | 🟢 可选 |
| **关联需求** | F-001, US-001 |
| **涉及文件** | `src/components/xxx.tsx` |

**执行步骤**：
1. [ ] 编写 UI 组件
2. [ ] 视觉验证
3. [ ] 编写 E2E 测试（实现后补）

**UI 约束**（参考 `/ui-skills`）：
- [ ] 使用 Tailwind CSS 默认值
- [ ] 使用无障碍组件原语（Base UI / Radix）
- [ ] 图标按钮必须有 aria-label
- [ ] 使用 h-dvh 替代 h-screen
- [ ] 动画仅限 transform/opacity

**测试用例**（来自 `03-test-e2e.md`）：
- [ ] E2E-001: US-001 - 完整用户流程

**验收标准**：
- [ ] 界面与设计稿一致
- [ ] E2E 测试通过
- [ ] 响应式布局正常

**Review 要点**：
- [ ] 组件是否可复用
- [ ] 是否遵循 ui-skills 约束
- [ ] 无障碍性是否达标

---

## 执行检查清单

| 任务 | TDD | 测试 | 验收 | Review | 提交 |
|------|-----|------|------|--------|------|
| T-01: <name> | ⚪ | [ ] | [ ] | [ ] | [ ] |
| T-02: <name> | 🔴 | [ ] | [ ] | [ ] | [ ] |
| T-03: <name> | 🟡 | [ ] | [ ] | [ ] | [ ] |
| T-04: <name> | 🟢 | [ ] | [ ] | [ ] | [ ] |

**TDD 图例**：🔴 强制 | 🟡 推荐 | 🟢 可选 | ⚪ 不适用

## 风险项

| 任务 | 风险 | 缓解措施 |
|------|------|----------|
| T-XX | <潜在风险> | <缓解策略> |

约束

基础约束

• 单个任务必须在 4 小时内可完成
• 必须指定任务依赖
• 必须按依赖排序，不能有循环依赖
• 文件路径必须具体，不能写"相关文件"
• 必须提供依赖关系图
• 优先级：P0（阻塞）、P1（重要）、P2（次要）
• 任务编号格式：T-XX（顺序编号）

需求追溯约束

• 每个任务必须关联功能点 (F-XXX) 和验收标准 (AC-XXX)
• 每个任务必须关联测试用例 (UT/IT/E2E-XXX)
• 测试用例来自 03-test-*.md 文档

Skill 协作约束

TAR 原则约束

• 每个任务必须包含测试方法（如何验证）
• 每个任务必须包含验收标准（可量化的完成标准）
• 每个任务必须包含 Review 要点（代码审查关注点）
• 测试方法必须可执行（不能是模糊描述）
• 验收标准必须可量化
• Review 要点必须针对任务类型

分层 TDD 约束

• 核心逻辑任务必须标记 🔴 强制 TDD
• 核心逻辑任务必须先写测试，后写实现
• 核心逻辑任务禁止在测试通过前提交
• 接口层任务标记 🟡 推荐 TDD
• UI 层任务标记 🟢 可选 TDD
• 基础设施任务标记 ⚪ 不适用 TDD
• TDD 任务必须包含红-绿-重构三步骤

任务执行流程

根据任务类型选择对应的执行流程。

核心逻辑任务（强制 TDD）🔴

Copy1. 开始任务
   │
   ▼
2. 编写测试代码（基于 03-test-*.md 的 UT-XXX）
   │
   ▼
3. 运行测试 → 确认失败（红）
   │
   ▼
4. 编写最小实现代码（遵循 /code-quality）
   │
   ▼
5. 运行测试 → 确认通过（绿）
   ├── 失败 → 修复实现 → 重新测试
   │
   ▼
6. 重构代码（保持测试通过）
   │
   ▼
7. 检查验收标准（AC-XXX）
   ├── 全部满足 ─────────────┐
   └── 未满足 → 补充测试+实现 │
                             ▼
8. 自查 Review 要点
   │
   ▼
9. 询问用户：是否提交代码？

接口层任务（推荐 TDD）🟡

Copy1. 开始任务
   │
   ▼
2. [推荐] 编写接口测试（基于 IT-XXX）
   │
   ▼
3. 编写接口实现
   │
   ▼
4. 运行测试 → 确认通过
   │
   ▼
5. 检查验收标准 → Review → 提交

UI 层任务（可选 TDD）🟢

Copy1. 开始任务
   │
   ▼
2. 编写 UI 组件（遵循 /ui-skills）
   │
   ▼
3. 视觉验证（手动检查）
   │
   ▼
4. 编写 E2E 测试（基于 E2E-XXX）
   │
   ▼
5. 运行测试 → 确认通过
   │
   ▼
6. 检查验收标准 → Review → 提交

基础设施任务 ⚪

Copy1. 开始任务
   │
   ▼
2. 实现基础设施（DB/配置/部署）
   │
   ▼
3. 运行集成测试验证
   │
   ▼
4. 检查验收标准 → Review → 提交

完成后操作

用户确认任务文档后：

1. 询问用户是否开始开发
2. 如是，使用 TodoWrite 添加所有任务到追踪列表
3. 建议从第一个任务（T-01）开始

任务完成流程

开发过程中完成每个任务时：

TDD 任务（核心逻辑 🔴）

1. 确认测试先行：检查是否先写了测试
2. 确认红-绿循环：测试从失败到通过
3. 检查重构：代码是否经过优化
4. 验证验收标准：检查所有 AC 是否满足
5. 自查 Review 要点：包含 TDD 流程检查
6. 询问提交：使用 AskUserQuestion 询问：
   • "任务 T-XX（TDD）已完成，测试通过，是否提交代码？"
   • 选项："提交" / "继续修改" / "跳过"
7. 如提交：执行 git add 和 commit，消息包含任务编号
8. 更新 TodoWrite：将任务标记为已完成

非 TDD 任务（接口/UI/基础设施）

1. 执行测试：运行任务定义的测试方法
2. 验证验收标准：检查所有验收标准是否满足
3. 自查 Review 要点：检查代码审查要点
4. 询问提交：使用 AskUserQuestion 询问：
   • "任务 T-XX 已完成，测试通过，是否提交代码？"
   • 选项："提交" / "继续修改" / "跳过"
5. 如提交：执行 git add 和 commit，消息包含任务编号
6. 更新 TodoWrite：将任务标记为已完成

提交信息格式

遵循 /commit-convention 规范，格式如下：

Copy<type>(T-XX): <任务名称>

- <完成内容1>
- <完成内容2>

关联: F-XXX, AC-XXX
测试: UT-XXX, IT-XXX 通过

type 类型：feat | fix | refactor | test | docs | chore

TodoWrite 集成

用户确认开始开发时：

Copy使用 TodoWrite 添加任务：
- 每个任务成为一个 todo 项
- 保持定义的任务顺序
- todo 内容包含任务编号
- 提交后更新状态