测试协作治理（test-collaboration）

目标

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

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

清单管理的是“为什么测、测什么、证据在哪”，测试代码仍然是可执行事实。普通小任务只改相关代码并运行与影响、风险相称的检查；文档事实未变就不更新，也不因收尾运行全量审计。MAP 只在路径、入口或定位关系变化时更新；LOG 只记值得追溯的重要事件；TESTS 只在测试入口、使用方法或重要覆盖范围变化时维护，不逐例登记或重复抄写运行结果。 不把 TESTS.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 时按实际风险选择有效验证：复用已有测试；缺少保护且值得自动化时补相关回归测试；类型、lint、schema 或人工验证更合适时使用它们。测试须覆盖真实失败形状，说明修复前后证据；不能先运行旧代码时说明复现依据和未实测项。

结果直接在回复说明。普通修复、新增边界用例或一次测试通过，不要求更新 TESTS、创建 TEST-ID 或追加 LOG；重要测试资产事实变化才更新现有索引。

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，不足以证明必要规则已覆盖。

核对实际任务的成功标准与验证证据。重要覆盖或契约事实变化才维护相应条目；仅重复运行得到绿色结果不更新台账或历史。重要事件沿用既有主记录，不在多份文档重抄。

测试设计纪律

• 标准入口优先：先让贡献者知道“一条命令怎么跑默认测试”；慢测试、联网测试和高成本 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. 下一步只列最重要的补测动作。

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