跳转到内容
Agentic Engineering Fieldbook

编码与软件工程智能体

编码智能体之所以诱人，是因为软件工作天然包含文本、工具、测试、版本控制和审查。模型可以阅读 issue、检查文件、修改代码、运行命令、观察失败，再继续尝试。这让软件工程成为最适合智能体系统的领域之一。

但它也最容易被误解。生成出来的补丁并不等于安全变更。本地测试通过并不等于发布决策。看似合理的解释也不能证明代码库行为正确。因此，编码智能体应被设计成生成带证据、可审查的变更候选，而不是把自然语言直接转换成可信软件的系统。

核心论点

Section titled “核心论点”

当一项任务可以被限定为变更候选，代码库环境能够提供所需上下文与工具，并且验收依赖可检查的差异、可执行验证和发布门槛，而不是智能体自称成功时，这项编码任务才适合委托。

核心产品对象是变更候选：分支、补丁、拉取请求或同类产物，必须可检查、可测试、可回退，并能关联到原始请求。智能体的对话可以作为有用的过程证据，但不能替代差异、测试、来源与构建记录，以及有责任主体的审查。

任务边界是变更，而不是愿望

Section titled “任务边界是变更，而不是愿望”

适合编码智能体的任务通常有明确目标：

  • 修复这个失败测试；
  • 根据这份规格实现这个 API 字段；
  • 在不改变外部可见行为的前提下重构这个模块；
  • 更新这些依赖并解决兼容性失败；
  • 为这个工作流补充观测埋点；
  • 调查这个 bug，并返回补丁或被证伪的假设。

不适合的任务会把本应属于产品、架构或发布负责人的问责交给智能体：

  • 让系统变得更好；
  • 清理代码库；
  • 全面提升性能；
  • 迁移技术栈；
  • 让它变得安全；
  • 发布这个功能。

区别不只在规模。一个很小的改动如果触及认证、授权、计费、隐私或迁移，也可能很危险。一个较大的机械性变更，如果影响面、检查项和审查标准明确，反而可能比较安全。委托问题在于：智能体能否产出一个能被正常工程体系测试或审查的产物。

代码库上下文是智能体的工作环境

Section titled “代码库上下文是智能体的工作环境”

编码智能体需要的不只是用户点名的文件。它需要一份代码库上下文约定：

  • 请求的行为以及请求来源；
  • 相关文件、生成代码、Schema、测试、构建配置和依赖约束；
  • 编码约定、架构边界和所有权文件；
  • 失败命令和预期通过的命令；
  • 近期可能解释问题的变更；
  • 安全、隐私和迁移约束；
  • 不应触碰的文件与目录。

SWE-agent 的结果提醒我们，智能体与计算机之间的接口会实质性影响行为（Yang et al., 2024）。命令输出、文件导航、编辑方式和观察信息不是偶然的界面选择，而是被评估系统的一部分。

上下文约定也要说明智能体不能自行推断什么。如果 issue 说“让登录更快”，但代码库中有多个登录流程，智能体应指出歧义，而不是修改第一个搜索到的路径。如果测试需要凭据或网络访问，智能体应说明验证不完整，而不是根据静态检查宣称成功。

控制回路是编辑、运行、观察、收窄

Section titled “控制回路是编辑、运行、观察、收窄”

一个有能力的编码智能体通常会经历这样的回路：

  1. 重新表述请求变更和验收证据。
  2. 检查相关代码库状态。
  3. 形成一个小计划。
  4. 修改一组受限文件。
  5. 先运行最具体的验证。
  6. 把失败当作证据，而不是尴尬。
  7. 修改补丁或收窄主张。
  8. 以可审查差异、测试结果和残余风险作为停止状态。

这个回路应被记录并设置边界。时间、Token、命令和触碰文件的预算都很重要，否则编码智能体可能一路游走到大范围重构。好的停止状态可以是成功、受阻、不安全、需要决策或无法复现。除非必要检查已经通过且产物可审查，否则“我已经修好”不是终止状态。

在高风险代码库中，命令应在沙盒里运行，并明确网络、文件系统和密钥边界。智能体不应仅因为能写出语法，就能够部署、轮换凭据、直接推送到受保护分支、修改计费配置或运行破坏性命令。

验证有多个层次

Section titled “验证有多个层次”

编码任务有异常丰富的验证手段，但每一层都有边界：

验证层 能证明什么 不能证明什么
静态检查 语法、类型、格式、明显 lint 规则 运行时行为、遗漏需求、业务正确性
聚焦测试 被复现的问题或新增行为 未测路径、集成影响、安全属性
完整测试套件 当前环境下更广的回归信号 生产配置、测试空洞、隐藏验收标准
差异审查 意图、可维护性、范围、所有权、风险 穷尽行为或排除细微 bug
预发或金丝雀 更接近真实环境的行为 长尾使用、完整发布安全、后续供应商漂移

