workflow-patterns

工作流模式

介绍如何使用 TDD 工作流实现任务、管理阶段检查点、处理 git 提交，以及执行贯穿整个实现过程的质量验证协议。

何时使用此技能

• 实现 track 的 plan.md 中的任务
• 遵循 TDD 红—绿—重构循环
• 完成阶段检查点
• 管理 git 提交和备注
• 了解质量保障关卡
• 处理验证协议
• 在计划文件中记录进度

TDD 任务生命周期

每项任务都遵循以下 11 个步骤：

步骤 1：选择下一个任务

阅读 plan.md，找出下一个待处理的 [ ] 任务。在当前阶段内按顺序选择任务。不要跳到后续阶段。

步骤 2：标记为进行中

更新 plan.md，将任务标记为 [~]：

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

将此状态变更单独提交，不要与实现内容一起提交。

步骤 3：RED - 编写失败测试

在编写实现代码之前，先编写用于定义预期行为的测试：

• 如有需要，创建测试文件
• 编写覆盖正常场景的测试用例
• 编写覆盖边缘情况的测试用例
• 编写覆盖错误情况的测试用例
• 运行测试——测试应当失败

示例：

def test_validate_user_email_valid():
    user = User(email="[email protected]")
    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 - 提高清晰度

在测试通过的基础上改进代码：

• 提取通用模式
• 改进命名
• 消除重复
• 简化逻辑
• 每次变更后都运行测试——测试应继续通过

步骤 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): implement email validation

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

Task: 2.1
Track: user-auth_20250115"

提交信息格式：

• 类型：feat、fix、refactor、test、docs、chore
• 范围：受影响的模块或组件
• 摘要：祈使语气，使用现在时
• 正文：以项目符号列出变更
• 页脚：任务和 track 的引用

步骤 9：添加 Git 备注

使用 git note 添加详细的任务摘要：

git notes add -m "Task 2.1: Implement user validation

Summary:
- Added email validation using regex pattern
- Handles edge cases: empty, no @, no domain
- Coverage: 94% on validation module

Files changed:
- src/models/user.py (modified)
- tests/test_user.py (modified)

Decisions:
- Used simple regex over email-validator library
- Reason: No external dependency for basic validation"

步骤 10：在计划中更新 SHA

更新 plan.md，将任务标记为已完成，并记录提交 SHA：

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

步骤 11：提交计划更新

提交计划状态更新：

