tdd-loop

TDD 循环

TDD 是一次只将一个失败测试变为通过的过程。这项技能规定了具体流程：循环的关卡、完成证据，以及不适合严格遵循测试先行的工作所需的例外处理流程。

此循环的位置

/implement（Matt Pocock，可选）负责一个工单，并在每个预先约定的接缝处调用此循环；如果不使用它，则直接针对每个工单运行此循环。 /tdd（Matt Pocock）是测试质量参考，说明什么是好的测试、接缝应位于何处，以及有哪些反模式。它不是一个循环；切勿单独使用它来代替此流程。

循环开始前

零署名：绝不在任何输出中添加或保留共同作者、AI 或工具署名。此工作流创建或更新的任何 Markdown 或设置文件中，都必须包含此规则。

在本地工作；绝不访问生产环境，也不创建面向生产环境的 PR。仅凭紧急程度并不能获准跳过测试；紧急热修复必须通过例外处理流程声明，并且仍需在关闭问题前提供回归测试失败的证明。

1. 将变更重述为可观察的行为。 用一句话表达：“当 <输入/操作> 时，会得到 <可观察结果>。”如果无法写出这句话，则说明请求尚未准备好实施——将其转交给 /feature-prompt（范围不明确）或 /diagnosing-bugs（原因不明确），然后停止。
2. 找到接缝。 找出负责该行为的代码、现有测试，以及项目的定向测试命令（单个文件或单个测试）。先阅读相邻测试和项目脚本/CI。如果仍不清楚该使用哪个命令，只阅读 references/test-commands.md 中对应的生态系统。遵循本地风格、测试夹具和命名惯例。 如果接缝的选择确实存在争议，询问用户；如果用户不在线，说明你的选择并继续。 选择实现方案前，先检查项目现有的辅助工具和组件，然后检查标准库或平台功能，最后检查已安装的依赖项。选择第一个完全满足验收标准和项目惯例的方案；已有的项目组件优先于原生替代方案。如果都不适用，只编写缺失的行为。避免仅为几行清晰代码新增依赖，并保留验证、错误处理、安全性和无障碍功能。复用同样需要遵循红/绿检查和已声明的例外处理流程。
3. 将验收标准映射到测试。 按 references/ac-matrix.md 构建矩阵——每项标准的每条路径（正常、边界、失败、替代）各占一行，另加范围检查。运行中的应用所对应的行，须通过合适的项目 E2E 测试关闭；如果没有测试运行器覆盖该项，则记录尚欠的证明，并交由 /agentic-qa 处理。工单中没有验收标准时，根据第 1 步的句子编写，并说明这一点。
4. 现在声明任何例外（见“例外处理流程”）——必须在编写任何代码之前声明。

除已声明的例外外，没有定向测试命令就无法运行循环。在此代码库中找到运行单个测试的方法属于第 2 步的工作，不能作为跳过红阶段的理由。

每次阶段转换时，输出 Stage / Found / Next / Needs user——每个字段单独一行。阶段转换包括：找到接缝、每个切片的红 → 绿，以及完成。

循环

每种行为重复一次，从最小切片开始。当一个会话处理一批任务—— 多个工单或 Bug 修复——时，每个切片只运行针对该切片的命令及扩展范围 的命令；项目的完整检查只在最后一个切片之后运行一次——每个切片都完整 运行一次不会带来额外信息。

1. 红。 编写一个断言新行为的失败测试。运行针对该测试的 测试，并阅读失败信息。
   • 它必须因正确的原因失败——缺少行为（断言失败），而不是导入、拼写 或配置错误。继续之前，先修复因错误原因导致的失败。
   • 新测试如果立即通过，就是停止信号：要么该行为已经存在（报告这一点 并停止），要么测试没有断言任何新内容（重写它）。如果本次会话中尚未 提交的代码实现了该行为，则撤销那部分改动，确认测试变红，然后再重新 应用；绝不要将其报告为已有行为。
2. 绿。 做出能通过针对该测试的最小改动——不要添加推测性的参数，也不要 顺手清理相邻代码。重新运行针对该测试的测试。
3. 扩展。 运行周边测试套件（模块或包范围——此处绝不运行项目的完整 测试套件）。由你的改动导致的新失败属于当前切片——立即修复。
   • 对疑似预先存在的失败，须通过隔离的基线检出目录，或在条件相同的情况 下记录的改动前运行结果来确认。保留工作树中的编辑；不要为了制造基线 而暂存其他工作。记录基线命令和结果。如果未能确认，则报告为尚未解决； 绝不要在假定失败原本就存在的情况下，声称该范围已通过。
   • 绝不要通过弱化断言或删除失败测试来让测试通过。如果确实必须更改测试 的契约，请说明原因并征求用户意见；如果用户不在线，只有在旧断言与已 达成一致的行为相矛盾时才更改，并在摘要中标明。
