这篇文章总结了我在实际应用 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 同步问题反倒是没那么难解决。
随着决策的深入，我又对上面的问题产生了新的认识：
（5）Agent适合执行线性流程，但不适合探索性的树形流程
让 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 进行重构。