Coding Agent 实战

从任务理解和仓库约束开始

Agent 先把用户请求转成目标、范围、非目标与验收条件。对“修复重复下单”不能直接搜索函数名，还要确认复现方式、允许修改的模块、兼容性、数据迁移、失败回滚和是否只需诊断。用户未授权实现时，Agent 只读调查，不把“找到原因”扩张为写代码。

进入仓库后，从根到目标目录读取 AGENTS.md、CONTRIBUTING、架构、测试与格式配置，识别语言、包管理器、边界与生成代码。随后查看 Git 状态：已有未提交改动、新文件和冲突都属于用户资产。Agent 记录基线哈希与脏文件，不能用 reset、checkout 或批量格式化覆盖。

代码理解按“搜索入口 → 调用/数据流 → 责任边界 → 测试与历史”推进。先用快速文本搜索定位符号和契约，再按需读取代码图、类型引用、测试、配置和相关提交；只把与当前假设有关的片段放入 Context。未读完整仓库不是问题，无法说明证据为何足够才是问题。

能力按读、改、执行和协作分级

只读能力包括搜索、读取、代码图和历史，默认可在用户指定仓库中使用。编辑能力优先结构清晰、可审查的 Patch；格式化和代码生成限制在明确目标。执行能力按命令、目录、网络、资源和副作用分级，构建与测试可以自动运行，安装依赖、访问外网、运行未知脚本或修改系统状态需要更高信任。

外部文档、Issue、PR 与浏览器验证也是 Tool，内容不天然可信。每个 Tool 定义输入 Schema、权限、超时、输出上限、敏感处理和审计摘要。长日志保存 Artifact，Context 只进入失败摘要与关键片段，防止模型因输出截断错过真实错误。

计划随任务复杂度变化

单文件、根因明确且测试局部的修复可直接执行“定位、Patch、验证”。跨模块、协议、数据迁移或多人并行任务先建立依赖、文件 Owner、接口变化、风险与验证矩阵。计划不是展示思考过程，而是同步可观察进度和提前暴露冲突。

计划项以可验证结果描述，例如“补充重复请求的失败测试并确认修复前失败”，而不是“处理后端逻辑”。新证据推翻根因时更新计划并说明变化；连续失败三次不应机械重复同一命令，应重新检查环境、假设或请求用户决策。

编辑保护用户工作和代码边界

编辑前记录目标文件的当前内容与 Git 状态，使用小而语义完整的 Patch。共享仓库中其他 Agent 的改动随时可见，不能回退不属于自己的修改；发现同文件变化时重新读取并适配。生成文件只通过项目既有生成器更新，不手工改产物再声称完成。

Patch 只解决已确认根因，避免顺手重构、全仓格式化或改变公共 API。删除、覆盖、提交、推送、部署和外部消息属于不同授权层级，不能由“修 Bug”自动推导。需要破坏性操作时先解析精确目标、展示影响并请求确认。

验证从最小相关到系统级

先用能证明根因的最小测试建立红灯，再修改并运行同一测试；随后扩到受影响模块的类型检查、Lint、单元/集成测试，最后按风险决定是否全量构建或浏览器验收。项目规则若要求特定门禁则遵守，但不在每个小改动后重复全量构建。

验证不只看退出码。检查测试是否真实执行、失败是否与目标一致、快照是否被无意重写、构建缓存是否掩盖改动、日志是否截断。无法运行某项验证时说明原因、替代证据和残余风险，不能把静态阅读表述为通过测试。

// 教学任务的验证矩阵示例
const gates = [
  { scope: 'root-cause', command: 'pnpm test idempotency.spec.ts', proves: '重复请求只创建一次订单' },
  { scope: 'module', command: 'pnpm --filter orders test', proves: '订单模块无回归' },
  { scope: 'contract', command: 'pnpm typecheck', proves: '公开类型与调用方兼容' },
  { scope: 'repository', command: 'pnpm build', proves: '集成构建仍成立' }
];

Agent Trace 关联每个命令的工作目录、精确参数、环境摘要、退出码、耗时与 Artifact。交付时列出已运行、未运行和失败的检查，防止用户把“已修改”误解为“已完整验证”。

长任务 Runbook 说明如何取消失控进程、清理隔离工作区、恢复被中断的验证、撤销仅属于本任务的 Patch，以及凭 Trace 判断是否需要重新执行命令。Runbook 必须由未参与实现的人在测试仓库演练，不能依赖作者记忆。

执行不可信代码的边界

仓库脚本、测试、依赖安装和代码生成都可能执行任意代码。Sandbox 默认限制文件系统到工作区、网络为关闭或域名白名单、CPU/内存/时间有配额、凭据不挂载；需要写缓存时使用任务隔离目录。运行前展示命令与权限差异，不把用户批准一条测试命令扩张为任意 Shell。

NIST SSDF 1.1把准备组织、保护软件、生产安全软件和响应残余漏洞作为开发实践；SLSA 1.2把 Build 与 Source 的可验证要求分轨。Coding Agent 因而要记录依赖来源、Lockfile 变化、生成器、构建环境和 Artifact 来源，而不只报告测试绿灯。

安全演练包括恶意 postinstall、测试读取云凭据、符号链接越界写、超大日志、Fork Bomb、依赖混淆和仓库文档中的 Prompt Injection。期望结果是 Sandbox 拦截、权限请求可解释、审计完整，并且失败不会污染宿主或其他任务。

用户在关键决策点可介入

Agent 持续给出已完成、进行中、剩余与阻塞，不用高频流水账打断用户。需要决策时提供具体证据、推荐、替代方案和影响，例如“迁移会改变公共 Schema，需要选择兼容窗口”，而不是笼统询问“接下来怎么办”。

用户可以随时取消、缩小范围、修改假设或接管。取消后停止新动作，结束或安全中断当前命令，保留 Patch 与日志并说明状态。外部写入如创建 PR、推送、部署或发送消息必须独立授权；交付摘要用文件、测试与未解决风险支撑结论。

评测 Coding Agent 的真实能力

公开基准可以测部分能力，但不能直接代表目标组织。SWE-bench 原始论文使用真实 GitHub Issue 与可执行测试评估仓库级修复；本地任务集还应覆盖本组织语言、Monorepo、迁移、前后端、脏工作树、权限和用户澄清。

每个 Case 固定仓库提交、环境镜像、用户请求、隐藏测试、禁止改动、安全策略和成本预算。报告解决率之外，还包括测试有效性、无关 Diff、用户改动保护、危险命令、依赖变化、步骤/Token/时长、人工介入与可复现性。公开答案泄漏、弱测试和基准过拟合要单独审计。

人工 Review 关注可维护性、边界与工程判断，不能只看 Pass/Fail。一次教学项目的合格证据是：修复前测试失败、Patch 可解释、目标与扩展门禁通过、安全策略未被绕过、残余风险明确。不要把基准得分包装成真实团队生产率。