如何用 AI 起草拉取请求说明，让审阅者看清风险与测试证据

要用 AI 起草拉取请求说明，先冻结 base 和 head 版本，查看真实 diff，并在让 AI 写正文前准备已核验的输入表。要求草稿分开写问题、范围、非目标、行为、测试、风险、发布和回滚。作者对每句话负责；新 commit 改变证据时必须更新说明。

本流程改善的是审阅沟通，不能代替代码审阅。如何使用 AI介绍安全的提示方式，用 AI 辅助编码和复核 AI 生成代码涉及实现与验证。

关键要点

• 总结之前，记录确切的 base 和 head commit。
• 查看有效 diff，包括生成文件、配置、迁移和测试变更。
• 给 AI 已核验的事实和真实命令输出，而不是假设。
• 不要声称未运行的测试已通过，也不要把推断变成安全结论。
• 让非目标、风险、部署顺序和回滚限制清晰可见。
• 每次有实质性 commit 后，重新核对说明。

审阅者需要做出什么决定？

拉取请求说明应帮审阅者回答三个问题：为什么需要这项变更？该检查哪些行为和风险？有什么证据支持合并？逐文件复述很少能回答。

GitHub 支持模板、必需审阅人、所有权规则、草稿拉取请求等方式统一贡献与审阅。［1］ 字段承载与决策相关的证据时，统一才有用；在每栏粘贴同样含糊的句子毫无意义。

起草前先写验收标准：确定用户、运维或开发者层面的结果、预期行为、重要的不变行为和失败条件。标准仍有争议时，说明里应如实写出，而非呈现成已定方案。

GitHub 的审阅指南强调提供背景、清楚说明变更做了什么，让审阅者集中精力。［2］ 把审阅者的注意力当作有限资源：先写语义和风险，再指向相关代码。

冻结 base、head 和工作树

记录代码库、目标分支或 base commit、head commit，以及说明只涵盖已提交变更，还是也含已复核的工作树补丁。即使托管界面显示分支名，证据笔记也要用不可变标识。

确认比较方向。从 base 到 head 的 diff，回答这项提议相对目标引入了什么。与错误的 base 比较，可能混入无关工作或遗漏必要背景。

检查常规源码审阅易漏的内容：生成文件、子模块、锁文件、迁移、配置、schema 和资源文件。堆叠式 PR 要写明依赖关系及哪些 commit 属于这一层。

绝不能把秘密、令牌、私钥、生产数据、敏感日志、禁发期内的漏洞细节或无关的客户信息粘贴进模型。建立一个有边界的证据包，只放写说明所需的材料。

提示 AI 之前要读懂哪些真实变更？

阅读 diff，并通过入口点、调用方、测试和文档追踪行为。重命名函数可能只是机械改动；一行默认值却可能改变每个请求。文件数和 diff 大小都不可靠。

检查代码是否实现了所述问题、测试是否真正覆盖该行为。像审查新增代码一样仔细审查删除的代码。复核配置默认值和发布路径，因为休眠代码可能要等开关或部署步骤改变后才影响用户。

API 或持久化数据要记下兼容性、必需的迁移顺序、重试行为和新旧版本混跑情况。用户界面则描述行为，只在 PR 确实改动界面时附真实界面证据。本文不需要截图，也绝不把虚构界面当证据。

如果凭现有证据无法判断行为，就在输入表中写“未知”。不要让 AI 用一个貌似合理的故事填补空白。

建立核验输入表

生成段落之前，先使用结构化的来源：

字段	已核验输入	证据
问题	[观察到的问题和受影响用户]	[Issue、复现、需求]
范围	[包含的行为和组件]	[diff 路径和验收标准]
非目标	[明确排除项]	[设计决定]
行为变化	[之前与之后]	[测试、契约、人工检查]
涉及组件	[服务、包、数据、UI]	[diff 清单]
测试及真实输出	[命令、环境、结果]	[保存的运行记录]
风险	[失败模式和影响范围]	[分析或测试]
迁移	[顺序、兼容性、验证]	[迁移计划]
发布	[开关、阶段、监控、负责人]	[发布计划]
回滚	[安全恢复方式和限制]	[已测试步骤]
文档	[已更新或无需更新及原因]	[路径]
关联 Issue	[稳定 ID]	[追踪系统]

