给AI生成的代码变更补上审查说明

AI 写完代码，往往也知道为什么这样改，但 reviewer 打开 PR 时，看到的只剩 diff。作者做的 DiffNotes，就是把这些决策理由贴回改动位置，让人少花一点时间反推上下文。

它的思路很直接：让 agent 为自己的 PR 补说明，却不把说明塞进 GitHub 评论区。对经常审核 AI 代码的团队，这个方向值得看；不过，解释写得顺，不代表代码就可靠。

为什么代码能看懂，PR 还是难审核

作者描述了一个场景：打开 Files changed，面对分布在 12 个文件里的 400 行改动，代码通常没什么明显问题，但每个代码块为什么出现，还得重新推理。

这些理由，agent 刚写代码时其实掌握过。等到人工审核，决策过程却没有跟着 diff 一起交付。

作者试过让 agent 发 PR 评论，但遇到了三个问题：评论会通知整个团队，机器说明混进人工讨论，而且一直留在 PR 中。

DiffNotes 因此增加了一层独立的审核说明：每个改动块旁边附上一段简短解释，回答「为什么这样改」，避免复述代码做了什么。

有价值的说明应该补充决策依据，而不是把代码翻译成自然语言。

审核需要的，不只有逐行解释

DiffNotes 在 diff 上方放了一张摘要卡，集中展示 PR 做了什么、部署步骤，以及哪些位置需要重点检查。

当 PR 准备好，开发者向 agent 输入 annotate this PR with diffnotes，agent 会读取自己的 diff，并上传几类内容：

• 部署卡，记录 migrations、flags 和 rollback。
• 风险列表，指出最需要仔细检查的位置。
• 每个改动块的说明，解释修改理由。
• UI 变化对应的截图或小型 demo。

说明还可以附带 Markdown 报告、CSV，以及在沙箱中运行的小型 HTML demo。审核者能查看前后对比、移动端与桌面端截图，也能把 demo 展开到手机、平板或桌面宽度。

仓库可以在 base branch 放置 .diffnotes.yml，写入「每个 migration 都需要部署说明」之类的规则。agent 会先读取规则，再生成说明。规则放在基准分支，提供了一个共同的审核要求来源；原文没有展示规则的完整语法，也没说明如何强制校验。

接入分三步，说明存在哪里也要看清

作者称配置约需 5 分钟，涉及服务端、开发者机器上的 Agent Skill，以及审核者使用的 Chrome 扩展。

服务端可使用免费托管服务，也能自行运行容器：

docker run -d -p 3000:3000 -v diffnotes:/data \
  -e ADMIN_EMAIL=you@company.com -e PUBLIC_URL=https://reviews.example.com \
  ghcr.io/igorkasyanchuk/diffnotes

注意 -v diffnotes:/data 负责挂载数据目录，PUBLIC_URL 则要替换成实际访问地址。

开发者通过欢迎页提供的命令安装 Agent Skill，页面会预填 token：

curl -fsSL https://diffnotes.dev/install.sh | DIFFNOTES_SETUP_TOKEN=dn_… sh

注意这里的 dn_… 是 token 占位写法。作者称 Claude Code、Codex、Cursor 等支持 skills 的 agent 可以识别它。

使用 MCP 的 agent 也有接入方式：claude mcp add --transport http diffnotes https://diffnotes.dev/mcp --header "Authorization: Bearer $DIFFNOTES_TOKEN"。

审核者安装扩展、填写服务地址并登录后，就能在 Files changed 中看到贴近代码行的说明，还能通过浮动栏查看说明数量或统一隐藏。

这些内容不会发布到 GitHub。作者给出的理由是减少通知、保留人工讨论空间，以及让说明到期失效。说明存放在所选服务端；作者称只有仓库所属账户的成员可读，但没有展开权限实现和过期策略。

项目采用 MIT 许可证，结构是一个容器、SQLite、两个运行时依赖。它看起来便于部署，但这些信息还不足以证明团队使用时的维护成本。

我的判断

我认同把「决策说明」作为 AI 代码的交付物。尤其是部署步骤、风险位置和 UI 证据，比一段泛泛的 PR 描述更容易辅助审核。

但原文没有给出审核耗时、缺陷发现率或团队对照数据。「能让审核更快」目前仍是作者的经验判断。

另一个前提也要打问号：agent 在 PR 完成后重新读 diff，生成的理由未必就是当时的真实决策过程，也可能是事后组织出的合理解释。说明可以帮助定位问题，不能充当正确性的证明。

与 PR 描述、人工评论相比，DiffNotes 的优势是位置更贴近改动、附件展示更丰富；代价则是多了服务、token 和浏览器扩展。改动很小的团队，先把 PR 描述写清楚，也许已经够用。

能拿来做什么

• 审核 AI 生成的前端改动时，可以要求同时交付关键交互说明和前后截图，让 reviewer 能对照检查实现。
• 涉及 migration 或功能开关的 PR，可以统一要求补充部署顺序与回滚步骤，并核对这些说明是否符合实际代码。
• 先挑一个仓库试用，记录说明是否减少了追问、是否出现错误解释，再决定是否扩大接入范围。