工作流模式

采用测试驱动开发（TDD，Test-Driven Development）方法，结合阶段检查点与验证协议，系统化地实现任务。确保每一步均符合质量要求。

安装

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install workflow-patterns

该技能的作用

为任务实施提供结构化方法：

• 每个任务均执行完整的 TDD 循环（红 → 绿 → 重构）
• 完成前须通过质量门禁（测试、覆盖率、代码规范检查等）
• 关键阶段需经人工审批方可进入下一环节
• Git 提交包含丰富元数据，保障可追溯性

适用场景

建议使用场景：

• 依据计划实施功能特性
• 严格遵循 TDD 方法论
• 对质量验证有明确要求的任务
• 存在代码覆盖率硬性指标的项目
• 团队协作中强调过程可追溯性的流程

不建议使用场景：

• 快速修复或微小变更
• 探索性原型开发
• 尚无测试基础设施的项目

关键词： TDD、实现、测试、覆盖率、检查点、验证、red-green-refactor

TDD 任务生命周期

每个任务共 11 个步骤：

步骤 1：选择下一个任务

阅读计划文档，定位下一个待处理的 [ ] 任务。在同一阶段内按顺序选取任务，禁止跳过或提前执行后续任务。

步骤 2：标记为进行中

更新计划，将该任务状态改为 [~]：

- [~] **Task 2.1**: Implement user validation

步骤 3：RED — 编写失败的测试

在实现逻辑前，先编写定义预期行为的测试用例：

• 如需，创建新测试文件
• 覆盖正常路径（happy path）
• 覆盖边界条件（edge cases）
• 覆盖错误场景（error conditions）
• 运行测试 —— 结果应为 失败（FAIL）

def test_validate_email_valid():
    user = User(email="test@example.com")
    assert user.validate_email() is True

def test_validate_email_invalid():
    user = User(email="invalid")
    assert user.validate_email() is False

步骤 4：GREEN — 实现最小可行代码

仅编写使测试通过所需的最少代码：

• 目标是让测试变绿，而非追求完美
• 避免过早优化
• 保持实现简洁
• 运行测试 —— 结果应为 通过（PASS）

步骤 5：REFACTOR — 提升代码可读性

在所有测试均为绿色的前提下，安全地重构代码：

• 提取重复逻辑为公共模块
• 优化命名以增强语义表达
• 消除冗余代码
• 简化复杂逻辑
• 每次修改后均需运行测试 —— 必须持续保持 绿色（GREEN）

步骤 6：验证覆盖率

确认测试覆盖率达标（目标值 ≥ 80%）：

pytest --cov=module --cov-report=term-missing

若覆盖率低于 80%：

• 识别未覆盖的代码行
• 为缺失路径补充测试用例
• 重新运行覆盖率检查

步骤 7：记录实施偏差

若实际实现偏离原始计划或引入新依赖项：

• 在 tech-stack.md 中登记新增依赖
• 在计划对应任务的注释中说明偏差详情
• 若需求发生变更，同步更新 spec 文档

步骤 8：提交实现代码

生成聚焦明确的 Git 提交：

git commit -m "feat(user): implement email validation

- Add validate_email method to User class
- Handle empty and malformed emails
- Add comprehensive test coverage

Task: 2.1"

步骤 9：在计划中记录提交 SHA

将任务标记为完成，并附上对应提交哈希值：

- [x] **Task 2.1**: Implement user validation `abc1234`

步骤 10：提交计划更新

git commit -m "docs: update plan - task 2.1 complete"

步骤 11：重复执行

继续处理下一任务，直至当前阶段全部完成。

阶段完成协议

当某阶段所有任务均已完成后：

1. 识别变更文件

git diff --name-only ..HEAD

2. 确保测试覆盖率

针对每个被修改的文件：

• 确认新/修改代码已有对应测试
• 对所涉模块运行覆盖率检查
• 若覆盖率 < 80%，补充测试用例

3. 运行完整测试套件

pytest -v --tb=short

所有测试必须通过。

4. 生成验证清单

## Phase 1 Verification

