测试协作治理（test-collaboration）

目标

用项目根目录的 TESTS.md 管理两类信息：

1. 现有测试资产地图：项目已经有哪些测试、从哪里运行、保护什么。
2. 必要测试点清单：哪些需求、规则、风险和 Bug 必须被测试保护，当前证据是否足够。

清单管理的是“为什么测、测什么、证据在哪”，测试代码仍然是可执行事实。不要把 TESTS.md 写成每个测试函数的镜像。

职责边界

资产	唯一职责
TESTS.md	测试资产、必要测试点、缺口、状态和证据
测试代码	可执行输入、断言、fixture/fake 和边界模拟
REGRESSION.md	模块下游、回归命令和改动后的重跑规则；只引用 TEST-ID
Spec/Issue	成功标准、问题现象、影响、优先级、任务状态和排期的唯一来源
PROJECT_LOG.md	只追加测试状态变化和交付结论，不复制整个清单

v1 由当前会话直接执行本 skill，不新增专用 agent、slash command 或强制脚本。

开始前读取

按存在性读取，不要求项目拥有全部文件：

1. TESTS.md 与 templates/TESTS.example.md。
2. 项目规则和地图，如 CLAUDE.md、AGENTS.md、CLAUDE_MAP.md。
3. 测试目录、测试配置、CI 配置、标准测试入口和专用测试任务。
4. Spec、Bug、Issue、审计、事故或回归清单；成功标准只引用，不复制进 TESTS.md。
5. REGRESSION.md，用于对齐模块回归命令与 TEST-ID。
6. 跨端接口的机器可读契约及生成/校验入口，例如 OpenAPI、JSON Schema、GraphQL schema 或 protobuf。

先识别仓库已有的测试框架和命名习惯，不强迫项目改成统一目录结构。

工作模式

1. 盘点现有测试资产

首次采用时做一次全量盘点，之后按事件增量维护：

1. 找到标准测试入口，例如 pytest、npm test、make test 或项目脚本。
2. 扫描测试目录、配置和 CI；可以使用 collect/list 模式，但不要为了盘点执行高风险外部操作。
3. 按模块、测试套件或关键流程聚合，禁止手抄每个测试函数。
4. 标注层级、用途、为什么存在/保护什么风险、执行组、外部依赖、位置和当前判断。
5. 将资产判断为：必要、疑似重复、缺失或疑似废弃。盘点阶段只报告，不擅自删除或重写测试。

重新盘点由事件触发，不按日历机械执行：

• 首次建立 TESTS.md：全量扫描。
• 测试目录、测试配置、CI 或标准入口变化：重扫受影响区域。
• 新增或更新 TEST-ID、Bug：增量核对相关模块。
• 重大功能、接口、业务规则或安全边界变化：重扫对应链路。
• 交付前或 /governance-sync 收尾：核对本次变更涉及的条目。
• 只有测试体系整体重构或地图明显失真时，才再次全量扫描。

2. 把需求、规则和风险转成 TEST-ID

每个必要测试点使用稳定 ID，例如 TEST-ORDER-001。至少记录：

• 状态：待补、开发中、已覆盖、不适用。
• 来源：需求、规则、风险、Bug 或事故编号。
• 模拟输入与业务预期。
• 层级与用途。
• 执行组和真实/模拟边界。
• 测试文件、测试节点和可执行命令。

纯模板、教程或历史方案中的示例编号不属于项目测试台账。确定性审计需要扫描这些文档时，可在文档顶部加 <!-- test-id-audit: examples-only --> 显式声明“本文件只有示例”；活动 Spec、Issue、Bug、评审或交付证据不得用该标记逃避登记。

来源必须链接回 Spec/Issue 中的原始成功标准。TESTS.md 只回答“哪条证据验证它”，不得另写一份可独立漂移的业务标准。成功标准含糊时，回到需求澄清能力或请项目负责人确认，不由测试 Skill 猜测。

受控层级：单元、集成、契约、E2E、冒烟。

受控用途：规则保护、关键链路、回归保护、专项保护。需要多个用途时用逗号分隔，不能临时发明新值。

不适用 必须写理由，例如风险由 schema、类型系统或 lint 更合适地机械拦截。不能用“不好测”作为理由。

3. 把 Bug 转成回归保护

修复 Bug 时，必须二选一：

