# 模块 6：变更证据链与可追溯说明

<div class="mt-6 text-sm">

AI 可以帮助定位和实现，但不能替代研发交付中的说明责任。

一次改动是否值得合入，取决于阅读者能否快速判断：改了什么、为什么改、验证到哪里、还存在哪些边界。

</div>

<div class="grid grid-cols-4 gap-3 mt-8 text-sm">
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">目标</div>
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">范围</div>
<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">证据</div>
<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">边界</div>
</div>

<!--
逐字稿：这一模块讨论技术交付为什么必须可追溯。一次改动能否被准确理解，取决于读者能否回答四个问题：目标是什么，范围到哪里，哪些结果已有证据，哪些边界仍未确认。AI 可以协助整理这些信息，但不能替代对每项结论的说明责任。

这一模块强调的是技术交付的可追溯性。四项信息分别回答：解决什么问题、修改到哪里、哪些行为已被证实、哪些路径仍不能下结论。
-->

---

# PR 模板不等于证据链

<div class="mt-5 text-xs">

| PR 模板解决什么 | 证据链解决什么 |
|---|---|
| 让评审者快速阅读改动说明 | 让每条结论回到可核对的事实 |
| 组织目标、实现、测试和风险 | 关联需求、diff、测试、CI、日志与人工观察 |
| 呈现本次交付 | 支撑结论强度与后续排查 |
| 可以由 AI 协助起草 | 必须由真实记录持续校验 |

</div>

<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
PR 是阅读入口；证据链是结论能够被复核的依据。
</div>

<!--
逐字稿：PR 模板解决的是如何让评审者快速阅读，证据链解决的是每句话凭什么成立。模板组织目标、实现、测试和风险，证据链把它们关联回需求、规则、diff、测试、CI、日志和实际观察。两者互相配合，但不能用写好了 PR 模板来代替真实证据。

模块 2 已讲 PR 的写法。本模块继续追问其中每个结论凭什么成立，因此不重复讲模板字段。
-->

---

# 一条变更证据链包含什么？

<div class="mt-5 text-xs">

| 证据节点 | 能支持的判断 | 不能替代的判断 |
|---|---|---|
| 需求与规则 | 改动目标、约束和非目标 | 实现已正确运行 |
| diff 与代码阅读 | 修改范围、调用关系与关键分支 | 线上或全链路行为 |
| 自动化测试 | 对应方法、接口或场景的行为 | 未覆盖路径的行为 |
| CI 结果与日志 | 构建、检查和已运行用例的结果 | 所有环境和业务风险 |
| API、浏览器或人工观察 | 特定环境下的真实交互结果 | 未观察到的条件组合 |
| 已知边界 | 仍需确认的依赖与缺口 | 已完成验证的替代结论 |

</div>

<!--
逐字稿：证据链不是要求每次都做完所有验证，而是要说明现有证据能支持到哪里。需求和规则确定目标，diff 支持范围判断，自动化测试和 CI 支持已运行场景，实际观察补充具体环境结果。每一类证据都有边界，不能替代尚未覆盖的结论。

证据链不是要求所有节点都必须存在，而是明确已有何种证据、它能支持到哪里、还缺少什么。不同场景可采用不同组合。
-->

---

# 用证据地图连接结论

<div class="mt-7 text-sm text-center">

<div class="inline-block px-4 py-2 rounded-lg bg-blue-500/10 border border-blue-500/30">需求与规则</div>
<span class="mx-2 op-50">-&gt;</span>
<div class="inline-block px-4 py-2 rounded-lg bg-emerald-500/10 border border-emerald-500/30">diff 与关键代码</div>
<span class="mx-2 op-50">-&gt;</span>
<div class="inline-block px-4 py-2 rounded-lg bg-amber-500/10 border border-amber-500/30">测试与 CI</div>
<span class="mx-2 op-50">-&gt;</span>
<div class="inline-block px-4 py-2 rounded-lg bg-purple-500/10 border border-purple-500/30">技术结论</div>

</div>

<div class="mt-9 grid grid-cols-3 gap-3 text-sm">
<div class="p-3 rounded-xl bg-blue-500/10 border border-blue-500/30">每个结论都能回指来源</div>
<div class="p-3 rounded-xl bg-amber-500/10 border border-amber-500/30">每项证据都有适用边界</div>
<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">缺口不能被推断补全</div>
</div>

<!--
逐字稿：可以把证据地图理解为每个重要结论的来源图。向左能回到需求、规则和关键代码，向右能回到测试、CI 或实际观察。只要某个结论无法连接到这些材料，它就应当被降级为假设或待确认项。

证据地图不是额外流程图，而是一种审查视角：任何重要结论都应能向左回到需求、规则和实现，向右回到验证结果。
-->

---

# 技术结论要和证据强度匹配

<div class="mt-5 text-xs">

