Skills
skills/ab300819/skills/devdocs-dev-tasks

devdocs-dev-tasks

SKILL.md

开发任务

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

语言规则

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

触发条件

  • 用户已完成系统设计和测试计划
  • 用户要求拆分开发任务
  • 用户需要迭代/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 行
  • 涉及多个独立模块

拆分方式：

docs/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

拆分内容分配：

文件 包含内容
04-dev-tasks.md 任务概览、依赖关系图、执行检查清单、风险项
04-dev-tasks-infra.md T-01 ~ T-XX 基础设施相关任务
04-dev-tasks-core.md T-XX ~ T-XX 核心业务逻辑任务
04-dev-tasks-api.md T-XX ~ T-XX 接口层任务
04-dev-tasks-test.md T-XX ~ T-XX 测试实现任务

主文档保留内容：

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

任务归档规则

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

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

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

主文档保留：

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

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

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

# 已完成任务归档

## 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 要点（已通过）

归档操作：

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

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

任务设计原则

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

原则 说明 必需内容
可测试 (Testable) 可通过自动化或手动测试验证 测试方法和预期结果
可验收 (Acceptable) 有明确的验收标准 具体、可量化的完成标准
可审查 (Reviewable) 可独立进行代码审查 Review 要点

分层 TDD 模式

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

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

TDD 循环

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

为什么分层？

层级 TDD 收益 理由
核心逻辑 🔴 高 业务逻辑复杂，测试先行能明确预期行为，防止过度设计
接口层 🟡 中 契约明确，TDD 有助于确保接口符合设计
UI 层 🟢 低 视觉反馈重要，过早写测试可能阻碍迭代
基础设施 ⚪ 无 依赖外部系统，集成测试更适合

文档模板

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

## 任务概览

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

## 任务设计原则

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

## 依赖关系图

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


## 任务列表

### 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 协作约束

任务类型 约束 Skill 检查点
核心逻辑 🔴 /code-quality, /testing-guide TDD 流程、MTE 原则、依赖注入
接口层 🟡 /testing-guide 接口测试、契约验证
UI 实现 🟢 /ui-skills 无障碍、动画、布局约束
测试编写 /testing-guide 覆盖率、断言质量、变异测试
代码提交 /git-safety 使用 git mv/rm 处理文件
提交信息 /commit-convention 遵循项目提交规范

TAR 原则约束

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

分层 TDD 约束

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

任务执行流程

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

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

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

接口层任务（推荐 TDD）🟡

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

UI 层任务（可选 TDD）🟢

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

基础设施任务 ⚪

1. 开始任务
   │
   ▼
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 规范，格式如下：

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

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

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

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

TodoWrite 集成

用户确认开始开发时：

使用 TodoWrite 添加任务：
- 每个任务成为一个 todo 项
- 保持定义的任务顺序
- todo 内容包含任务编号
- 提交后更新状态
Weekly Installs
6
Repository
ab300819/skills
First Seen
3 days ago
Installed on
claude-code5
opencode4
antigravity4
gemini-cli4
windsurf3
codex3