证据要精确：“单元测试通过”应写成“command 在 head [commit]、[environment] 中运行完成；[count] 个测试通过；[已知排除项]”。输出太长时，存入获批的产物，只引用相关摘要。

非目标保护审阅边界，如“不迁移历史记录”“不改变公共 schema”“不在生产环境启用该功能”。逐条核实；与 diff 矛盾的非目标本身就是说明的缺陷。

风险应写明失败模式、触发条件、影响、缓解、检测方式和负责人。“低风险”是结论，不是证据。仍有不确定时写出来，并把审阅者引向相关代码或测试。

怎样按结构用 AI 起草拉取请求说明？

提供已核验的输入表、选定的 diff 摘录或摘要、代码库术语和 PR 模板。把任务限定为组织和措辞。

一条可复用的提示词是：

只使用所提供的输入表和证据起草拉取请求说明。保留确切的 base/head 标识、范围、非目标、行为、命令、输出、风险、迁移、发布、回滚、文档和 Issue ID。不要声称未运行的测试已通过。不要根据文件名或 diff 大小推断安全、性能、兼容性、部署或用户影响。缺少证据时标为 Unknown，并向审阅者提问。不要包含秘密、敏感日志或未公开的漏洞细节。

要求草稿附一份主张台账：

声明 ID	草稿陈述	证据	状态	审阅重点
PR-01	[有边界的陈述]	T-02、D-04	已核验	[路径或行为]

润色前先复核台账，删除证据不足以支持其全部范围的陈述。一个错误路径的测试不能证明整体可靠；笔记本上跑的基准测试也不能证明生产环境延迟。

使用面向审阅者的结构

实用的说明结构是：

1. 问题： 观察到的行为、受影响的对象和决策背景。
2. 方案与范围： 语义层面的做法和包含的组件。
3. 非目标： 刻意的排除项和后续工作的边界。
4. 行为变化： 之前、之后、条件和兼容性。
5. 验证： 真实的命令、环境、输出和人工检查。
6. 风险与安全： 失败模式、信任边界、缓解措施和未知项。
7. 迁移、发布与回滚： 顺序、负责人、监控和限制。
8. 文档与相关工作： 更新的页面、Issue 和依赖的 PR。

逐文件细节只放在有助导航处。把审阅者引向最重要的路径或 commit，并说明为何重要。别把破坏性变更埋在冗长的实现过程叙述里。

Google 的工程实践指南认为，小而自成一体的变更更易审阅，也更不易引入缺陷。［3］ 说明需要讲好几个不相关的故事时，考虑拆分变更。AI 能改善组织，却无法让杂乱的范围变得易于验证。

如何如实报告测试？

区分“已运行且通过”“已运行但失败”“未运行”和“不适用”，写明 head 版本和环境。命令被中断、结果不稳定、用了 mock 或无法访问外部依赖时，说明这一边界。

不要声称未运行的测试已通过。行为改变后，不要不重跑相关检查就照搬早先 commit 的绿色结果。生成的说明可能用自信的过去时措辞，要把每句验证描述与保存的输出对照。

说明某项重要测试为什么没运行，以及还有什么证据。“未运行，因为本机缺少所需平台；必需的 CI 任务是 X”比直接略过缺口有用得多。本地测试、CI、预发和生产观察是不同层次的证据。

AI 辅助生成的测试也需要常规审阅。AI 生成测试流程可以帮助提出用例，但只有针对冻结的 head 执行并做语义检查，才能形成有用的证据。

描述风险而不虚构保证

找出 diff 影响的信任边界、授权变更、敏感数据流、外部调用、后台任务、重试和状态转换，既说明改了什么，也说明保留了什么。

不要只因为没改安全相关文件，就写“无安全影响”。反过来，也不要在没有验证证据时声称存在漏洞或给出严重程度。写明已复核的边界：“认证代码未改；本变更修改的是认证之后的格式化”，这样更窄，也可以检查。

NIST 的生成式 AI 风险概况涉及虚构、隐私、信息完整性和人工监督。［4］ 对 PR 说明而言，相应的控制是：最少输入、脱敏、不可变的版本 ID、主张与证据的映射，以及有人负责的审阅。

