tdd

测试驱动开发

每次只构建或修复一个经过验证的行为切片。如果本地测试成本低，先编写失败的检查。如果测试成本高或路径不明确，则说明原因，并采用最接近的可执行验证。

契约

输入：

• 功能请求、错误报告、PRD、问题或实施计划
• 现有测试命令和项目约定
• 需要保护的公共接口或面向用户的行为

输出：

• 存在低成本路径时，提供测试优先的实施计划
• 请求实施时，新增或更新测试及代码
• 验证命令，以及修改前失败、修改后通过的证据

创建/修改：

• 实现所请求行为所需的测试文件和生产代码
• 不做无关重构或大范围重写测试套件

外部副作用：

• 默认没有
• 测试不得使用生产数据或对外部服务进行实时写入

需要确认：

• 更改公共 API、架构、迁移，或超出请求范围的用户可见行为之前

委派给：

• testing-expert，处理广泛的测试策略或框架设置
• testing-expert（AI 回归模式），处理特定错误的回归覆盖和路径一致性
• debug，在根本原因仍不明确时使用
• codebase-design，在仍需调整测试边界这一模块接缝时使用
• verification-before-completion，在准备宣称工作已完成时使用

低成本路径门槛

仅当路径成本低且在本地可运行时，才编写新测试：

• 针对该代码路径的聚焦单元测试、组件测试或现有集成检查
• 结果确定、运行速度足以反复执行，且不依赖仅存在于生产环境的状态
• 验证预期行为，而非当前有问题的实现

如果测试需要搭建大范围测试框架、脆弱的模拟对象、耗时的端到端基础设施、含糊的复现步骤，或大量无关的测试固件变更，则跳过新增测试。宁可不写测试，也不要写糟糕的测试。

糟糕的测试主要是在测试模拟对象、编码实现细节、依赖时序或无关的全局状态、为小修复依赖昂贵的基础设施，或在证明修复有效后会立即被删除。

不要默默跳过测试。在更改生产代码之前，说明为什么不值得花费成本编写失败测试，并指出最接近的可执行检查：定向脚本、复现命令、浏览器操作、快照对比、日志断言或聚焦的集成检查。

核心规则

先编写一个验证行为的失败测试，让它通过，然后再重构。重复此过程。

测试应通过公共接口验证行为，并能经受内部重构。如果私有辅助函数重命名后行为仍正常，但测试却因此失败，那么测试就与实现耦合过度。

编写测试之前

如果存在，请先阅读 GLOSSARY.md 和 CONTEXT.md，以及相关的 ADR，确保测试名称和接口术语符合项目领域。

1. 查找至少 3 个符合本地模式的现有测试或实现。
2. 找出最有用的测试边界：用户流程、路由、服务 API、CLI 或纯函数。
3. 用用户或调用方的语言描述行为。
4. 选择运行新测试所需的最精简命令。
5. 仅列出构成有效纵向切片所需的前 1-3 项行为。

仅在公共行为或接口确实不明确时提问。否则，做出保守假设并继续。

Red-Green-Refactor 循环

1. Red（红）

为一个可观察行为添加一个测试。

测试必须因正确的原因而失败：

• 测试公共行为，而非私有细节。
• 测试因行为缺失或出错而失败。
• 测试结果确定且足够精简，可反复运行。

在更改生产代码之前，先运行新测试。如果测试通过，或因无关原因失败，先修正测试或复现步骤。

2. Green（绿）

编写能使测试通过的最小生产代码改动。

测试处于失败状态时，不要添加推测性选项、未来分支或无关的清理工作。

3. 重构

测试通过后：

• 移除重复内容。
• 使用仓库中已有的领域语言，改进命名。
• 仅当当前切片证明有必要时，才将复杂性封装在更清晰的接口之后。
• 每完成一个重构步骤，都重新运行范围最窄的测试。

垂直切片

优先采用精简的端到端切片，而非横向批量处理。

好的做法：

• 一个行为测试
• 一条实现路径
• 一条验证命令
• 一个可演示或可检查的结果

不好的做法：

• 先编写所有测试，再完成所有实现
• 行为尚未存在，就针对设想中的数据结构编写测试
• 仅为符合预先计划的设计而模拟内部协作者
• 按层拆分工作，而每个切片都无法独立发挥作用

Bug 修复

修复 Bug 时，先重现问题。如果原因未知，请使用 debug。

确定原因且通过低成本路径门槛后：

1. 将问题重现过程转化为失败的回归测试。
2. 确认测试在问题行为下失败。
3. 修复行为。
4. 确认回归测试通过。
5. 重新运行原始重现过程或用户工作流。

提交时，先将失败的重现过程提交到 git 历史中，再提交修复。差异会讲述这个过程：先红，再绿。

如果没有合适的测试边界，请将其说明为一项设计发现。添加现有条件下最佳的验证，并注明残余风险。

防护准则

• 不要为了迁就错误的实现而修改测试。
• 除非预期行为确实发生了变化，否则不要弱化现有断言。
• 让回归测试聚焦于 Bug。避免大范围改动测试夹具。
• 如果 Bug 具有不稳定性，请尽可能让测试具有确定性，并记录锁定的信号。
• 如果 Bug 暴露出一类更广泛的故障，先提交针对该路径的修复，再考虑覆盖同类问题。

模拟规则

• 模拟网络、时间、随机性、支付服务提供商、电子邮件、存储及其他外部系统。
• 避免模拟由被测模块拥有的代码。
• 在有助于保持行为真实性时，优先使用伪实现或测试夹具。
• 除非调用本身就是公开契约，否则不要断言实现调用。

完成检查清单

• 至少有一个先失败、后通过的测试覆盖新行为；若跳过，需说明跳过原因及最接近的检查。
• 测试名称描述行为，而非实现。
• 测试使用调用方或用户可用的公开接口。
• 范围最窄的验证命令通过。
• 条件允许时，相关的更大范围测试套件、类型检查或 lint 命令通过。
• 此切片中未捆绑无关重构或大范围改写。

最终回复

报告证据，而不只是结果：

• 指明修复前失败的测试或可执行检查，以及它产生的失败。
• 指明修复后通过的运行，以及执行过的相邻验证。
• 如果无法提供修复前失败的证据，请说明原因，并描述替代使用的最接近的回归检查。

TDD 流程

应用上述低成本路径门槛和垂直切片约定时，请阅读 TDD 流程。 在每个步骤中，都应用此入口点授权的范围和模式。 通过此发行版的活动目录解析其他技能；相对于已安装的技能目录解析资源。