AGENTS.md — qa-skills 项目指令

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

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

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

总目标章程（"测试领域最强"的判定记分牌、审查-对比常设回路、达成判据）见本地 docs/GOAL.md（规划文件，不入库）；本季度执行方案 = 补强方案 v1.2（Phase 0–4）， 为章程记分牌的季度执行切片。

战略路径：迭代飞轮

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/ 为本地链路，不随公开仓库分发）。