按代码库的披露流程处理未公开的漏洞信息。公开的 PR 说明可能只需一句有限的陈述，或一个仅授权审阅者能访问的链接。绝不能让 AI 决定什么可以披露。

发布和回滚该怎样如实说明？

如果变更在合并后立即生效，就直说。如果它依赖功能开关、配置、迁移、包发布或多个服务按顺序协调，写明确切的前提和负责人。

用可观察的信号和决策阈值定义监控。“密切监控”不是计划；写明检查哪个指标、日志、告警或用户反馈、检查多久，以及谁有权叫停发布。

回滚须考虑数据和兼容性。回退代码未必能撤销迁移、外部副作用或已发出的事件。回滚不安全时，写明前向恢复、隔离或关闭开关的办法，而非编造简单的撤销。

不要在合并前的说明里声称已在生产环境验证。把部署后的检查列为计划中的验收步骤，只有在正确的环境中实际完成后，才更新记录。

对照 diff 复核草稿

AI 起草之后，把说明放在确切的 diff 旁边阅读。对每句话，判断它是事实、推断、计划还是未知。事实需要证据，计划需要负责人，未知需要解决途径。

执行以下检查清单：

• base 和 head 标识是最新的；
• 问题和验收标准与 Issue 及实现一致；
• 范围包含了每个与行为相关的文件；
• 非目标没有被代码或配置推翻；
• 前后行为已经演示；
• 测试引用了真实的命令和实际输出；
• 风险、迁移、发布和回滚都有边界和负责人；
• 文档状态准确；
• 没有秘密和敏感细节；
• 审阅者的问题保持可见，而不是被猜测抹掉。

作者对说明负责（the author owns it）。审阅者可以质疑，但 AI 无法为遗漏、证据质量或代码库政策承担责任。

新提交后要更新哪些内容？

PR 说明与特定版本绑定。有新 commit 时，比较新旧 head，找出哪些主张变了，并重跑受影响的测试。在再次请求审阅之前，更新范围、风险和发布部分。

不要盲目重新生成而丢失审阅背景。保留仍有效的解释，标出实质变化，并回复已解决的问题。范围大幅扩大时，考虑另开 PR，而非把原叙述越拉越长。

合并前，最后做一次说明与 head 的核对。部署之后，除非代码库明确用 PR 记录这类回读，否则把生产验证放进相应的发布或运维记录中。

常见问题

AI 可以直接读 diff 写完整说明吗？

它可以根据有边界的 diff 起草，但作者必须追踪行为、提供真实的测试证据，并复核每一条主张。单看 diff 文本，可能看不出运行时或部署背景。

是否列出所有文件？

不必。先解释行为和风险，再指出有助于审阅的文件。自动生成的文件清单不能代替语义层面的范围说明。

未运行的测试怎么写？

标为“未运行”，说明原因，并指出所需的环境或后续步骤。绝不能用早先版本或不同平台的结果暗示已经通过。

PR 非目标应该写什么？

列出人们可能合理期待、但这项变更刻意没有满足的内容，并核实 diff 确实守住了这些边界。

AI 能评估 PR 安全风险吗？

它可以整理所提供的证据和问题，但不应编造安全结论、严重程度或披露决定。

PR 说明需要截图吗？

只有当变更影响可视界面、且真实证据有助于审阅时才需要。使用来自正确版本和环境的真实截图，并去除敏感数据。

有迁移但不能回滚怎么办？

清楚写明这一限制，并记录已批准的恢复或前向修复途径。不要承诺回退代码就能撤销数据变更。

何时必须更新说明？

任何改变行为、证据、测试、风险、迁移、发布或范围的 commit 之后都要更新，并在合并候选版本上做最后一次核对。

来源

1. GitHub Docs, Managing and standardizing pull requests — https://docs.github.com/en/pull-requests/reference/managing-and-standardizing-pull-requests
2. GitHub Docs, Helping others review your changes — https://docs.github.com/en/pull-requests/concepts/helping-others-review-your-changes
3. Google Engineering Practices, Small CLs — https://google.github.io/eng-practices/review/developer/small-cls.html
4. National Institute of Standards and Technology, Artificial Intelligence Risk Management Framework: Generative Artificial Intelligence Profile — https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence

Sources checked 2026 年 8 月 30 日。