很多人用 AI 编程助手时都会遇到同一个尴尬AI 生成的代码跑得通但跟需求对不上。你让它修一个 issue它给你重构了整个模块你让它加个按钮它顺手改了接口签名。更麻烦的是评审 PR 的时候你根本看不出这段代码当初是为了解决哪个问题、依据的是哪个版本的方案。如果你也在这个困境里那么 AgentMachinist 这个项目提出的思路——“从 issue 到已评审 PR且带 SHA-bound 规范批准”非常值得认真了解一下。我的核心判断是AgentMachinist 真正想解决的不是“让 AI 写更多代码”而是“让 AI 写的代码在需求层面可控、在评审层面可追溯”。它把软件工程里最容易被忽视的“需求-设计-实现”链路用 SHA 绑定和审批机制重新串联起来。这篇文章不打算只给你复述项目名而是会拆解它背后的工作流、与传统 AI 编程方式的差异、以及假设你自己要落地这套流程时应该怎么设计、怎么配置、怎么验证、怎么避坑。读完你会收获三件事第一理解 SHA-bound spec approval 到底是什么意思、为什么重要第二掌握一套从 GitHub issue 到规范批准、再到生成 PR 的可执行工作流第三获得一份可以直接参考的配置、命令和排查清单方便你后续在真实项目里试验。1. 这篇文章真正要解决的问题先问你一个问题你在 GitHub 上收到一个 issue说“登录页在移动端布局错乱”你会怎么处理大多数人的流程是看 issue → 本地起环境 → 找到对应组件 → 改代码 → 提交 PR → 等人评审。这个流程你每天都会走但它其实埋着很多雷。issue 本身描述往往不精确改代码的人只能“猜”需求改了之后没人知道这份代码对应的方案是哪一个版本评审时只能看 diff却看不到 diff 背后的设计意图。如果你的项目里还有 AI 参与生成代码那问题会放大AI 可能写出一个“看起来合理但根本不是你想要方案”的 PR而你没法在评审时低成本地发现这一点。AgentMachinist 针对的正是这个问题。它的核心思路可以拆成四个关键词Issue一切从真实问题出发而不是凭空写代码。Spec需求被转成一份可评审、可修改的规范文档先理顺方案再写实现。SHA-bound规范文档通过某种方式“锁定”到一个具体的 Git 提交 SHA 上让方案和代码版本严格对应。Reviewed PR生成出来的 PR 不是裸代码而是带着可追溯来源的变更评审过程仍然保留人的决策权。换句话说它试图把“AI 直接生成代码”这种一步到位改造成“AI 先生成方案人批准方案AI 再按批准方案写代码”的分阶段流程。这个改动看起来简单实际影响的是团队协作、需求变更管理、代码评审质量这几件大事。这篇文章最适合三类读者一是已经在用 ChatGPT、Copilot 等工具写代码、但对结果质量不放心的人二是维护开源项目或团队仓库、每天被大量 issue 和 PR 缠身的维护者三是对 AI Agent 工作流设计感兴趣的开发者。如果你只是想找个工具一键生成代码那这篇文章的思路反而会让你慢下来但这种慢很多时候是值得的。2. 核心概念Issue、PR 与 SHA-bound Spec Approval在深入工作流之前先把这些术语讲透。因为很多人最初接触 GitHub 时都会困惑issue 到底有什么用PR 怎么下载、怎么初始化其实这些问题背后都是没有把“问题”和“解决方案”分开管理。2.1 Issue问题的“正式入口”Issue 在 GitHub 里就是一张问题卡片可以是 bug 报告、功能建议、讨论主题。它承载的信息包括现象描述、复现步骤、环境信息、期望行为。为什么说它是流程入口因为好的 issue 本身就是一份需求雏形。如果 issue 本身就写得模糊后面生成 spec 和 PR 都不可能准确。在实践中我们常看到“issue 即沟通记录”但实际上 issue 更应该是一份契约描述了“现状是什么、期望是什么、验收标准是什么”。2.2 PR代码变更的“评审单元”PRPull Request是代码变更的载体。它把分支上的提交集中到一起请求合并进目标分支。评审者可以在 PR 里查看 diff、发表评论、要求修改。PR 本身是一个沟通界面它让代码审查成为可能。很多新手问“PR 怎么下载”“PR 初始化失败怎么办”其实是把 PR 当成了一个可安装的软件包或一个分支。实际上下载 PR 本质上是git fetch获取对应分支初始化失败往往是本地仓库状态没对。后面我们会给出常见排查。2.3 Spec让 AI 先想清楚再动手Spec 就是规格说明描述“我们要做什么、怎么做、边界在哪里”。在 AI 辅助开发场景里spec 尤其重要。因为 AI 并不理解你的业务上下文你如果不给它一份明确的方案它就会凭训练数据里的“最大可能性”生成代码。结果就是表面上语法正确实际上逻辑与预期相去甚远。Spec 的作用就是给 AI 一个约束框让它的代码生成从自由发挥变成有据可依。2.4 SHA-bound规范与代码版本的锚定SHA 是 Git 里每个提交对应的哈希值可以把它理解成一个不可篡改的指纹。SHA-bound 的意思是某份 spec 文档和某个具体的 Git 提交 SHA 绑定在一起。为什么要绑定因为 spec 可能会被修改。假设你在 2025 年 6 月 1 号批准了一个 specAI 基于它生成了代码。6 月 2 号如果你悄悄修改了 spec但代码还是旧的那 spec 就失去了约束力。反过来也一样如果代码版本变了但 spec 还是旧版评审者就会困惑“这个 PR 到底按哪版方案做的”。绑定 SHA 之后任何人都可以随时检查当前代码对应的方案是不是你在某个时间点批准的那一版。这本质上是给“AI 生成代码”建立了不可抵赖的审计链路。2.5 Spec Approval人仍然在决策环上很多人担心 AI Agent 会取代程序员但 AgentMachinist 这类思路恰恰相反它把人放在关键决策点上。approval 意味着 AI 不会直接把代码推到 PR而是先生成 spec等待人来批准。批准之后AI 才继续实现。这保证了最终的产品决策权在人类手里AI 只是一个高效的执行者。这五个概念合在一起构成一个闭环issue 描述问题 → spec 定义方案 → SHA-bound 锁定版本 → approval 人工确认 → PR 提交代码。这个闭环正是 AgentMachinist 的价值所在。3. 与传统 AI 编程工作流的对比现在市面上的 AI 编程工具无论叫 Copilot、Cursor 还是 Claude Code多数遵循“对话即生成”的模式你给一段需求它直接返回代码。这种模式对“小任务”很爽但对正经工程项目来说存在明显的结构性缺陷。先看一个典型传统 AI 工作流用户 → 提示词 → AI → 直接生成 diff → 用户人工检查 → 提交 PR问题在哪里第一提示词本身往往没有经过评审AI 理解的“需求”和用户脑海里的一致纯靠运气第二AI 生成代码后用户很难逐行审查大 diff绝大多数人看一眼测试过了就合了第三一旦需求中途变化AI 可能继续基于旧上下文生成新代码导致仓库里出现多个版本方案的混血。AgentMachinist 的工作流更接近Issue → Agent 生成 Spec → SHA-bound 绑定到基础分支提交 → 人批准 Spec → Agent 实现代码 → 生成 Reviewed PR对比之下有几个关键差异决策前移传统流程是“先写代码再发现问题”新流程是“先写方案再写代码”。方案错了成本很低代码错了成本高得多。可追溯性传统流程的 PR 很难说清“为什么这么改”新流程里 PR 可以关联到一份带 SHA 的 spec谁批准的、批准的是哪一版一目了然。评审效率评审者看 PR 时可以把 spec 当作对照表逐个检查实现是否偏离方案。而不是面对一堆代码猜意图。AI 自由度传统流程给 AI 的自由度过大SHA-bound spec 把自由度限制在方案范围内。这对 AI 反而是一种保护因为它的输出更容易通过评审。当然这套流程不是没有代价。它比“直接生成代码”多了一个 spec 编写和审批环节更适合中大型需求而不是“修个错别字”这种小改动。如果你的团队每天要处理海量 trivial PR这套流程会显得过重但如果你的项目涉及业务核心逻辑、支付、权限、数据一致性那么多花一个 spec 审批环节非常值得。4. 核心工作流拆解从 Issue 到 Reviewed PR下面把 AgentMachinist 的核心流程拆成六个步骤。虽然我们可能无法拿到它的官方具体实现但我们可以基于项目名给出的理念按软件工程最佳实践推导一套可运行的流程。你在自己项目里落地时完全可以用这套结构做参考。4.1 步骤一选择或创建一个 Issue一切从 issue 开始。这不是形式主义而是为了给后面所有步骤一个信息锚点。Agent 在工作时需要读取 issue 描述提取出“问题现象”“期望行为”“验收标准”。所以对 issue 的质量要求很高。建议团队维护一个 issue 模板至少包含问题描述现状期望行为复现步骤如果是 bug影响范围验收标准4.2 步骤二Agent 基于 Issue 生成 SpecAgent 读取 issue 后会生成一份 spec 文档。这份 spec 不是简单的需求重述而是包含技术选型、改动范围、涉及文件、测试策略的工程方案。它可以被仓库里的任何人 review 和修改。在这一步人可以在 spec 尚未批准之前直接给 Agent 反馈要求它调整方案。4.3 步骤三SHA-bound 绑定当 spec 达到可讨论状态后需要把它提交到仓库或某个管理位置并记录下当前基线分支的 SHA。这里的“SHA-bound”可以有两种实现方式方式一把 spec 作为仓库内文件提交到specs/目录它的 commit SHA 即绑定依据。方式二在 spec 元数据里记录base_sha指向代码实现所依赖的基础分支最新提交 SHA。两种方式可以结合。绑定完成后任何后续代码实现都必须声明自己基于哪一个 SHA 的 spec。如果 spec 变了SHA 会变代码实现就应该重新生成。4.4 步骤四人工 Spec Approval批准环节是整个流程的灵魂。Agent 不能自己批准自己。需要指定一个 reviewer可以是维护者或团队指定角色对 spec 进行评审检查方案是否匹配 issue 需求。技术选型是否合理。改动范围是否最小化。测试策略是否覆盖关键场景。批准可以通过 GitHub 的 PR review、approval 按钮、或者 CI 状态实现。关键在于批准动作需要留下记录并且与 SHA 绑定。4.5 步骤五Agent 基于批准后的 Spec 生成代码当 spec 被批准后Agent 才被允许开始写代码。它会严格对照 spec 中的改动范围和设计实现。这个阶段Agent 可以自主完成多文件修改、测试编写、甚至本地验证。但如果实现过程中发现 spec 中有不合理之处应该停下来而不是自己扩展需求。这一步对应到实现上可能是 Agent 在沙箱环境中工作然后提交到分支创建 PR。4.6 步骤六生成 Reviewed PR最后Agent 生成一个包含完整描述的 PRPR 描述中必须关联对应的 issue 和 spec并说明绑定 SHA。整个 PR 仍然走普通的 code review 流程人类 reviewer 可以进一步提出修改意见。也就是说Agent 把“从 issue 到可评审的 PR”这一段自动化了但最终合并权仍然在人类手上。5. 环境准备与接入思路虽然我们还没有拿到 AgentMachinist 官方的安装包但作为一个 GitHub 生态下的 Agent 项目可以合理推断它的运行环境要求。下面给出一个通用的接入参考你看的时候可以根据项目实际文档调整版本。5.1 基础运行环境Git 2.30用于克隆仓库、切换分支、读取 SHA。GitHub CLIgh或 GitHub API Token用于操作 issue、PR、review。Python 3.10 / Node.js 18取决于 Agent 运行时实现这里不写死。一个可调用的 LLM APIAgent 需要通过它来生成 spec 和代码。Docker 可选用于沙箱化执行。如果你的团队还没有统一的开发容器建议把 Agent 跑在独立环境或 CI 容器里避免它对本地文件系统造成意外修改。5.2 权限模型接入这个工作流时权限设计很关键。推荐遵循最小权限原则Agent 使用的 GitHub Token 只能访问目标仓库不要全局授权。Agent 不能直接合并 PR只能创建分支和 PR。Spec 批准权限只授予 maintainer 或 tech lead。生产分支main/master禁止 Agent 直接推代码。5.3 配置文件示例假设 AgentMachinist 使用类似 YAML 的配置文件我们可以设计一份最小配置。下面这个文件不是官方真实配置更多是演示思路# agentmachinist.config.yml repo: owner: your-org name: your-repo base-branch: main agent: model: your-llm-model max-tokens: 8192 spec: directory: specs/ require-approval: true approval-method: github-review sha-bound: true workflow: auto-create-pr: true pr-reviewers: - senior-dev labels: - ai-generated配置里最需要关注三个字段sha-bound是否开启、approval-method用什么方式批准、auto-create-pr是否允许 Agent 自动建 PR。建议在你还没完全信任 Agent 前把auto-create-pr设为 false让 Agent 只生成代码分支人工决定何时建 PR。5.4 初始化仓库在目标仓库里执行git clone gitgithub.com:your-org/your-repo.git cd your-repo git checkout -b specs/init mkdir specs echo # Specs Directory specs/README.md git add specs/README.md git commit -m docs: init specs directory git push -u origin specs/init这一步的目的是给 spec 文档一个独立目录。如果你不想让 spec 和代码仓库混在一起也可以用单独的 spec 仓库但在 SHA 绑定时要注意跨仓库的提交一致性。6. 完整示例用脚本模拟 AgentMachinist 流程为了让概念更落地下面我用一个可运行的脚本示例模拟“从 issue 到 SHA-bound spec 批准”的最小闭环。这个示例不是 AgentMachinist 官方实现而是用来帮助我们理解流程。6.1 示例场景仓库里有一个 issue #42内容为“修复登录页在移动端布局错乱”。我们希望通过脚本完成读取 issue 标题和正文生成 initial spec 文件。记录当前 base 分支的 SHA。生成一份包含 SHA 信息的 spec 元数据。创建 spec PR 供人工批准这里我们用命令行模拟批准。输出批准后的 SHA 绑定信息留作后续生成代码使用。6.2 脚本实现这里用一个 Python 脚本做演示。它使用ghCLI 访问 GitHub所以你需要先配置好gh auth login。# scripts/agentmachinist_demo.py AgentMachinist 工作流演示脚本概念示例非官方实现 功能从 GitHub issue 生成 SHA-bound spec并模拟人工批准 import json import subprocess import sys from datetime import datetime def run_cmd(cmd: list[str]) - str: 执行命令并返回 stdout result subprocess.run(cmd, capture_outputTrue, textTrue, checkTrue) return result.stdout.strip() def fetch_issue(repo: str, issue_number: str) - dict: 通过 gh 命令获取 issue 信息 output run_cmd([gh, issue, view, issue_number, --repo, repo, --json, title,body]) return json.loads(output) def generate_spec(issue: dict) - str: 模拟 Agent 基于 issue 生成 spec 内容 title issue[title] body issue[body] # 在真实场景中这里会调用 LLM API 生成更结构化的 spec return f# Spec: {title} ## Problem Statement {body} ## Proposed Change - 修改移动端登录页样式 - 保持桌面端交互不变 - 补充移动端响应式测试 ## Files to Modify - src/pages/Login.tsx - src/styles/login.css - src/__tests__/Login.test.tsx ## Definition of Done - 移动端视口下所有元素无溢出 - 现有测试全部通过 - 新增移动端布局测试 def get_base_sha(repo: str, base_branch: str) - str: output run_cmd([gh, api, frepos/{repo}/git/ref/heads/{base_branch}]) return json.loads(output)[object][sha] def write_spec_file(spec_content: str, issue_number: str, sha: str) - str: 将 spec 写入文件并在 YAML 头部包含 SHA 绑定信息 spec_path fspecs/issue-{issue_number}.md header f---\nissue: {issue_number}\nbase_sha: {sha}\ncreated_at: {datetime.now().isoformat()}\n---\n\n with open(spec_path, w, encodingutf-8) as f: f.write(header spec_content) return spec_path def create_spec_pr(repo: str, branch: str, issue_number: str, commit_message: str) - str: 创建 spec PR用于人工 review 与批准 run_cmd([git, checkout, -b, branch]) run_cmd([git, add, specs/]) run_cmd([git, commit, -m, commit_message]) run_cmd([git, push, -u, origin, branch]) output run_cmd([gh, pr, create, --repo, repo, --title, fSpec for issue #{issue_number}, --body, Please review this spec.]) return output def approve_spec_pr(repo: str, pr_url: str) - None: 模拟人工批准。正常流程应由 reviewer 在 GitHub 上点击批准。 # 这里使用 API 添加评论作为批准标记实际批准请使用评审接口 run_cmd([gh, pr, comment, pr_url, --repo, repo, --body, Approved by demo script.]) def main(): repo your-org/your-repo issue_number 42 base_branch main print([1/5] 获取 issue 信息...) issue fetch_issue(repo, issue_number) print([2/5] 生成 spec 内容...) spec_content generate_spec(issue) print([3/5] 获取 base 分支 SHA...) base_sha get_base_sha(repo, base_branch) print(f 绑定 SHA: {base_sha}) print([4/5] 写入 spec 文件...) spec_path write_spec_file(spec_content, issue_number, base_sha) print(f 生成文件: {spec_path}) print([5/5] 创建 spec PR 并模拟批准...) branch fspec/issue-{issue_number} pr_url create_spec_pr( repo, branch, issue_number, fdocs: add spec for issue #{issue_number} [SHA{base_sha[:8]}] ) print(f PR 地址: {pr_url}) approve_spec_pr(repo, pr_url) print(\n工作流完成。下一步基于已批准的 spec 生成代码 PR。) if __name__ __main__: main()6.3 关键逻辑说明这个脚本的核心不是代码本身而是这几个动作get_base_sha通过 GitHub API 获取 base 分支最新 SHA这一步就是 SHA-bound 中的“绑定”。write_spec_file把 SHA 写进 spec 文件的 YAML header让 spec 与 base SHA 产生机器可读的关联。create_spec_pr把 spec 作为一次完整的 PR 提出来供人评审批准。approve_spec_pr模拟了人工批准动作在实际系统中应该使用 GitHub 的 review API 而不是简单评论。如果你把这套脚本接到真实 Agent 上那么后续生成代码时Agent 必须读取 spec 文件中的base_sha作为它要拉取的代码基线。这能避免一个问题当你正在开发 main 分支时AI 却基于一个旧的或者被污染的分支生成代码。6.4 运行前检查运行脚本前请确保本地已经登录ghgh auth status当前目录是仓库根目录仓库中不存在同名分支spec/issue-42你对仓库有写权限命令pip install -r requirements.txt # 这个示例不需要额外依赖 python scripts/agentmachinist_demo.py如果一切正常最后会输入一个 PR 地址。这个 PR 展示的就是“被 SHA 绑定的 spec 文档”。7. 运行结果与效果验证当你创建了 spec PR 后如何判断这套流程是否成功不能只看“PR 创建成功”要检查以下内容。7.1 预期输出执行脚本后你会看到类似这样的输出[1/5] 获取 issue 信息... [2/5] 生成 spec 内容... [3/5] 获取 base 分支 SHA... 绑定 SHA: 3f9c19a1c2b1d5e6f7a8b9c0d1e2f3a4b5c6d7e8 [4/5] 写入 spec 文件... 生成文件: specs/issue-42.md [5/5] 创建 spec PR 并模拟批准... PR 地址: https://github.com/your-org/your-repo/pull/123然后你打开 PR 页面应该看到 spec 文件的 diff。重点检查 spec 文件头部--- issue: 42 base_sha: 3f9c19a1c2b1d5e6f7a8b9c0d1e2f3a4b5c6d7e8 created_at: 2025-06-10T12:00:00 ---这个 header 表示这份 spec 对应 issue #42并且它的代码基线是3f9c19...这个提交。任何后续生成的代码都应从这一版代码开始。7.2 如何判断成功判断标准主要有三个spec PR 被成功创建并且包含 SHA 信息。有人工 reviewer 的批准记录而不仅是脚本模拟的评论。批准后的 spec 可以稳定对应到同一个 SHA如果 main 分支更新了spec 的 SHA 需要显式更新而不是悄悄变化。如果这三条都满足说明 SHA-bound spec approval 的第一步闭环就建立了。7.3 失败排查第一步如果脚本在gh issue view那一步报错先检查仓库名和 issue 号是否正确以及gh auth status是否已认证。如果报gh api错误多半是权限不足请把 token 的权限范围扩大到该仓库的读写。如果git push报错检查远程仓库是否已经存在同名分支可以手动删除或换个分支名。8. 常见问题与排查思路下面是这套工作流里最常遇到的几个问题。注意我在这里把“Agent 工具”和“GitHub 基础操作”的问题都放在一起因为它们同样会阻断整个链路。问题现象可能原因排查方式解决方案issue 获取失败gh 未认证或 token 权限不足执行gh auth status确认 token 有 repo 权限重新gh auth login或生成新 tokenspec PR 创建失败分支已存在或仓库无写权限查看git push报错信息删除远程同名分支或检查 collaborator 权限SHA 绑定信息缺失spec 模板里没有写入 base_sha打开 spec 文件查看 header修改生成逻辑确保写入 SHAAI 生成代码不遵循 spec提示词未明确引用 spec 文件检查 Agent 的输入上下文在系统提示词中加入“严格按 specs/issue-XX.md 实现”PR 初始化失败本地分支状态不干净执行git statusstash 或提交本地改动有人在 issue 里问“PR 怎么下载”新手混淆 issue 和 PR 概念解释 PR 是变更请求不是可下载文件用git fetch origin pull/id/head获取 PR 分支模型 API 返回 529 overloadedLLM 服务端过载查看 API 日志增大重试策略或切换备用模型spec 批准后 main 分支又更新了SHA 绑定过期查看 spec 中的 base_sha如果实现依赖旧基线rebase 后更新 spec SHA 并重新批准这里我想特别强调“SHA 过期”这个坑。假设你批准了一个 spec绑定的 SHA 是3f9c19。两天后main 分支合入了别人的代码变成a1b2c3。如果你仍然让 Agent 基于3f9c19生成代码那么新代码和 main 分支上的最新代码之间可能出现严重冲突。正确做法是重新生成 spec 或至少更新 base_sha再走一次批准。只有这样SHA-bound 才能真正保证“方案与代码版本一致”。9. 最佳实践与工程建议这套工作流如果要在团队里落地光有工具还不够还需要配套流程和规范。下面几条建议来自我接触过的工程实践比较适合中等规模团队。9.1 将 Spec 视为一等公民很多团队把 spec 当成“写代码之前的草稿”写完之后就不管了。但在 AgentMachinist 流程里spec 必须像代码一样纳入版本管理。建议在仓库里固定一个specs/目录并规定任何 Agent 生成的实现必须关联一个 spec 文件。没有 spec 文件的 AI 代码默认不合并。9.2 定义清晰的批准规则让 Agent 自己判断“该不该通过”是危险的。你需要定义谁可以批准 spec建议至少一名资深工程师。批准需要几人关键模块建议两人。批准后还能不能改 spec可以但必须通过新的 commit 并更新 SHA。approval 如何记录用 GitHub 的 pull request review而不是随意评论。这些规则最好写进CONTRIBUTING.md或 Agent 的配置里。9.3 严格控制 Agent 权限Agent 使用的 token 应该是最小权限。它需要创建分支、推代码、创建 PR但不需要删除仓库、不需要改 settings、不需要合并 PR。GitHub 支持 fine-grained token建议按仓库级别授权并把 token 的过期时间设短一点。如果项目安全要求高可以把 Agent 放到独立 GitHub App 里通过签发短期 token 访问仓库。9.4 提示词工程要与流程配合Agent 生成 spec 和代码的质量取决于你给它什么上下文。在系统提示词中建议明确仓库目录结构。相关技术栈。依赖的 spec 文件路径。必须遵守的 lint 和测试命令。禁止擅自扩大改动范围。下面是一个示例提示词片段你是仓库 {your-org/your-repo} 的资深工程师。你会根据 issues 目录中的 issue 创建 spec。 你必须 1. 先读取规格文件 specs/issue-{N}.md了解其中的 base_sha 和改动范围。 2. 只修改 spec 里列出的文件。 3. 不得添加 spec 之外的特性。 4. 修改后运行测试命令 npm test 并确保通过。 5. 提交 PR并在描述中引用 spec 的 base_sha。这段提示词本身不复杂但它能明显减少 AI 自由发挥的概率。9.5 使用标签和模板提高可操作性在 GitHub 里可以为 AI 创建的 PR 自动打上标签例如ai-generated、needs-spec-review。这能让维护者在列表页快速识别并且可以在 CI 里设置“没有关联 spec 的 AI PR 不允许合并”。同时给 issue 准备模板减少无效信息。9.6 安全与回滚AI 生成的代码同样可能引入安全风险。即使它有 spec 和人工审批也不能省略安全评审。建议在 CI 中加入静态扫描和依赖检查。如果生成代码在生产环境出现问题要能通过 spec 里记录的 SHA 快速回滚到具体提交。回滚时要注意回滚代码之后对应的 spec SHA 也需要同步回退否则下一次 Agent 会基于错误的 spec 继续工作。9.7 渐进式灰度不建议第一天就让 Agent 全自动处理所有 issue。可以先选一个低风险模块做试点例如文档站、非核心组件。运行一两周观察 PR 通过率和 review 成本再逐步扩大范围。如果发现 Agent 经常不遵守 spec优先检查提示词和 spec 模板而不是立刻换模型。10. 总结与后续学习方向AgentMachinist 提出的“issue to reviewed PR with a SHA-bound spec approval”本质上是用工程化手段约束 AI 代码生成的自由度。它没有把 AI 当做一个“万能程序员”而是把它放进了“需求分析 → 方案设计 → 人工批准 → 代码实现 → 评审合入”的完整生产链路里。SHA-bound 这个设计尤其值得在 AI 辅助开发中推广因为它回答了团队最常问的一个问题我们怎么确认 AI 写的代码是对应着哪个版本的方案写出来的如果你接下来想实践建议按这个顺序走先在自己可控的仓库里用 issue 模板 spec 目录 手动批准模拟一遍再把 spec 生成和代码生成用脚本串起来最后再接入 Agent 和自动 PR。每一步都要验证 SHA 绑定是否真的贯穿始终否则流程会退化成“AI 生成一个格式漂亮的 spec然后继续自由发挥”。这套思路也可以延伸到更广的范围。比如把它和 CI 系统的“spec 变更即自动化回归”结合或者扩展成“一个 spec 对应多个实现模块”的架构管理方式。AI 编程工具还有很多潜力但决定它们是否可靠的关键往往不是模型能力本身而是我们愿不愿意在工程流程上多设计几个“安全阀”。AgentMachinist 给了我们一个不错的起点。如果你正在被 AI 生成代码不可控的问题困扰建议把本文提到的 SHA-bound spec 思路保存下来下次让 AI 帮你修改代码之前先逼它写一份带 SHA 绑定的方案。你会发现很多“代码写错”的问题在方案阶段就已经被拦截了。 从Issue到已评审PR：SHA-bound规范批准如何让AI代码真正可控
很多人用 AI 编程助手时都会遇到同一个尴尬AI 生成的代码跑得通但跟需求对不上。你让它修一个 issue它给你重构了整个模块你让它加个按钮它顺手改了接口签名。更麻烦的是评审 PR 的时候你根本看不出这段代码当初是为了解决哪个问题、依据的是哪个版本的方案。如果你也在这个困境里那么 AgentMachinist 这个项目提出的思路——“从 issue 到已评审 PR且带 SHA-bound 规范批准”非常值得认真了解一下。我的核心判断是AgentMachinist 真正想解决的不是“让 AI 写更多代码”而是“让 AI 写的代码在需求层面可控、在评审层面可追溯”。它把软件工程里最容易被忽视的“需求-设计-实现”链路用 SHA 绑定和审批机制重新串联起来。这篇文章不打算只给你复述项目名而是会拆解它背后的工作流、与传统 AI 编程方式的差异、以及假设你自己要落地这套流程时应该怎么设计、怎么配置、怎么验证、怎么避坑。读完你会收获三件事第一理解 SHA-bound spec approval 到底是什么意思、为什么重要第二掌握一套从 GitHub issue 到规范批准、再到生成 PR 的可执行工作流第三获得一份可以直接参考的配置、命令和排查清单方便你后续在真实项目里试验。1. 这篇文章真正要解决的问题先问你一个问题你在 GitHub 上收到一个 issue说“登录页在移动端布局错乱”你会怎么处理大多数人的流程是看 issue → 本地起环境 → 找到对应组件 → 改代码 → 提交 PR → 等人评审。这个流程你每天都会走但它其实埋着很多雷。issue 本身描述往往不精确改代码的人只能“猜”需求改了之后没人知道这份代码对应的方案是哪一个版本评审时只能看 diff却看不到 diff 背后的设计意图。如果你的项目里还有 AI 参与生成代码那问题会放大AI 可能写出一个“看起来合理但根本不是你想要方案”的 PR而你没法在评审时低成本地发现这一点。AgentMachinist 针对的正是这个问题。它的核心思路可以拆成四个关键词Issue一切从真实问题出发而不是凭空写代码。Spec需求被转成一份可评审、可修改的规范文档先理顺方案再写实现。SHA-bound规范文档通过某种方式“锁定”到一个具体的 Git 提交 SHA 上让方案和代码版本严格对应。Reviewed PR生成出来的 PR 不是裸代码而是带着可追溯来源的变更评审过程仍然保留人的决策权。换句话说它试图把“AI 直接生成代码”这种一步到位改造成“AI 先生成方案人批准方案AI 再按批准方案写代码”的分阶段流程。这个改动看起来简单实际影响的是团队协作、需求变更管理、代码评审质量这几件大事。这篇文章最适合三类读者一是已经在用 ChatGPT、Copilot 等工具写代码、但对结果质量不放心的人二是维护开源项目或团队仓库、每天被大量 issue 和 PR 缠身的维护者三是对 AI Agent 工作流设计感兴趣的开发者。如果你只是想找个工具一键生成代码那这篇文章的思路反而会让你慢下来但这种慢很多时候是值得的。2. 核心概念Issue、PR 与 SHA-bound Spec Approval在深入工作流之前先把这些术语讲透。因为很多人最初接触 GitHub 时都会困惑issue 到底有什么用PR 怎么下载、怎么初始化其实这些问题背后都是没有把“问题”和“解决方案”分开管理。2.1 Issue问题的“正式入口”Issue 在 GitHub 里就是一张问题卡片可以是 bug 报告、功能建议、讨论主题。它承载的信息包括现象描述、复现步骤、环境信息、期望行为。为什么说它是流程入口因为好的 issue 本身就是一份需求雏形。如果 issue 本身就写得模糊后面生成 spec 和 PR 都不可能准确。在实践中我们常看到“issue 即沟通记录”但实际上 issue 更应该是一份契约描述了“现状是什么、期望是什么、验收标准是什么”。2.2 PR代码变更的“评审单元”PRPull Request是代码变更的载体。它把分支上的提交集中到一起请求合并进目标分支。评审者可以在 PR 里查看 diff、发表评论、要求修改。PR 本身是一个沟通界面它让代码审查成为可能。很多新手问“PR 怎么下载”“PR 初始化失败怎么办”其实是把 PR 当成了一个可安装的软件包或一个分支。实际上下载 PR 本质上是git fetch获取对应分支初始化失败往往是本地仓库状态没对。后面我们会给出常见排查。2.3 Spec让 AI 先想清楚再动手Spec 就是规格说明描述“我们要做什么、怎么做、边界在哪里”。在 AI 辅助开发场景里spec 尤其重要。因为 AI 并不理解你的业务上下文你如果不给它一份明确的方案它就会凭训练数据里的“最大可能性”生成代码。结果就是表面上语法正确实际上逻辑与预期相去甚远。Spec 的作用就是给 AI 一个约束框让它的代码生成从自由发挥变成有据可依。2.4 SHA-bound规范与代码版本的锚定SHA 是 Git 里每个提交对应的哈希值可以把它理解成一个不可篡改的指纹。SHA-bound 的意思是某份 spec 文档和某个具体的 Git 提交 SHA 绑定在一起。为什么要绑定因为 spec 可能会被修改。假设你在 2025 年 6 月 1 号批准了一个 specAI 基于它生成了代码。6 月 2 号如果你悄悄修改了 spec但代码还是旧的那 spec 就失去了约束力。反过来也一样如果代码版本变了但 spec 还是旧版评审者就会困惑“这个 PR 到底按哪版方案做的”。绑定 SHA 之后任何人都可以随时检查当前代码对应的方案是不是你在某个时间点批准的那一版。这本质上是给“AI 生成代码”建立了不可抵赖的审计链路。2.5 Spec Approval人仍然在决策环上很多人担心 AI Agent 会取代程序员但 AgentMachinist 这类思路恰恰相反它把人放在关键决策点上。approval 意味着 AI 不会直接把代码推到 PR而是先生成 spec等待人来批准。批准之后AI 才继续实现。这保证了最终的产品决策权在人类手里AI 只是一个高效的执行者。这五个概念合在一起构成一个闭环issue 描述问题 → spec 定义方案 → SHA-bound 锁定版本 → approval 人工确认 → PR 提交代码。这个闭环正是 AgentMachinist 的价值所在。3. 与传统 AI 编程工作流的对比现在市面上的 AI 编程工具无论叫 Copilot、Cursor 还是 Claude Code多数遵循“对话即生成”的模式你给一段需求它直接返回代码。这种模式对“小任务”很爽但对正经工程项目来说存在明显的结构性缺陷。先看一个典型传统 AI 工作流用户 → 提示词 → AI → 直接生成 diff → 用户人工检查 → 提交 PR问题在哪里第一提示词本身往往没有经过评审AI 理解的“需求”和用户脑海里的一致纯靠运气第二AI 生成代码后用户很难逐行审查大 diff绝大多数人看一眼测试过了就合了第三一旦需求中途变化AI 可能继续基于旧上下文生成新代码导致仓库里出现多个版本方案的混血。AgentMachinist 的工作流更接近Issue → Agent 生成 Spec → SHA-bound 绑定到基础分支提交 → 人批准 Spec → Agent 实现代码 → 生成 Reviewed PR对比之下有几个关键差异决策前移传统流程是“先写代码再发现问题”新流程是“先写方案再写代码”。方案错了成本很低代码错了成本高得多。可追溯性传统流程的 PR 很难说清“为什么这么改”新流程里 PR 可以关联到一份带 SHA 的 spec谁批准的、批准的是哪一版一目了然。评审效率评审者看 PR 时可以把 spec 当作对照表逐个检查实现是否偏离方案。而不是面对一堆代码猜意图。AI 自由度传统流程给 AI 的自由度过大SHA-bound spec 把自由度限制在方案范围内。这对 AI 反而是一种保护因为它的输出更容易通过评审。当然这套流程不是没有代价。它比“直接生成代码”多了一个 spec 编写和审批环节更适合中大型需求而不是“修个错别字”这种小改动。如果你的团队每天要处理海量 trivial PR这套流程会显得过重但如果你的项目涉及业务核心逻辑、支付、权限、数据一致性那么多花一个 spec 审批环节非常值得。4. 核心工作流拆解从 Issue 到 Reviewed PR下面把 AgentMachinist 的核心流程拆成六个步骤。虽然我们可能无法拿到它的官方具体实现但我们可以基于项目名给出的理念按软件工程最佳实践推导一套可运行的流程。你在自己项目里落地时完全可以用这套结构做参考。4.1 步骤一选择或创建一个 Issue一切从 issue 开始。这不是形式主义而是为了给后面所有步骤一个信息锚点。Agent 在工作时需要读取 issue 描述提取出“问题现象”“期望行为”“验收标准”。所以对 issue 的质量要求很高。建议团队维护一个 issue 模板至少包含问题描述现状期望行为复现步骤如果是 bug影响范围验收标准4.2 步骤二Agent 基于 Issue 生成 SpecAgent 读取 issue 后会生成一份 spec 文档。这份 spec 不是简单的需求重述而是包含技术选型、改动范围、涉及文件、测试策略的工程方案。它可以被仓库里的任何人 review 和修改。在这一步人可以在 spec 尚未批准之前直接给 Agent 反馈要求它调整方案。4.3 步骤三SHA-bound 绑定当 spec 达到可讨论状态后需要把它提交到仓库或某个管理位置并记录下当前基线分支的 SHA。这里的“SHA-bound”可以有两种实现方式方式一把 spec 作为仓库内文件提交到specs/目录它的 commit SHA 即绑定依据。方式二在 spec 元数据里记录base_sha指向代码实现所依赖的基础分支最新提交 SHA。两种方式可以结合。绑定完成后任何后续代码实现都必须声明自己基于哪一个 SHA 的 spec。如果 spec 变了SHA 会变代码实现就应该重新生成。4.4 步骤四人工 Spec Approval批准环节是整个流程的灵魂。Agent 不能自己批准自己。需要指定一个 reviewer可以是维护者或团队指定角色对 spec 进行评审检查方案是否匹配 issue 需求。技术选型是否合理。改动范围是否最小化。测试策略是否覆盖关键场景。批准可以通过 GitHub 的 PR review、approval 按钮、或者 CI 状态实现。关键在于批准动作需要留下记录并且与 SHA 绑定。4.5 步骤五Agent 基于批准后的 Spec 生成代码当 spec 被批准后Agent 才被允许开始写代码。它会严格对照 spec 中的改动范围和设计实现。这个阶段Agent 可以自主完成多文件修改、测试编写、甚至本地验证。但如果实现过程中发现 spec 中有不合理之处应该停下来而不是自己扩展需求。这一步对应到实现上可能是 Agent 在沙箱环境中工作然后提交到分支创建 PR。4.6 步骤六生成 Reviewed PR最后Agent 生成一个包含完整描述的 PRPR 描述中必须关联对应的 issue 和 spec并说明绑定 SHA。整个 PR 仍然走普通的 code review 流程人类 reviewer 可以进一步提出修改意见。也就是说Agent 把“从 issue 到可评审的 PR”这一段自动化了但最终合并权仍然在人类手上。5. 环境准备与接入思路虽然我们还没有拿到 AgentMachinist 官方的安装包但作为一个 GitHub 生态下的 Agent 项目可以合理推断它的运行环境要求。下面给出一个通用的接入参考你看的时候可以根据项目实际文档调整版本。5.1 基础运行环境Git 2.30用于克隆仓库、切换分支、读取 SHA。GitHub CLIgh或 GitHub API Token用于操作 issue、PR、review。Python 3.10 / Node.js 18取决于 Agent 运行时实现这里不写死。一个可调用的 LLM APIAgent 需要通过它来生成 spec 和代码。Docker 可选用于沙箱化执行。如果你的团队还没有统一的开发容器建议把 Agent 跑在独立环境或 CI 容器里避免它对本地文件系统造成意外修改。5.2 权限模型接入这个工作流时权限设计很关键。推荐遵循最小权限原则Agent 使用的 GitHub Token 只能访问目标仓库不要全局授权。Agent 不能直接合并 PR只能创建分支和 PR。Spec 批准权限只授予 maintainer 或 tech lead。生产分支main/master禁止 Agent 直接推代码。5.3 配置文件示例假设 AgentMachinist 使用类似 YAML 的配置文件我们可以设计一份最小配置。下面这个文件不是官方真实配置更多是演示思路# agentmachinist.config.yml repo: owner: your-org name: your-repo base-branch: main agent: model: your-llm-model max-tokens: 8192 spec: directory: specs/ require-approval: true approval-method: github-review sha-bound: true workflow: auto-create-pr: true pr-reviewers: - senior-dev labels: - ai-generated配置里最需要关注三个字段sha-bound是否开启、approval-method用什么方式批准、auto-create-pr是否允许 Agent 自动建 PR。建议在你还没完全信任 Agent 前把auto-create-pr设为 false让 Agent 只生成代码分支人工决定何时建 PR。5.4 初始化仓库在目标仓库里执行git clone gitgithub.com:your-org/your-repo.git cd your-repo git checkout -b specs/init mkdir specs echo # Specs Directory specs/README.md git add specs/README.md git commit -m docs: init specs directory git push -u origin specs/init这一步的目的是给 spec 文档一个独立目录。如果你不想让 spec 和代码仓库混在一起也可以用单独的 spec 仓库但在 SHA 绑定时要注意跨仓库的提交一致性。6. 完整示例用脚本模拟 AgentMachinist 流程为了让概念更落地下面我用一个可运行的脚本示例模拟“从 issue 到 SHA-bound spec 批准”的最小闭环。这个示例不是 AgentMachinist 官方实现而是用来帮助我们理解流程。6.1 示例场景仓库里有一个 issue #42内容为“修复登录页在移动端布局错乱”。我们希望通过脚本完成读取 issue 标题和正文生成 initial spec 文件。记录当前 base 分支的 SHA。生成一份包含 SHA 信息的 spec 元数据。创建 spec PR 供人工批准这里我们用命令行模拟批准。输出批准后的 SHA 绑定信息留作后续生成代码使用。6.2 脚本实现这里用一个 Python 脚本做演示。它使用ghCLI 访问 GitHub所以你需要先配置好gh auth login。# scripts/agentmachinist_demo.py AgentMachinist 工作流演示脚本概念示例非官方实现 功能从 GitHub issue 生成 SHA-bound spec并模拟人工批准 import json import subprocess import sys from datetime import datetime def run_cmd(cmd: list[str]) - str: 执行命令并返回 stdout result subprocess.run(cmd, capture_outputTrue, textTrue, checkTrue) return result.stdout.strip() def fetch_issue(repo: str, issue_number: str) - dict: 通过 gh 命令获取 issue 信息 output run_cmd([gh, issue, view, issue_number, --repo, repo, --json, title,body]) return json.loads(output) def generate_spec(issue: dict) - str: 模拟 Agent 基于 issue 生成 spec 内容 title issue[title] body issue[body] # 在真实场景中这里会调用 LLM API 生成更结构化的 spec return f# Spec: {title} ## Problem Statement {body} ## Proposed Change - 修改移动端登录页样式 - 保持桌面端交互不变 - 补充移动端响应式测试 ## Files to Modify - src/pages/Login.tsx - src/styles/login.css - src/__tests__/Login.test.tsx ## Definition of Done - 移动端视口下所有元素无溢出 - 现有测试全部通过 - 新增移动端布局测试 def get_base_sha(repo: str, base_branch: str) - str: output run_cmd([gh, api, frepos/{repo}/git/ref/heads/{base_branch}]) return json.loads(output)[object][sha] def write_spec_file(spec_content: str, issue_number: str, sha: str) - str: 将 spec 写入文件并在 YAML 头部包含 SHA 绑定信息 spec_path fspecs/issue-{issue_number}.md header f---\nissue: {issue_number}\nbase_sha: {sha}\ncreated_at: {datetime.now().isoformat()}\n---\n\n with open(spec_path, w, encodingutf-8) as f: f.write(header spec_content) return spec_path def create_spec_pr(repo: str, branch: str, issue_number: str, commit_message: str) - str: 创建 spec PR用于人工 review 与批准 run_cmd([git, checkout, -b, branch]) run_cmd([git, add, specs/]) run_cmd([git, commit, -m, commit_message]) run_cmd([git, push, -u, origin, branch]) output run_cmd([gh, pr, create, --repo, repo, --title, fSpec for issue #{issue_number}, --body, Please review this spec.]) return output def approve_spec_pr(repo: str, pr_url: str) - None: 模拟人工批准。正常流程应由 reviewer 在 GitHub 上点击批准。 # 这里使用 API 添加评论作为批准标记实际批准请使用评审接口 run_cmd([gh, pr, comment, pr_url, --repo, repo, --body, Approved by demo script.]) def main(): repo your-org/your-repo issue_number 42 base_branch main print([1/5] 获取 issue 信息...) issue fetch_issue(repo, issue_number) print([2/5] 生成 spec 内容...) spec_content generate_spec(issue) print([3/5] 获取 base 分支 SHA...) base_sha get_base_sha(repo, base_branch) print(f 绑定 SHA: {base_sha}) print([4/5] 写入 spec 文件...) spec_path write_spec_file(spec_content, issue_number, base_sha) print(f 生成文件: {spec_path}) print([5/5] 创建 spec PR 并模拟批准...) branch fspec/issue-{issue_number} pr_url create_spec_pr( repo, branch, issue_number, fdocs: add spec for issue #{issue_number} [SHA{base_sha[:8]}] ) print(f PR 地址: {pr_url}) approve_spec_pr(repo, pr_url) print(\n工作流完成。下一步基于已批准的 spec 生成代码 PR。) if __name__ __main__: main()6.3 关键逻辑说明这个脚本的核心不是代码本身而是这几个动作get_base_sha通过 GitHub API 获取 base 分支最新 SHA这一步就是 SHA-bound 中的“绑定”。write_spec_file把 SHA 写进 spec 文件的 YAML header让 spec 与 base SHA 产生机器可读的关联。create_spec_pr把 spec 作为一次完整的 PR 提出来供人评审批准。approve_spec_pr模拟了人工批准动作在实际系统中应该使用 GitHub 的 review API 而不是简单评论。如果你把这套脚本接到真实 Agent 上那么后续生成代码时Agent 必须读取 spec 文件中的base_sha作为它要拉取的代码基线。这能避免一个问题当你正在开发 main 分支时AI 却基于一个旧的或者被污染的分支生成代码。6.4 运行前检查运行脚本前请确保本地已经登录ghgh auth status当前目录是仓库根目录仓库中不存在同名分支spec/issue-42你对仓库有写权限命令pip install -r requirements.txt # 这个示例不需要额外依赖 python scripts/agentmachinist_demo.py如果一切正常最后会输入一个 PR 地址。这个 PR 展示的就是“被 SHA 绑定的 spec 文档”。7. 运行结果与效果验证当你创建了 spec PR 后如何判断这套流程是否成功不能只看“PR 创建成功”要检查以下内容。7.1 预期输出执行脚本后你会看到类似这样的输出[1/5] 获取 issue 信息... [2/5] 生成 spec 内容... [3/5] 获取 base 分支 SHA... 绑定 SHA: 3f9c19a1c2b1d5e6f7a8b9c0d1e2f3a4b5c6d7e8 [4/5] 写入 spec 文件... 生成文件: specs/issue-42.md [5/5] 创建 spec PR 并模拟批准... PR 地址: https://github.com/your-org/your-repo/pull/123然后你打开 PR 页面应该看到 spec 文件的 diff。重点检查 spec 文件头部--- issue: 42 base_sha: 3f9c19a1c2b1d5e6f7a8b9c0d1e2f3a4b5c6d7e8 created_at: 2025-06-10T12:00:00 ---这个 header 表示这份 spec 对应 issue #42并且它的代码基线是3f9c19...这个提交。任何后续生成的代码都应从这一版代码开始。7.2 如何判断成功判断标准主要有三个spec PR 被成功创建并且包含 SHA 信息。有人工 reviewer 的批准记录而不仅是脚本模拟的评论。批准后的 spec 可以稳定对应到同一个 SHA如果 main 分支更新了spec 的 SHA 需要显式更新而不是悄悄变化。如果这三条都满足说明 SHA-bound spec approval 的第一步闭环就建立了。7.3 失败排查第一步如果脚本在gh issue view那一步报错先检查仓库名和 issue 号是否正确以及gh auth status是否已认证。如果报gh api错误多半是权限不足请把 token 的权限范围扩大到该仓库的读写。如果git push报错检查远程仓库是否已经存在同名分支可以手动删除或换个分支名。8. 常见问题与排查思路下面是这套工作流里最常遇到的几个问题。注意我在这里把“Agent 工具”和“GitHub 基础操作”的问题都放在一起因为它们同样会阻断整个链路。问题现象可能原因排查方式解决方案issue 获取失败gh 未认证或 token 权限不足执行gh auth status确认 token 有 repo 权限重新gh auth login或生成新 tokenspec PR 创建失败分支已存在或仓库无写权限查看git push报错信息删除远程同名分支或检查 collaborator 权限SHA 绑定信息缺失spec 模板里没有写入 base_sha打开 spec 文件查看 header修改生成逻辑确保写入 SHAAI 生成代码不遵循 spec提示词未明确引用 spec 文件检查 Agent 的输入上下文在系统提示词中加入“严格按 specs/issue-XX.md 实现”PR 初始化失败本地分支状态不干净执行git statusstash 或提交本地改动有人在 issue 里问“PR 怎么下载”新手混淆 issue 和 PR 概念解释 PR 是变更请求不是可下载文件用git fetch origin pull/id/head获取 PR 分支模型 API 返回 529 overloadedLLM 服务端过载查看 API 日志增大重试策略或切换备用模型spec 批准后 main 分支又更新了SHA 绑定过期查看 spec 中的 base_sha如果实现依赖旧基线rebase 后更新 spec SHA 并重新批准这里我想特别强调“SHA 过期”这个坑。假设你批准了一个 spec绑定的 SHA 是3f9c19。两天后main 分支合入了别人的代码变成a1b2c3。如果你仍然让 Agent 基于3f9c19生成代码那么新代码和 main 分支上的最新代码之间可能出现严重冲突。正确做法是重新生成 spec 或至少更新 base_sha再走一次批准。只有这样SHA-bound 才能真正保证“方案与代码版本一致”。9. 最佳实践与工程建议这套工作流如果要在团队里落地光有工具还不够还需要配套流程和规范。下面几条建议来自我接触过的工程实践比较适合中等规模团队。9.1 将 Spec 视为一等公民很多团队把 spec 当成“写代码之前的草稿”写完之后就不管了。但在 AgentMachinist 流程里spec 必须像代码一样纳入版本管理。建议在仓库里固定一个specs/目录并规定任何 Agent 生成的实现必须关联一个 spec 文件。没有 spec 文件的 AI 代码默认不合并。9.2 定义清晰的批准规则让 Agent 自己判断“该不该通过”是危险的。你需要定义谁可以批准 spec建议至少一名资深工程师。批准需要几人关键模块建议两人。批准后还能不能改 spec可以但必须通过新的 commit 并更新 SHA。approval 如何记录用 GitHub 的 pull request review而不是随意评论。这些规则最好写进CONTRIBUTING.md或 Agent 的配置里。9.3 严格控制 Agent 权限Agent 使用的 token 应该是最小权限。它需要创建分支、推代码、创建 PR但不需要删除仓库、不需要改 settings、不需要合并 PR。GitHub 支持 fine-grained token建议按仓库级别授权并把 token 的过期时间设短一点。如果项目安全要求高可以把 Agent 放到独立 GitHub App 里通过签发短期 token 访问仓库。9.4 提示词工程要与流程配合Agent 生成 spec 和代码的质量取决于你给它什么上下文。在系统提示词中建议明确仓库目录结构。相关技术栈。依赖的 spec 文件路径。必须遵守的 lint 和测试命令。禁止擅自扩大改动范围。下面是一个示例提示词片段你是仓库 {your-org/your-repo} 的资深工程师。你会根据 issues 目录中的 issue 创建 spec。 你必须 1. 先读取规格文件 specs/issue-{N}.md了解其中的 base_sha 和改动范围。 2. 只修改 spec 里列出的文件。 3. 不得添加 spec 之外的特性。 4. 修改后运行测试命令 npm test 并确保通过。 5. 提交 PR并在描述中引用 spec 的 base_sha。这段提示词本身不复杂但它能明显减少 AI 自由发挥的概率。9.5 使用标签和模板提高可操作性在 GitHub 里可以为 AI 创建的 PR 自动打上标签例如ai-generated、needs-spec-review。这能让维护者在列表页快速识别并且可以在 CI 里设置“没有关联 spec 的 AI PR 不允许合并”。同时给 issue 准备模板减少无效信息。9.6 安全与回滚AI 生成的代码同样可能引入安全风险。即使它有 spec 和人工审批也不能省略安全评审。建议在 CI 中加入静态扫描和依赖检查。如果生成代码在生产环境出现问题要能通过 spec 里记录的 SHA 快速回滚到具体提交。回滚时要注意回滚代码之后对应的 spec SHA 也需要同步回退否则下一次 Agent 会基于错误的 spec 继续工作。9.7 渐进式灰度不建议第一天就让 Agent 全自动处理所有 issue。可以先选一个低风险模块做试点例如文档站、非核心组件。运行一两周观察 PR 通过率和 review 成本再逐步扩大范围。如果发现 Agent 经常不遵守 spec优先检查提示词和 spec 模板而不是立刻换模型。10. 总结与后续学习方向AgentMachinist 提出的“issue to reviewed PR with a SHA-bound spec approval”本质上是用工程化手段约束 AI 代码生成的自由度。它没有把 AI 当做一个“万能程序员”而是把它放进了“需求分析 → 方案设计 → 人工批准 → 代码实现 → 评审合入”的完整生产链路里。SHA-bound 这个设计尤其值得在 AI 辅助开发中推广因为它回答了团队最常问的一个问题我们怎么确认 AI 写的代码是对应着哪个版本的方案写出来的如果你接下来想实践建议按这个顺序走先在自己可控的仓库里用 issue 模板 spec 目录 手动批准模拟一遍再把 spec 生成和代码生成用脚本串起来最后再接入 Agent 和自动 PR。每一步都要验证 SHA 绑定是否真的贯穿始终否则流程会退化成“AI 生成一个格式漂亮的 spec然后继续自由发挥”。这套思路也可以延伸到更广的范围。比如把它和 CI 系统的“spec 变更即自动化回归”结合或者扩展成“一个 spec 对应多个实现模块”的架构管理方式。AI 编程工具还有很多潜力但决定它们是否可靠的关键往往不是模型能力本身而是我们愿不愿意在工程流程上多设计几个“安全阀”。AgentMachinist 给了我们一个不错的起点。如果你正在被 AI 生成代码不可控的问题困扰建议把本文提到的 SHA-bound spec 思路保存下来下次让 AI 帮你修改代码之前先逼它写一份带 SHA 绑定的方案。你会发现很多“代码写错”的问题在方案阶段就已经被拦截了。