用途
test-hygiene 面向的是“测试套件在智能体与人类不断添加测试时逐渐退化”的问题。对智能体而言，新建一个测试文件几乎零成本，而理解既有套件需要消耗上下文，于是主导策略变成“再建一个新文件”，隐含目标变成“任务关闭、CI 变绿”，而不是“套件健康”。由于没有人度量套件健康度，也就没有人去优化它，结果会快速累积：同一模块出现并行测试文件、同一行为在三个层被重复断言、与实现耦合的测试在每次重构时断裂并被替换而非修复、skip 标记悄悄把安全网变成装饰。这套规则的目的，是让“健康的做法”同时成为“成本最低的做法”。
主要能力：绑定规则
- 测试归属：单元层归属源码，行为层归属集成、契约与 e2e。
- 写前先搜索：先定位目标层与行为范围内既有的归属文件并扩展它；为同一归属新建并行文件需要合理的范围拆分理由。
- 按层确定性归属：单元测试每个源文件一个主测试文件，镜像源码路径（如 src/foo/bar.py 对应 tests/unit/foo/test_bar.py），遵循项目既有约定并记录合理的范围拆分。集成、契约与 e2e 测试按行为归属：每个行为范围（一个流程、一个端点、一份契约）一个主文件，可以合法跨越多个源模块；这些层的违规是“同一范围出现无法解释的第二个文件”，而不是跨模块覆盖。
- 显式分层：unit、integration、contract、e2e 各有运行时预算，通过项目目录、同置路径或运行器标记识别。新测试放入能证明其契约、又不隐藏相关边界的最低层。
- 通过合理接口验证行为：优先使用可观察契约。内部访问、边界替身与顺序检查需要具名边界或诊断性回归作为依据；重写前先检查其用途。
- 不得用 skip 标记换取变绿：在修复或接受临时隔离前，先对产品缺陷、断言错误、环境失败与间歇性失败分类。仅有被跟踪的原因，不足以成为失去回归保护的理由。
- 断言保护：保留针对已批准行为的断言；只有在具备独立权威与证据时才修正错误断言，同时保持有效的产品保护处于激活状态。
- 测试退役：仅当行为已退役，或在同一候选中存在经验证的等价替代保护时才退役测试；仅凭数量、覆盖率、年龄或重构不足以退役。
- 重构、重命名与迁移：保留并重新指向有意义的保护。依赖资源的测试遵循 references/prevention-rules.md 第 9 条的隔离与复现清单。
修复阶梯
当套件已经退化时，仅靠规则无法修复，需要在正常开发过程中分层、机会性地逐步改善。完整机制见 references/remediation-workflow.md。
- 先度量：/testing:test-audit 生成带版本的 TEST_AUDIT.md，包含数量、运行时、跳过、失败、不稳定、孤儿、层分布、最慢测试、按模块覆盖率。指标用于指导调查，不能确立行为价值或正确性。
- 隔离前先分类：加载 testing:test-remediation-method 技能；产品缺陷、错误断言、环境失败、间歇性与未知原因各有不同归属。临时隔离需有明确证据、剩余风险、回归条件与负责人；仅凭套件变绿并不能使其变得可信。
- 按模块整合：重写前先盘点受保护行为、独立失败模式与缺陷修复来源。被接受的替换与移除共享同一候选与授权提交。
- 验证：每条受保护清单条目都映射到一个有合理依据的存活检查。覆盖率与数量支持评估，但不能证明等价。
- 按风险排序修复：先生产缺陷，再按 git log 的变更频率，而不是按模块看起来有多乱。
层模型与预算
以下为默认值，项目自身约定优先。
- unit：包含隔离行为、在合理边界使用受控替身、无真实外部 I/O；单个测试低于 100ms，整层低于 60s。
- integration：通过容器或 fixture 使用真实边界（数据库、HTTP、文件系统）；整层低于 5min。
- e2e：仅关键用户流程；运行时预算由项目定义，依据合理的关键流程与失败模式，不设测试配额。
一个行为的主要证明只存在于一个层。跨层重叠只有在两个测试通过同一可观察契约保护基本相同的失败模式、且未增加独立风险覆盖时，才算重复；在单元层检查计算、在集成层检查持久化、在 e2e 层检查用户流程，是三种行为而非一个行为的重复。跨越真实数据库边界的测试属于集成层。受控的数据库端口替身可以在单元层隔离服务行为，但无法证明 SQL、事务或持久化；这些契约需要在合适的测试通道中使用真实边界。
使用方式与相关依赖
所需的上游技能需要在当前宿主上做能力预检：解析并加载实际已安装的技能，然后才接受需要它的操作。依赖元数据与五宿主渲染，并不能证明某个外部市场在全部五个宿主上都能运行。若不可用，应记录受影响的操作处于未决状态，并给出当前宿主支持的安装指引；不要替换成其他提示词，也不要声称上游方法已运行。
- 编写测试内容（红到绿工作流、行为优先设计、mock 纪律）：加载 mattpocock-skills:tdd 技能。它随上游 mattpocock/skills 插件发布，是本插件的硬依赖；若不可用，应停止并告知用户安装（claude plugin marketplace add mattpocock/skills，然后 claude plugin install mattpocock-skills@mattpocock）。
- 浏览器 E2E 模式（页面对象、fixture、等待、网络 mock）：加载 developer-essentials:e2e-testing-patterns 技能。它随上游 wshobson/agents 市场发布，是本插件的硬依赖；若不可用，应停止并告知用户安装（claude plugin marketplace add wshobson/agents，然后 claude plugin install developer-essentials@claude-code-workflows）。
- 运行器检测与度量命令：用于审计工作流，见 references/runner-playbook.md。
适用场景与限制
适用于需要长期维护测试套件、且测试由智能体与人类共同添加的项目，尤其是已经出现重复文件、跨层重复断言、实现耦合测试与 skip 标记泛滥的退化套件。限制方面：规则本身不能修复已退化的套件，需要配合修复阶梯；度量指标不能证明行为价值或正确性；覆盖率与数量不能证明等价；上游技能依赖需在宿主上实际安装，否则相关操作应保持未决。