---
name: change-impact
description: >-
  在改代码、数据、接口或治理文档前做有证据的影响分析，并在实施后把计划影响与实际 diff 对照；覆盖代码调用、数据/Schema、API 契约、测试、文档、ADR、部署、迁移和回滚。用于跨模块修改、高风险变更、数据库迁移、认证、公共接口、用户问“会影响哪里”“改之前检查一下”或实施后需要反思偏差时。English triggers: change impact analysis, blast radius, pre-change analysis, migration impact, rollback plan, post-implementation alignment.
---

# 变更影响分析

默认只读。先用真实依赖与现有文档证明影响面，再实施；未知项明确标“未验证”。

## 修改前

依次回答：

1. **代码**：入口、直接调用方、下游消费者、生成物和兼容层会受什么影响？
2. **数据**：Schema、迁移、历史数据、序列化、缓存和幂等键是否变化？
3. **接口**：API、消息、文件格式或 CLI 是否改变？消费者和提供者分别是谁？
4. **测试**：哪些成功标准、TEST-ID、契约测试和回归命令应证明变更正确？
5. **文档**：是否影响 MAP、ARCHITECTURE、STATUS、LOG、CONTEXT、ADR、CONTRACT、Spec/Plan、TESTS 或 REGRESSION？
6. **发布**：部署顺序、兼容窗口、数据恢复、回滚命令和不可逆部分是什么？

证据优先取自真实 import/调用、路由、Schema、配置、生成脚本、`git grep`、`git diff` 和可执行测试。不要凭目录名猜依赖。

## 路由规则

- 架构、数据库、认证、部署拓扑或长期技术策略：检查 `context-and-decisions` / ADR。
- 跨端接口：先更新 `contract-first` 管理的唯一契约源，再规划消费者、提供者和联调证据。
- 需求、业务规则、风险或 Bug：让成功标准保留在 Spec/Issue，并用 `test-collaboration` 关联 TEST-ID。
- Module 行为或下游依赖变化：实施后运行 `module-regression`；若权责、状态归属、Interface、依赖方向或核心流转改变，调用 `architecture-docs` 判断必要性并维护实际架构主记录，确保 MAP 能导航；无需创建或证据不足时说明依据与缺口。
- 数据库迁移、破坏性接口、认证和生产发布：必须写回滚条件、恢复步骤、兼容期和不可逆部分；缺任何一项就标为阻塞，不代替人执行回滚。

## 输出

小改动在回复中给出：影响对象、证据、所需验证、文档同步和未知项。只有跨模块、高风险或用户明确要求留档时，才把报告写入 `docs/impacts/`；写文件前先确认，避免制造一次性文档。

## 按事实核对文档

解决“AI 改完功能或接口，用户还得自己找漏改文档，下一轮又被旧说明误导”的问题。候选检索由 Agent 执行并完成判读，向用户交付具体冲突、依据和处理结果，不把原始候选清单当成完成。

变更后的语义审查与阶段同步共用此流程。先通过现有确定性审计，再由当前 Agent 执行；路径映射、文件修改时间、Markdown 已产生 diff 或扫描退出码 0 都不能代替内容核对。

先单独运行 `python3 <插件目录>/scripts/audit-docs.py --root <项目根> --scope full` 并检查退出码；非零就停止候选检索、语义核对及据此进行的文档同步。即使判断是原有问题或误报，也须修复并复跑通过后再继续；超出授权或无法修复时报告阻塞。不用分号或忽略失败的命令串绕过此步骤。已提交审查须对受检快照审计，可复用同一 base/head 的 PR 检查结果。

先自动收集候选，再执行下方判读；输出是线索，不是过期结论：

```bash
# 已提交变更：比较共同祖先与 head，只读提交快照
python3 <插件目录>/scripts/find-doc-impact.py --root <项目根> --base <基线> --head <受检提交>
# 日常维护：比较任务开始时的提交与当前文件，含未提交及非忽略的未跟踪文件
python3 <插件目录>/scripts/find-doc-impact.py --root <项目根> --base <任务起点> --worktree
```

检索合并 `change_rules`、变更路径引用、diff 中的标识符，返回候选路径、行号、原文和命中依据。功能变化补充 `--term '功能名'` 或旧流程术语，重点核对 Spec、使用说明与相关流程；契约变化重点核对机器契约引用、API 说明、调用示例与接入指南。架构、MAP、STATUS、LOG 按实际影响核对，不要求每次全改。

