regression-suite

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow,qa.level,system_overrides

以上已解析——直接使用。无代码块时 → 使用 .claude/docs/config-resolution.md 中的默认值。

回归测试套件

此技能确保每项错误修复都有对应的测试，且该测试本可以捕获原始错误——并确保回归测试套件随着游戏的发展保持更新。它还会检测是否有新功能在加入后未配备相应的回归测试覆盖。

回归测试套件并不是一种新的测试类别，而是从 tests/ 中精选出的一组现有测试，共同覆盖游戏的关键路径和已知故障点。此技能负责维护该列表。

输出： tests/regression-suite.md

运行时机：

• 修复错误后（确认已编写回归测试，或找出覆盖缺口）
• 阶段关卡检查前——在 qa.level: full 时，/gate-check 要求提供回归测试套件
• 冲刺收尾时，作为检测覆盖偏差的一部分

---

每次调用 AskUserQuestion 都遵循 .claude/docs/automation-modes.md （协作模式始终提问 · 引导模式仅在重大事项上提问 · 自主模式记录并继续； automation_always_ask 类别始终提问）。

工作流层级：使用上文解析出的 modes.workflow——除非显式设置，否则由 modes.rigor 提供——遵循 .claude/docs/workflow-modes.md；在 audit 模式下，读取每份 GDD 时，应按系统考虑 workflow_overrides.system_overrides.<system>。它决定是映射 GDD 关键路径，还是仅进行冒烟测试——参见步骤 2c。

qa.level：控制是否生成测试套件。minimal 时，不生成回归测试套件（报告这一情况并停止）；standard 时，在润色阶段开始时生成；full 时，在生产阶段开始时生成。这是与 workflow 不同的维度。

1. 解析参数

提前检查 qa.level（上文已解析）： 如果 qa.level: minimal，则不生成回归测试套件——报告“Regression suite not generated at qa.level minimal”，并在任何扫描开始前立即停止，适用于所有模式 （update / audit / report）。这是 qa.level 维度，与步骤 2c 中 workflow 层级的 minimal 分支不同（后者只改变关键路径的来源，而不改变是否运行测试套件）。不要因为 qa.level 而进入步骤 2c 的 minimal 分支。此停止的判定结果为未评估（第 7 节）——此级别不要求测试，且没有进行任何扫描。

模式：

• /regression-suite update — 扫描本次冲刺中新增的错误修复，并检查是否存在回归测试；将新测试添加到套件清单中
• /regression-suite audit — 全面审计所有 GDD 关键路径与现有测试覆盖情况；标记没有回归测试的路径
• /regression-suite report — 只读状态报告（不写入）；适用于冲刺评审
• 无参数 — 如果冲刺明确处于进行中（存在包含进行中故事的冲刺计划），运行 update。如果情况不明确或未检测到正在进行的冲刺，则使用 AskUserQuestion：
  • 提示：“未指定子命令。你想运行哪种模式？”
  • 选项：
    • [A] update — 扫描本次冲刺中新增的错误修复，并补充缺失的回归测试
    • [B] audit — 全面审计所有 GDD 关键路径与现有测试覆盖情况
    • [C] report — 只读状态报告（不写入）

---

2. 加载上下文

步骤 2a — 加载现有回归测试套件

如果 tests/regression-suite.md 存在，则读取它。提取：

• 已登记的回归测试总数
• 最后更新日期
• 所有标记为 STALE 或 QUARANTINED 的测试

如果文件不存在，则记录“未找到回归测试套件——将创建一个”。

步骤 2b — 加载测试清单

Glob 搜索所有测试文件：

tests/unit/**/*_test.*
tests/integration/**/*_test.*
tests/regression/**/*

对每个文件，记录其系统（根据目录路径确定）和文件名。 除非需要将名称映射到测试，否则不要读取测试文件内容。

第 2c 步 — 加载 GDD 关键路径

对于 audit 模式：读取 design/gdd/systems-index.md 获取所有系统，然后 根据每个系统的工作流层级（已在上文确定）限定扫描范围：

• full — 读取 GDD，并从所有章节中梳理关键路径。
• standard — 同样梳理，但仅限必需章节（验收标准、边界情况，以及系统定义了数值规则时的公式）。 通过 system_overrides 提升层级的系统，按其更高层级梳理。
• minimal — 跳过 GDD 关键路径扫描。改为读取 production/qa/smoke-*.md 中最新的冒烟检查报告，并将其覆盖的关键路径作为回归范围（第 3 步将针对这些路径梳理覆盖情况，而不是 GDD 验收标准）。如果不存在冒烟检查报告，则停止并给出结论：未评估 — 没有可用于提取关键路径的冒烟检查报告 — 在 minimal 层级下，如果没有报告，就没有关键路径来源；请先运行 /smoke-check。

