MR-TDD 工作流使用指南

本指南介绍 MotionDeck 项目的 MR-TDD（多角色测试驱动开发）工作流，适用于 Factory Droid、OpenAI Codex、Claude Code。

---

1. 核心理念

边界前置 - 在 Spec 阶段定义所有边界，而非在审计阶段发现问题。

角色分离 - 架构师、测试工程师、开发工程师、审计工程师各司其职，避免职责混淆。

---

2. 分级流程

根据改动规模选择合适的流程：

级别	触发词	流程	适用场景
L	"作为架构师"	Spec → 测试 → 实现 → 审计	新模块、复杂功能
M	"作为测试工程师"	测试 → 实现	现有模块加功能
S	"修复..."/"调整..."	改代码 → 跑测试	Bug 修复、小改动

重要： M/S 级改动如涉及接口变更，必须同步更新 Spec 文件。

---

3. L 级完整流程

3.1 架构师：设计 Spec

触发： "作为架构师，设计 xxx 的 spec"

输出： docs/specs/{feature}_spec.md

Spec 必须包含：

• 边界定义（字段约束表、错误码表）
• API 接口定义
• 业务规则
• 测试用例清单

禁止： 写任何实现代码

3.2 测试工程师：编写测试

触发： "作为测试工程师，为 xxx 写测试"

输出：

• server/tests/test_{feature}_service.py（单元测试）
• server/tests/test_{feature}_integration.py（集成测试）

要求：

• 覆盖 Spec 所有边界值和错误场景
• 测试运行结果为 Red（失败）

3.3 开发工程师：实现代码

触发： "作为开发工程师，实现 xxx 功能"

输出：

• server/app/models/{feature}.py
• server/app/schemas/{feature}.py
• server/app/services/{feature}.py
• server/app/api/v1/{feature}.py

要求：

• 严格遵循 Spec 边界定义
• 测试运行结果为 Green（通过）

3.4 审计工程师：审计验收

触发： "作为审计工程师，审计 xxx"

输出： docs/audit/{feature}_audit_{YYYY-MM-DD}.md

检查项：

• 测试覆盖是否完整
• 实现是否与 Spec 一致
• 错误码是否精确匹配

问题分类：

类型	处理
代码缺陷	打回开发工程师
测试缺陷	打回测试工程师
Spec 缺陷	打回架构师
建议优化	不阻塞验收

---

4. M 级流程

适用于现有模块增加功能，跳过 Spec 设计阶段。

作为测试工程师，为xxx写测试 → 测试代码（Red）
作为开发工程师，实现xxx功能 → 实现代码（Green）

如涉及接口变更，完成后更新 Spec 文件。

---

5. S 级流程

适用于 Bug 修复和小改动，不需要触发 Skill。

1. 确认相关测试文件存在
2. 修改代码
3. 运行测试：cd server && ./venv/bin/pytest tests/test_{module}_*.py -v
4. 确认测试通过

Bug 修复最佳实践：

1. 先写一个失败的测试复现 Bug
2. 修复代码
3. 确认测试通过

---

6. Skills 位置

平台	位置
Factory Droid	.factory/skills/mr-tdd-{role}/SKILL.md
OpenAI Codex	.codex/skills/mr-tdd-{role}/SKILL.md
Claude Code	.claude/agents/mr-tdd-{role}.md

---

7. Spec 维护规则

改动类型	是否更新 Spec
新增字段/接口	✅ 必须
删除字段/接口	✅ 必须
约束调整	✅ 必须
Bug 修复	❌ 不需要
内部重构	❌ 不需要

---

8. 常见问题

Q: 审计发现的问题已经修复了，为什么还在报告里？

A: 审计工程师可能没有读取最新文件。确保审计前清理旧报告，并检查所有文件（包括未提交的新文件）。

Q: 什么时候用 L 级，什么时候用 M 级？

A: 新模块或涉及多个接口的复杂功能用 L 级；现有模块加一两个字段或接口用 M 级。

Q: S 级改动需要写测试吗？

A: Bug 修复建议先写失败测试；小调整如果现有测试已覆盖，只需确保测试通过。