4. 仅在通过后重构。 对当前切片涉及的内容进行不改变行为的清理，然后 重新运行扩展范围的测试。无需清理 → 跳过。
5. 下一行。 回到红阶段，处理矩阵中的下一行未完成项，包括你所改代码中 防护逻辑对应的边界情况。若下一个测试将断言无人要求的行为，则停止。

循环之后

• 文档。 行为已改变 → 更新所有相关文档：README 片段、API 示例、声明 旧契约的注释。没有相关文档 → 说明这一点并跳过。

• 摘要。 以以下内容结束：

  Behavior: <the one-sentence behavior>
  Red → Green: <test name(s)> — seen failing (<how>), now passing
  Scope run: <focused command> · <widened command> · <full check | deferred to batch end | widest feasible — why>[; pre-existing failures: <names, baseline command and result>]
  AC map: <AC-n path → test | agentic-qa (surface) | deferred — why>; span check: <finding | none found>
  Edges: <covered: …> · <deferred: … — why>
  Docs: <path updated | nothing documents this behavior>
  Exception: <declared exception + follow-up test plan | none>
  

  只有在不确定如何填写具体的证据字段时，才加载 references/summary-example.md。

  然后建议运行 /code-review，接着运行 /commit-push-close 或 /commit-push-pr；如果更改可能影响屏幕，或有任何与之相关的矩阵行尚未 完成，再建议在已交付的修订版上运行 /agentic-qa——只提出建议，绝不自动 串联运行。所有地方都使用 Project Matrix 中完整的 PROJECT-CODE；绝不要将 一个项目的约定、令牌或组件混用到另一个项目中。

完成标准——证据，而非保证

完成意味着你能展示以下所有内容。对于已声明的例外，仅将不适用的测试检查替换为其指定的验证命令或手动步骤及观察结果；将这些测试标记为 N/A 并说明原因，绝不编造红灯／绿灯证据。保留其余检查和后续计划。只有在修复前的提交上观察到回归测试失败、并在修复后观察到测试通过，已声明的紧急热修复才算完成；在此之前，应如实说明，而不是建议使用 /commit-push-close。

• 每项新测试在通过之前，都观察到过其失败——引用失败的运行结果。（特征测试旨在锁定当前行为，按设计应当通过——请引用它捕获的锁定输出。）
• 定向测试通过，扩大范围后的测试也通过（已核实为既有的问题须注明在 Scope 运行记录行中）；两条命令都已列明。
• 建议发布之前：根据 The loop，项目的完整检查（全套测试或 CI 命令）针对本批次至少有一次运行成功——已核实为既有的问题除外，并注明；或者总结说明为何扩大后的范围已是可行的最大运行范围。
• 没有弱化断言，也没有为让测试通过而删除失败的测试（或者已标记合约变更，并由用户决定）。
• 矩阵中的每一行都已通过测试关闭、交由 /agentic-qa 处理，或说明原因后延期；跨度检查已作答；矩阵参考中的测试质量检查确认没有待处理项。
• 文档已更新，或注明“没有文档记录此行为”。
• 任何例外都已事先声明，并记录后续测试计划。

自主权边界

当工单包含编号验收标准、切入点已事先商定，且最多经过一次针对性提问后需求仍然明确时，无需询问即可继续。如果工单为验收标准编号，请在每项测试的描述中注明对应标准（AC-3: 五次失败尝试后锁定）——可追溯性本身就是证据的一部分。

如果需求仍有歧义、工作范围超出工单的验收标准，或身份验证、支付、数据迁移场景尚未获得用户批准，请停止并询问。用户已在本次会话中明确批准的，视为已获批准；追求测试通过之前不要再次请求批准。

例外流程

对于技术探索、遗留切入点、紧急热修复、配置变更或探索性重构，请在编辑前加载 references/exception-protocol.md。声明具体情况、原因、验证方式和后续测试计划；例外绝不意味着可以访问生产环境，也不能默默跳过验证。