1. 新增或关联一个 TEST-ID；或
2. 明确记录为什么只能人工验收，以及人工验收步骤和证据。

TEST-ID 应复现真实失败形状，而不是换成更容易通过的相似输入。记录修复前失败、修复后通过的证据；如果无法先运行旧代码，至少说明复现依据和未实测项。

没有 TEST-ID 或明确的人工出口，不得宣称 Bug 已完整闭环。

4. 用同一契约驱动跨端测试

前端与后端或多个服务分开开发时，把接口契约作为测试共同输入，不让各端分别手写一份接口事实：

1. 找到仓库已有的机器可读契约，记录路径及可核验的版本、commit 或 hash；不把字段表复制进 TESTS.md。
2. 用同一个 TEST-ID 串起四层证据：
   • 契约自身：schema lint 或格式校验；
   • 消费方：由契约生成或校验的类型、mock、fixture 与消费者测试；
   • 提供方：对真实序列化后的响应或消息做契约校验，不能只验证内部 DTO 或类型；
   • 联调：至少一条真实跨端路径；暂时没有时明确登记缺口。
3. 每层记录实际命令、退出码和证据位置。生成类型或 mock 未重新生成、与契约不一致时，不得标为 已覆盖。
4. 接口需要变化时先更新唯一契约源，再重新生成消费方资产并重跑提供方与联调测试。
5. 仓库没有机器可验证契约时，标为 待补 或 不可验证，说明当前只能依赖什么证据；不能把双方各自测试为绿写成“兼容性已验证”。

契约测试证明双方是否遵守同一接口边界；E2E 继续证明真实业务路径能否工作。两者不能互相替代。

5. 审查测试证据

将状态标为 已覆盖 前，逐项确认：

1. 测试文件真实存在。
2. 断言验证业务行为，不只是“函数被调用”或“状态码是 200”。
3. 命令可执行且退出码为 0。
4. 测试进入标准 runner，或登记为命名清楚的专用执行组。
5. 证据能对应 TEST-ID 的输入、预期和边界。

只看到测试文件、测试数量或绿色 CI，不足以证明必要规则已覆盖。

交付闭环还要确认：活跃 Spec/Issue 有明确成功标准；关键标准已关联 TEST-ID 或可复核的人工出口；证据确实验证预期行为；标准变化和本次重要结果已按活文档规则记入 PROJECT_LOG.md。

测试设计纪律

• 标准入口优先：先让贡献者知道“一条命令怎么跑默认测试”；慢测试、联网测试和高成本 E2E 放入命名清楚的专用组。
• 边界写清楚：E2E 要说明哪些部分真实运行、哪些外部系统被 fake/mock，以及为什么。
• 真实故障形状：Bug 回归测试使用导致事故的输入、路径和边界条件。
• 行为契约优先：断言数据之间必须满足的关系和不变量，少写只会在正常更新时报警的快照、固定枚举数量或版本字面量。
• 复用 fixture/fake：同类输入和外部边界优先复用项目已有设施，避免每个测试自造一套。
• 正反两面：关键规则至少考虑正常输入和拒绝/边界输入；权限、安全、配置传播和文件/网络路径尤其如此。
• 真实路径优先：涉及解析链、配置传播、安全边界、远程后端或文件/网络 I/O 时，应有真实导入和临时目录上的集成或 E2E 证据，不能只靠单元 mock。
• 契约单源：消费者类型/mock、提供方验证和联调测试必须引用同一契约源；禁止维护多份手写字段定义。
• 序列化边界：提供方契约测试必须检查线上实际返回形状，覆盖字段名、类型、空值、枚举、错误结构和大整数 ID 等易漂移边界。
• 规模适配：借鉴这些纪律，不复制别的大项目的并行测试基础设施或目录规模。

输出要求

创建或更新 TESTS.md 时使用 templates/TESTS.example.md 的结构，并在回复中给出：

1. 标准测试入口和测试资产概况。
2. 必要、缺失、疑似重复、疑似废弃的数量。
3. 本轮新增或变更的 TEST-ID。
4. 已实际运行的命令、退出码和未实测项。
5. 下一步只列最重要的补测动作。

盘点任务默认只修改测试治理文档。除非用户另行授权，不修改生产代码、不删除测试，也不替贡献者偷偷补实现。