Coding Agent 如何理解代码库并安全地产生补丁

写代码只是 Coding Agent 的一小部分

在空白文件中生成函数并不困难，真正复杂的是在已有代码库中做正确修改。Coding Agent 需要理解目录结构、现有约定、调用关系、测试方式和未提交改动，还要避免把一个局部需求变成大规模重构。

因此，一个成熟的 Coding Agent 更像受约束的软件工程工作流：先建立证据，再形成最小补丁，最后通过构建、测试和差异审查证明改动符合目标。

第一步是建立代码库地图

Agent 不应一开始递归读取所有文件。更有效的顺序是：确认工作目录和版本控制状态；查找项目说明与 Agent 指令；识别语言、包管理器和入口；根据用户提到的符号或错误搜索相关文件。

可以维护一个轻量地图：

{
  "entrypoints": ["src/server.js"],
  "relevantFiles": ["src/auth.js", "tests/auth.test.mjs"],
  "commands": {"test": "npm test", "build": "npm run build"},
  "constraints": ["不要修改公共 API", "保留未提交改动"],
  "unknowns": ["生产会话存储是否共享"]
}

地图不是一次生成后永久正确。发现新的调用关系时更新它，但不要把大量源码原文都复制进上下文。文件路径、关键符号和短摘要足够支持导航，具体实现按需读取。

从失败或成功标准反推修改

“修复登录问题”应先转成可验证目标：构造会失败的输入，确认当前行为，定义修复后响应和副作用。若能够写测试，先让测试稳定重现问题；若是环境故障，至少保存精确日志与配置证据。

在动手前，Agent 应给出一个很短的变更假设：根因在哪里、准备修改哪些文件、如何验证。它不是长篇计划，而是防止搜索过程中偏离目标的锚点。

遇到歧义时不能默默选择。例如“删除缓存”可能指运行缓存、构建缓存或用户数据；不同解释的破坏性差异很大。应继续只读调查，仍无法确定时再询问用户。

最小补丁比漂亮重构更重要

Coding Agent 容易在看到相邻问题时顺手清理。这样的补丁更难审查，也增加回归面。修改应只覆盖当前目标，并匹配原有风格，即使 Agent 更喜欢另一套抽象。

使用补丁式编辑可以清楚表达意图。每次改动后重新读取相关片段，确认没有错位或重复。若修改导致本次新增的导入或变量变成死代码，应一并删除；预先存在的无关死代码只记录，不要顺手处理。

自动格式化也要限制范围。全库格式化会制造大量噪声，使真正逻辑变化淹没在空格中。优先格式化修改文件或让项目现有钩子处理。

工具权限与工作区保护

代码库不是 Agent 的独占环境。开始前必须检查 git status，把已有改动视为用户资产。不能用硬重置、强制覆盖或清理未跟踪文件来获得“干净状态”。修改与用户改动重叠时，应先理解差异并尽量局部合并。

命令执行也应分级。搜索、读取和构建通常是低风险；安装依赖会改变锁文件并访问网络；数据库迁移、部署和推送会影响外部状态，需要符合用户授权。Agent 不应因为测试需要就自动重置共享数据库。

密钥、环境文件和个人凭据不能出现在补丁、日志或提交中。执行命令时避免把完整环境变量输出到终端。

验证应与风险成比例

最小验证通常包含语法或类型检查、与改动直接相关的测试，以及差异检查。高风险修改还需要更宽的回归测试、构建产物检查或实际运行验证。

“命令退出码为 0”不一定等于功能正确。前端变化需要检查真实页面，API 修复需要验证请求与持久化状态，部署变化需要验证目标主机。相反，文案调整不必启动整套性能测试。

验证失败时，Agent 应先判断是代码回归、测试环境问题还是预先存在的失败。不要为了让测试变绿而删除断言，也不要把无关失败伪装成本次成功。

差异审查是最后一道门

在交付前查看完整 diff，逐项回答：每个文件是否与任务相关；是否有意外格式化；是否包含调试输出、临时文件或秘密；新行为是否有验证；错误路径是否仍然合理。

提交时让信息描述用户可见结果，而不是“update files”。推送、创建 PR 或部署属于外部写操作，只有在用户明确要求时执行。

对于大型任务，可以把变更拆成可独立验证的阶段，但每个阶段都要保持代码库可构建。不要留下只有 Agent 自己理解的半成品状态。

小结

可信 Coding Agent 的能力不是一次生成更多代码，而是更快找到正确修改点、保护现有工作、保持补丁最小并用证据完成交付。搜索、测试、差异审查和权限边界，和模型生成能力同样重要。