开发工作流

执行单个开发任务的工作流指导，采用自顶向下开发模式和分层 TDD。

语言规则

• 支持中英文提问
• 统一中文回复

触发条件

• 用户开始执行某个任务（如 T-01）
• 用户需要开发指导
• 用户从 devdocs-dev-tasks 进入开发阶段
• 关键词："开发任务"、"执行任务"、"开始 T-XX"

前置条件

• 任务文档：docs/devdocs/04-dev-tasks.md
• 任务已定义并包含：关联需求、验收标准、测试方法

工作流程

1. 读取任务定义
   ├── 从 04-dev-tasks.md 获取任务详情
   ├── 确认关联的 F-XXX、AC-XXX
   └── 确认关联的测试用例 UT/IT/E2E-XXX
           │
           ▼
2. 生成骨架代码（自顶向下）
   ├── 接口骨架 + @requirement/@satisfies 标注
   └── 测试骨架 + @verifies/@testcase 标注
           │
           ▼
3. 执行开发（分层 TDD）
   ├── 核心逻辑 🔴：测试先行
   ├── 接口层 🟡：推荐测试先行
   ├── UI 层 🟢：可实现后补测试
   └── 基础设施 ⚪：集成测试验证
           │
           ▼
4. 完成检查
   ├── 验收标准全部满足
   ├── 测试通过
   └── Review 要点自查
           │
           ▼
5. 提交代码（遵循 /commit-convention）
           │
           ▼
6. 更新追溯（运行 /devdocs-sync --trace）

代码追溯标注规范

实现文档↔代码的双向追溯，AI 在生成代码时自动添加标注。

标注类型

标注示例

/**
 * 创建用户
 * @requirement F-001 - 用户注册
 * @satisfies AC-001 - 邮箱格式校验
 * @satisfies AC-002 - 密码强度校验
 */
export async function createUser(dto: CreateUserDTO): Promise<User> {
  // 实现代码
}

/**
 * @verifies AC-001 - 邮箱格式校验
 * @testcase UT-001
 */
test('createUser 应该拒绝无效邮箱格式', () => {
  // 测试代码
});

标注规则

自顶向下开发模式

先定义骨架，后填充细节。确保追溯链在代码生成时就建立。

开发流程

Step 1: 生成接口骨架
        ├── 方法签名（来自 02-system-design.md）
        ├── 添加 @requirement/@satisfies 标注
        └── 方法体: throw new Error('Not implemented')
                │
                ▼
Step 2: 生成测试骨架
        ├── 测试结构（来自 03-test-cases.md）
        ├── 添加 @verifies/@testcase 标注
        └── 测试体: test.skip() 或 test.todo()
                │
                ▼
Step 3: 实现接口细节（遵循 /code-quality）
                │
                ▼
Step 4: 完善测试（遵循 /testing-guide）
                │
                ▼
Step 5: 运行 /devdocs-sync --trace 更新追溯矩阵

骨架生成约束

• 接口骨架必须包含完整签名（参数、返回值、泛型）
• 接口骨架必须添加追溯标注
• 未实现方法必须抛出 Error 并注明任务编号
• 测试骨架必须使用 skip/todo 标记
• 测试骨架必须添加 @verifies 和 @testcase 标注

详见 skeleton-examples.md

分层 TDD 模式

根据任务类型决定测试优先级：

TDD 循环

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

详细执行流程见 execution-flow.md

Skill 协作

约束

骨架生成约束

• 接口骨架必须包含完整签名
• 接口骨架必须添加追溯标注
• 未实现方法必须抛出 Error
• 测试骨架必须使用 skip/todo 标记
• 测试骨架必须添加 @verifies 和 @testcase 标注

分层 TDD 约束

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

完成检查约束

• 验收标准 (AC-XXX) 全部满足
• 关联测试全部通过
• Review 要点自查完成
• 代码追溯标注完整

任务完成流程

TDD 任务（核心逻辑 🔴）

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

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

1. 执行测试：运行任务定义的测试方法
2. 验证验收标准：检查所有验收标准是否满足
3. 自查 Review 要点：检查代码审查要点
4. 询问提交：使用 AskUserQuestion 询问
5. 如提交：执行 git add 和 commit
6. 更新状态：将任务标记为已完成

提交信息格式

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

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

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

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

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

参考资料

• skeleton-examples.md - 接口/测试骨架示例
• execution-flow.md - 任务执行流程详解