- [ ] User can register with valid email
- [ ] Invalid email shows appropriate error
- [ ] Database stores user correctly

5. 等待人工审批

向用户呈现验证清单：

Phase 1 complete. Please verify:
1. [x] Test suite passes (automated)
2. [x] Coverage meets target (automated)
3. [ ] Manual verification items (requires human)

Respond with 'approved' to continue.

未经明确批准，严禁继续推进。

6. 创建检查点提交

git commit -m "checkpoint: phase 1 complete

Verified:
- All tests passing
- Coverage: 87%
- Manual verification approved"

7. 记录检查点 SHA

更新计划中的检查点表格：

## Checkpoints

| Phase   | SHA     | Date       | Status   |
|---------|---------|------------|----------|
| Phase 1 | def5678 | 2025-01-15 | verified |
| Phase 2 |         |            | pending  |

质量门禁

在将任何任务标记为完成前，必须满足以下全部条件：

Git 提交格式

(): 



Task: 

提交类型（type）说明：

• feat — 新增功能
• fix — 修复缺陷
• refactor — 不涉及功能或缺陷修复的代码重构
• test — 新增测试
• docs — 文档更新
• chore — 维护类任务（如构建配置、依赖升级等）

偏差处理方式

范围扩展（Scope Addition）

发现规格说明（spec）中未涵盖的新需求：

• 在 spec 中作为新需求正式记录
• 在计划中新增对应任务条目
• 在相关任务注释中注明此扩展

范围缩减（Scope Reduction）

经评估认定某功能非必需：

• 将对应任务标记为 [-]（已跳过），并注明原因
• 更新 spec 中的范围（scope）章节
• 在计划或决策日志中记录裁剪依据

技术方案偏差（Technical Deviation）

实际采用的技术方案与原计划不同：

• 在任务条目注释中明确说明偏差
• 若依赖项发生变化，同步更新 tech-stack.md
• 解释原定方案不可行的具体原因

- [x] **Task 2.1**: Implement validation `abc1234`
  - DEVIATION: Used library instead of custom code
  - Reason: Better edge case handling
  - Impact: Added email-validator to dependencies

错误恢复机制

GREEN 后测试意外失败

1. 禁止进入 REFACTOR 阶段
2. 定位具体是哪个测试开始失败
3. 回退至最近一次已知的 GREEN 状态
4. 重新设计并实现该功能

检查点被驳回

1. 在计划中记录驳回原因
2. 创建专项任务用于修复问题
3. 完成所有整改任务
4. 再次申请检查点审批

被外部依赖阻塞

1. 将任务标记为 [!]，并在旁注中说明阻塞原因
2. 检查其余任务是否可并行推进
3. 记录预期解决时间或前置条件

任务状态符号表

最佳实践

1. 绝不跳过 RED 阶段 —— 必须始终先编写失败的测试
2. 小粒度提交 —— 每次提交仅包含一个逻辑变更
3. 即时更新计划 —— 任务完成后立即同步更新计划文档
4. 静待审批 —— 绝不绕过检查点验证环节
5. 覆盖率纪律性 —— 不接受低于目标值的覆盖率结果
6. 阶段顺序执行 —— 严格按序完成各阶段，不可跳跃或重排
7. 偏差必留痕 —— 所有与原计划的出入均须如实记录
8. 状态洁净 —— 每次提交后代码均处于可运行状态

严禁行为

1. 严禁跳过 RED 阶段 —— 在 TDD 中，先写测试是不可协商的前提
2. 严禁未经审批越过检查点 —— 必须等待用户明确确认后方可继续
3. 严禁提交未通过测试的代码 —— 每次提交都必须是可工作的稳定状态
4. 严禁接受低于 80% 的覆盖率 —— 必须持续补充测试直至达标
5. 严禁隐瞒计划偏差 —— 所有偏离原始 spec 的变更均须完整披露
6. 严禁跳过或重排阶段 —— 阶段顺序经过精心设计，具备内在逻辑依赖
7. 严禁遗漏提交 SHA 记录 —— 可追溯性依赖于任务与 Git 提交的精确关联