模块回归台账（module-regression）

治什么病

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

解法：一份回归台账（REGRESSION.md）+ 一个照单审计动作——改完任何模块，按台账把受牵连的下游全部验一遍，全绿才算改完。

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

## 模块 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：

关联测试点：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 挂入口。报告模块、命令、退出码、结论和未跑项；用户确认真实验收命令后再审计。