| 信息类别 | 可以形成的结论 | 常见误区 |
|---|---|---|
| 代码阅读 | 已定位到调用入口、状态写入点或权限判断 | 把源码推断当作线上运行结论 |
| 实际变更 | 本次修改了哪些文件、条件和分支 | 用“优化”“完善”等词掩盖改动范围 |
| 自动化验证 | 已覆盖某个方法、接口或用例 | 用局部测试替代全链路验证 |
| 待确认事项 | 业务规则、外部调用、环境差异仍需核对 | 用“应该没有影响”替代事实 |

</div>

<div class="mt-6 p-3 rounded-xl bg-amber-500/10 border border-amber-500/30 text-sm">
证据能支持多大的结论，就只写多大的结论。
</div>

<!--
逐字稿：技术结论的强度必须匹配证据强度。代码阅读只能说明调用入口或状态写入位置，定向测试只能说明被覆盖的方法或场景，不能外推为线上或全链路结论。没有事实支持时，写清待确认项比写一句“应该没有影响”更专业。

源码阅读可以支持调用关系判断，不能替代线上行为；一个定向单测能支持对应方法的行为，不能代替浏览器、数据库、审计等整条链路的结论。
-->

---

# 证据丢失时，结论也会失效

<div class="mt-5 text-xs">

| 缺失的证据 | 常见后果 | 正确处理 |
|---|---|---|
| 原始 CI 日志 | 无法判断失败来自代码还是环境 | 保留失败阶段、原始错误与关联链接 |
| 已执行命令与结果 | “已测试”无法复核 | 记录命令、环境和结果摘要 |
| 需求或规则依据 | 不清楚为什么改、是否越界 | 关联明确的约束与非目标 |
| diff 与关键位置 | 无法核对实际影响范围 | 说明模块、入口和关键条件 |
| 未覆盖边界 | 被误解为全量验证 | 明确写出待确认项和原因 |

</div>

<div class="mt-6 p-3 rounded-xl bg-red-500/10 border border-red-500/30 text-sm">
没有证据的“已完成”，在工程上等同于不可审查的结论。
</div>

<!--
逐字稿：证据一旦丢失，结论就失去复核基础。没有原始 CI 日志，无法区分代码和环境问题；没有执行命令和结果，“已测试”就无法追溯；没有未覆盖边界，局部验证很容易被误解为全量验证。我们不需要保存所有过程，但需要保存支撑关键判断的最小事实集。

这页强调记录的最低粒度：不需要保存完整聊天过程，但应保存足以复核关键结论的事实。
-->

---

# 一份可审查的改动说明

<div class="mt-5 text-xs">

```md
## 改动目标
解决什么业务问题或风险，并关联需求或规则依据。

## 实现范围
涉及的模块、入口和关键判断；明确未修改的相邻范围。

## 验证证据
已执行的测试、检查项、CI 或实际观察，以及对应结果。

## 已知边界
尚未覆盖的场景、依赖的前提和需要业务确认的事项。
```

</div>

<div class="mt-6 grid grid-cols-2 gap-3 text-sm">
<div class="p-3 rounded-xl bg-red-500/10 border border-red-500/30">避免：功能已完成、已充分测试</div>
<div class="p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30">写清：已覆盖范围与未覆盖范围</div>
</div>

<!--
逐字稿：一份可审查的改动说明至少包含目标、实现范围、验证证据和已知边界。它不靠“已完成”或“已充分测试”这种笼统表述制造确定感，而是明确写出已覆盖和未覆盖的场景。这个结构既可以用于 PR，也可以用于缺陷修复和后续排查。

这四段内容可以写进 PR、变更记录或缺陷修复说明。重点不是固定格式，而是每一段都能被代码、测试记录或明确的待确认项支撑。
-->

---

# 让 AI 产出成为工程知识

<div class="mt-5 text-xs">

| 只保留对话 | 留下可追溯说明 |
|---|---|
| 结论散落在窗口和临时文件里 | 关键结论随代码或 PR 一起保存 |
| 难以判断 AI 建议是否被采纳 | 清楚说明人工选择了什么、舍弃了什么 |
| 后续排查需要重新理解上下文 | 可直接定位目标、范围、证据和边界 |
| 相同问题容易重复分析 | 可复用判断方式，但重新核对项目事实 |

</div>

<div class="mt-6 p-3 rounded-xl bg-emerald-500/10 border border-emerald-500/30 text-sm">
AI 的价值不止是更快产出代码，也包括留下经得起复核的技术结论。
</div>

<!--
逐字稿：只有对话记录并不会自动形成工程知识，因为结论会散落在窗口和临时文件中。真正可复用的是能够和代码、PR、测试与变更记录对应的技术结论，以及人工采纳或舍弃建议的理由。这样下一次遇到相似问题时，复用的是可靠判断结构，而不是上一段对话的记忆。

对话记录是过程材料，不能天然成为工程知识；能够与代码、PR、测试和变更记录对应的结论，才可以被后续维护者可靠使用。
-->