name: workflow-patterns description: TDD任务实现模式 - 红绿重构循环、阶段检查点、git提交和质量保证的验证协议。 version: 1.0 model: sonnet invoked_by: both tools:
- Read
- Write
- Edit
- Bash
- Glob
- Grep verified: false lastVerifiedAt: 2026-02-19T05:29:09.098Z
工作流模式
使用TDD工作流实现任务的指南，管理阶段检查点，处理git提交，并执行验证协议以确保整个实施过程中的质量。
何时使用此技能
- 从跟踪的plan.md中实施任务
- 遵循TDD红绿重构循环
- 完成阶段检查点
- 管理git提交和备注
- 理解质量保证门控
- 处理验证协议
- 在计划文件中记录进度
TDD任务生命周期
对每个任务遵循以下11个步骤：
步骤1: 选择下一个任务
读取plan.md并识别下一个待处理的[ ]任务。在当前阶段内按顺序选择任务。不要跳过后面的阶段。
步骤2: 标记为进行中
更新plan.md以将任务标记为[~]：
- [~] **任务2.1**: 实现用户验证
将此状态更改与实施分开提交。
步骤3: RED - 编写失败测试
在编写实现之前，编写定义预期行为的测试：
- 如果需要，创建测试文件
- 编写涵盖快乐路径的测试用例
- 编写涵盖边缘案例的测试用例
- 编写涵盖错误条件的测试用例
- 运行测试 - 它们应该失败
示例：
def test_validate_user_email_valid():
user = User(email="test@example.com")
assert user.validate_email() is True
def test_validate_user_email_invalid():
user = User(email="invalid")
assert user.validate_email() is False
步骤4: GREEN - 实现最小代码
编写使测试通过所需的最小代码：
- 专注于使测试变绿，而不是追求完美
- 避免过早优化
- 保持实现简单
- 运行测试 - 它们应该通过
步骤5: REFACTOR - 提高清晰度
在测试变绿后，改进代码：
- 提取常见模式
- 改进命名
- 移除重复
- 简化逻辑
- 每次更改后运行测试 - 它们应保持GREEN
步骤6: 验证覆盖率
检查测试覆盖率是否达到80%目标：
pytest --cov=module --cov-report=term-missing
如果覆盖率低于80%：
- 识别未覆盖的行
- 为缺失路径添加测试
- 重新运行覆盖率检查
步骤7: 记录偏差
如果实施偏离计划或引入了新的依赖：
- 使用新依赖更新tech-stack.md
- 在plan.md任务评论中注明偏差
- 如果需求变更，更新spec.md
步骤8: 提交实施
为任务创建专注的提交：
git add -A
git commit -m "feat(user): 实现邮箱验证
- 向User类添加validate_email方法
- 处理空和格式错误的邮箱
- 添加全面的测试覆盖
Task: 2.1
Track: user-auth_20250115"
提交消息格式：
- 类型：feat, fix, refactor, test, docs, chore
- 范围：受影响的模块或组件
- 摘要：命令式、现在时
- 正文：更改要点
- 页脚：任务和跟踪引用
步骤9: 附加Git备注
添加详细的任务摘要作为git备注：
git notes add -m "任务2.1: 实现用户验证
摘要:
- 使用正则表达式模式添加邮箱验证
- 处理边缘案例：空、无@、无域名
- 覆盖率：验证模块的94%
更改文件:
- src/models/user.py (修改)
- tests/test_user.py (修改)
决策:
- 使用简单正则而非email-validator库
- 原因：基本验证无需外部依赖"
步骤10: 使用SHA更新计划
更新plan.md以用提交SHA标记任务完成：
- [x] **任务2.1**: 实现用户验证 `abc1234`
步骤11: 提交计划更新
提交计划状态更新：
git add .claude/context/tracks/*/plan.md
git commit -m "docs: 更新计划 - 任务2.1完成
Track: user-auth_20250115"
阶段完成协议
当阶段中所有任务完成时，执行验证协议：
识别更改文件
列出自上次检查点以来修改的所有文件：
git diff --name-only <last-checkpoint-sha>..HEAD
确保测试覆盖率
对每个修改的文件：
- 识别对应的测试文件
- 验证新/更改代码的测试是否存在
- 为修改模块运行覆盖率
- 如果覆盖率<80%，添加测试
运行完整测试套件
执行完整测试套件：
pytest -v --tb=short
在继续之前，所有测试必须通过。
生成手动验证步骤
创建手动验证清单：
## 阶段1验证清单
- [ ] 用户可以用有效邮箱注册
- [ ] 无效邮箱显示适当的错误
- [ ] 数据库正确存储用户
- [ ] API返回预期的响应代码
等待用户批准
向用户呈现验证清单：
阶段1完成。请验证：
1. [ ] 测试套件通过（自动）
2. [ ] 覆盖率达到目标（自动）
3. [ ] 手动验证项目（需人工）
回复“approved”以继续，或注明问题。
没有明确批准，请勿继续。
创建检查点提交
批准后，创建检查点提交：
git add -A
git commit -m "checkpoint: 阶段1完成 - user-auth_20250115
已验证:
- 所有测试通过
- 覆盖率: 87%
- 手动验证批准
阶段1任务:
- [x] 任务1.1: 设置数据库架构
- [x] 任务1.2: 实现用户模型
- [x] 任务1.3: 添加验证逻辑"
记录检查点SHA
更新plan.md检查点表：
## 检查点
| 阶段 | 检查点 SHA | 日期 | 状态 |
| ------- | -------------- | ---------- | -------- |
| 阶段1 | def5678 | 2025-01-15 | verified |
| 阶段2 | | | pending |
质量保证门控
在标记任何任务完成之前，验证这些门控：
通过测试
- 所有现有测试通过
- 新测试通过
- 无测试回归
覆盖率 >= 80%
- 新代码有80%以上覆盖率
- 整体项目覆盖率保持
- 关键路径完全覆盖
样式合规
- 代码遵循样式指南
- 代码检查通过
- 格式正确
文档
- 公共API有文档
- 复杂逻辑有解释
- 如有需要，更新README
类型安全
- 存在类型提示（如适用）
- 类型检查器通过
- 无无理由的type: ignore
无代码检查错误
- 零检查器错误
- 警告已处理或合理化
- 静态分析干净
安全审计
- 代码中无秘密
- 存在输入验证
- 认证/授权正确
- 依赖无漏洞
Git集成
提交消息格式
<类型>(<范围>): <主题>
<正文>
<页脚>
类型：
feat: 新功能fix: 错误修复refactor: 无功能/修复的代码更改test: 添加测试docs: 文档chore: 维护
Git备注以丰富摘要
将详细备注附加到提交：
git notes add -m "<详细摘要>"
查看备注：
git log --show-notes
好处：
- 保留上下文而不使提交消息杂乱
- 支持跨提交的语义查询
- 支持基于跟踪的操作
在plan.md中记录SHA
完成任务时始终记录提交SHA：
- [x] **任务1.1**: 设置架构 `abc1234`
- [x] **任务1.2**: 添加模型 `def5678`
这启用：
- 从计划到代码的可追溯性
- 语义恢复操作
- 进度审计
处理偏差
在实施过程中，可能会发生偏离计划的情况。系统处理：
偏差类型
范围增加 发现原始规范中未包含的要求。
- 在spec.md中记录为新要求
- 向plan.md添加任务
- 在任务评论中注明增加
范围减少 实施过程中认为不必要的功能。
- 将任务标记为
[-]（跳过）并注明原因 - 更新spec.md范围部分
- 记录决策理由
技术偏差 与计划不同的实施方法。
- 在任务完成评论中注明偏差
- 如果依赖变更，更新tech-stack.md
- 记录为何原始方法不合适
需求变更 工作期间对需求的理解变更。
- 用更正需求更新spec.md
- 如有需要，调整plan.md任务
- 重新验证验收标准
偏差文档格式
完成有偏差的任务时：
- [x] **任务2.1**: 实现验证 `abc1234`
- 偏差: 使用库而非自定义代码
- 原因: 更好的边缘案例处理
- 影响: 向依赖添加email-validator
错误恢复
GREEN后测试失败
如果在达到GREEN后测试失败：
- 请勿继续到REFACTOR
- 识别哪个测试开始失败
- 检查重构是否破坏了某些内容
- 恢复到最后一个已知GREEN状态
- 重新处理实施
检查点拒绝
如果用户拒绝检查点：
- 在plan.md中注明拒绝原因
- 创建任务以解决问题
- 完成修复任务
- 再次请求检查点批准
依赖阻塞
如果任务无法进行：
- 将任务标记为
[!]并附阻塞描述 - 检查其他任务是否可以进行
- 记录预期解决时间线
- 考虑创建依赖解决跟踪
最佳实践
- 永不跳过RED: 始终先编写失败测试
- 小提交: 每个提交一个逻辑更改
- 立即更新: 任务完成后立即更新plan.md
- 等待批准: 永不跳过检查点验证
- 丰富git备注: 包含有助于未来理解的上下文
- 覆盖率纪律: 不接受低于目标的覆盖率
- 质量门控: 在标记完成前检查所有门控
- 顺序阶段: 按顺序完成阶段
- 文档偏差: 注明任何与原始计划的变更
- 清洁状态: 每个提交应使代码处于工作状态
- 快速反馈: 开发期间频繁运行相关测试
- 明确阻塞: 及时处理阻塞，不要回避
内存协议（强制）
开始前：
cat .claude/context/memory/learnings.md
完成后：
- 新模式 ->
.claude/context/memory/learnings.md - 发现问题 ->
.claude/context/memory/issues.md - 决策 ->
.claude/context/memory/decisions.md
假设中断: 如果不在内存中，则表示未发生。