git add .claude/context/tracks/*/plan.md
git commit -m "docs: update plan - task 2.1 complete

Track: user-auth_20250115"

阶段完成协议

阶段中的所有任务完成后，执行验证协议：

找出已变更的文件

列出自上一个检查点以来修改的所有文件：

git diff --name-only <last-checkpoint-sha>..HEAD

确保测试覆盖率

对每个修改过的文件：

1. 找出对应的测试文件
2. 确认新代码或变更代码有对应测试
3. 检查修改过的模块的覆盖率
4. 如果覆盖率低于 80%，则添加测试

运行完整测试套件

运行完整的测试套件：

pytest -v --tb=short

继续之前，所有测试都必须通过。

生成手动验证步骤

创建手动验证清单：

## Phase 1 Verification Checklist

- [ ] User can register with valid email
- [ ] Invalid email shows appropriate error
- [ ] Database stores user correctly
- [ ] API returns expected response codes

等待用户批准

向用户展示验证清单：

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

Respond with 'approved' to continue, or note issues.

未经明确批准，不要继续。

创建检查点提交

获得批准后，创建检查点提交：

git add -A
git commit -m "checkpoint: phase 1 complete - user-auth_20250115

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

Phase 1 tasks:
- [x] Task 1.1: Setup database schema
- [x] Task 1.2: Implement user model
- [x] Task 1.3: Add validation logic"

记录检查点 SHA

更新 plan.md 中的检查点表格：

## Checkpoints

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

质量保障关卡

将任何任务标记为完成之前，确认满足以下关卡要求：

测试通过

• 所有现有测试均通过
• 新测试通过
• 没有测试回归

覆盖率 >= 80%

• 新代码的覆盖率达到或超过 80%
• 整个项目的覆盖率保持稳定
• 关键路径得到完整覆盖

符合风格规范

• 代码遵循风格指南
• Lint 检查通过
• 格式正确

文档

• 为公共 API 编写文档
• 解释复杂逻辑
• 如有需要，更新 README

类型安全

• 包含类型提示（如适用）
• 类型检查器通过
• 不得无理由使用 type: ignore

无代码检查错误

• 代码检查器错误数为零
• 已处理警告或说明其合理性
• 静态分析无问题

安全审计

• 代码中没有机密信息
• 已进行输入验证
• 身份验证／授权正确
• 依赖项不存在漏洞

Git 集成

提交消息格式

<type>(<scope>): <subject>

<body>

<footer>

类型：

• feat：新功能
• fix：修复错误
• refactor：不涉及功能或错误修复的代码更改
• test：添加测试
• docs：文档
• chore：维护

使用 Git Notes 编写详细摘要

为提交附加详细说明：

git notes add -m "<detailed summary>"

查看说明：

git log --show-notes

优点：

• 保留上下文，同时避免提交消息杂乱
• 支持跨提交进行语义查询
• 支持基于轨道的操作

在 plan.md 中记录 SHA

完成任务时务必记录提交 SHA：

- [x] **Task 1.1**: Setup schema `abc1234`
- [x] **Task 1.2**: Add model `def5678`

这有助于：

• 从计划追溯到代码
• 执行语义化回滚操作
• 审查进度

处理偏差

实施过程中可能会偏离计划。请系统地处理：

偏差类型

增加范围 发现原始规范中未包含的需求。

• 在 spec.md 中记录为新需求
• 向 plan.md 添加任务
• 在任务注释中注明新增内容

缩减范围 实施过程中认为某项功能没有必要。

• 将任务标记为 [-]（跳过），并说明原因
• 更新 spec.md 的范围部分
• 记录决策理由

技术偏差 采用了不同于计划的实施方法。

• 在任务完成注释中注明偏差
• 如果依赖项发生变化，则更新 tech-stack.md
• 说明原方法不适用的原因

需求变更 工作过程中对需求的理解发生变化。

• 在 spec.md 中更新为正确的需求
• 按需调整 plan.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 后测试失败

如果达到 GREEN 后测试失败：

1. 不要进入 REFACTOR
2. 找出开始失败的测试
3. 检查是否有内容被重构破坏
4. 回退到最后一个已知的 GREEN 状态
5. 重新尝试实施

检查点未获批准

如果用户拒绝检查点：

1. 在 plan.md 中记录拒绝原因
2. 创建任务来解决问题
3. 完成修复任务
4. 再次请求检查点审批

被依赖项阻塞

如果任务无法继续：

1. 将任务标记为 [!]，并注明阻塞原因
2. 检查其他任务是否可以继续
3. 记录预计解决时间
4. 考虑创建依赖项解决轨道

最佳实践

1. 绝不跳过 RED：务必先编写失败的测试
2. 小步提交：每次提交只包含一项逻辑更改
3. 立即更新：任务完成后立即更新 plan.md
4. 等待批准：绝不跳过检查点验证
5. 详尽的 Git Notes：加入有助于后续理解的上下文
6. 严格遵守覆盖率要求：不要接受低于目标的覆盖率
7. 质量门禁：标记完成前检查所有门禁
8. 按顺序推进阶段：依次完成各阶段
9. 记录偏差：注明任何偏离原计划的更改
10. 保持状态干净：每次提交后，代码都应处于可运行状态
11. 快速反馈：开发过程中频繁运行相关测试
12. 及时解决阻塞：尽快处理阻塞，不要绕过问题

记忆协议（强制）

开始前：

cat .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 作出决策 -> .claude/context/memory/decisions.md

假设工作可能中断：如果没有记录在记忆中，就等于没有发生。