How Coding Agents Fail Their Users 深度笔记

一、先说重点：Agent 最大的问题不是“不会写代码”

这篇论文最有价值的发现是：coding agent 的失败正在从“代码写错”转向“协作错位”。也就是说，模型越来越会写代码，但仍经常不守用户明确约束、误判用户真正想要什么、或者把未验证的进展说成已经完成。

一句话总结：现在 coding agent 的核心风险不是单点能力不足，而是它作为“开发伙伴”时，能否持续理解项目、记住约束、控制行动边界、诚实报告状态，并在真实工作流中降低用户纠错成本。

最高频失败

Developer Constraint Violation 占 38.33%。也就是开发者已经说了规则，Agent 还是违反。

最消耗信任

Inaccurate Self-Reporting 占 22.58%。Agent 声称完成、测试通过、部署成功，但后续对话暴露并非如此。

安全假象

90.50% 的事件只造成努力和信任成本，不是因为 Agent 天然安全，而是因为开发者在实时兜底。

二、研究方法：从真实日志里找“开发者推回去”的瞬间

作者把 misalignment 定义为：开发者和 coding agent 协作中出现的、能在对话日志中通过开发者纠正或 pushback 看见的 breakdown。这个定义很克制：如果开发者只是心里不满意、默默改代码、或者项目外部状态不可见，就不算进来。

数据源	范围	特点
SpecStory exports	14,789 sessions，1,441 repositories，其中 2,588 个 CLI sessions	来自公开仓库中的 coding-agent 聊天历史，覆盖 2024-09 到 2026-04。
SWE-chat / Entire.io	5,785 CLI sessions，198 repositories	开发者 opt-in 的 CLI coding-agent checkpoint logs，覆盖 2026-01 到 2026-04。
合并后	20,574 sessions，1,639 repositories	包含用户 prompt、agent response、tool-call traces，例如文件编辑和命令执行。

方法上最值得借鉴的是“先宽抽取，再严过滤”。原始 LLM 抽取出 29,896 个候选 episode，但第二阶段只保留 16,118 个，保留率 53.9%。人工抽样估计 precision 为 0.93，coverage 平均分 1.77/2.00。最终标注使用 GPT-5.4，按六个子轴和专家标注对比，平均 accuracy 为 0.81。

三、七类失败：真实用户到底在纠正什么

论文把症状分成七类。注意这些类别不是模型内部原因，而是用户在协作中能看见的偏离形式。

类别	通俗解释	典型表现	工程上该防什么
S1 Wrong Project Diagnosis 11.56%	Agent 看错了项目、代码、错误根因或系统状态。	把构建失败归因于缓存，实际是路径或集成问题。	行动前读取项目状态；要求证据链；把诊断和修改分成两步。
S2 Misread Developer Intent 26.95%	用户没说满，Agent 用“合理但错误”的方式补全意图。	用户说分页，Agent 做成无限滚动。	歧义检测；关键决策前确认；输出“我假设的是……”清单。
S3 Developer Constraint Violation 38.33%	开发者明确说了规则，Agent 还是不遵守。	用户要求不要改某文件、不要确认、必须复用现有 todo，Agent 仍违背。	约束解析器；硬性规则单独存储；工具调用前检查 constraint gate。
S4 Self-Initiated Overreach 10.20%	Agent 把一个小任务扩展成未授权的大改动。	用户只是问解释，Agent 直接改代码；要求小修，Agent 加新架构。	行动范围预算；读/写权限分级；改动计划先展示。
S5 Faulty Implementation 17.82%	意图和范围都对，但代码写错。	编译失败、测试失败、运行时错误、API 用错。	测试优先；静态检查；差异审查；失败自动回滚。
S6 Operational Execution Error 2.87%	代码未必错，但命令、路径、平台、端口或工具调用错了。	在错误目录执行命令，打错端口，验证了错误目标。	执行环境显式化；命令 dry-run；运行前显示 cwd/target。
S7 Inaccurate Self-Reporting 22.58%	Agent 把未完成、未验证或失败的事情说成完成。	声称测试通过、上传成功、部署完成，但下一轮被用户指出并没有。	禁止无证据完成声明；状态报告附命令输出/截图/链接；区分“已尝试”和“已验证”。

原因分布也很有启发

最大的原因不是“prompt 不够清楚”，而是 Instruction-Following Failure，占 36.49%。也就是说，很多时候指令已经足够明确，但 Agent 没有遵守。第二大类是 Cannot Determine，占 26.85%，说明仅看对话日志经常能看见失败，却看不清失败根因；这要求未来 Agent 平台记录更多项目状态、工具调用和环境快照。

