---
name: qshanx-module-regression
description: "大项目模块间联动回归——一份 REGRESSION.md 回归台账登记\"每个模块的下游消费者 + 可执行的回归验收命令\"，跨模块行为或依赖变化后按受影响范围回归，防\"改一个模块悄悄弄坏其他模块\"。判决靠退出码，不靠 AI 看着没问题。中文触发：模块回归、回归台账、回归审计、改A坏B、模块联动检查、影响面检查、模块牵连、下游验证、大项目改动检查。English triggers: module regression, regression ledger, impact regression audit, downstream verification."
license: "MIT"
metadata:
  decimalai-skill-id: "39044c2a-3b76-4b85-abe8-b43adb962498"
  decimalai-version-id: "779e2e62-b718-420c-8be7-611252268f19"
  decimalai-version: "1"
  decimalai-body-sha256: "2f7e0e2c69da3085d81ab47e05342fe29a93b85cad1c1748899343d82fa895ab"
  decimalai-name: "qshanx/module-regression"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "testing"
  decimalai-source: "https://app.decimal.ai/s/qshanx-module-regression@1/SKILL.md"
---
# 模块回归台账（module-regression）

## 治什么病

大项目里模块互相引用。改模块 A 时，AI 和人都只盯着 A 本身对不对，**下游的 B、C 被悄悄改坏了没人知道**——直到几天后 B 的产出数字对不上才发现。这是 AI 协作大项目里最高发、最晚爆雷的事故。

解法：一份**回归台账**（`REGRESSION.md`）+ 一个**照单审计**动作——跨模块行为或依赖变化后验证实际受影响的下游；局部实现修复只跑相关检查，不自动启动台账审计。

## 台账三要素（每个模块一段，缺一不可）

```markdown
## 模块 03-店铺数据清洗
下游（谁依赖我）：05-汇总、07-成品导出        <!-- 脚本从 import 生成，勿手改 -->
回归验收命令：pytest tests/test_03.py && python scripts/对账.py --module 03
联动规则：改我的对外行为 → 必须跑 05、07 的验收命令；只改内部实现且本模块验收绿 → 可豁免下游
```

1. **下游消费者**——**脚本从 import/调用关系生成，禁止手写**。手写的依赖清单必然腐烂（变动最频繁、没人记得同步），生成的永远反映真实代码。
2. **回归验收命令**——**台账的核心资产**：每个模块一条"怎么证明我没坏"的**可执行命令**（pytest / 对账脚本 / golden sample diff）。没有这行，审计退化成"AI 看一眼说没问题"（把裁判权交给被告）；有这行，判决就是退出码。
3. **联动规则**——改我 → 谁必须被验证；什么情况可豁免。

## 与 TESTS.md 的连接

`REGRESSION.md` 不再维护业务规则和测试缺口。已有 TEST-ID 时引用它；否则直接使用现有测试路径与命令，不为本轮验证补建 TESTS 或编号。例如：

```markdown
关联测试点：TEST-ORDER-001、TEST-REFUND-003
```

- 哪些规则必须被保护、测试处于什么状态、证据在哪：由 `test-collaboration` skill 和 `TESTS.md` 管理。
- 改了某模块后要重跑哪些模块、执行哪条命令：由本 skill 和 `REGRESSION.md` 管理。
- `/regression-audit` 只按回归台账执行命令和报告退出码，不重复审查测试必要性。

## 台账纪律

- **验收命令优先"对账型"而非"断言型"**：锚外部事实（golden sample / 上游合计 / 财务勾稽），"测试全过"能被钻（改松断言、注水 mock），"和基准差异 < 0.01"钻不了。
- **下游列表只由重扫刷新**：加了新 import → 重跑生成脚本，不许手补一行了事。
- 台账放项目根或 `docs/`，从 `CLAUDE.md` 挂指路牌（否则成孤儿文档没人读必烂）。

## 审计流程（跨模块影响或明确要求审计时）

Claude Code 可通过 `/regression-audit` 调用 `regression-auditor`；Codex / ChatGPT 直接调用 `$module-regression`，由当前 agent 承担同一“只跑、只报、不修”职责。宿主不同不改变退出码终审和红着不交付的边界。

