# AGENTS.md — qa-skills 项目指令

> 本文件是**维护者的迭代 SOP**。"评测三轨道"及各处 `eval/` 引用描述的是本地维护的评测链路
> （2026-08-22 起不随公开仓库分发，公开仓库只含 skills 产品内容）；公开侧证据链为按里程碑
> 随 Release 附带的增益矩阵快照。

## 使命（所有工作的对齐点）

安装 qa-skills 之后，对**任何 agent、任何模型**，在软件测试领域带来**质的提升**。
一切决策——改 skill、建评测、扩任务、发版本——的优先级判断都以这一句话为锚。

## 战略路径：迭代飞轮

skill bench 是驱动 qa-skills 迭代的手段，不是目的。标准回路：

> 跑 bench → 失败模式归类、定位 skill 短板 → 修改 skill → 复验（评测-修复闭环）

bench 的产出是"改哪里"，不是总分。聚合数字（如覆盖 +8.7pp）用于发布，不用于指导迭代；
指导迭代的是逐 GT 点的失败明细及其归类（澄清缺失 / 边界遗漏 / 状态遗漏 / 断言强度不足 →
映射到 skill 的具体环节）。

## 北极星指标

**跨模型 × 跨宿主的 On/Off 增益下限（min，不是均值）。**

- 弱模型段位：追求可执行性、真实执行通过率等**类别性质变**（0.2→0.98 型）
- 强模型段位：覆盖增益趋零后，价值在流程纪律与系统行为（复审拦截、回归编排、接口一致）
- 对单一模型（当前 glm-5.2）迭代出的提升若不能跨模型复现，视为**过拟合而非进步**

## 评测三轨道（eval/）

1. **模型矩阵（常设回归）**：标准回路固定 2–3 个段位的便宜模型（flash 级 + 中档），
   强模型按里程碑跑。skill 修改的合入门槛之一：**最弱模型上的增益不回退**。
2. **in-situ 轨道**：真实宿主会话中量三个数——触发正确率、装载文件集合、产出质量。
   这是"任何 agent"的关键证据（注入式评测只证明内容值得装，不证明装了会生效）。
3. **注入式轨道（现有 harness）**：内容质量哨兵，原样保留。

## 迭代纪律

- **只有类别性 / 大效应信号才触发 skill 变更**；+2pp 级差异一律视为采样噪声
  （n=3 的采样方差与单次普通修改的效应同量级，见澄清任务跨轮方向翻转案例）。
- 任务池轮换（30–50 任务抽半跑，季度换血），防 skill 对着题库优化。
- 迭代涉及的任务做双人 GT 复核——GT 错标会让飞轮朝错误方向持续优化，是最危险的失败模式。
- 日常真实使用中的触发失败 / 产出不佳案例，每周沉淀 2–3 个进任务池（dogfooding 反哺）。
- 里程碑版 Release 配增益矩阵快照（跨模型 On/Off 对比）与迭代记录——这是 skill bench 的自然形态，
  也是"安装这个 skill 会发生什么"的纵向证据。

## 门禁入口（维护者本地 ≠ CI）

CI 与贡献者入口（CONTRIBUTING 自检）只覆盖已跟踪面：`unittest discover tests -p "test_*.py"`
+ 两个校验器 + 安装器冒烟。`tests/test_harness.py`（harness 单测，随 eval/ 本地维护、gitignore）
**只能用 pytest 跑**：`python3 -m pytest tests/ -q`（收集面 = 上述已跟踪用例 + harness 全部用例）。
改 skill / 加 skill 后本地合入前必须跑 pytest 口径——用例数一律以实际收集数为准、不写进文档
（2026-09-07 审查教训：qa-memory 合入使 harness 断言红了一次，unittest 入口永远看不到它，
红灯静默 9 天；同批 AGENTS 写死的用例计数在加测试的同一个提交里就过期了）。

## 报告与对外发布的定位

评测报告（eval/reports/）是里程碑快照，不是目标本身。对外数字发布前跑零成本污染三件套
（cutoff 核对 / n-gram 扫描 / canary），见本地维护的 eval/harness/CONTAMINATION.md（eval/ 为本地链路，不随公开仓库分发）。