SWE-bench 和 SWE-bench Verified 有价值，是因为它们用代码库测试来评估 issue 级变更，而不是评估孤立代码片段（SWE-bench；OpenAI, 2024）。它们给生产环境的启示不是“基准分数证明可发布”，而是编码智能体评估应贴近真实工作：代码库状态、任务说明、环境交互和结果检查。

本地验证应保留三组区别。第一，智能体变更前已有的测试不同于智能体新写的测试。第二，如果智能体先复现了失败，再让测试通过，证据更强。第三，隐藏检查或审查者拥有的检查仍然有价值，因为智能体和人一样会过拟合可见测试。

审查是产品的一部分

Section titled “审查是产品的一部分”

编码智能体的体验应让审查变得容易。审查者应看到：

  • 原始请求和验收标准；
  • 修改了哪些文件，以及为什么；
  • 运行过哪些命令，并准确概括通过或失败输出；
  • 新增、删除或修改了哪些测试；
  • 未解决的风险与假设；
  • 生成文件或依赖变更；
  • 是否触及安全敏感路径；
  • 智能体是否使用了网络访问、密钥或外部工具。

OpenAI Codex 与 Claude Code 都体现了围绕代码库工作空间、命令执行、可审查输出和带权限运行的当前产品模式（OpenAI Codex 文档；Claude Code 文档）。这些材料说明这个领域正在走向工作空间导向的编码智能体，但不能证明任何具体任务都可以跳过审查。

审查界面应区分“智能体写了这个”和“系统接受了这个”。前者是作者元数据；后者是带负责人和证据的工程决策。

设计选项

Section titled “设计选项”
选项 最适合 主要风险
行内代码助手 本地补全、解释、小改动 用户可能在上下文不足时接受看似合理的代码
任务范围内的编码智能体 有边界的 issue、bug 修复、测试、小功能 智能体可能扩大范围，或在弱验证后停止
代码库维护智能体 依赖更新、迁移、重复性变更 反复自动变更会压垮审查，并漏掉语义风险
有发布权限的智能体 极窄且强门控的内部自动化 模糊变更生成与发布问责

多数团队应从任务范围内的变更候选开始。自动合并只应留给很窄的任务类别，而且这些类别需要已经具备强所有权、强测试、回退、监控和策略。

失效模式

Section titled “失效模式”
  1. 问题错了，补丁看起来对。 智能体修改了关键词匹配的代码，却不是用户真正失败的路径。
  2. 测试表演。 智能体编写或选择只证明自己补丁的测试。
  3. 过度清理。 智能体把请求变更与重构、格式化噪声或依赖更新混在一起。
  4. 环境混淆。 本地命令在不同运行时、数据库、功能开关或供应商配置下通过。
  5. 隐藏权限升级。 能编辑文件的工具同时拥有密钥、网络、包发布或部署凭据。
  6. 虚假完成。 智能体声称工作完成，但验证被跳过、失败或只跑了一部分。
  7. 审查过载。 组织接受更多机器生成变更，却没有增加审查证据和所有权。

本手册的判断

Section titled “本手册的判断”

在产物可以具体化的地方使用编码智能体。给智能体代码库工作空间，而不是无限的组织意图。优先选择小的变更候选、明确的验收证据和确定性的发布门槛。

要求智能体展示自己的验证路径。如果命令无法运行，它应说明原因。如果它修改了测试，应标明。若发现歧义，应询问或返回有边界的假设。如果触及安全敏感代码，应触发更严格审查。

不要绕开工程体系。版本控制、代码审查、CI、构建来源记录、部署控制和事件学习之所以存在，是因为软件变更有长尾影响。编码智能体可以让这些系统更高效，但不应成为不可见、无人负责的变更作者。

检查清单

Section titled “检查清单”
  • 请求的工作是否能表达为有边界的变更候选？
  • 代码库上下文、排除路径、依赖约束和所有权边界是否明确？
  • 智能体是否在沙盒中运行，并且文件系统、网络、密钥和命令权限都已限定？
  • 破坏性命令、受保护分支、部署、包发布和凭据变更是否在模型之外设有门槛？
  • 智能体是否记录计划、触碰文件、运行命令、测试结果和未解决假设？
  • 智能体编写的测试是否与既有检查区分开？
  • 审查是否包含差异、验证证据和风险敏感所有权，而不只是智能体摘要？
  • 自动合并或自动发布路径是否只限于已有本地证据、回退和监控的任务类别？

参考文献及其使用方式

Section titled “参考文献及其使用方式”