---
name: module-regression
description: >-
  大项目模块间联动回归——一份 REGRESSION.md 回归台账登记"每个模块的下游消费者 + 可执行的回归验收命令"，每次改动后照台账跑回归审计，防"改一个模块悄悄弄坏其他模块"。判决靠退出码，不靠 AI 看着没问题。中文触发：模块回归、回归台账、回归审计、改A坏B、模块联动检查、影响面检查、模块牵连、下游验证、大项目改动检查。English triggers: module regression, regression ledger, impact regression audit, downstream verification.
metadata:
  origin: 小磊 · 模块间回归审计
---

# 模块回归台账（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` 不再维护业务规则和测试缺口。它只引用 `TESTS.md` 中稳定的 TEST-ID：

```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. **查联动**：台账告诉你下游是谁。
3. **跑回归**：本模块验收命令 + 所有下游模块的验收命令，逐个跑，记录每条的退出码。
4. **退出码终审**：全绿 = 没牵连，可交付；任何一条红 = 改动波及下游，**修完从第 3 步重跑**，不许带红交付。
   - **红了怎么归因（控制变量，不靠猜）**：基线全绿 + 本次只改了 A + B 红 → 错误必然由 A 引入，顺着 B 验收命令的输出（对账差异行 / assert 信息）反查 A 碰到的交接字段。若 B 在改动**前**就红 = B 的旧债，不赖本次改动，标台账缺口另行处理。**改动批次越小归因越准**——一次改 5 个模块再跑，红了就说不清谁干的。台账应记「上次全绿的 commit」，保证归因有干净基线。
5. **出审计摘要**：改了哪个模块 / 跑了谁的回归 / 各自结果（命令 + 关键输出行）/ 豁免了谁及理由。

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

1. **判决 = 退出码**，不是"看着没问题"。没有可执行验收命令的模块 = 台账缺口，先补命令再审计。
2. **审计员只报不修**：跑回归、报红绿；红了怎么修是改动者（主会话/人）的事——裁判不能下场踢球。
3. **红着不准交付**：下游红 = 本次改动没完成，没有"下游的问题以后再说"。
4. **坑必下沉**：每修一个 bug，必须在 `TESTS.md` 新增或关联 TEST-ID，写清回归测试 / lint / schema 校验落在哪；确实只能人工验收时写明理由、步骤和证据。只改代码不登记保护证据 = 没修完。

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

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

## 渐进采用

- 模块 < 3 个、或模块间零引用 → 不需要，别过度治理。
- **预警信号**：第一次发生"改 A 坏了 B"的事故 → 当天建台账。
- 已有测试/对账脚本的项目：台账 = 把现成验收命令按模块归位登记，半天出第一版。


## 初始化与参数

- 默认按 Git 工作区改动定位模块；指定模块时只检查该模块及其下游。台账不存在且没有 init 请求时报告缺失，不猜依赖。
- init 模式可以生成 REGRESSION 台账文档，不修改业务实现。先从真实 import/require/调用关系生成下游，记录生成命令；不把手写列表标成脚本生成。
- 从现有测试和对账脚本寻找验收命令候选，标待确认；没有命令的模块登记缺口，不能编造绿色结果。
- 使用 `templates/REGRESSION.example.md`，从项目 CLAUDE 挂入口。报告模块、命令、退出码、结论和未跑项；用户确认真实验收命令后再审计。