AgentMachinist 这个项目在 Show HN 上展示的核心信息很短issue to reviewed PR。从一个 issue 出发最后得到一个经过审查的 pull request。很多 AI 编程工具现在都能做到“从 issue 生成 PR”但 reviewed 这个限定词让它的思路变得不太一样。现在用 AI 写代码最常见的困境不是生成不出来而是生成之后不敢合。代码看起来能跑但你不确定它有没有真正理解需求有没有动不该动的文件有没有在边界条件上突然翻车。review 的本质是拿实现去对照一个预期。如果没有对照物reviewer 就只能凭经验逐行读代码效率很低结论也容易因人而异。AgentMachinist 的关键设计标题里也写得很清楚SHA-bound spec approval。翻译成大白话就是先把要做的事写成一份 spec经过人批准之后用 SHA 哈希把这份 spec 固定成不可变契约然后让 AI 基于这份固定的 spec 去实现最后产出可审查的 PR。这篇文章想拆解一下这个设计到底在解决什么问题以及这类流程到底适合谁、不适合谁。1. AI 生成 PR 早就不新鲜了真正难的是“敢合进去”1.1 直接生成 PR 的模式问题出在哪现在的 AI 编程助手已经能承担不少编码工作。输入一个问题描述输出一个 diff把 diff 推到远端就形成了一个 PR。这个过程确实很快可能几分钟就能完成以前需要一两个小时的任务。但问题不在生成速度而在生成之后的那道关卡。第一关是理解偏差。AI 根据 issue 生成代码但它理解的“需求”和 issue 作者脑子里的“需求”很可能不是同一件事。字面上看起来它实现了某个函数但边界条件、异常处理、对周边模块的影响它可能完全没考虑。如果这种偏差出现在几百行代码里reviewer 很难一眼看出来。更麻烦的是人脑会自动脑补缺失的信息你看着一段 AI 代码可能会自己帮它“圆”成一个合理的实现结果 review 就变成了自我说服。第二关是范围蔓延。AI 在生成代码时可能为了让“功能跑通”随手改了一个配置文件、一个公共组件的签名或者调整了和本任务无关的样式。这些改动单个看可能无害合在一起就会让 PR 变得很难审。reviewer 不知道哪些改动是必要的哪些是 AI 的自作主张。最难受的是这种改动通常不会写在 commit message 里你只能靠 diff 去猜。第三关是缺少对照物。如果仓库里只有一个 issue那“预期”就是一段日常语言。它描述的是业务问题不是技术方案。比如“用户登录后偶尔会掉线”这种 issue 根本无法直接对应到具体的代码改动。不同 reviewer 从同一段文字里还原出来的预期很可能不一样。这样一来review 就变成了“检查代码是不是合理”而不是“检查代码是不是精准实现了约定”。单次跑通只说明流程没有断它说明不了 AI 的理解和你的理解一致。1.2 reviewed PR 不是目标而是对流程的约束回头看 AgentMachinist 的表述它写的是 reviewed PR不是简单的 PR。这个细节很值得琢磨。reviewed 不是在夸输出质量好而是在说流程里必须内置审查环节。要审查就必须有参照物否则审查就变成了凭感觉读代码。所以这个项目的切入点其实不是“怎么让 AI 更快写出代码”而是“怎么让 AI 写出的代码可以被审、被追溯、被验证”。这是两种完全不同的产品思路。前者比拼的是模型能力后者比拼的是流程设计和工程化能力。从工程实践看一个改动能不能合入从来不只是看“代码能不能跑”。还要看它是否在预期范围内、是否满足验收条件、是否引入了不可控风险。这些要求没法在代码生成之后靠 prompt 补救必须在动手编码之前就建立一份明确、稳定、经过确认的契约。AgentMachinist 把这份契约叫做 spec并且用 SHA 把它绑定住。这一步可能就是它和普通 AI 编码工具拉开距离的地方。2. 从 issue 到 reviewed PRAgentMachinist 想固化的流程2.1 一条完整的工作流示意从项目命名和机制描述来看AgentMachinist 的工作流大致可以理解成下面这个链路。我这里只做流程层面的抽象具体实现细节会因仓库配置和版本不同有差异但你拿到手之后核心环节大概率是类似的。Issue ↓ Spec 生成 AI 根据 issue 起草本次要改什么、明确不改什么、验收标准、影响的文件范围 ↓ Spec 审批 人参与批准这份 spec或打回让它补充修改 ↓ SHA 绑定 批准后的 spec 被固定成不可变契约绑定到一个 SHA ↓ 代码实现 AI 基于这份被绑定的 spec 实现代码不允许超出范围 ↓ Reviewed PR 生成 PR并附上 spec 引用和 SHA 记录供 reviewer 对照审查这条链路的重点不是某个环节的技术含量而是它通过流程节点把“人的判断”放回了对的时机。2.2 每一步在解决什么问题issue 到 spec把模糊需求变成明确契约。issue 通常描述一个现象、一个期望但很少能直接成为编码依据。AI 先把 issue 翻译成一份 spec等于把“我认为要实现什么”摊开在桌面上。这一步的价值在于它把 AI 对需求的理解从隐式变成显式。原来你只能看到最终代码现在你能先看到它准备怎么做。spec 审批把人的判断放在编码之前。这一步是这套流程和普通 AI 编程工具最明显的区别。AI 直接生成 PR人在事后审代码AgentMachinist 让人在事前审 spec。为什么这个顺序重要因为改 spec 的成本几乎为零而改已经写完的代码成本高得多。与其等 AI 把理解偏差写进几百行代码里再返工不如在纸面上先确认一次。很多团队在传统开发里也会先写设计文档再动手但设计文档常常和实现脱节把 spec 当成流程中的强制节点等于逼着团队把这一步做完。SHA 绑定把被批准的 spec 固定下来。没有绑定的话spec 可能在后续讨论里被改来改去最后没人说得清代码实现到底对应哪一版 spec。SHA 绑定解决的是版本漂移后面会单独展开。代码实现在边界内执行。AI 只能基于这份被绑定的 spec 干活。这能有效降低范围蔓延减少前面提到的“AI 顺手改不相关文件”的问题。当然这只是一种约束不是保证。AI 仍然可能写错但它不太容易“做着做着就跑到另一个需求里去了”。Reviewed PR最终交付物不是一堆裸代码而是带上下文、带契约引用、带追溯记录的变更。Reviewer 拿到 PR 时可以先看 spec再对照 diff判断哪些实现是符合约定的、哪些偏离了。如果 PR 里有不符合 spec 的改动就不需要一句一句去猜动机可以直接指出“这个改动在 spec 之外”。从工程经验看这套流程最值得借鉴的不是某个具体步骤而是它把“一次性对话”变成了“有记录的流程”。AI 和人的协作不再是一次 prompt 的交互而是以 spec 为中间产物、以 SHA 为锚点的多阶段协作。2.3 这不是调 prompt而是流程设计单独用 AI 工具质量看运气看这次模型有没有理解对、有没有发挥好。流程化之后质量来自节点控制。每个节点都有通过标准不通过就回到上游。这和 CI/CD 里的门禁本质上是一个思想在关键节点施加约束而不是指望每个环节都完美。所以如果你尝试这类工具可以换一个视角你真正在做的事情不是给 AI 加一个写 spec 的前置动作而是给自己加了一个需求确认的节点。它改变的不只是 AI 的产出方式还有团队协作的节奏。Issue 会写得更清楚review 会前置变更记录会更完整。这些都是流程设计的结果不是某个模型参数带来的。3. SHA 绑定 spec 审批不是技术细节是信任机制3.1 没有 SHA 绑定时会出什么问题假设没有 SHA 绑定流程会变成什么样第一次讨论生成了 spec v1AI 基于 v1 开始实现。中途产品经理说这里再加一个字段。于是 spec 文档被更新成 v2。AI 继续实现但这时它手里的实现可能已经混着 v1 和 v2 的内容。等到 PR 出来reviewer 打开 spec 文档看到的已经是 v2他以为代码实现的是 v2但代码里可能有一半是按 v1 写的。更隐蔽的问题是审批人和实现者之间的信息不对等。审批时说“我批准了这份 spec”但“这份”到底指哪个版本如果没有哈希就只能靠路径、时间、文件名去猜。这就像两个人开会说“按上次说的做”但“上次”具体是哪个版本谁也没有锚点。SHA 绑定解决的就是这种版本漂移。把 spec 文件当作一个不可变对象任何修改都会产生新的哈希。审批人批准的是哈希 A 对应的内容后续实现和 PR 也必须引用哈希 A。如果有人改了 spec哈希变为 B那这次改动就进入了一个新的审批流程而不是悄悄混在旧的实现里。3.2 SHA 绑定为什么比“文件名加更新记录”更可靠Git 本身用 commit SHA 做快照。把 spec 放进仓库或者至少把审批对应的 spec 提交信息记录下来就能用 SHA 精确指向内容。这比“文档已更新至 v2”可靠得多因为文件名和版本号都可能被误用但哈希是对内容的唯一表示。这里可以做一个类比施工图会标注版本和图号但真正把“施工队按哪一版图纸施工”锁定住的是盖章和签字流程。SHA 绑定就是数字世界里的盖章。图纸内容不能偷换施工范围不能边做边改。如果确实要改设计正确做法是走变更流程重新出图、重新盖章而不是施工的时候顺手改一下图纸。放到软件开发里这个机制给整个流程带来两个很实际的好处。第一可审计。谁批准了什么、实现的是哪一版约定都可以回溯。团队复盘时不需要争论“当初到底是谁定的这个方案”去看 SHA 记录就行。第二可自动化。只要实现和 spec 的 SHA 能对上后续的检查、对比、测试都能基于这个关联去做。它给了工具一个精确的校验点。3.3 这套机制的边界在哪SHA 绑定保护的是“版本一致性”不是“spec 内容正确性”。如果 AI 一开始生成的 spec 就理解错了审批人也没有发现那绑定一份错误的 spec只会让错误更早被固化下来。工具不能替代人对产品需求的理解。另一个边界是SHA 绑定能否发挥作用取决于审批环节是否真的在起作用。如果团队里所有人都习惯直接点同意spec 审批就会变成橡皮图章。SHA 能锁定契约但锁定不了一个走过场的流程。这是一个很现实的问题。任何流程工具只要参与者没有意愿最终都会变成流程表演。如果需求在实现中确实发生变化正确做法是回到 spec 阶段更新 spec、重新审批、生成新的 SHA、再继续实现。从表面看这增加了流程成本。但它避免了一个更贵的成本实现完成后才发现两边理解的不一致。早改永远比晚改便宜这是工程里最朴素也最容易被忽略的道理。4. 适合谁、不适合谁先看清边界再决定要不要尝试4.1 我判断这类流程更适合的场景AgentMachinist 这类“issue → spec → reviewed PR”的流程并不适合所有软件项目。它更适合那些本来就有一定正式度的团队和仓库。适合场景原因有明确验收标准的内部服务边界清晰、可测试适合先写 spec 再实现开源项目或公共仓库需要可追溯的变更记录reviewer 异步参与带 SHA 的 spec 能减少沟通成本风险较高的跨模块变更公共接口、数据模型或依赖升级先在 spec 阶段确认影响范围能避免连锁返工异步协作、reviewer 时间碎片化的团队一个带 spec 和 SHA 的 PR能让 review 的上下文被提前准备好这些场景有一个共同点错误成本高、沟通成本高、对追溯有要求。spec 审批多花的时间通常可以被返工和扯皮成本的减少抵消。如果团队正在做一个涉及多个服务、需要多人确认的改动这种“先确认再实现”的节奏会很有价值。4.2 不适合什么场景如果团队做的是探索性原型今天想验证一个交互明天可能推翻重来那这套流程就太重了。需求每天都在变spec 还没审批完方向就已经变了。这种情况下优先追求快速试错而不是契约稳定。让 AI 直接帮你写探索代码反而更合适。如果 issue 写得极其模糊团队也不打算把它写清楚那 spec 生成环节会变成猜谜。AI 猜一次审批人懵一次最后得到一份看起来合理但毫无信息量的 spec。这种场景下问题的根不在工具而在需求定义本身。如果团队本身没有 review 文化PR 都是直接合那么加一个 spec 审批也只是多一个形式。工具能给流程增加节点但不能培养流程意识。工具的前提是团队有共同的质量底线否则任何节点都拦不住“差不多就算了”。4.3 落地前需要先补上的前置条件想尝试这类工作流有几个前置条件值得先确认。首先是 issue 质量。issue 至少要包含目标、期望行为、涉及模块、验收点。如果平时 issue 只写半句话建议先统一一次 issue 模板。这不是为了工具好用而是因为 issue 是整个流程的输入源头。输入是模糊的后面每一步都会放大模糊。其次是 spec 的评审人。谁有权批准 spec这个人需要对业务和技术都有判断力不是谁有空谁来点按钮。在传统开发里设计文档通常需要技术负责人确认在 AgentMachinist 这类流程里这个角色同样重要。然后是变更流程。如果 spec 被批准后需求变了团队是否接受“重新批准”这一步骤这在习惯敏捷、快速变更的团队里可能是最大的阻力。但如果这一步被绕开SHA 绑定就形同虚设。还有一点必须明确仍然需要人工 review。即使 PR 已经过了工具内部的自查也仍然需要人去看 diff、跑场景、评估技术债。工具帮的是把 review 做得更快、更有依据不是取消 review。任何一个把“AI 已审查”当成“可以合入”的团队都会在某个时刻付出代价。5. 想试这套工作流用一个最小案例走完全程5.1 先选一个足够“小而有代表性”的 issue不要第一次就挑一个跨模块的大改动也不要挑“修复某个文案”这种 trivial 任务。理想的最小案例是一个真实存在、边界清晰、能写清楚验收标准的小功能或 bugfix。把 issue 整理干净说明现状、目标、期望行为、不做什么。这一步看着简单但决定了后续 spec 生成的质量。实际测试时会发现如果 issue 本身只有一句话AI 生成的 spec 也会非常零散。它只能从字面去猜猜不出你脑子里没写出来的约束。之后让 AgentMachinist 生成 spec。重点看三件事AI 有没有识别出真正的改动范围有没有列出不做什么验收标准是不是足够具体到可以作为测试依据。一份好的 spec不应该只有“实现登录功能”这种话而应该包含“用户输入错误密码时返回特定错误码”“密码重试次数上限为 5”这类可验证的描述。5.2 检查 SHA 绑定是否真的贯穿始终最小案例里最值得验证的不是“AI 是否写出了代码”而是“SHA 绑定是否真的锁住了流程”。具体可以检查这几个点spec 被批准后是否有一个可定位的 SHA 记录。后续实现版本和这个 SHA 是否有明确关联。PR 里能否清楚看到“实现的是哪一版 spec”。如果中途修改了 spec新的 SHA 是否对应一个新的审批流程而不是默认沿用。这个检查非常关键。因为 SHA 绑定如果只是设计文档里的一句话那整个流程的信任基础就不存在。你拿到 PR 时应该能清晰地说出“这份代码对应的约定是哪个版本”。如果做不到那它和普通 AI 工具没有本质区别。5.3 最容易出问题的环节和排查链路如果跑完最小案例发现实现与 spec 不一致或者 PR 没法审我一般按这个顺序排查现象先确认是“代码和 spec 不符”还是“reviewer 看不懂 PR”还是“审批被跳过”。输入回头检查 issue 是否清晰AI 是不是从一条模糊描述里硬猜出来的 spec。契约检查 spec 是否有更新、审批是否发生在更新前、SHA 是否指向被批准的那一份。环节检查是“AI 实现跑偏”还是“流程没有绑定住”。边界如果 issue 本身就是“研究一下要不要做”那它不应该走这个流程而是先做探索。这个排查顺序的核心思路是先确认输入和契约是否出了偏差再判断工具环节是否失效最后才怀疑是不是用错了场景。很多时候问题不在工具而是因为输入本身就缺少确定性。注意不要一上来就用大 issue 或批量任务测。先用一条样例把 spec 生成、审批、绑定、实现、PR 这五个环节跑通确认每个节点都能留下记录再扩大范围。5.4 工具落地本质是流程变更最小案例不只是验证 AI 能力更重要的是让团队体会到多了一个节点之后协作方式发生了哪些变化。比如issue 写得更清了review 之前的讨论前置了变更记录更容易追溯了。如果这些变化对团队是正向的再逐步扩大到更多任务。如果团队觉得“多了一个审批流程很烦”那就需要先解决 spec 模板、审批人、变更频率这些流程问题而不是逼大家硬用工具。流程变革从来不是把软件装上去就完成的它需要团队在协作方式上达成新的共识。6. AI 编码的下一个分水岭从生成能力到验证能力6.1 生成代码正在变成“低门槛能力”验证才是瓶颈现在的 AI 编程工具已经让代码生成变得非常便宜生成一个 diff、补一个函数、写一段测试几乎都是成本极低的动作。真正昂贵的是验证这个改动是否满足需求是否引入回归是否值得合入如果只看生成速度AgentMachinist 不一定比直接让 AI 写代码更快。它甚至明显更慢因为中间多了一个 spec 审批环节。但它的价值在于生成之后的验证成本大幅下降。Reviewer 不再需要从零开始理解一个突变出现的 PR而是可以先读 spec再对照 diff再有针对性地提出问题。这种“生成更慢、验证更快”的取舍在真实工程里通常是对的因为验证成本才是长期主要成本。6.2 开发者的新工作把模糊需求翻译成可验证契约当工具能承担更多实现细节时开发者的核心精力会往上游移动。写代码之前先要把需求变成一份可以被验证、被绑定、被追溯的契约。这其实是在重新拾起 spec-driven development 的核心理念但这一次契约的执行者不只是人还有 AI。对开发者个人来说能写好 spec 可能会变成一项越来越重要的能力。一份好 spec 要能回答为什么做、做什么、不做什么、什么时候算完成。这些内容正好也是 issue 评审和代码审查最关心的问题。反过来看如果一个开发者只会写代码不愿意把需求想清楚那么工具化程度越高的团队他的瓶颈就会越早暴露。6.3 什么不会变不管工具怎么迭代有一点不会变总得有人为产品和代码负责。AI 可以把功能实现得很好但它没法替团队判断“这个功能是否应该做”“这么做是否符合长期架构”“技术债是否可以接受”。这些判断需要人对业务的理解、对系统的全局观以及对技术风险的权衡。工具降低了从 issue 到 PR 的摩擦但它把更多人引向了更本质的环节定义问题、确认边界、审查质量。这其实是一件好事。人的时间应该花在判断上而不是花在机械劳动上。AgentMachinist 做的是把判断的依据变得更明确把判断的节点放得更靠前。这比“让 AI 自动把活全干了”更靠谱也更接近工程的本意。