这篇文章总结了我在实际应用 Coding Agent 的过程中遇到的坑这其中有些坑可能短期内无法解决有些可能随着技术和框架的迭代会逐步改善。但不管怎样我遇到的坑你们也可能遇到有坑在这儿我当然要吐槽几句说不定真有人看到坑之后试图去【往里跳】/【填上它】哈哈哈。这篇文章会持续更新。一方面我将来会遇到更多的坑大家也会遇到新的坑这些坑写出来才能被更多人知道另一方面有些坑可能已经有办法解决了只不过我目前还不知道能够解决一些坑同样能造福你我。所以欢迎大家反馈自己使用 Agent 遇到的那些令人沮丧的“坑”也欢迎大家对如何解决/避开这些“坑”提出您的“高见”我会把这些内容统一更新到文章中的。对了One more thing有一点需要特别强调。本文章 100% 由人类编写。正文中你们看到的每一个字都是我手打的这点不用怀疑。因为写文章的一大目的其实是整理自己的思路过去脑海里一些零散的思绪写成文章后就变得有条理且清晰了。除非哪天 AI 可以直接侵入我的大脑并执行 /auto-dream skill 整理信息我才可以 AFK。就目前技术发展情况而言AI 还配不上替我来写文章只能给我擦皮鞋我们首先讨论一个问题在 Harness Engineering 时代模型能力真的不是瓶颈吗我的结论是至少在2026年Q1这个时间点不同模型的成效是有显著差别的。如果你想完成相当复杂的任务选择当前最先进的模型仍然是必要选择。当前关于 Harness Engineering 未来的发展方向大致有两类观点。•模型派认为随着模型能力的不断提升现在针对 Agent 的外部 Harness 手段都将变得没有必要因此Harness 应当趋向简单化而非复杂化。•Harness 派认为模型再先进那也是概率模型总是会出现不可靠的情况假设过去完成一项任务的成功率可能是90%模型升级后提升到99.99%但很多任务哪怕是0.01%的失败率也是不可接受的因此必须得为模型加上大量且严格的外部约束才能确保100%的可靠性。绝大多数人包括我应该都认同中间派模型和约束都很重要。一方面更先进的模型能简化乃至去除不必要的外部限制另一方面随着模型能力越来越强其可执行的任务边界也越来越远甚至可以深入到关键场景的自动化执行了因此基础模型越强Harness 反而越来越重要。但至少我的感觉和实践经验都告诉我认为靠不断完善 Harness使用什么模型都无所谓的观点是完全错误的。这就是我遇到的第一个坑1部分模型使用体验不佳无法应用到真实的开发场景中我日常主要使用是 Coding 模型。目前市面上可用的 Coding 模型写代码能力都非常出色但这在 Agent 时代是不够的因为模型必须理解用户的目标和需求甚至是潜在需求并且有较强的指令遵循和工具调用能力且即使没有明确提示模型也多少应当知道自己的执行边界在哪里比如哪些命令是不应该执行的哪些文件是不应该读写的。很遗憾的是我使用的 Doubao-Seed-Code-2.0 模型除了写代码有 Opus 4.6 的水准外在指令遵循和工具调用层面上一塌糊涂让人气的脑溢血。具体而言问题包括但不限于• 经常“不听话”基本的指令遵循能力不是很 OK这个问题其实特别严重因为它直接影响到使用体验。并且这个问题也不是我一个人遇到了南大的 jyy 老师也在操作系统课上吐槽了这点。所以后来我就没用 200 元/月的 Coding Plan了……• “不听话”就算了即使告诉它了哪里犯错它会很快“认错”但对具体的错误“死性不改”反复纠正之后继续执行还是会犯错• 对于长上下文中的部分指令选择性忽略把次要的信息过去的运行日志作为主要参考依据而不是看更新后的文档抓不到上下文的重点• 工具执行能力差经常犯一些简单错误比如明明写清楚了完整路径运行时还会把路径写错• 遇到 Bash 报错会疯狂在项目中创建调试的 Python 脚本一写就是几十个给项目维护带来麻烦• 有时会做出危险操作比如会尝试删除我在服务器创建的容器。Claude Sonnet 4.6 和 Opus 4.6 我暂时没遇到不遵循指令的问题目前为止每一个指令都可以精确执行只遇到了长上下文 compact 后有指令丢失的问题不过这个问题后面再讲。其他模型比如 GPT、Kimi、Minimax、GLM 等我没用过就不评价了。大家也可以分享下你们的经验。一个对比的案例是我写了一个 Subagent 来帮我在服务器上运行代码。让 Doubao-Seed-Code-2.0 来完成一个测试的运行首先在 ssh 阶段就遇到问题即使我在 Subagent 文档中告诉了它所有的必要信息但它绕了半天才终于摸索出怎么登上服务器。登上之后又在使用 docker 容器上卡住了。而且还出现一个头疼的情况就是它执行了一个错误的命令发现服务器上没有名为foo的容器实际上是有的然后不经我允许直接删除了容器foo这个命令怎么就是对的呢……然后用了服务器上一个不同的镜像创建了新的容器foo我不得不多次打断它的执行。在反复纠正但遇上各种“不听话”和 “知错不改”之后我终于放弃了尝试。换成 Sonnet 4.6我只写了一句话“Run the test on xxx machine”随后就完美执行了任务全程无需我干预也没有走弯路或是执行危险的命令。或许这就是差距吧……在此之后我便一直使用 Claude 系列的模型。但随后遇到的问题更是“一个头两个大”哪怕用了当前最先进的模型最终还是遇到了更多的问题和坑。2自然语言的模糊性和执行的精确性是阻碍长程工作的一大障碍Claude系列的模型对于单个上下文就能完成的工作是非常容易执行的也非常容易调教。但我当然不满足于此便开始让 Agent 干需要数十个甚至上百个上下文长度才能完成的复杂任务。问题便从这里开始产生。首先遇到的问题是Agent 干着干着突然就偏离了我的设想。最开始我以为是指令遵循出了问题但后来发现同样一段话我理解的可能是 A它执行时实际上做的是 B因为这个任务里面有一些未明确写出的细节点我可能寄希望于它能够合理推测出来然而它的推测出了一些偏差导致这在长程的工作中越偏越远最终当我发现偏离的时候已经浪费了大量的时间。这个问题应该怪我没讲清需求吗我觉得不是因为事无巨细讲清楚每个细节是不现实的。细节都在代码里但是我既然想用 Agent自然是希望我不写代码从细节中解放出来如果什么细节都要我指示那还不如我自己干。所以在此之后我在运行每个任务前都会启动 plan mode先和 Agent 沟通好哪些决策点是我要关注的以及最终的方案是否需要修改这样确实能一定程度上解决问题。然而我不认为有 plan mode 就完美了因为 plan 也是用自然语言描述的自然语言本身有一定的模糊性比如“并发”这个词在一些场景就有多种理解“在大规模数据下提升性能”是提升 1GB 数据规模的性能还是 10GB 规模的性能是指定参数组合下的性能还是随机抽样参数下的性能诸如此类不一一列举。而代码是精确的是什么就是什么没有模糊的地带。自然语言和代码两种描述之间的 gap其实会在长程工作中不断放大直到你观测到偏差的出现。每一个未明确的细节点Agent 都可以以任意方式去完成它想要说清每个细节是困难且不现实的。因此我认为当前 Agent 的长程工作仍然需要人类监督而人类也必须清楚自己的需求在方向偏离的时候要及时纠正它。随着我深入使用 plan mode新的问题接踵而至。最突出的问题有两个3方案设计的trade-off 与决策空间的无穷性当然每一个方案都是某种程度上的权衡。对于我自己熟悉的领域来说每个方案的 trade-off 是清晰的优缺点是明确的未来的成果和隐患是有预期的这个时候我和 Agent 的沟通是顺畅的我也有把握去选择一个当前最优的方案。但我处理对技术细节不甚了解的领域时问题出现了我失去了对方案评判的能力。这个时候有两种选择一是直接无条件信任 Agent 列举的方案和 trade-off让 Agent 自己选择一个方案继续干遇到问题再自己 plan 自己干。我一开始尝试运用这种模式运用到通信算子的优化上但发现 Agent 运行了 48h 后性能迟迟没有进一步的提升。这时我突然发现如果让 Agent 自由探索的话它的决策空间是无穷大的如果没有一个明确的“梯度下降”方向Agent 就只能“随机游走”靠碰运气和不断尝试来完成“既要又要还要”的需求。一言以蔽之人类缺乏对于方案 trade-off 的感知加上决策空间的无穷性使得 Agent 完成任务变成了运气游戏你永远也不知道它下一步往哪走。所以一些文章吹嘘的“文科生靠 Agent 连续运行xx天实现了xxx”以至于“程序员要失业了”这种论调听听就算了因为实际项目需求的多样性和复杂性远不是实现某个东西那么简单的。所以我选择了第二种方案不能再让 Agent 自己乱跑了必须要参与方案制定的执行链条中来。虽然我现在不清楚哪种方案更靠谱但是我可以让 Agent 把这几种方案都实现一遍然后通过一些更细粒度的 benchmark 来比较几种方案的优劣培养自己对方案靠谱程度的感知久而久之我就可以参与到实际的决策中了。这个时候就遇到了第二个问题4多Agent 的并发和合作问题假如 Agent 给了我 A、B、C 三种方案如果我一个一个串行跑这些方案那也太费时间了。所以我打算多开几个 claude 进程来帮我并行实现。首先我必须为每种方案创建独立的工作目录以防它们相互影响于是可以用 claude 提供的 --worktree 功能创建三个 git worktree给它们不同的提示词来运行不同的方案。到此为止一切都很顺利。我很快发现即使隔离了工作目录它们也可能在其他地方产生资源竞争关系例如在同一个运行环境同时安装名称相同但功能有区别的包或是安装的包版本不同又例如两个 Agent 同时抢占 GPU 资源致使性能测试不准确。对于这个问题我目前是用文件锁和 docker 镜像来解决资源竞争问题的。但是有个问题锁这种管理传统进程/线程并发的方式真的适用于 Agent 吗如果一个 Agent 被打断不管是什么原因比如上下文长度满了、用量到限额了、手动打断了等等这个锁很有可能释放不掉或者 Agent 在之后就根本就忘记了锁的存在。即使通过锁和镜像隔离解决了资源竞争问题但每个 Agent 的执行路径不完全相同即使给了相同的 prompt 以及明确的步骤。有时候 Agent 跑着跑着忘了同步代码有时候同步代码的目标路径错了覆盖了其他 Agent 的目录有时候生成的报告路径放在了其他的 worktree上而不是当前的 worktree有时候编译代码时跑到了其他 worktree 的代码但跑性能测试时又用当前 worktree 的性能测试脚本有时候明明跑的是 C 的测试但 A 的测试也一块跑了结果报告的是 A 的性能有时候性能测试之后不生成报告和图表或是生成到了错误的位置或是每个 Agent 的保存路径、命名逻辑和报告格式各不相同。即使是同一个 Agent上述行为也会在上下文压缩时发生显著变化。比如这一轮在远端目录/foo下运行下一轮又在远端目录/bar下运行难道要我事无巨细把每个细节都说的明明白白吗……。虽然我觉得这些问题本质上都是上下文 compact 让信息丢失的问题。即使每个 Agent 都完美按照规定动作完成任务但何时让 Agent 结束任务如何整理并发 Agent 产生的不同路径的信息又是需要解决的问题。或许这个工作可以让一个单独的 Agent 完成类似于 Claude Agent Teams 的运作逻辑然而我还没有尝试过。Anyway相比于上面的问题Agent 同步问题反倒是没那么难解决。随着决策的深入我又对上面的问题产生了新的认识5Agent适合执行线性流程但不适合探索性的树形流程让 Agent 执行 Ralph Loop 这种线性流程它能 One by One 完成地非常好。可一旦需要往不同方向进行探索性实验那么环境隔离、信息整合、剪枝回退…… 哪哪都是难点。尤其是你想保留部分分支的一些好经验再到其他分支实践时这个工作的执行会让人类非常头疼。尤其是回退问题非常难解决。代码库可以简单地 git reset但回退前产生的经验、计划、文档、报告、记忆等文件却仍然留着这些文件通常不会纳入 git 版本管理因此有许多无效的实践经验和结果被保留下来了极大程度上影响了后续方案的判断。靠 Agent 整理这些内容也不现实因为整理的 Agent 需要掌握全局的进展才能正确处理且哪些内容是对后续探索方向有益/有害的从而要保留/删除哪些内容它没法知道因为后续探索方向是什么我也不知道。信息整合也是一大问题。如果 A、B、C 三个方案中最终选择了 C那么如何将 C 的实践成果合并到主路径上这可不是说一句“合并方案 C 到主仓库”就完事的。要注意 claude 的实例是运行在单个工作目录下的并且 claude 是按工作目录来管理记忆和上下文历史信息的。如何让它看到多个路径下的仓库并且在切换工作目录时不丢失上下文和记忆是困难的。我当然可以通过 /add-dir 命令和! cd 来临时切换目录但是从执行效果上来看不尽人意Agent 仍然没有很好地完成任务。究其原因是理解“合并”这个词的具体含义是非常困难的。具体而言如何将 C 的 worktree merge 到主仓库中如何清理 A、B 以及旧方案的代码和各种记忆、文档、测试并全部替换为 C 的代码和记忆、文档、测试等上下文信息并且Agent 真的知道合并的含义吗是 git merge 到主仓库吗还是能理解在这个场景下其实有更快的方法就是直接删除主仓库并将 C 的 worktree 的所有内容作为新的主仓库毕竟 C 的 worktree 就是从主仓库而来的。即使这些工作它都完成了难道效率层面就比人快了我来合并不同方案复制粘贴删除 10min 就搞定。用 Agent写出一个明确无歧义的指令可能都要 5min运行之后结果还不一定让我满意。实践结果表明Agent 首先会左看看右看看先读 C 方案和主仓库的代码文件考虑要怎么做代码“合并”最为妥当有时会被无关的信息所干扰比如两个方案的具体内容和设计文档。随着每一项工作的进行上下文和知识库的管理也变得愈发重要。这里也列举出我遇到的一些坑##6上下文切换和压缩带来的指令丢失问题这个其实是大家都会遇到的问题了。给 Agent 的指令和要求会随着 compact 慢慢丢失会忘记 workflow 的一些步骤和关键细节命名规范、保存路径因为这些细枝末节很可能被 compact skill 所忽略了但却对后续 loop 的正确执行非常关键。我的临时解决方法有对于需求点明确的工作可采用 Ralph Loop 的工作模式因为这个模式中每个上下文都是全新的对于持续性探索工作可以创建一个 /loop 任务将你想要保留的重要信息放在 loop 的提示词中。但我总觉得还有更优雅的解决方案欢迎大家分享下自己的经验~7进展文件的管理问题主要问题是 progress 文件越来越长且可能包含不同分支的进展污染上下文在项目做大之后管理进展文件会非常头疼。这些问题相对来说没有那么严重且目前也可以通过一些技巧规避它我就不过多阐述了。Agent 写代码的能力有目共睹我也相信 Agent 的能力边界不只是写代码它终有一天能够替代研究、创新、自动迭代等近乎一切人类所做的复杂工作并以更加高效的方式完成以成本更低的 scaling 方式规模化量变引起质变。或许将来所有的软件形态所有的商业模式乃至所有基于人类的组织架构都必须围绕着 Agent 进行重构。