Coding Agent 并不是“会补全代码的聊天机器人”。它要在一个真实仓库里完成任务：定位相关文件，理解现有约束，修改多个位置，运行检查，处理错误，并交付可审阅的变更。

这类 Agent 的关键能力可以概括成一条工程循环：

搜索 -> 阅读 -> 计划 -> 编辑 -> 运行 -> 观察 -> 修正 -> 验证

一、先读取事实，再开始编辑

直接根据用户描述修改代码，是 Coding Agent 最常见的失败起点。仓库里的类型定义、调用方、测试和配置文件，往往比任务描述更能说明真实约束。

一个稳妥的最小顺序是：

  1. 查看项目结构和工作区状态。
  2. 搜索符号、路由、配置和相关测试。
  3. 阅读完整的调用链，而不是只读命中的一行。
  4. 写出要改变的行为和不应改变的行为。
  5. 选择最小的文件集合开始修改。

这里的“计划”不需要一篇长文，而是一个能被验证的变更清单。每一项都应该能对应到文件、命令或测试。

二、代码是思考过程的一部分

在普通对话中，模型的文字解释很容易被下一轮覆盖；在代码仓库中，文件、测试和错误日志会留下持久状态。对 Coding Agent 来说，代码不只是最终产物，也是一种外部记忆和约束。

因此，编辑工具应当支持精确定位和可审阅的差异。大范围重写会增加误改概率，也会让失败后的恢复变得困难。一个好的 Agent 会先让变更可见，再运行格式化、类型检查和测试。

三、失败反馈比“再想一次”更有价值

测试失败后，模型需要看到结构化的反馈：命令、退出码、失败测试、相关堆栈以及可能的文件位置。只返回一行“命令失败”，相当于把最有价值的观察结果丢掉。

修复时也要区分错误类型：

  • 语法或类型错误：通常可以直接定位并修复。
  • 行为测试失败：需要回到需求和调用链，确认假设是否错误。
  • 环境或依赖错误：不能把基础设施问题误改成业务代码。
  • 不确定的外部副作用：先查询状态，再决定是否重试。

Agent 不应该为了让测试变绿而删除测试、放宽断言或隐藏错误。验证器的输出是边界，不是需要被绕过的障碍。

四、让长任务可以暂停和恢复

Coding Agent 经常面对超出单轮上下文的任务。一个可恢复的会话需要保存：当前目标、已检查的文件、已经应用的差异、测试结果、未决问题和下一步动作。

这比保存完整聊天记录更有用。聊天记录包含大量重复解释，而状态摘要可以让 Agent 在中断后快速回到正确的工作面。每次恢复时，都应重新读取工作区状态，因为用户或其他自动化流程可能已经修改了文件。

五、把安全边界放进运行环境

提示词可以提醒 Agent 不要泄露密钥，但真正的边界应该由环境保证：

  • 只允许访问任务所需的目录。
  • 将网络和凭据访问拆成明确的权限。
  • 高风险命令需要确认或在沙箱执行。
  • 保留每次读写、命令和验证的审计记录。
  • 通过分支、补丁或提交让变更可回退。

隔离的工作区还带来一个工程好处：Agent 可以大胆尝试，失败后只需丢弃或修正可见差异，不会把半完成状态直接带到生产环境。

六、Coding Agent 的完成标准

“代码已经生成”不是完成标准。至少要回答：功能是否满足需求，类型和 lint 是否通过，相关测试是否通过，变更是否容易审阅，是否记录了仍然存在的风险。

当搜索、编辑、执行和验证都成为可观察的工具调用时，Coding Agent 才从代码生成器变成了一个能在工程约束中工作的智能体。

参考阅读

  • 李博杰：《深入理解 AI Agent：设计原理与工程实践》，v1.3，2026-07-29。