候选包括历史与无关同名内容，须读上下文排除；标识符未变的行为变化、同义表达和外部资料仍需 Agent 补查。无命中不能判无影响；报告跳过文件、不可访问资料及检索范围。退出 0 仅表示检索完成，退出 2 表示执行失败。没有可靠基线时列出缺口并按文档当前声明核对，不伪造变更范围。需求与实现冲突分别报告，不自动改写已确认 Spec。

1. **固定范围和版本。** 记录实际 base/head 提交及其共同祖先，以共同祖先为比较起点，读取该起点与 head 的 diff 和旧／新正文；不要把当前工作区修复当作已提交内容。审查未提交修改时另列暂存／未暂存／未跟踪范围及相关文件哈希。基线或来源缺失时标未验证，不猜旧规则。
2. **提取改变的事实。** 从代码、机器契约、配置及已确认需求中核对旧值、新值和原因，覆盖接口输入输出、流程步骤／条件、职责、依赖和外部副作用。契约删除一个字段并新增另一个字段，只能先记为删除／新增；有确认来源或实现证据才称重命名。内部修复若未改变对外事实，记录依据后结束相应同步检查。
3. **找到主记录与引用。** 从项目地图、契约入口、需求主记录及 `change_rules` 命中项开始，再用 `rg`／`git grep` 查变更对象的路径、旧标识和相关术语，沿链接补读映射外的说明。已提交审查应对 head 快照检索。无链接但描述同一事实的说明也要核对；检索无结果不证明没有遗漏，记录实际检索范围及不可访问对象。
4. **逐条判读候选。** 阅读命中位置的上下文，确认是否属于同一接口／流程、是否仍作为当前操作依据。当前正文与新事实冲突时给出具体位置、旧表述和对照证据，文件本次改过也不能跳过。历史记录、引用和无关同名字段不因关键词命中而要求改写；历史内容仍被当作当前指引时，报告误用它的入口。纯引用且目标有效时说明无需同步正文。
5. **核对重复与证据。** 同一生效规则若有可独立编辑的多份正文，列出主记录与副本，建议其余位置改引用；主源不明先待核实，不自行选一份覆盖。机器契约、实现和历史各自承担职责，不按相同词句数量判重复。测试结果引用原始回执及对应版本／输入哈希，结果缺失或已过期时标未验证，不重抄结果补齐表格。
6. **交付并按变化失效。** 在现有回复、PR 或审查记录中输出下表，绑定范围与版本。相关契约、代码或文档变化后重核受影响项，旧结论不自动沿用。不新建同步台账，不因普通待复核项一律阻断提交；沿用项目已有风险与合并要求。

| 事实变化及依据 | 文档位置与原表述 | 结论与下一步 |
|---|---|---|
| 旧／新事实，来源路径与版本 | 路径、行号／条款、必要短引文；重复项另指主记录 | 已核对：需要更新／无需更新及理由；待复核：候选尚未判读；未验证：缺少何种来源或执行证据 |

先报告需要更新的当前说明，再列无需更新的反例和剩余缺口。没有实际运行文档中的步骤时，不声称已复现失败；未知项不能计入通过。治理成本只记录本轮实际核对、修改的文档及原始回执位置，耗时未测就注明未知，不预设节省比例。

可复跑的接口字段样例及审查验收见 [接口变更场景](examples/interface-change.md)。它只验证这一切片，不代表所有事实类型或业务项目都已覆盖。

## 实施后对照

完成实现后检查：

1. 实际改动是否解决 Spec/Issue 中的原始问题。
2. 实际 diff 是否超出已声明范围；超出项是否获得授权并补充影响分析。
3. 测试和人工证据是否真正覆盖成功标准，而非只证明命令运行过。
4. CONTEXT、ADR、CONTRACT、TESTS、REGRESSION、MAP、ARCHITECTURE、STATUS 和 LOG 是否按实际变化同步。
5. 是否遗留临时代码、兼容逻辑、迁移尾项或后续 Issue。

默认在交付回复中报告对照结论。只有高风险变更或用户要求正式评审时，才保存到 `docs/reviews/`。不要创建通用 `REFLECTION.md`。