2026/8/30 22:30:51
FEATURED · 精选文章 
AgentMachinist 是一个很有意思的自动化开发项目它把 GitHub issue 直接变成经过审查的 pull request而且中间加了一道“SHA-bound spec approval”的关卡。简单说它不是让 AI 读完 issue 就闷头写代码而是要求 AI 先写一份技术方案 spec由人确认这份 spec并通过 Git commit SHA 把这个批准绑定到具体版本。最值得关注的地方就在这里agent 到底做了什么、按哪一版方案实现都可以被事后审计而不是只靠一段 prompt 和历史对话撑着。先说明一下目前公开资料里项目标题非常简洁没有给出完整的配置文件、命令或版本说明所以下面会结合这套机制常见的技术实践来拆解。实际落地时以你拿到手的仓库文档为准。下面按“这套流程为什么值得用、怎么搭环境、怎么跑通、会遇到哪些坑、适合什么场景”的顺序写。1. 先看懂这套机制解决了什么问题如果只是让 AI 自动提 PR市面上已经有很多工具能做到。但真正用过的人都会遇到同一个尴尬agent 改完代码提交上来的 PR 看起来能用仔细一读跟 issue 要的东西对不上。要么多做了额外功能要么漏掉了核心验收条件要么把项目里原本约定好的结构推翻了一半。最后 reviewer 要一边重新理解需求一边对照 diff 猜 agent 的设计意图反而比人工改代码更累。AgentMachinist 想解决的正是这一类问题。它不把“写代码”当成第一步而是把“明确实现方案”当成第一步。issue 进来后agent 先研究仓库和需求产出一份 spec这份 spec 会以 commit 的形式出现在一个独立分支上。审批人确认这份 spec 符合预期后用该 commit 的 SHA 作为批准凭证。之后 agent 才能按这个版本的 spec 去写代码、出 PR。这样做有四个直接好处。第一需求偏差被提前拦截。agent 如果理解错了会在 spec 阶段暴露出来而不是等到写完代码、PR 都提了才发现。第二实现过程可追溯。每次批准都对应一个 SHA任何人都能查“agent 是按哪一版方案实现的”。第三review 的负担变小。reviewer 看 PR 时可以拿 PR 的 diff 和之前批准的 spec 逐条核对不再需要从零推断设计意图。第四需求变更不会静默发生。如果 agent 实现到一半发现 spec 需要调整它不能偷偷修改已经批准的 spec而是要走新的审批拿到新的 SHA。这样所有变更都留在记录里。这套机制本质上是在人与 AI 之间增加了一个“中间检查点”。对团队来说这个检查点不是流程负担而是把责任边界划清楚了人负责判断方向agent 负责在指定方向内执行。1.1 直接从 issue 到 PR 的问题出在哪自动化开发最怕的是“黑箱生成”。直接把 issue 文本、仓库代码、上下文全部丢给模型让它输出一个完整 PR看起来效率很高但问题很明显模型可能把 issue 里的模糊表述“脑补”成确定需求。模型可能为了实现一个功能顺带改了无关的配置文件、格式化了大片代码。没有独立的方案版本PR 里的每一行代码都像是第一次出现的决定。如果模型生成过程中换了版本、改了 prompt最终代码和最初理解可能完全对不上。这些问题的共同点是缺少“方案确认”的环节。AgentMachinist 把方案确认变成硬性步骤就是这个工具最核心的思路。1.2 与传统人工流程的差异传统人工流程通常是产品提 issue开发读 issue开发口头或文档里确认方案开发写代码提 PRreviewer 审查。AgentMachinist 做的事情是把这个流程自动化但保留了最重要的确认节点——spec 审批。它没有把 review 取消而是把 review 拆成两次第一次 review spec看方向对不对。第二次 review PR看实现是否符合已批准 spec。所以它不是“替人类做决定”而是“替人类跑通决定之后的执行路径”。这一点想清楚后后面配置权限、设置并发、判断失败原因都会容易很多。2. AgentMachinist 的四件关键对象issue、spec、SHA、reviewed PR这套流程里有四个核心对象理解它们之间的关系基本就理解了工具的全部逻辑。2.1 issue 是起点但不是一个“标题”就行这里说的 issue 并不仅仅是 GitHub 上那条文字而是一个被结构化处理过的需求输入。一个能让 agent 跑出可接受结果的 issue至少应该包含背景、变更目标、验收标准、可能受影响的模块、测试要求。如果仓库里原本有 bug 复现步骤也应该写进去。很多人一开始以为 agent 很聪明给个标题就能完成全部工作。实测下来不是这样。agent 生成 spec 的质量上限基本由 issue 的信息完整度决定。issue 写得太模糊它就会在 spec 里写一堆“根据常见实践推断”最后做出的实现不一定符合团队预期。所以在跑 AgentMachinist 之前建议先把 issue 模板整理好。模板里固定放下面几项业务背景为什么需要这个变更。当前行为现在系统表现是什么样。期望行为改完之后应该是什么样。验收条件怎样才算完成最好有可执行的检查命令。范围限制哪些路径、模块不要动。2.2 spec 是“将怎么做”的工程契约spec 不是需求文档而是技术实现方案。它回答的是“我要用什么方式实现这个 issue”。一份合格的 spec 通常包括变更范围新增、修改、删除哪些文件。接口变化如果有 API、函数、数据库结构变化要明确兼容策略。实现思路用哪种技术方案为什么不用别的。测试策略单测、集成测、手动验证分别覆盖什么。风险点可能影响哪些现有功能需要关注什么。AgentMachinist 里的 spec 不是随手写在 PR 描述里的而是作为一个文件提交到仓库分支上。这样它才有独立版本也才能通过 SHA 被精确引用。建议把 spec 放在统一目录例如.agent-specs/或docs/specs/避免散落在各处不好找。2.3 SHA 是如何变成“批准凭证”的Git 每次提交都会生成一个 SHA-1 或 SHA-256 值这个值由提交内容、父提交、作者、时间等信息计算出来。只要内容有任何变化SHA 就会完全不一样。所以 SHA 是“某一版内容”的精确指纹。SHA-bound spec approval 的逻辑就是审批人看到一份 spec确认没问题后在某个 commit SHA 上表示批准。之后这个批准就绑定在那个 SHA 对应的内容上。如果 agent 修改了 spec哪怕只改一个词commit SHA 也会变化原来绑定的批准就不再自动适用于新版本。这个机制比“审批人说一句‘可以了’然后 agent 自由发挥”可靠得多。因为人和 agent 都知道被批准的是哪一份文件、哪一版方案。实现过程中 agent 不能把 spec 悄悄改掉否则它会失去批准状态。2.4 reviewed PR 是最终交付物最后交付的 PR 不只是代码改动它需要携带一个“来源链”对应的 issue 编号、被批准 spec 的 SHA、按 spec 实现的完整 diff、测试结果。reviewer 拿到 PR 后可以按这条链逐项检查。如果 PR 里没有这些信息说明流程没有走完整。这也解释了为什么 AgentMachinist 强调“reviewed PR”。它追求的不是无人干预的自动化而是可审查、可回溯的自动化。PR 仍然要有人看但看的人不再需要花大量时间猜测agent的意图因为规范和实际实现是绑定在一起的。3. 跑通最小闭环前先把环境和权限准备到位在把 AgentMachinist 接入正式仓库之前我强烈建议先准备一个最小实验环境。这套流程涉及的环节很多如果第一次就跑真实项目出了问题会很难分清是 agent 的模型问题、spec 审批逻辑问题还是仓库权限问题。3.1 最小实验仓库怎么准备找一个不太活跃、改动不频繁的仓库或者直接新开一个私有仓库。仓库结构要足够简单但必须包含真实项目的基本要素至少一个业务模块例如一个简单的 API 服务。已有的测试框架哪怕是几个基础测试用例。明确的目录结构例如src/、tests/。CI 或本地测试命令能快速判断代码是否通过。不建议用特别大的仓库试跑。原因是 agent 在生成 spec 时会把项目结构、关键文件读一遍仓库越大上下文越长模型越容易漏掉关键信息也越难判断到底是模块理解问题还是工具配置问题。3.2 用最小权限配置访问凭证无论 AgentMachinist 以本地 CLI、GitHub Actions 还是 GitHub App 的方式运行它都需要访问仓库和创建 PR。访问凭证建议按最小权限配置只给目标仓库不要给组织级或全局权限。需要读取 issue用来获取任务。需要提交代码用来创建 spec 和实现分支。需要创建 pull request用来提 PR。需要读取和写入 commit status如果要让批准状态显示到 PR 上。如果是在 GitHub Actions 里使用可以用permissions字段限制默认 token 的权限例如permissions: contents: write pull-requests: write issues: read不要把带有全部仓库权限的 token 放进日志或环境变量里直接输出。agent 执行命令时可能打印环境变量一旦包含 token很容易被误写到日志文件。3.3 三个关键配置先别急着拉满跑第一个任务之前有几个配置值得单独确认分支策略。建议让 agent 为每个 issue 创建独立分支分支名包含 issue 号例如agent/issue-42-health-endpoint。这样多个任务并发时不会互相污染。文件路径限制。如果 agent 能力比较开放建议指定它只能修改某些目录。先限制成src/和tests/不要让它在跑第一个任务时就改动 CI 配置、依赖锁文件或根目录脚本。并发数量。第一个任务一定要设置成 1。同时跑多个 agent 任务问题不会来得更快只会更难排查。3.4 建议先手工模拟一遍完整流程正式接入前可以先不用 agent而是人工把整条链路走一遍创建一个 issue。手动在分支上写一份 spec。记录该分支最新 commit 的 SHA。在 GitHub 上对该 commit 或该分支做一个 review / approval。然后按 spec 手动修改代码创建 PR。在 PR 中注明“spec 批准 SHA”。做完这一遍你会对“SHA 绑定”产生非常直观的感觉如果中途修改了 spec 文件再去查 SHA会发现和审批时不一样。理解了这个变化再看 AgentMachinist 的行为就不会觉得它多此一举。4. 从 issue 到 reviewed PR 的完整操作流程下面按照 AgentMachinist 的核心链路逐步拆解。以 GitHub 仓库为例但不绑定具体的安装命令因为不同实现方式的入口可能不同。4.1 第一步把 issue 写成像样的需求单agent 对待 issue 的方式和人类开发很像第一步都是理解需求。所以 issue 质量决定了最终产物质量。比较好的做法是把 issue 模板固定下来。一个推荐模板结构## 背景 为什么要做这个变更。 ## 当前行为 当前系统的实际表现。 ## 期望行为 变更完成后的预期表现。 ## 验收标准 - [ ] 新增接口 /health返回 {status:ok} - [ ] 现有测试全部通过 ## 范围限制 - 不要修改数据库表结构 - 不要改动已有认证逻辑这里写验收标准时最好给出具体、可脚本化的描述而不是“提升用户体验”这类无法自动判断的说法。agent 在生成 spec 和实现代码时会反复对照验收标准。4.2 第二步agent 生成 spec并提交到独立分支agent 拿到 issue 后会做三件事读取 issue 内容。扫描仓库目录结构读取与需求相关的文件。生成一份 spec写入例如.agent-specs/issue-42.md的文件。然后 agent 会创建一个新分支提交这份 spec并推送到远端。推送完成后记录下当前 commit 的 SHA把它作为“待批准版本”。这一步是整个流程里最关键的切分点。agent 在这个阶段不写业务代码只写方案。这个约束能让 agent 的“研究-输出”分离避免它一边想方案一边改代码最后把方案和实现混在一起。4.3 第三步审批人按 SHA 批准 specspec 推上去之后需要有人来批准。这个“人”是流程里的重要角色。AgentMachinist 不追求把人也去掉而是把人的参与前置到方案阶段。审批人需要做的工作打开 spec 文件检查变更范围是否清晰。对照 issue 的验收标准确认方案能覆盖核心需求。检查是否有过度设计、遗漏风险。如果 spec 有问题可以直接回复评论请 agent 调整。如果确认没问题就对该 commit SHA 做批准。批准的方式可以是 GitHub 的 commit review也可以是项目自定义的批准标记。核心原则是批准记录必须能够对应到具体 SHA。如果 agent 修改了 specGit 会生成新的 commit、新的 SHA原来的批准状态就不能直接迁移。需要审批人重新检查新版本并批准。4.4 第四步agent 按已批准 spec 实现代码拿到“已批准 SHA”后agent 才进入实现阶段。它会读取被批准的 spec 文件内容。按照 spec 中的变更范围和实现思路修改代码。写测试或更新测试用例。运行测试确保通过。提交实现代码创建 PR。这个过程里agent 不能修改已经批准的 spec 文件。一旦它发现实现方案有问题必须停下来把新的方案作为一个新的 spec commit 提交重新走审批流程。这就是所谓的“绑定”在工程上的体现不是靠模型自律而是靠 Git 的内容不可变性。只要 spec 文件变了SHA 就变审批关系自然断裂。4.5 第五步最终 review PR 并合并PR 创建后reviewer 需要做最终确认。这个确认比传统 AI PR 的 review 要轻松因为可以直接对照issue确认原始需求。spec 文件确认批准时的方案。PR diff确认实现是否和 spec 一致。测试结果确认没有破坏现有功能。如果 PR 里所有改动都能和 spec 对得上review 基本只剩一些代码风格和边界情况的意见。如果 PR 里有 spec 没有提到的改动那就要问 agent这部分为什么加进来。正常情况下除了必要的兼容性改动不应该出现 spec 之外的“惊喜”。5. SHA 绑定里的技术细节和最容易踩的坑SHA-bound spec approval 的核心是 Git 提交内容不能被随意改动。但在实际使用中Git 本身有很多操作会让 SHA 发生变化这些变化并不都意味着 spec 内容被修改如果处理不好会造成“我明明没改 spec为什么批准失效了”的困惑。5.1 为什么 SHA 会变变了意味着什么Git 提交的 SHA 由很多信息组成文件内容、父提交、提交时间、作者、提交信息等。任何一项变化都可能改变 SHA。常见触发情况对 spec 文件做了文本修改。对 spec 所在分支做了 rebase。对 spec 提交做了 amend修改了提交信息。把 spec 提交转移到另一个分支做了 cherry-pick。换行符或文件编码被自动转换。前一种是 spec 内容真的变了后几种是“内容没变但提交身份变了”。但审批绑定的是 commit SHA所以所有这些情况都会让旧批准不再适用。处理方式很明确spec 分支一旦生成并提交就不要重写历史。如果需要修改 spec就新增一个 commit让新 commit 拥有新 SHA重新申请审批。不要去 amend、rebase也不要在推送后强行修改历史。5.2 在 CI 里校验 spec 是否仍然匹配为了确保最终 PR 使用的 spec 与批准的 SHA 一致可以在 CI 中加一个检查脚本。思路是记录批准的 SHA然后对比当前分支上的 spec 文件是否和该 SHA 上的 spec 文件完全一致。下面是一个 bash 示例逻辑是检查当前分支的 spec 文件与指定 SHA 对应版本是否没有差异set -euo pipefail APPROVED_SHA${APPROVED_SHA:-} SPEC_PATH.agent-specs/issue-42.md if [ -z $APPROVED_SHA ]; then echo missing APPROVED_SHA exit 1 fi # 如果当前分支上的 spec 与批准 SHA 中的 spec 内容不同就说明 spec 被修改过。 if ! git diff --quiet $APPROVED_SHA -- $SPEC_PATH; then echo spec has changed since approved SHA ${APPROVED_SHA} exit 1 fi echo spec matches approved SHA这个示例做的是“当前文件与批准版本一致”的校验属于最基础的防护。更进一步可以校验整个仓库当前 HEAD 上 spec 文件内容而不是只看工作区。这个可以根据你使用的 CI 实现调整。5.3 分支会被 squash merge 怎么办团队普遍会使用 squash merge 合并 PR也就是把整个 PR 的多个提交压缩成一个提交。这对普通代码没什么问题但会影响 spec 绑定的可读性。如果 spec 提交和实现提交在同一个 PR 里合并后 SHA 会全部变化。这时候再去回溯“被批准 SHA”和“最终合入主分支的代码”之间的对应关系会变得麻烦。更推荐的做法是spec 审批发生在独立的分支上这个分支本身只包含 spec 文件。实现分支基于已批准 SHA 创建或者实现 PR 中明确记录被批准 SHA。合并 PR 时spec 文件不一定需要进入主分支可以把它看作一个流程产物保留在独立分支或归档目录里。这样即使 PR 被 squash mergespec 原始 SHA 仍然可以在独立分支上找到。5.4 最容易被忽略的日志和 token 安全自动化 agent 一旦跑起来会执行大量命令读取环境变量调用远端 API。安全方面有几件事必须提前做好不要把所有环境变量输出到日志。agent 里打印变量时先过滤掉 token、密钥等字段。记录日志时把每次操作的 SHA、分支、命令都留下来方便排查。tag 或注释里不要放敏感信息Git 历史一旦推送就删不掉。实际踩坑中很多“agent 没按 spec 执行”的问题最后查出来是 agent 在实现阶段重新读取了仓库代码但读取的是另一个分支上的过期版本。所以在日志里记录每一步的 HEAD SHA能快速定位 agent 到底在哪个版本上工作。6. 并发处理多个 issue 时怎么避免流水线互相干扰AgentMachinist 跑单条任务很容易真正难的是同时跑多个 issue。问题通常出现在文件冲突、分支混乱、资源抢占、日志交织几个地方。6.1 并发任务的分支和日志隔离每个 issue 必须使用独立分支这是底线。分支名里最好包含 issue 编号和简短描述例如agent/issue-42-health-endpoint agent/issue-57-fix-login-session日志也要按任务隔离。不要把多个 agent 任务的日志全部写到同一个文件里。推荐目录结构logs/ 42/ spec-generation.log implementation.log 57/ spec-generation.log implementation.log每个任务只读自己的日志排错效率会高很多。如果所有任务混在一个日志里等到第 8 个任务出错时你根本看不清当时到底发生了什么事。6.2 文件冲突需要提前限制两个 agent 任务如果同时修改同一个文件后推的那个大概率会遇到冲突。AgentMachinist 这类工具不会自动解决所有冲突最终还是要靠 git 和人工介入。比较稳妥的做法是启动任务时声明每个任务允许修改的路径范围。如果两个任务存在路径重叠就串行执行不要并行。在 spec 阶段就让 agent 明确列出会修改的文件检查这些文件和现有任务是否冲突。比如一个任务要改api/users.py另一个任务要改api/users.py那就不应该同时跑。哪怕两个改动看起来互不相关合并时也容易出问题。6.3 失败重试与状态机agent 任务必然会出现失败模型调用超时、测试挂掉、依赖安装失败、网络抖动。失败以后能不能恢复是判断工具落地程度的重要指标。建议把每个任务建模成状态机pending等待处理。spec_reviewspec 已生成等待审批。implementingspec 已批准正在写代码。pr_readyPR 已创建等待最终 review。blocked需要人工介入。出现异常时先进入blocked而不是自动重试。自动重试适合问题是临时的例如网络超时但如果问题是 spec 方案不对重试多少次都没用只会浪费模型调用时间。6.4 控制成本模型调用和超时agent 每次读取代码、生成 spec、实现代码都会消耗模型调用。仓库越大、任务越复杂成本越高。建议在一开始就设置调用上限或任务超时时间。示例参考配置项建议值说明单个任务超时30 分钟避免无限卡住并发任务数1 到 2一开始一定从 1 开始单个任务读取文件数20 个内防止 agent 读太多无关文件模型输出 token 上限4000 到 8000防止 spec 或 diff 被截断等跑稳定后再逐步放宽。把资源拉满不是效率是给自己制造排查负担。7. 什么团队和任务适合用这套机制什么场景不要硬套看一个自动化工具好不好不能只看 Demo要看它适合长在什么流程里。AgentMachinist 这套机制并不是所有开发任务都适用。7.1 适合自动化处理的任务特征如果任务满足以下条件成功率会比较高验收标准明确能够用文字或命令表达。改动范围收敛例如新增接口、修 bug、补测试。仓库已有测试覆盖agent 能通过跑测试验证自己的改动。代码规范和目录结构清晰agent 可以快速定位相关文件。不需要和真实用户反复确认交互细节。典型的例子是新增一个轻量接口、修复某个已知 bug、给某个模块补充单元测试、重构一个函数的内部实现但不改变外部行为。7.2 适合承接这套机制的团队流程团队需要具备两个条件。第一有人愿意做 spec 审批。这个角色不一定非常资深但必须了解需求背景和代码结构。他需要在 agent 生成 spec 后花几分钟检查方向而不是等到 PR 阶段才看。第二CI 足够可靠。agent 写完代码后需要依赖测试和静态检查来判断自己是否完成。如果 CI 形同虚设agent 很容易在错误的方向上继续前进。如果团队已经养成了“先方案、后代码”的习惯那么 AgentMachinist 的适应成本会非常低。它只是把原本开会确认方案的过程变成了线上审批 spec 的过程。7.3 不适合的场景和我的建议遇到下面这些情况建议不要急着上 agent需求高度依赖业务判断例如“重新设计用户激励体系”。对代码出处有严格的合规要求不允许第三方模型接触源码。仓库结构混乱测试缺失agent 无法判断自己的改动是否安全。团队没有时间 review spec认为“AI 应该自己搞定一切”。在这些场景下硬套只会得到一堆“看起来完成但实际不能上线”的 PR。工具本身没有错是任务上下文不合适。7.4 从最小闭环开始推进如果你想在团队里引入 AgentMachinist我不建议第一次就开放给整个仓库所有 issue。可以先从下面几步做起选一个最边缘、最独立的 issue例如给某个工具函数增加日志。在最小实验仓库里完整跑一遍 spec 审批和 PR 流程。把流程跑顺后再在真实仓库的pinned/marked标签上启用。观察几次任务后再逐步放开范围。这一步是为了建立信任。只有当你亲眼看到 agent 按已批准的 spec 产出 PR并且 reviewer 能快速核对才会放心把它用于更多场景。结尾处我想说一个自己的感受这类自动化工具真正能落地的关键往往不是模型多强而是流程里有没有一个明确的“对账点”。AgentMachinist 用 SHA 把 spec 批准和代码实现绑在一起让人类检查和 AI 执行之间不再是两个模糊的黑箱。如果你也在做类似的 agent 开发流程最值得学的不是具体命令而是“先让方向被批准再让执行有凭据”这个思路。先从小仓库、单任务开始把 spec 评审和 SHA 校验跑扎实再谈批量和全自动化。
AgentMachinist：用SHA绑定spec审批，打造可审计的AI自动开发流程
AgentMachinist 是一个很有意思的自动化开发项目它把 GitHub issue 直接变成经过审查的 pull request而且中间加了一道“SHA-bound spec approval”的关卡。简单说它不是让 AI 读完 issue 就闷头写代码而是要求 AI 先写一份技术方案 spec由人确认这份 spec并通过 Git commit SHA 把这个批准绑定到具体版本。最值得关注的地方就在这里agent 到底做了什么、按哪一版方案实现都可以被事后审计而不是只靠一段 prompt 和历史对话撑着。先说明一下目前公开资料里项目标题非常简洁没有给出完整的配置文件、命令或版本说明所以下面会结合这套机制常见的技术实践来拆解。实际落地时以你拿到手的仓库文档为准。下面按“这套流程为什么值得用、怎么搭环境、怎么跑通、会遇到哪些坑、适合什么场景”的顺序写。1. 先看懂这套机制解决了什么问题如果只是让 AI 自动提 PR市面上已经有很多工具能做到。但真正用过的人都会遇到同一个尴尬agent 改完代码提交上来的 PR 看起来能用仔细一读跟 issue 要的东西对不上。要么多做了额外功能要么漏掉了核心验收条件要么把项目里原本约定好的结构推翻了一半。最后 reviewer 要一边重新理解需求一边对照 diff 猜 agent 的设计意图反而比人工改代码更累。AgentMachinist 想解决的正是这一类问题。它不把“写代码”当成第一步而是把“明确实现方案”当成第一步。issue 进来后agent 先研究仓库和需求产出一份 spec这份 spec 会以 commit 的形式出现在一个独立分支上。审批人确认这份 spec 符合预期后用该 commit 的 SHA 作为批准凭证。之后 agent 才能按这个版本的 spec 去写代码、出 PR。这样做有四个直接好处。第一需求偏差被提前拦截。agent 如果理解错了会在 spec 阶段暴露出来而不是等到写完代码、PR 都提了才发现。第二实现过程可追溯。每次批准都对应一个 SHA任何人都能查“agent 是按哪一版方案实现的”。第三review 的负担变小。reviewer 看 PR 时可以拿 PR 的 diff 和之前批准的 spec 逐条核对不再需要从零推断设计意图。第四需求变更不会静默发生。如果 agent 实现到一半发现 spec 需要调整它不能偷偷修改已经批准的 spec而是要走新的审批拿到新的 SHA。这样所有变更都留在记录里。这套机制本质上是在人与 AI 之间增加了一个“中间检查点”。对团队来说这个检查点不是流程负担而是把责任边界划清楚了人负责判断方向agent 负责在指定方向内执行。1.1 直接从 issue 到 PR 的问题出在哪自动化开发最怕的是“黑箱生成”。直接把 issue 文本、仓库代码、上下文全部丢给模型让它输出一个完整 PR看起来效率很高但问题很明显模型可能把 issue 里的模糊表述“脑补”成确定需求。模型可能为了实现一个功能顺带改了无关的配置文件、格式化了大片代码。没有独立的方案版本PR 里的每一行代码都像是第一次出现的决定。如果模型生成过程中换了版本、改了 prompt最终代码和最初理解可能完全对不上。这些问题的共同点是缺少“方案确认”的环节。AgentMachinist 把方案确认变成硬性步骤就是这个工具最核心的思路。1.2 与传统人工流程的差异传统人工流程通常是产品提 issue开发读 issue开发口头或文档里确认方案开发写代码提 PRreviewer 审查。AgentMachinist 做的事情是把这个流程自动化但保留了最重要的确认节点——spec 审批。它没有把 review 取消而是把 review 拆成两次第一次 review spec看方向对不对。第二次 review PR看实现是否符合已批准 spec。所以它不是“替人类做决定”而是“替人类跑通决定之后的执行路径”。这一点想清楚后后面配置权限、设置并发、判断失败原因都会容易很多。2. AgentMachinist 的四件关键对象issue、spec、SHA、reviewed PR这套流程里有四个核心对象理解它们之间的关系基本就理解了工具的全部逻辑。2.1 issue 是起点但不是一个“标题”就行这里说的 issue 并不仅仅是 GitHub 上那条文字而是一个被结构化处理过的需求输入。一个能让 agent 跑出可接受结果的 issue至少应该包含背景、变更目标、验收标准、可能受影响的模块、测试要求。如果仓库里原本有 bug 复现步骤也应该写进去。很多人一开始以为 agent 很聪明给个标题就能完成全部工作。实测下来不是这样。agent 生成 spec 的质量上限基本由 issue 的信息完整度决定。issue 写得太模糊它就会在 spec 里写一堆“根据常见实践推断”最后做出的实现不一定符合团队预期。所以在跑 AgentMachinist 之前建议先把 issue 模板整理好。模板里固定放下面几项业务背景为什么需要这个变更。当前行为现在系统表现是什么样。期望行为改完之后应该是什么样。验收条件怎样才算完成最好有可执行的检查命令。范围限制哪些路径、模块不要动。2.2 spec 是“将怎么做”的工程契约spec 不是需求文档而是技术实现方案。它回答的是“我要用什么方式实现这个 issue”。一份合格的 spec 通常包括变更范围新增、修改、删除哪些文件。接口变化如果有 API、函数、数据库结构变化要明确兼容策略。实现思路用哪种技术方案为什么不用别的。测试策略单测、集成测、手动验证分别覆盖什么。风险点可能影响哪些现有功能需要关注什么。AgentMachinist 里的 spec 不是随手写在 PR 描述里的而是作为一个文件提交到仓库分支上。这样它才有独立版本也才能通过 SHA 被精确引用。建议把 spec 放在统一目录例如.agent-specs/或docs/specs/避免散落在各处不好找。2.3 SHA 是如何变成“批准凭证”的Git 每次提交都会生成一个 SHA-1 或 SHA-256 值这个值由提交内容、父提交、作者、时间等信息计算出来。只要内容有任何变化SHA 就会完全不一样。所以 SHA 是“某一版内容”的精确指纹。SHA-bound spec approval 的逻辑就是审批人看到一份 spec确认没问题后在某个 commit SHA 上表示批准。之后这个批准就绑定在那个 SHA 对应的内容上。如果 agent 修改了 spec哪怕只改一个词commit SHA 也会变化原来绑定的批准就不再自动适用于新版本。这个机制比“审批人说一句‘可以了’然后 agent 自由发挥”可靠得多。因为人和 agent 都知道被批准的是哪一份文件、哪一版方案。实现过程中 agent 不能把 spec 悄悄改掉否则它会失去批准状态。2.4 reviewed PR 是最终交付物最后交付的 PR 不只是代码改动它需要携带一个“来源链”对应的 issue 编号、被批准 spec 的 SHA、按 spec 实现的完整 diff、测试结果。reviewer 拿到 PR 后可以按这条链逐项检查。如果 PR 里没有这些信息说明流程没有走完整。这也解释了为什么 AgentMachinist 强调“reviewed PR”。它追求的不是无人干预的自动化而是可审查、可回溯的自动化。PR 仍然要有人看但看的人不再需要花大量时间猜测agent的意图因为规范和实际实现是绑定在一起的。3. 跑通最小闭环前先把环境和权限准备到位在把 AgentMachinist 接入正式仓库之前我强烈建议先准备一个最小实验环境。这套流程涉及的环节很多如果第一次就跑真实项目出了问题会很难分清是 agent 的模型问题、spec 审批逻辑问题还是仓库权限问题。3.1 最小实验仓库怎么准备找一个不太活跃、改动不频繁的仓库或者直接新开一个私有仓库。仓库结构要足够简单但必须包含真实项目的基本要素至少一个业务模块例如一个简单的 API 服务。已有的测试框架哪怕是几个基础测试用例。明确的目录结构例如src/、tests/。CI 或本地测试命令能快速判断代码是否通过。不建议用特别大的仓库试跑。原因是 agent 在生成 spec 时会把项目结构、关键文件读一遍仓库越大上下文越长模型越容易漏掉关键信息也越难判断到底是模块理解问题还是工具配置问题。3.2 用最小权限配置访问凭证无论 AgentMachinist 以本地 CLI、GitHub Actions 还是 GitHub App 的方式运行它都需要访问仓库和创建 PR。访问凭证建议按最小权限配置只给目标仓库不要给组织级或全局权限。需要读取 issue用来获取任务。需要提交代码用来创建 spec 和实现分支。需要创建 pull request用来提 PR。需要读取和写入 commit status如果要让批准状态显示到 PR 上。如果是在 GitHub Actions 里使用可以用permissions字段限制默认 token 的权限例如permissions: contents: write pull-requests: write issues: read不要把带有全部仓库权限的 token 放进日志或环境变量里直接输出。agent 执行命令时可能打印环境变量一旦包含 token很容易被误写到日志文件。3.3 三个关键配置先别急着拉满跑第一个任务之前有几个配置值得单独确认分支策略。建议让 agent 为每个 issue 创建独立分支分支名包含 issue 号例如agent/issue-42-health-endpoint。这样多个任务并发时不会互相污染。文件路径限制。如果 agent 能力比较开放建议指定它只能修改某些目录。先限制成src/和tests/不要让它在跑第一个任务时就改动 CI 配置、依赖锁文件或根目录脚本。并发数量。第一个任务一定要设置成 1。同时跑多个 agent 任务问题不会来得更快只会更难排查。3.4 建议先手工模拟一遍完整流程正式接入前可以先不用 agent而是人工把整条链路走一遍创建一个 issue。手动在分支上写一份 spec。记录该分支最新 commit 的 SHA。在 GitHub 上对该 commit 或该分支做一个 review / approval。然后按 spec 手动修改代码创建 PR。在 PR 中注明“spec 批准 SHA”。做完这一遍你会对“SHA 绑定”产生非常直观的感觉如果中途修改了 spec 文件再去查 SHA会发现和审批时不一样。理解了这个变化再看 AgentMachinist 的行为就不会觉得它多此一举。4. 从 issue 到 reviewed PR 的完整操作流程下面按照 AgentMachinist 的核心链路逐步拆解。以 GitHub 仓库为例但不绑定具体的安装命令因为不同实现方式的入口可能不同。4.1 第一步把 issue 写成像样的需求单agent 对待 issue 的方式和人类开发很像第一步都是理解需求。所以 issue 质量决定了最终产物质量。比较好的做法是把 issue 模板固定下来。一个推荐模板结构## 背景 为什么要做这个变更。 ## 当前行为 当前系统的实际表现。 ## 期望行为 变更完成后的预期表现。 ## 验收标准 - [ ] 新增接口 /health返回 {status:ok} - [ ] 现有测试全部通过 ## 范围限制 - 不要修改数据库表结构 - 不要改动已有认证逻辑这里写验收标准时最好给出具体、可脚本化的描述而不是“提升用户体验”这类无法自动判断的说法。agent 在生成 spec 和实现代码时会反复对照验收标准。4.2 第二步agent 生成 spec并提交到独立分支agent 拿到 issue 后会做三件事读取 issue 内容。扫描仓库目录结构读取与需求相关的文件。生成一份 spec写入例如.agent-specs/issue-42.md的文件。然后 agent 会创建一个新分支提交这份 spec并推送到远端。推送完成后记录下当前 commit 的 SHA把它作为“待批准版本”。这一步是整个流程里最关键的切分点。agent 在这个阶段不写业务代码只写方案。这个约束能让 agent 的“研究-输出”分离避免它一边想方案一边改代码最后把方案和实现混在一起。4.3 第三步审批人按 SHA 批准 specspec 推上去之后需要有人来批准。这个“人”是流程里的重要角色。AgentMachinist 不追求把人也去掉而是把人的参与前置到方案阶段。审批人需要做的工作打开 spec 文件检查变更范围是否清晰。对照 issue 的验收标准确认方案能覆盖核心需求。检查是否有过度设计、遗漏风险。如果 spec 有问题可以直接回复评论请 agent 调整。如果确认没问题就对该 commit SHA 做批准。批准的方式可以是 GitHub 的 commit review也可以是项目自定义的批准标记。核心原则是批准记录必须能够对应到具体 SHA。如果 agent 修改了 specGit 会生成新的 commit、新的 SHA原来的批准状态就不能直接迁移。需要审批人重新检查新版本并批准。4.4 第四步agent 按已批准 spec 实现代码拿到“已批准 SHA”后agent 才进入实现阶段。它会读取被批准的 spec 文件内容。按照 spec 中的变更范围和实现思路修改代码。写测试或更新测试用例。运行测试确保通过。提交实现代码创建 PR。这个过程里agent 不能修改已经批准的 spec 文件。一旦它发现实现方案有问题必须停下来把新的方案作为一个新的 spec commit 提交重新走审批流程。这就是所谓的“绑定”在工程上的体现不是靠模型自律而是靠 Git 的内容不可变性。只要 spec 文件变了SHA 就变审批关系自然断裂。4.5 第五步最终 review PR 并合并PR 创建后reviewer 需要做最终确认。这个确认比传统 AI PR 的 review 要轻松因为可以直接对照issue确认原始需求。spec 文件确认批准时的方案。PR diff确认实现是否和 spec 一致。测试结果确认没有破坏现有功能。如果 PR 里所有改动都能和 spec 对得上review 基本只剩一些代码风格和边界情况的意见。如果 PR 里有 spec 没有提到的改动那就要问 agent这部分为什么加进来。正常情况下除了必要的兼容性改动不应该出现 spec 之外的“惊喜”。5. SHA 绑定里的技术细节和最容易踩的坑SHA-bound spec approval 的核心是 Git 提交内容不能被随意改动。但在实际使用中Git 本身有很多操作会让 SHA 发生变化这些变化并不都意味着 spec 内容被修改如果处理不好会造成“我明明没改 spec为什么批准失效了”的困惑。5.1 为什么 SHA 会变变了意味着什么Git 提交的 SHA 由很多信息组成文件内容、父提交、提交时间、作者、提交信息等。任何一项变化都可能改变 SHA。常见触发情况对 spec 文件做了文本修改。对 spec 所在分支做了 rebase。对 spec 提交做了 amend修改了提交信息。把 spec 提交转移到另一个分支做了 cherry-pick。换行符或文件编码被自动转换。前一种是 spec 内容真的变了后几种是“内容没变但提交身份变了”。但审批绑定的是 commit SHA所以所有这些情况都会让旧批准不再适用。处理方式很明确spec 分支一旦生成并提交就不要重写历史。如果需要修改 spec就新增一个 commit让新 commit 拥有新 SHA重新申请审批。不要去 amend、rebase也不要在推送后强行修改历史。5.2 在 CI 里校验 spec 是否仍然匹配为了确保最终 PR 使用的 spec 与批准的 SHA 一致可以在 CI 中加一个检查脚本。思路是记录批准的 SHA然后对比当前分支上的 spec 文件是否和该 SHA 上的 spec 文件完全一致。下面是一个 bash 示例逻辑是检查当前分支的 spec 文件与指定 SHA 对应版本是否没有差异set -euo pipefail APPROVED_SHA${APPROVED_SHA:-} SPEC_PATH.agent-specs/issue-42.md if [ -z $APPROVED_SHA ]; then echo missing APPROVED_SHA exit 1 fi # 如果当前分支上的 spec 与批准 SHA 中的 spec 内容不同就说明 spec 被修改过。 if ! git diff --quiet $APPROVED_SHA -- $SPEC_PATH; then echo spec has changed since approved SHA ${APPROVED_SHA} exit 1 fi echo spec matches approved SHA这个示例做的是“当前文件与批准版本一致”的校验属于最基础的防护。更进一步可以校验整个仓库当前 HEAD 上 spec 文件内容而不是只看工作区。这个可以根据你使用的 CI 实现调整。5.3 分支会被 squash merge 怎么办团队普遍会使用 squash merge 合并 PR也就是把整个 PR 的多个提交压缩成一个提交。这对普通代码没什么问题但会影响 spec 绑定的可读性。如果 spec 提交和实现提交在同一个 PR 里合并后 SHA 会全部变化。这时候再去回溯“被批准 SHA”和“最终合入主分支的代码”之间的对应关系会变得麻烦。更推荐的做法是spec 审批发生在独立的分支上这个分支本身只包含 spec 文件。实现分支基于已批准 SHA 创建或者实现 PR 中明确记录被批准 SHA。合并 PR 时spec 文件不一定需要进入主分支可以把它看作一个流程产物保留在独立分支或归档目录里。这样即使 PR 被 squash mergespec 原始 SHA 仍然可以在独立分支上找到。5.4 最容易被忽略的日志和 token 安全自动化 agent 一旦跑起来会执行大量命令读取环境变量调用远端 API。安全方面有几件事必须提前做好不要把所有环境变量输出到日志。agent 里打印变量时先过滤掉 token、密钥等字段。记录日志时把每次操作的 SHA、分支、命令都留下来方便排查。tag 或注释里不要放敏感信息Git 历史一旦推送就删不掉。实际踩坑中很多“agent 没按 spec 执行”的问题最后查出来是 agent 在实现阶段重新读取了仓库代码但读取的是另一个分支上的过期版本。所以在日志里记录每一步的 HEAD SHA能快速定位 agent 到底在哪个版本上工作。6. 并发处理多个 issue 时怎么避免流水线互相干扰AgentMachinist 跑单条任务很容易真正难的是同时跑多个 issue。问题通常出现在文件冲突、分支混乱、资源抢占、日志交织几个地方。6.1 并发任务的分支和日志隔离每个 issue 必须使用独立分支这是底线。分支名里最好包含 issue 编号和简短描述例如agent/issue-42-health-endpoint agent/issue-57-fix-login-session日志也要按任务隔离。不要把多个 agent 任务的日志全部写到同一个文件里。推荐目录结构logs/ 42/ spec-generation.log implementation.log 57/ spec-generation.log implementation.log每个任务只读自己的日志排错效率会高很多。如果所有任务混在一个日志里等到第 8 个任务出错时你根本看不清当时到底发生了什么事。6.2 文件冲突需要提前限制两个 agent 任务如果同时修改同一个文件后推的那个大概率会遇到冲突。AgentMachinist 这类工具不会自动解决所有冲突最终还是要靠 git 和人工介入。比较稳妥的做法是启动任务时声明每个任务允许修改的路径范围。如果两个任务存在路径重叠就串行执行不要并行。在 spec 阶段就让 agent 明确列出会修改的文件检查这些文件和现有任务是否冲突。比如一个任务要改api/users.py另一个任务要改api/users.py那就不应该同时跑。哪怕两个改动看起来互不相关合并时也容易出问题。6.3 失败重试与状态机agent 任务必然会出现失败模型调用超时、测试挂掉、依赖安装失败、网络抖动。失败以后能不能恢复是判断工具落地程度的重要指标。建议把每个任务建模成状态机pending等待处理。spec_reviewspec 已生成等待审批。implementingspec 已批准正在写代码。pr_readyPR 已创建等待最终 review。blocked需要人工介入。出现异常时先进入blocked而不是自动重试。自动重试适合问题是临时的例如网络超时但如果问题是 spec 方案不对重试多少次都没用只会浪费模型调用时间。6.4 控制成本模型调用和超时agent 每次读取代码、生成 spec、实现代码都会消耗模型调用。仓库越大、任务越复杂成本越高。建议在一开始就设置调用上限或任务超时时间。示例参考配置项建议值说明单个任务超时30 分钟避免无限卡住并发任务数1 到 2一开始一定从 1 开始单个任务读取文件数20 个内防止 agent 读太多无关文件模型输出 token 上限4000 到 8000防止 spec 或 diff 被截断等跑稳定后再逐步放宽。把资源拉满不是效率是给自己制造排查负担。7. 什么团队和任务适合用这套机制什么场景不要硬套看一个自动化工具好不好不能只看 Demo要看它适合长在什么流程里。AgentMachinist 这套机制并不是所有开发任务都适用。7.1 适合自动化处理的任务特征如果任务满足以下条件成功率会比较高验收标准明确能够用文字或命令表达。改动范围收敛例如新增接口、修 bug、补测试。仓库已有测试覆盖agent 能通过跑测试验证自己的改动。代码规范和目录结构清晰agent 可以快速定位相关文件。不需要和真实用户反复确认交互细节。典型的例子是新增一个轻量接口、修复某个已知 bug、给某个模块补充单元测试、重构一个函数的内部实现但不改变外部行为。7.2 适合承接这套机制的团队流程团队需要具备两个条件。第一有人愿意做 spec 审批。这个角色不一定非常资深但必须了解需求背景和代码结构。他需要在 agent 生成 spec 后花几分钟检查方向而不是等到 PR 阶段才看。第二CI 足够可靠。agent 写完代码后需要依赖测试和静态检查来判断自己是否完成。如果 CI 形同虚设agent 很容易在错误的方向上继续前进。如果团队已经养成了“先方案、后代码”的习惯那么 AgentMachinist 的适应成本会非常低。它只是把原本开会确认方案的过程变成了线上审批 spec 的过程。7.3 不适合的场景和我的建议遇到下面这些情况建议不要急着上 agent需求高度依赖业务判断例如“重新设计用户激励体系”。对代码出处有严格的合规要求不允许第三方模型接触源码。仓库结构混乱测试缺失agent 无法判断自己的改动是否安全。团队没有时间 review spec认为“AI 应该自己搞定一切”。在这些场景下硬套只会得到一堆“看起来完成但实际不能上线”的 PR。工具本身没有错是任务上下文不合适。7.4 从最小闭环开始推进如果你想在团队里引入 AgentMachinist我不建议第一次就开放给整个仓库所有 issue。可以先从下面几步做起选一个最边缘、最独立的 issue例如给某个工具函数增加日志。在最小实验仓库里完整跑一遍 spec 审批和 PR 流程。把流程跑顺后再在真实仓库的pinned/marked标签上启用。观察几次任务后再逐步放开范围。这一步是为了建立信任。只有当你亲眼看到 agent 按已批准的 spec 产出 PR并且 reviewer 能快速核对才会放心把它用于更多场景。结尾处我想说一个自己的感受这类自动化工具真正能落地的关键往往不是模型多强而是流程里有没有一个明确的“对账点”。AgentMachinist 用 SHA 把 spec 批准和代码实现绑在一起让人类检查和 AI 执行之间不再是两个模糊的黑箱。如果你也在做类似的 agent 开发流程最值得学的不是具体命令而是“先让方向被批准再让执行有凭据”这个思路。先从小仓库、单任务开始把 spec 评审和 SHA 校验跑扎实再谈批量和全自动化。 
