从提交历史找回代码决策,拦截回归风险
Patchwork 根据 GitHub PR 涉及文件的历史,重建既有修改的原因,并引用具体提交提示新改动可能推翻的决策。作者展示了在 Express 仓库中识别依赖降级可能重新引入已修复漏洞的案例,并提供源码和演示。
AI 深度解读
代码库会留下改动,却未必能把改动背后的理由传给后来的人。作者为 Kiroween 2026 黑客松开发了 Patchwork:读取 GitHub pull request,追查变更文件的历史,在合并前提醒开发者是否推翻了过去有意做出的决定,并附上对应 commit。
这篇值得读的还有它的开发过程:作者把需求、项目约定和自动检查交给 Kiro 持续读取,让 AI 编程有明确依据。不过,文中展示的是一次项目实践,距离证明审查可靠性还有差距。
Patchwork 要找的是「这段代码为什么不能随便改」
常规代码审查容易关注当前改动是否合理,Patchwork 试图补上另一层信息:过去为什么要这样写。
例如,一次依赖升级可能是在修复安全漏洞,一段看似多余的判断可能是在保护资金安全。只看现在的代码,新接手的人很容易把这些限制当成历史包袱删掉。
Patchwork 的入口是 GitHub pull request。它针对每个发生变更的文件,从历史中重建相关知识,再判断新改动是否撤销了某个刻意保留的决定。警告会引用具体 commit,方便开发者回查依据。
作者给出的实际例子来自 expressjs/express:降低 body-parser 版本时,工具能指出这会重新引入一个已有记录的 CVE 问题,并标出当初修复它的 commit。原文没有给出具体版本号、CVE 编号和完整审查结果,因此这里能确认的是作者报告了这个案例。
附上 commit 能让警告接受核查,但不能单凭这一点保证判断正确。
Kiro 怎么记住需求和项目约定
作者没有直接让 Kiro 开始写代码,而是先在 /.kiro/specs 下准备三类材料:采用 EARS 风格验收条件的需求、设计文档和任务列表。EARS 可以理解为把需求写成条件明确、能够检查是否满足的句子。
这一步带来一个具体的架构决定:本地 Git 路径和 GitHub API 路径共用一个 knowledge builder。两种方式负责取得历史,后面的知识构建复用同一套逻辑,避免各写一份。
另一类材料放在 /.kiro/steering,包括技术栈、目录结构,以及项目主题必须遵守的硬性规则。specs 说明要做什么,steering 说明在这个项目里应该怎样做,减少每次提示都要重复交代的内容。
作者用一个小功能说明效果:给每条警告增加一句有历史依据的「下一步建议」。据作者描述,Kiro 先探索项目并运行测试,确认基线为 4/4 passing,再同时修改审查引擎和 UI,最后保持测试通过,整个过程来自一次提示。
他们还配置了两个 agent hooks:
- dogfood hook 在每次保存源码时运行 Patchwork 自身的审查,让工具检查自己的改动。
- syntax-guard hook 在每轮结束后对源码执行
node --check,及时发现语法错误。
此外,GitHub MCP server 让 agent 在开发时读取仓库。这里几种机制分工很清楚:文档提供约束,hooks 执行检查,MCP 提供访问仓库的通道。
我的判断
我认同把历史决策带回审查现场。尤其是安全修复和业务边界,当前代码往往只能告诉你「怎么做」,commit 才可能解释「为什么」。
但这套办法依赖历史本身有足够信息。提交说明含糊、决策散落在聊天记录里,或者旧限制已经不再适用时,找到 commit 也未必能得出正确结论。原文没有说明 Patchwork 怎样处理这些情况,也没有给出误报、漏报或与常规审查方式的对照数据。
Kiro 的部分同样应按经验案例看待。一次提示完成跨审查引擎和 UI 的修改,说明这次协作顺利;4/4 测试通过则只覆盖已有测试检查的范围。node --check 能发现语法问题,不能代替业务验证。
相较于只维护一份项目说明,作者把功能需求、长期约定和自动检查分别落到了文件与执行机制里,这一点更容易借鉴。至于它能节省多少开发时间,原文没有测量。
能拿来做什么
- 在 Node 项目的依赖降级或安全修复回退审查中,增加一步追查历史 commit,并要求 AI 给出可核查的依据。
- 给 AI 安排同时涉及审查逻辑和 UI 的任务前,先写清验收条件、设计选择和任务列表,让完成标准能够逐项检查。
- 把技术栈、目录结构和固定约定写进项目文档,再配置适合项目的自动检查;使用
node --check时,要明确它检查的是语法。 - 评估 Patchwork 这类工具时,用仓库中已知的历史修复尝试回退,检查它能否发现问题、引用正确 commit,并给出适用的建议。