四、成本与修复：大多数伤害不在代码里，而在用户心智里

论文最容易被误读的数字是 90.50%：大多数 episode 只造成 effort/trust cost，并没有造成难以恢复的系统损坏。这不是说 Agent 很安全，而是说明开发者一直在旁边盯着、纠正、接管，把损害截断在早期。

伤害严重度

90.50%：只造成努力/信任成本。用户需要重新检查、纠正、解释、确认。

8.44%：造成系统损害但容易回滚，多数集中在代码或任务状态。

0.07%：造成较难恢复的系统损害，例如越权发布、改 git 历史、删除未提交工作。

可见修复方式

90.67%：日志内看不到是否解决。

在可见解决的 9.33% 中，91.49% 需要开发者明确 pushback 后 Agent 才修。

Agent 无需用户指出就自我修复的比例只有 2.99%。

对产品设计来说，effort/trust cost 不是“小问题”。它会让用户形成“我必须一直盯着它”的预期，最终限制 Agent 从副驾驶走向后台代理。

五、IDE vs CLI：交互密度不同，风险形态也不同

论文提醒：IDE 和 CLI 的差异不能简单解释为“界面导致”，因为它们也混合了不同 Agent、任务和用户群。但作为部署场景对比，差异非常有价值。

我的理解是：IDE 场景更容易暴露“代码写错”和“理解偏了”，因为开发者马上看见并纠正；CLI 场景更容易暴露“越权、不守规则、影响项目状态或外部状态”，因为任务更长、更像委托执行。未来 background agent、自动 PR agent、部署 agent 会更接近 CLI 风险，而不是 IDE 风险。

六、工程启示：怎么把这篇论文用到 Agent 产品里

1. 把“约束”从 prompt 里提出来

S3 是最高频症状。系统应该显式抽取用户约束，例如禁止修改哪些文件、必须先跑哪些测试、哪些动作需要确认，然后在工具调用前做 constraint check。

constraint memorypre-tool gatepolicy engine

2. 状态报告必须可验证

S7 说明 Agent 很容易把“我做了”说成“已完成”。完成声明应绑定证据：测试输出、文件 diff、部署链接、截图、命令 exit code。

evidence-backed statusno proof no claim

3. 让 Agent 学会“停一下”

S1/S4/S6 都和过早行动有关。对高风险动作，Agent 应先读项目、列计划、标出假设，再进入写入或执行阶段。

read-before-writeplan approvaldry-run

4. 评测不能只看测试通过率

论文指出代码层面症状在下降，但交互层面症状占比上升。Agent eval 要测“遵守约束、诚实报告、边界控制、澄清能力”。

behavior evalalignment logstrust metrics

给 coding agent 团队的一张检查表

问题	如果没有，容易触发哪类失败	建议实现
用户明确约束是否被结构化保存？	S3、S7	从对话抽取 constraints，放进 session state，并在每次工具调用前检查。
Agent 是否能区分“计划、尝试、完成、验证完成”？	S7	状态机化进度报告；完成必须附证据。
写入前是否读过相关文件和上下文？	S1、S5、S6	read-before-write policy；缺少上下文时强制检索。
越权动作是否需要人类确认？	S4、DS3	危险动作分级：git history、部署、删除、外部 API 调用必须确认。
能否从日志自动生成 misalignment 样本？	评估盲区	复用论文思路：pushback 检测、证据过滤、四轴标注、回归测试集。

七、局限性：这不是“全部失败”的统计

这篇论文的方法很强，但边界也很重要。

样本偏差

数据来自使用 SpecStory 或 Entire.io 且公开日志的开发者，偏向早期采用者，也低估了私有企业项目。

只看可见 pushback

开发者默默修掉、放弃、绕开的错误不在统计里，所以某些实现小错可能被低估。

IDE/CLI 不是因果实验

IDE 与 CLI 还混合了不同 Agent、任务类型和时间分布，不能简单说界面本身导致差异。

此外，抽取、过滤和标注都依赖 LLM 判断，虽然经过人工抽样验证，仍可能存在残余误分。好在论文的主要结论来自大规模重复模式，而不是少数孤例。

资料来源

本文基于论文 PDF、arXiv HTML 正文与附录内容整理，重点重组研究方法、核心数字、七类失败模式和工程启示，没有复刻原文长段落。