---
name: test-collaboration
description: "盘点并维护项目测试资产，把需求、业务规则、风险、Bug 和跨端接口契约转成 TEST-ID 与可验证证据，生成或更新 TESTS.md。用于测试资产盘点、测试缺口分析、单元/集成/契约/E2E/冒烟分类、Bug 回归保护、前后端或多服务基于同一契约的消费者/提供者测试、测试必要性判断、测试清单维护与交付前测试证据审查。中文触发：测试盘点、测试清单、测试资产、测试缺口、测试必要性、Bug 转测试、契约测试、前后端接口测试、测试治理。English triggers: test inventory, test catalog, test gap analysis, bug-to-test, contract testing, consumer contract, provider verification, test governance."
---

# 测试协作治理（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. 下一步只列最重要的补测动作。

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