（层级仅影响 audit 模式；update 和 report 模式不受层级影响。）

按章节读取每份 GDD：使用 Grep 工具查找所需标题（模式 ^#，内容模式），然后通过 offset 和 limit 读取相应范围。在 full 层级下， 需要分范围读取所有章节，因为超过 40 KB 的整份文件读取请求会被拒绝。

对于每个纳入范围的 MVP 层级系统的 GDD，提取：

• 验收标准（用于定义关键路径）
• 公式章节（公式必须有回归测试）
• 边界情况章节（已知边界情况应有回归测试）

对于 update 模式：跳过完整 GDD 扫描。改为读取当前冲刺计划 和故事文件，查找状态为本冲刺已完成的故事。

第 2d 步 — 加载已关闭的 Bug

对 production/qa/bugs/*.md 执行 Glob，并筛选包含 Status: Closed 或 Status: Fixed 字段的 Bug。记录：

• Bug 所属的故事或系统
• 修复说明中是否提到了回归测试

---

3. 梳理覆盖情况 — 关键路径

仅适用于 audit 模式。（在 minimal 层级下，关键路径来自第 2c 步中确定的 冒烟检查报告，而不是 GDD 验收标准 — 针对这些冒烟检查路径梳理覆盖情况， 并跳过下方的 GDD 标准循环。）

对于每条 GDD 验收标准，判断是否存在测试：

1. 在 tests/unit/[system]/ 和 tests/integration/[system]/ 中使用 Grep 查找与标准的关键名词/动词相关的文件名 和函数名
2. 分配覆盖状态：

状态	含义
COVERED	存在针对该标准逻辑的测试文件
PARTIAL	存在测试，但未覆盖所有情况（例如，仅覆盖正常路径）
MISSING	未找到针对该关键路径的测试
EXEMPT	视觉/体验或 UI 标准 — 按设计不可自动化

3. 将与公式或状态机有关的 MISSING 项提升为 高优先级缺口 — 这些最可能导致回归。

---

4. 梳理覆盖情况 — 已修复的 Bug

对于每个已关闭的 Bug：

1. 从 Bug 的元数据中提取系统 slug
2. 在 tests/unit/[system]/ 和 tests/integration/[system]/ 中使用 Grep 查找引用 Bug ID 或具体故障场景的测试
3. 分配状态：
   • 有回归测试 — 找到了能够捕获该 Bug 的测试
   • 缺少回归测试 — Bug 已修复，但没有测试防止问题复发

对于缺少回归测试的项目：

• 将其标记为回归缺口
• 建议测试文件路径：tests/unit/[system]/[bug-slug]_regression_test.[ext]
• 备注：“没有此测试，该 Bug 可能会在未来的冲刺中悄然复发。”

5. 检查覆盖漂移

当游戏不断扩展，而回归测试套件却没有跟进时，就会出现覆盖漂移。

检查漂移迹象：

• 本迭代已完成的故事在 tests/ 中没有对应的测试文件
• 自上次更新回归测试套件以来，systems-index.md 中新增了系统
• 自上次更新回归测试套件以来，GDD 中新增或修订了章节 （如果可用，请在 GDD 文件修改提示中使用 Grep，或询问用户）
• tests/regression-suite.md 的最后更新日期与当前日期之间的间隔——如果超过 2 个迭代，则标记为可能已过时

---

6. 生成报告和套件清单

报告格式（在对话中）

## Regression Suite Status

**Mode**: [update | audit | report]
**Existing registered tests**: [N]
**Test files scanned**: [N]

### Critical Path Coverage (audit mode only)
| System | Total ACs | Covered | Partial | Missing | Exempt |
|--------|-----------|---------|---------|---------|--------|
| [name] | [N] | [N] | [N] | [N] | [N] |

**Coverage rate (non-exempt)**: [N]%

### Bug Regression Coverage
| Bug ID | System | Severity | Has Regression Test? |
|--------|--------|----------|----------------------|
| BUG-NNNN | [system] | S[N] | YES / NO ⚠ |

**Bugs without regression tests**: [N]

### Coverage Drift Indicators
[List new systems or stories with no test coverage, or "None detected."]

### Recommended New Regression Tests
| Priority | System | Suggested Test File | Covers |
|----------|--------|---------------------|--------|
| HIGH | [system] | `tests/unit/[system]/[slug]_regression_test.[ext]` | BUG-NNNN / AC-[N] |
| MEDIUM | [system] | `tests/unit/[system]/[slug]_test.[ext]` | [criterion] |

套件清单格式（tests/regression-suite.md）

计算覆盖率前，先检查分母。 如果 GDD glob 返回的关键路径为 零，或测试 glob 返回的测试 文件为 零，则不要输出百分比——请报告 Coverage: NOT ASSESSED — [no GDDs found | no test files found]，并说明哪一侧为空，以及负责生成它的技能（GDD 使用 /map-systems 和 /design-system，测试脚手架使用 /test-setup）。

以空分母计算出的百分比不是低分；它根本不是一个数字。0% 表示“已测量，结果很差”，而 100% 表示“已测量，结果完美”——两者都在对从未进行过的比较作出判断。这与 /scope-check 在第 4 阶段设置的防护措施是同一个缺陷，措辞也相同： “基于零个基准项计算出的百分比不是一个小数字；它根本不是一个数字。”

该清单是经过整理的索引——不是测试本身，而是一份登记表，列出发布前应始终通过的测试：

# Regression Suite Manifest

> Last Updated: [date]
> Total registered tests: [N]
> Coverage: [N]% of GDD critical paths

## How to run

[Engine-specific command to run all regression tests]

## Registered Regression Tests

### [System Name]

| Test File | Test Function (if known) | Covers | Added |
|-----------|--------------------------|--------|-------|
| `tests/unit/[system]/[file]_test.[ext]` | `test_[scenario]` | AC-N / BUG-NNNN | [date] |

## Known Gaps

Tests that should exist but don't yet:

| Priority | System | Suggested Path | Covers | Reason Not Yet Written |
|----------|--------|----------------|--------|------------------------|
| HIGH | [system] | `tests/unit/[system]/[path]` | BUG-NNNN | Bug fixed without test |

## Quarantined Tests

Tests that are flaky or disabled (do not run in CI):

| Test File | Function | Reason | Quarantined Since |
|-----------|----------|--------|-------------------|
| (none) | | | |

---

7. 写入输出

在 update 或 audit 模式下，询问：“我可以使用当前的回归测试套件清单写入或更新 tests/regression-suite.md 吗？”

对于 update 模式：追加新条目；绝不移除现有条目 （使用 Edit 定点插入）。 对于 audit 模式：重写完整清单，并更新覆盖率数据。 对于 report 模式：不要写入任何内容。

如果获准写入，完成后：

• 对于每个 HIGH 优先级缺口：“请考虑在下一个迭代前创建缺失的回归测试。 运行 /test-helpers 来搭建测试文件。”
• 如果 Bug 回归缺口 > 0：“这些 Bug 可能在没有回归测试的情况下悄然复发。下一个迭代应包含编写缺失测试的故事。”
• 如果检测到覆盖漂移：“回归测试套件可能已出现漂移。请考虑在下一个迭代节点运行 /regression-suite audit。”

对于没有迭代的 workflow: minimal，请在上述三行中将“下一个迭代”改为“下一个故事”。

判定结果按顺序匹配，命中第一项即停止：

• NOT ASSESSED — 第 1 节在 qa.level: minimal 处停止：“Regression suite not generated at qa.level minimal”。此级别不要求测试；未扫描或写入任何内容。
• NOT ASSESSED — 上述 minimal 停止条件：没有可用于提取关键路径的冒烟测试报告；请指出应使用 /smoke-check 解决。
• NOT ASSESSED — 覆盖率结果为 Coverage: NOT ASSESSED — [reason]（没有 GDD 或没有测试文件）；请说明原因。绝不要在未计算覆盖率的情况下报告 COMPLETE。
• BLOCKED — 处于 update 或 audit 模式，且用户拒绝写入。
• COMPLETE — update / audit：回归测试套件已更新；report：已显示覆盖率报告（report 模式不写入任何内容）。

---

协作协议

适用于 collaborative 模式（默认模式）。 关于 guided 和 autonomous 模式，请参阅 .claude/docs/automation-modes.md——以下规则 说明的是协作模式的要求，并非所有模式通用的行为。

• 未经用户明确批准，绝不从清单中移除现有回归测试——移除刻意编写的测试本身就存在引入回归的风险
• 缺口仅供参考，不会阻止工作——应清楚指出缺口，但不得因此妨碍其他工作继续进行（qa.level: full 除外；此时阶段关卡要求运行回归测试套件）
• 隔离不等于删除——有间歇性故障的测试应隔离（并在清单中注明），但不得移除；应通过 /test-flakiness 修复
• 写入前先询问——创建或更新清单前，始终先确认