1. **列改动**：`git status -s` / `git diff --name-only`，对照台账定位改的是哪个（些）模块。
2. **查联动**：复用 `change-impact` 的影响清单，并核对实际 diff、台账及当前调用关系；清单不是已验证结论，新增消费者不能漏验。
3. **跑回归**：本次相关的本模块检查和实际受影响下游的验收命令，记录退出码；不按目录或台账存在就全跑。
4. **核对结果**：全绿只证明已登记、已执行范围通过；列出未覆盖或未运行项，交付仍须满足原任务成功标准。任何一条红先定位原因；本次引入的问题修复后从第 3 步重跑，未解决的失败不计入通过。
   - **红了怎么归因（控制变量，不靠猜）**：基线全绿 + 本次只改了 A + B 红 → 优先检查 A，并核对环境、依赖和输入是否一致，不能仅凭一次失败认定因果，顺着 B 验收命令的输出（对账差异行 / assert 信息）反查 A 碰到的交接字段。若 B 在改动**前**就红 = B 的旧债，不赖本次改动，标台账缺口另行处理。**改动批次越小归因越准**——一次改 5 个模块再跑，红了就说不清谁干的。台账应记「上次全绿的 commit」，保证归因有干净基线。
5. **出审计摘要**：改了哪个模块 / 跑了谁的回归 / 各自结果（命令 + 关键输出行）/ 豁免了谁及理由。

## 铁律（四条，违反任何一条审计无效）

1. **判决 = 退出码**，不是"看着没问题"。缺少可执行验收命令时如实报告未验证；可直接复用已有测试，不以补写台账为运行前提。
2. **审计员只报不修**：跑回归、报红绿；红了怎么修是改动者（主会话/人）的事——裁判不能下场踢球。
3. **不以失败结果背书**：本次引入的下游失败必须修复；基线旧失败或环境阻塞说明证据和边界，按项目已有交付门禁处理，不宣称全量通过。
4. **保护实际行为**：Bug 修复按风险复用或补充相关回归测试、类型／schema 检查或人工验证，并在回复说明结果。仅当测试入口、使用方法或重要覆盖范围变化时维护 TESTS；不强制新增 TEST-ID、LOG 或回归台账。

## 与相邻方法的边界（别混）

| 方法 | 管什么 | 文档 | 验证时机 |
|---|---|---|---|
| contract-first | 跨端接口（前后端 / 服务间字段契约） | `CONTRACT.md` | 集成对账 |
| test-collaboration | 测试资产、必要测试点、Bug 回归保护和证据 | `TESTS.md` | 测试资产或重要覆盖范围变化时 |
| module-regression | 同一代码库内模块间行为回归 | `REGRESSION.md`（下游 + 验收命令 + TEST-ID 引用） | 每次相关改动后 |

## 渐进采用

- 模块 < 3 个、或模块间零引用 → 不需要，别过度治理。
- **预警信号**：反复发生“改 A 坏 B”、现有测试入口无法支撑下游验证时，再判断是否需要台账；单次事故不自动建档。
- 已有测试/对账脚本的项目：台账 = 把现成验收命令按模块归位登记，半天出第一版。


## 初始化与参数

- 默认按本次实际 diff 定位模块；指定模块时检查该模块及其受影响下游。没有台账时，复用 `change-impact` 核实的调用关系及项目已有测试命令完成本轮验证，不强制新建台账；缺少依赖证据或可执行命令时报告未验证，不编造绿色结果。
- init 模式可以生成 REGRESSION 台账文档，不修改业务实现。先从真实 import/require/调用关系生成下游，记录生成命令；不把手写列表标成脚本生成。
- 从现有测试和对账脚本寻找验收命令候选，标待确认；没有命令的模块登记缺口，不能编造绿色结果。
- 使用 `templates/REGRESSION.example.md`，从项目 CLAUDE 挂入口。报告模块、命令、退出码、结论和未跑项；init 中新增的命令经确认后再审计；本轮复用项目既有命令不重复请求确认。