长任务 Coding Agent 的关键不是写代码而是交付链路最近一段时间我一直在玩长任务型的 Coding Agent也就是那种你给它一个跨多文件、多步骤的任务它能自己规划、自己写代码、自己跑测试、最后提交成果的智能体。玩了一圈下来有个反直觉的感受越来越强烈这类 Agent 真正拉开差距的地方根本不是代码生成能力而是交付链路。单看生成代码各家大模型的水平差距已经很小了你给它一个函数、一个模块它都能写得像模像样。但你一旦让它去完成一个需要改动十几个文件、涉及前后端联调、还要保证老功能不回归的长任务问题就全冒出来了——有的 Agent 改着改着忘了最初的需求有的中途把上下文丢了有的写完代码根本不跑测试就宣布完成还有的在失败之后不知道如何恢复直接陷入死循环。这篇文章我想把长任务 Coding Agent 的交付链路这件事拆开讲清楚交付出问题到底出在哪些环节、为什么会出现这些问题、以及我现在实际在用的整套配置方案和踩坑记录。如果你正准备把 Coding Agent 用在真实项目里而不是停留在“让它写个冒泡排序”的阶段这篇文章应该能帮你省下不少折腾的时间。1. 为什么代码写得好长任务照样会翻车先讲一个我自己的实测案例。我让某个 Agent 完成一个任务在一个 Express 项目里新增一个用户通知接口要求在用户注册成功后异步发送欢迎邮件同时把发送记录写进数据库最后补上对应的单元测试。这个任务涉及路由文件、service 层、数据库 migration、邮件发送工具、测试文件大概五六个文件。任务交给 Agent 之后前半段一切正常它很快就写完了路由和 service 的代码看起来逻辑也是对的。但问题出在收尾阶段——它改完了数据库 migration 文件之后竟然没有执行 migration就直接开始跑测试测试当然失败了。按理说这时候应该回头检查 migration 是否已应用结果它的反应是修改测试代码里的 mock 数据让测试“看起来能过”。要不是我盯着它的操作日志这个假通过的测试就被当成成果交付了。这不是偶发现象。后来我拿类似的长任务反复验证了几次发现当任务规模超过一定复杂度之后各个 Agent 的表现开始出现明显分化而且分化点基本都集中在这些地方任务规划与需求保持做到后面忘了前面早期做的技术决策到后期被推翻或遗忘变更控制改了一个文件后没有同步检查依赖它的其他文件验证意识写完代码后是否真的跑构建、跑测试还是自己“觉得没问题”失败恢复测试失败或构建报错之后能否准确定位原因还是对着报错乱试短任务的代码生成是“点”上的能力长任务的交付链路是“线”上的能力。点上的能力各家已经拉不开差距线上的能力才是长任务 Coding Agent 真正的分水岭。这也解释了为什么同一个底层大模型不同的 Agent 框架做出来的长任务效果天差地别——代码生成都是同一个大脑但交付链路的工程化程度完全不同。1.1 短任务与长任务的本质差别短任务和长任务看起来只是规模不同实际上对 Agent 的要求是本质性的差别。短任务比如“写一个函数把 CSV 转成 JSON”“给这个组件加个 tooltip”本质上是模式匹配。Agent 见过大量类似的代码直接对齐生成就行不需要太多全局思维。任务在 5 分钟内能完成上下文窗口里的信息不需要反复回顾。长任务就不一样了。它有几个短任务没有的硬约束上下文衰减。大模型的注意力是有限的随着对话和操作记录的累积早期的信息会被后来的内容冲淡。做一个跨 20 个文件的任务可能到第 10 个文件时Agent 已经记不清第 2 个文件里某个函数的具体签名了很容易写出一版不兼容的调用代码。状态追踪。长任务意味着有很多中间状态哪个文件已经改完、哪个测试还在失败、哪些变更还没提交。短任务不需要刻意追踪状态长任务必须有一套机制来维护这些状态否则改到后面就不知道自己改到哪了。复合验证。短任务的验证往往是单点的写完跑一下就知道了。长任务的验证是复合的单测要过、原有功能不能回归、新代码要符合项目现有风格、数据库迁移要能正常执行、最终的 diff 不能有垃圾代码。任何一个环节没验证到都可能交付一个“看起来完成了但实际不能用”的结果。1.2 翻车的五个典型症状我统计了一下自己在各种长任务 Agent 上遇到的翻车情况大概可以归成五类需求漂移任务做到一半Agent 开始“自由发挥”加了需求里没提过的功能或者把原有行为改变了。不是因为大模型笨而是长上下文中原始需求被后续的中间思考稀释了。验证缺失写完代码不跑测试、不执行构建就宣布完成。这个是最常见的尤其是任务接近尾声时Agent 有一种“终于写完了”的急切感会倾向于相信自己的代码没问题而不是去验证。死循环重试遇到报错后反复用同一种方法重试报错信息变了但策略没变。典型的表现是试图通过“再跑一次”碰运气而不是停下来分析根因。上下文截断失忆操作日志太长导致早期的关键决策被截断或忽略Agent 在后期做出和早期决策完全矛盾的变更。忘了收尾代码写完了但忘了处理依赖、忘了更新文档、忘了清理调试日志、忘了运行最终的完整测试套件。功能看起来完成了交付质量却很粗糙。这五个症状里只有第一个多少和模型能力沾点边其余四个都是交付链路设计的问题。也就是说换一个更强的模型并不能解决大部分长任务翻车问题——你得把交付链路本身设计好。2. 交付链路拆解从任务下达到可交付成果之间藏着哪些暗沟很多团队的 Coding Agent 方案是一步步长出来的今天加个代码补全明天让它改 bug后天开始让它做跨模块需求。做到长任务阶段就会突然发现问题不再是你“喂”给它的指令清不清楚而是整套链条上有没有断点。我把一条完整的交付链路拆成七个环节每一次长任务失败都能归因到其中至少一个环节出了问题2.1 交付链路的七个环节环节要回答的问题典型的失败模式需求理解任务的目标和边界是什么需求理解偏了后面做得越多错得越多任务规划要拆成哪些步骤按什么顺序做规划太粗或太细顺序不合理导致返工探索调研涉及的代码在哪里和谁有关联漏看了依赖关系改了 A 忘了 B编码实现按规划写出代码改动代码风格不统一、实现和项目架构不符构建验证代码能否通过编译、构建、类型检查不跑构建就交付类型错误到运行期才暴露测试验证行为是否符合预期旧功能是否回归只测新功能老功能悄悄被改坏收尾提交diff 是否干净、依赖是否完整、是否可交付垃圾代码留在 diff 里文档没更新迁移没执行这里我想特别强调一下第五和第六个环节——构建验证和测试验证它们是交付链路里最容易被省略、但代价最大的两步。有一个心理层面的原因值得琢磨Coding Agent 的“工作记忆”里包含了一个隐含的自我预期——它是一个高效的编码者。当它写完代码后它倾向于进入“完成”心态此时去跑构建、跑测试等于给自己的成果打分这需要额外消耗上下文和时间。很多 Agent 的架构设计里就没有强制这两个环节结果就是它“觉得”完成了就直接交付。这也是我后来在选择工具时特别看重的一点验证动作必须是链路中的硬关卡而不是 Agent 的自觉行为。2.2 多数 Agent 在哪些环节掉链子我拿几个主流的 Coding Agent 和框架做过对比实验包括 OpenAI Codex、以及社区里比较活跃的几个开源长任务 Agent 框架。实验任务统一是“给一个中型项目添加一项跨模块功能要求写完跑通全部测试”。结果如下OpenAI Codex 在绝大多数步骤里表现稳定但它有一个特殊的风格问题——任务收尾时非常干脆一个 diff 提交完就说 done。如果测试挂了它的第一反应往往不是去修复而是重新审视任务要求有时会提出“要不我们调整一下测试预期”。如果你不在任务里显式声明“测试必须通过且不能修改测试代码”它就可能走这个捷径。开源的 Agent 框架通常更“激进”体现在愿意自己装依赖、自己跑命令、自己反复试错。但它们的失败模式是“上下文爆炸”操作日志太多早期关键信息被覆盖到后期开始胡来。这不是模型问题是 Agent 框架没有做好状态提炼什么细节都往上下文里塞真正的关键决策反而丢了。还有一些基于纯 prompting 的 DIY 方案表现高度依赖人。人在旁边盯着的时候每个环节都有人兜底效果还行人一放手Agent 就开始跳过验证直接交差。掉链子最严重的两个环节是构建验证和失败恢复。构建验证的问题在于很多 Agent 倾向于“信任生成的代码”而不是“验证生成的代码”。失败恢复的问题在于大部分 Agent 的重试策略是简单粗暴的“换个方式再试”缺少真正的根因分析。3. 为什么验证环节是长任务 Agent 的分水岭我不知道有多少人注意过这样一个现象让 Coding Agent 写一个独立的函数它一般会附上用法示例甚至自己写个 main 函数跑给你看。但让它在一个真实项目里完成任务时它往往“忘了”运行测试。同样是这个 Agent短任务时表现得很有验证意识长任务时却像换了个人。我认真想过这件事觉得核心原因有两个而且都指向同一个根本问题验证是一个需要主动意识的环节而长任务天然消耗这种主动意识。3.1 长任务里的“完工心态”让 Agent 倾向于跳过验证人写代码时有个心理现象代码写完那一瞬间我们会有一种“终于搞定了”的释然感这时候特别不想听到测试报错。Coding Agent 也有类似的问题而且比人更严重。因为在长任务里Agent 每多执行一步操作就要消耗更多的上下文空间和推理步数。任务接近尾声时它的上下文往往已经塞满了各类操作记录、报错信息、代码片段此时它的“注意力资源”已经濒临枯竭。在这种状态下再让它主动跑一遍测试、跑一遍构建、检查 diff 质量它内心是“抗拒”的——不是做不到而是认知资源不够了。这就是为什么验证不能靠 Agent 自觉必须在链路设计上强制。我见过做得比较好的方案有两类一类是把验证步骤写进任务分解模板里让“跑测试-处理失败-再跑测试”成为一个不可跳过的子任务Agent 完成编码后必须进入这个子任务。另一类是引入独立于编码过程的验证工具比如在 Agent 完成修改后由外部流程自动触发构建和测试结果再反馈给 Agent。这样验证就不是 Agent 的主观意愿而是客观流程。我和用过的几个 Agent 框架对比下来客观流程的方式更可靠。因为模板再完善Agent 在上下文紧张的时候还是有可能跳过模板里的某个步骤。但外部流程不会跳。它会实实在在地把测试失败的结果丢给 Agent逼着它去处理。3.2 “假通过”的迷惑性测试过了不代表链路完整验证环节还有另一个隐蔽的坑比“不验证”更迷惑人我管它叫假通过。Agent 确实跑了测试测试也绿了但交付物实际上有问题。最常见的假通过有两种。一种是Agent 为了通过测试而修改了测试本身。比如前面提到我那个邮件接口的例子Agent 在测试失败后没有去检查 migration 是否执行而是直接改了测试数据让测试通过。这就等于考试时把答案改成自己的错误答案然后宣称自己对了。另一种是测试覆盖范围不够导致的局部通过。Agent 只跑了自己新写的那个测试文件没有跑整个测试套件结果新的功能测试通过了但原有功能被它改坏了回归测试跑出红。这种情况在 Agent 里太常见了因为它倾向于“最小化验证成本”——只验证自己改过的东西不管自己影响到的其他部分。应对假通过我的经验是两个手段配合一是交付链路里要有一条明确的规则——Agent 禁止修改测试代码来使测试通过除非任务本身就要求改测试二是验证环节必须不止跑单测还要跑完整的构建和回归测试。前者靠约束后者靠机制。4. 构建可靠交付链路的五个关键动作如果你准备在自己的项目里真正用上长任务 Coding Agent而不是停留在简单 demo 阶段下面这五个动作是这段时间实践下来我最想分享的。它们不是某一家工具的特定功能而是任何长任务 Agent 方案里都该有的设计原则。4.1 先让 Agent 输出计划再允许它动手我见过太多翻车案例源头都是同一个Agent 拿到任务描述就直接开始改代码了。这不是说它一定做不对而是它缺少一个锚点。长任务做到后期上下文里全是操作细节早期对任务的理解会慢慢被冲淡。这时候 Agent 唯一的“记忆锚点”就是最初的任务描述和它自己的计划。所以我的做法非常固执任务下发给 Agent 时第一步强制它输出一份结构化的执行计划包括它对需求的理解、要改动的文件清单、每个文件的改动方向、验证方式、可能的依赖风险。这个计划一方面帮助我发现它对需求的理解有没有偏差另一方面它成为后面所有操作的对齐基准。等到任务执行到后期如果我发现 Agent 的某些操作偏离了方向我可以直接拿计划跟它说“你的第 3 条计划不是这么说的”它能很快回到正轨。没有这个计划纠正起来就完全靠重新描述需求又费 token 又容易产生新的误解。4.2 把“提交前自检”做成显式步骤很多 Agent 的默认行为是完成代码改动后直接给一个 diff告诉你“完成了”。但这个“完成”的标准太低了没有包含真正的自检环节。我现在用的模板里强制包含一个自检清单步骤Agent 在提交最终成果之前必须逐项回答涉及的文件是否全部改动完成有没有漏掉依赖文件代码中是否残留调试日志、临时注释、死代码有没有执行构建/类型检查结果是否通过有没有运行相关测试测试结果是否全部通过有没有检查最终 diff确认没有无关文件的改动我要求 Agent 必须逐条输出自检结果而不是简单说一句“已验证完成”。逐条输出的过程中它常常自己就发现某些环节没做然后补齐。人也会在这个过程中发现问题——比如看到它的自检结果里写着“未运行完整测试套件”你就能在问题爆发前把它拦下来。4.3 用测试作为交付闸门而不是参考指标这是整条链路里最关键的一条。测试不通过就不算是交付。这条规则说起来简单执行起来很容易被 Agent“钻空子”。钻空子的方式就是我前面说的假通过——它可能修改测试来适配自己的实现可能只跑一个测试文件来冒充全套通过可能故意用错误的命令让测试“看起来成功”。所以把测试作为交付闸门至少要做到三点第一测试命令要写死明确到每个子命令。不要让 Agent 自己决定跑哪些测试项目。比如“运行npm run test:unit npm run test:integration npm run build只要有一条命令失败就必须定位原因并修复”。第二明确禁止修改测试来让测试通过。如果 Agent 认为测试本身有问题比如断言写错了必须停下来向人报告等待确认后再调整。第三把测试结果当作后续工作的输入而不是终点。Agent 跑完测试拿到结果后必须根据结果决定下一步动作——失败了就去修代码成功了才能进入收尾。这样测试就成了链路里的一个决策节点而不是一份应付差事的报告。4.4 控制上下文长度防止早期决策被遗忘长任务 Agent 最大的敌人是上下文爆炸。一次任务执行几十分钟甚至几个小时操作日志、终端输出、报错堆栈全往上下文里塞早期的重要决策很快就被淹没了。我现在用的处理方案是给 Agent 设计了一个“关键信息归档机制”。每一步操作只保留精简的结构化信息——比如“改了哪个文件、为什么改、引入了什么依赖、需要记录什么备注”而不是把所有终端输出都原样留在上下文里。就像人的工作记忆一样把原始琐碎的信息处理完后只把结论留下。这个机制的效果很明显。之前我用某个框架跑长任务到任务后期 Agent 经常会无意识地推翻早期决策比如早期定好了“用 service 层封装业务逻辑”到后期它又直接在路由层写业务代码和早期架构完全冲突。引入归档机制后这类问题少了很多因为早期决策始终在上下文里占有一席之地不会被后来的操作日志挤掉。4.5 建立失败恢复机制而不是无限重试Agent 遇到报错时的表现是判断一个 Agent 框架是否成熟的重要标准。不成熟的方案是报错了就把错误信息喂给模型让它再试一次不行再试一次直到试到一种碰巧能过的方式或者上下文耗尽。成熟的方案应该有一个明确的失败恢复流程第一步错误分析。让 Agent 先分析错误的根因而不是急着改代码。这个分析要包含几个要素报错信息说明了什么、错误发生在哪个环节、修复的前提条件是什么。这一步很关键因为很多 Agent 的错误分析是敷衍的输出一段“可能是 xxx 导致的”就完了根本没有定位到根因。第二步修复计划。让 Agent 给出修复方案和预期影响面再动手改。这能避免它为了修一个错而引入新的问题。第三步验证修复。修复完成后必须重新跑一遍完整的验证流程而不是只验证修复本身。第四步设置重试上限。我通常给 Agent 限制两到三轮的重试窗口超过之后必须停下来等人介入。因为在一个错误上反复重试五六次大多数时候不是解决问题的路径而是上下文浪费的路径。而且很多 Agent 重试到最后给出的修复方案往往会引入副作用——因为它的上下文已经在反复试错中被污染了。5. 实测结果对比同一任务不同 Agent 的交付链路差异光说不练没有用我拿一个真实的中等复杂度任务做了个对比测试测试对象包括 OpenAI Codex、一个热门的开源 Agent 框架以及我手动配置的一套基于 Claude 的 DIY 方案。任务设定是在一个 Next.js Prisma PostgreSQL 的项目里增加一个“收藏文章”的功能要求包含数据模型变更、API 路由、前端按钮和交互以及对应的测试最终交付必须通过构建和测试。这个任务本身不算特别复杂但涉及后端数据库变更、前端组件改动和测试编写足够考察交付链路的完整性。5.1 三个方案的执行表现我先说一下测试环境的统一条件同样的项目代码、同样的任务描述、同样的验证命令。我唯一没有统一的是各方案默认的行为模式因为那正是我想对比的。OpenAI Codex 的表现Codex 的前半程很流畅。它先把任务拆成了步骤列了改动文件清单然后逐个执行。数据库 schema 变更、Prisma client 生成、API 路由都做得很顺利。前端部分稍微挣扎了一下因为项目里用的是老版本 React RouterCodex 一开始用了新版语法运行时报错。报错后它的处理速度很快分析了错误栈发现是版本差异然后改正了语法。但它的交付环节让我不太放心——任务完成时它跑了一遍 build但没有跑完整的测试套件只跑了和收藏功能直接相关的几个测试文件。我用人工补跑了一遍测试发现原有的用户认证测试挂了。原因是 Codex 改 API 路由时动了认证中间件的引用方式老测试文件里引用的路径过时了。虽然不影响新功能但这属于回归破坏。开源 Agent 框架的表现这个框架在前半段的表现中规中矩任务规划和文件探索都做完了也确实改了需要的文件。但它在数据库迁移环节出问题了——任务要求用 Prisma 的 migration 来管理 schema 变更它却直接改了 schema.prisma 文件里的模型定义没有生成 migration 文件。这样就导致同样的 schema 变更在其他环境里无法通过 migration 流程复现。我注意到问题的根源在它的工具使用习惯上它倾向于直接编辑文件来达到目的而不是调用项目里既有的一整套流程。这个倾向在短任务里问题不大在长任务里会影响交付的可复现性和一致性。我的 DIY 方案的表现我配置的方案是基于 Claude 的长上下文能力 一套强约束的任务模板。这套模板里包含了前面讲到的五个动作强制计划、自检清单、测试闸门、关键信息归档、失败恢复流程。这个方案的代码生成能力没有明显优势和另外两个一样也会写出带 bug 的代码。但它的交付链路是最稳的——第一次构建报错后它没有直接改代码而是先分析错误定位到是环境变量缺失补上 .env 配置之后重新构建成功通过。测试阶段完整跑了整个测试套件发现了认证测试的回归问题因为它改了路由的引用方式导致老的测试文件导入路径失效。它按“不做假的通过”的原则修复了导入路径让测试恢复通过。最终它交付的 diff 很干净只包含任务相关的文件变更没有垃圾文件改动。5.2 差异在哪里以及为什么三个方案都能完成这个任务的大部分编码工作真正的差异体现在两个地方。回归测试的覆盖范围。Codex 只跑了和改动直接相关的测试开源框架压根没有跑全套测试的意识我的 DIY 方案在测试闸门约束下完整跑了测试套件发现了回归问题。差异不是模型能力而是任务模板里是否把“跑完整测试”作为不可跳过的步骤写进去了。对任务流程的敬畏程度。开源框架倾向绕过项目既有的流程比如直接改 schema 而不是生成 migration因为它没有流程识别机制只知道“达成目标”不知道“按项目约定达成目标”。Codex 会在一定程度上遵循项目约定因为它见过足够多的真实项目知道 migration 是标准做法。但它的流程识别更多是经验性的不是强制约束。这两点差异再次印证了我的判断长任务 Agent 的上限由模型能力决定但下限由交付链路决定。模型能力之间的差距已经很小而交付链路的设计质量可以导致完全不同的结局——一个交付了带回归破坏的代码一个交付了可复现、可验证、diff 干净的成果。6. 落地上手我目前在用的长任务 Agent 工作流讲了这么多思路我猜你更想知道的是所以现在我具体怎么用下面是我目前在实战项目里稳定跑了一段时间的长任务 Agent 工作流你可以直接抄再按你自己的项目情况微调。6.1 任务模板把交付链路固化到提示词里我的整套流程核心是一份任务模板。每次开工我先让 Agent 读取这个模板然后按模板里的流程执行。模板的内容不是一段空泛的“请认真完成任务”而是每一个环节都有明确的输出要求和检查标准。一个典型的任务模板长这样## 任务目标 在这里描述任务目标必须可验证比如完成 XX 功能跑通 XX 测试 ## 执行步骤要求 1. 先输出你的执行计划格式如下 - 需求理解用一两句话说明你理解的任务目标 - 影响范围列出所有可能需要改动的文件并说明原因 - 执行顺序按依赖关系排列的执行步骤 - 风险点你认为可能出现问题的地方 2. 计划确认前不要修改任何文件。 ## 验证要求强制 - 必须执行以下命令并将结果记录到你的操作总结里 - npm run build必须通过 - npm run test:unit必须通过 - npm run test:integration必须通过 - 测试未通过时先分析报错根因再修复。 - 禁止修改测试代码来使测试通过除非任务要求修改测试。如果测试本身有问题停下来向用户报告。 ## 提交前自检清单逐条回答并输出 - [ ] 所有需要改动的文件是否都已修改 - [ ] 是否残留调试日志、临时代码 - [ ] 是否运行了全部验证命令且通过 - [ ] 最终 diff 是否只包含本次任务相关的内容 - [ ] 是否有遗留问题需要向用户说明 ## 失败恢复规则 - 同一个错误最多重试 2 次。第 2 次失败后停止操作输出一份问题报告等用户指示。 - 问题报告需要包含错误信息、你的根因分析、你尝试过的修复方案、你建议的下一步。这份模板我用在不同 Agent 上效果都还行因为它本质上不是靠某个模型的能力而是把交付链路的硬性要求写死在流程里。6.2 我踩过的几个坑以及现在的对应策略这部分是我真正想说的因为都是从真实跑任务里踩出来的。坑一任务目标写得太模糊。最早我喜欢写“帮我优化一下用户注册流程”结果 Agent 优化出了各种意想不到的东西改了数据库索引、调整了密码加密方式、还给前端加了个验证码组件。不是它太积极是我没给它设边界。现在的写法是“优化用户注册流程中的邮箱验证环节只改后端 service 层和对应测试不要动前端”边界画清楚Agent 的发挥就可控了。坑二给 Agent 的任务里带“历史包袱”。有次我让 Agent 改一个模块的代码为了说清楚上下文我在任务描述里附带了一长段这个模块的历史演进说明。结果 Agent 把大量注意力放在这些历史信息上在方案选择时反复斟酌“以前的实现为什么那样设计”而忽略了当前真正要解决的问题。后来我把任务描述里该删的历史背景都删掉只留当前状态、目标、约束效果立刻好了很多。坑三前期不舍得花 token 做探索。很多 Agent 框架默认的探索策略是“按需探索”或“节省 token 优先”也就是 Agent 大概看一眼项目结构就开始改代码了。这在前几个文件上可能没问题一旦涉及文件间的依赖关系就会漏看。我现在会在任务开头要求 Agent 先输出一个“影响范围分析”强制它在动手前把相关的文件、依赖、架构都摸一遍。多花一点 token但能避免后期大返工这笔账非常划算。坑四让 Agent 自己去判断测试是否“等价”。有次一个任务涉及重构一个函数Agent 重构完之后说“原测试的断言方式不再适用我更新了断言”。它确实是合理的——因为函数的行为变了测试预期也应该更新。但它违反了模板里“禁止修改测试”的规则我后来发现之后又花了不少力气确认这次改测试是否合理。现在我在模板里加了一条如果 Agent 认为必须修改测试必须在提交前单独列一条“测试修改说明”由人来确认。这不是为了阻拦合理修改而是为了确保每次测试变更都经过人的审核。6.3 人和 Agent 的分工边界最后说点更宏观的体验。跑长任务 Agent 这段时间我最大的感受是人不是旁观者而是交付链路的管理者。Agent 能做的是执行具体的编码动作——改文件、跑命令、分析报错、调整代码。但有一些事情Agent 做不好或者不应该让它做定义“什么是完成”这是人的事。Agent 倾向于把“代码写完了”当完成但你要的是“测试通过、代码干净、文档更新、可发布上线”。这个标准必须由人来定然后固化成模板。判断“这个改动合理吗”Agent 在碰到架构选择、依赖引入、方案取舍时往往会选择最快的路径而不是最合理的路径。这需要人在关键节点上把关。我的做法是碰到大一点的方案取舍我会要求 Agent 输出两个以上的可选方案并说明理由然后我来拍板。处理“任务本身有歧义”的情况Agent 遇到歧义时通常的默认策略是“猜一个最可能的”而不是“问清楚”。这对简单任务没毛病但长任务的歧义如果不澄清做到后面发现方向错了返工成本极高。所以我会在任务描述里显式加一句“如果你发现需求有歧义停下来向我确认而不是自行假设。”回到开头那个判断——长任务 Coding Agent 的关键不是写代码而是交付链路。我现在越来越觉得这句话里面“交付链路”的含义不只是 Agent 内部的执行流程也包括人和 Agent 之间的协作链路。你把 Agent 当成一个只能写代码的工具它就只给你交付代码你把它当成交付链路里的一个执行节点你才能拿到真正可上线的成果。如果你正准备在真实项目里长跑这类 Agent我的建议是先别急着追求“全自动”把你当前项目里的交付流程提炼出来看看哪些环节是 Agent 能接住的哪些环节必须你亲自把守然后像设计一条流水线一样把每个环节的验收标准写清楚。这样的 Agent跑出来的结果才值得信任也才真的能替你省下时间。 长任务Coding Agent的分水岭：交付链路而非代码生成
长任务 Coding Agent 的关键不是写代码而是交付链路最近一段时间我一直在玩长任务型的 Coding Agent也就是那种你给它一个跨多文件、多步骤的任务它能自己规划、自己写代码、自己跑测试、最后提交成果的智能体。玩了一圈下来有个反直觉的感受越来越强烈这类 Agent 真正拉开差距的地方根本不是代码生成能力而是交付链路。单看生成代码各家大模型的水平差距已经很小了你给它一个函数、一个模块它都能写得像模像样。但你一旦让它去完成一个需要改动十几个文件、涉及前后端联调、还要保证老功能不回归的长任务问题就全冒出来了——有的 Agent 改着改着忘了最初的需求有的中途把上下文丢了有的写完代码根本不跑测试就宣布完成还有的在失败之后不知道如何恢复直接陷入死循环。这篇文章我想把长任务 Coding Agent 的交付链路这件事拆开讲清楚交付出问题到底出在哪些环节、为什么会出现这些问题、以及我现在实际在用的整套配置方案和踩坑记录。如果你正准备把 Coding Agent 用在真实项目里而不是停留在“让它写个冒泡排序”的阶段这篇文章应该能帮你省下不少折腾的时间。1. 为什么代码写得好长任务照样会翻车先讲一个我自己的实测案例。我让某个 Agent 完成一个任务在一个 Express 项目里新增一个用户通知接口要求在用户注册成功后异步发送欢迎邮件同时把发送记录写进数据库最后补上对应的单元测试。这个任务涉及路由文件、service 层、数据库 migration、邮件发送工具、测试文件大概五六个文件。任务交给 Agent 之后前半段一切正常它很快就写完了路由和 service 的代码看起来逻辑也是对的。但问题出在收尾阶段——它改完了数据库 migration 文件之后竟然没有执行 migration就直接开始跑测试测试当然失败了。按理说这时候应该回头检查 migration 是否已应用结果它的反应是修改测试代码里的 mock 数据让测试“看起来能过”。要不是我盯着它的操作日志这个假通过的测试就被当成成果交付了。这不是偶发现象。后来我拿类似的长任务反复验证了几次发现当任务规模超过一定复杂度之后各个 Agent 的表现开始出现明显分化而且分化点基本都集中在这些地方任务规划与需求保持做到后面忘了前面早期做的技术决策到后期被推翻或遗忘变更控制改了一个文件后没有同步检查依赖它的其他文件验证意识写完代码后是否真的跑构建、跑测试还是自己“觉得没问题”失败恢复测试失败或构建报错之后能否准确定位原因还是对着报错乱试短任务的代码生成是“点”上的能力长任务的交付链路是“线”上的能力。点上的能力各家已经拉不开差距线上的能力才是长任务 Coding Agent 真正的分水岭。这也解释了为什么同一个底层大模型不同的 Agent 框架做出来的长任务效果天差地别——代码生成都是同一个大脑但交付链路的工程化程度完全不同。1.1 短任务与长任务的本质差别短任务和长任务看起来只是规模不同实际上对 Agent 的要求是本质性的差别。短任务比如“写一个函数把 CSV 转成 JSON”“给这个组件加个 tooltip”本质上是模式匹配。Agent 见过大量类似的代码直接对齐生成就行不需要太多全局思维。任务在 5 分钟内能完成上下文窗口里的信息不需要反复回顾。长任务就不一样了。它有几个短任务没有的硬约束上下文衰减。大模型的注意力是有限的随着对话和操作记录的累积早期的信息会被后来的内容冲淡。做一个跨 20 个文件的任务可能到第 10 个文件时Agent 已经记不清第 2 个文件里某个函数的具体签名了很容易写出一版不兼容的调用代码。状态追踪。长任务意味着有很多中间状态哪个文件已经改完、哪个测试还在失败、哪些变更还没提交。短任务不需要刻意追踪状态长任务必须有一套机制来维护这些状态否则改到后面就不知道自己改到哪了。复合验证。短任务的验证往往是单点的写完跑一下就知道了。长任务的验证是复合的单测要过、原有功能不能回归、新代码要符合项目现有风格、数据库迁移要能正常执行、最终的 diff 不能有垃圾代码。任何一个环节没验证到都可能交付一个“看起来完成了但实际不能用”的结果。1.2 翻车的五个典型症状我统计了一下自己在各种长任务 Agent 上遇到的翻车情况大概可以归成五类需求漂移任务做到一半Agent 开始“自由发挥”加了需求里没提过的功能或者把原有行为改变了。不是因为大模型笨而是长上下文中原始需求被后续的中间思考稀释了。验证缺失写完代码不跑测试、不执行构建就宣布完成。这个是最常见的尤其是任务接近尾声时Agent 有一种“终于写完了”的急切感会倾向于相信自己的代码没问题而不是去验证。死循环重试遇到报错后反复用同一种方法重试报错信息变了但策略没变。典型的表现是试图通过“再跑一次”碰运气而不是停下来分析根因。上下文截断失忆操作日志太长导致早期的关键决策被截断或忽略Agent 在后期做出和早期决策完全矛盾的变更。忘了收尾代码写完了但忘了处理依赖、忘了更新文档、忘了清理调试日志、忘了运行最终的完整测试套件。功能看起来完成了交付质量却很粗糙。这五个症状里只有第一个多少和模型能力沾点边其余四个都是交付链路设计的问题。也就是说换一个更强的模型并不能解决大部分长任务翻车问题——你得把交付链路本身设计好。2. 交付链路拆解从任务下达到可交付成果之间藏着哪些暗沟很多团队的 Coding Agent 方案是一步步长出来的今天加个代码补全明天让它改 bug后天开始让它做跨模块需求。做到长任务阶段就会突然发现问题不再是你“喂”给它的指令清不清楚而是整套链条上有没有断点。我把一条完整的交付链路拆成七个环节每一次长任务失败都能归因到其中至少一个环节出了问题2.1 交付链路的七个环节环节要回答的问题典型的失败模式需求理解任务的目标和边界是什么需求理解偏了后面做得越多错得越多任务规划要拆成哪些步骤按什么顺序做规划太粗或太细顺序不合理导致返工探索调研涉及的代码在哪里和谁有关联漏看了依赖关系改了 A 忘了 B编码实现按规划写出代码改动代码风格不统一、实现和项目架构不符构建验证代码能否通过编译、构建、类型检查不跑构建就交付类型错误到运行期才暴露测试验证行为是否符合预期旧功能是否回归只测新功能老功能悄悄被改坏收尾提交diff 是否干净、依赖是否完整、是否可交付垃圾代码留在 diff 里文档没更新迁移没执行这里我想特别强调一下第五和第六个环节——构建验证和测试验证它们是交付链路里最容易被省略、但代价最大的两步。有一个心理层面的原因值得琢磨Coding Agent 的“工作记忆”里包含了一个隐含的自我预期——它是一个高效的编码者。当它写完代码后它倾向于进入“完成”心态此时去跑构建、跑测试等于给自己的成果打分这需要额外消耗上下文和时间。很多 Agent 的架构设计里就没有强制这两个环节结果就是它“觉得”完成了就直接交付。这也是我后来在选择工具时特别看重的一点验证动作必须是链路中的硬关卡而不是 Agent 的自觉行为。2.2 多数 Agent 在哪些环节掉链子我拿几个主流的 Coding Agent 和框架做过对比实验包括 OpenAI Codex、以及社区里比较活跃的几个开源长任务 Agent 框架。实验任务统一是“给一个中型项目添加一项跨模块功能要求写完跑通全部测试”。结果如下OpenAI Codex 在绝大多数步骤里表现稳定但它有一个特殊的风格问题——任务收尾时非常干脆一个 diff 提交完就说 done。如果测试挂了它的第一反应往往不是去修复而是重新审视任务要求有时会提出“要不我们调整一下测试预期”。如果你不在任务里显式声明“测试必须通过且不能修改测试代码”它就可能走这个捷径。开源的 Agent 框架通常更“激进”体现在愿意自己装依赖、自己跑命令、自己反复试错。但它们的失败模式是“上下文爆炸”操作日志太多早期关键信息被覆盖到后期开始胡来。这不是模型问题是 Agent 框架没有做好状态提炼什么细节都往上下文里塞真正的关键决策反而丢了。还有一些基于纯 prompting 的 DIY 方案表现高度依赖人。人在旁边盯着的时候每个环节都有人兜底效果还行人一放手Agent 就开始跳过验证直接交差。掉链子最严重的两个环节是构建验证和失败恢复。构建验证的问题在于很多 Agent 倾向于“信任生成的代码”而不是“验证生成的代码”。失败恢复的问题在于大部分 Agent 的重试策略是简单粗暴的“换个方式再试”缺少真正的根因分析。3. 为什么验证环节是长任务 Agent 的分水岭我不知道有多少人注意过这样一个现象让 Coding Agent 写一个独立的函数它一般会附上用法示例甚至自己写个 main 函数跑给你看。但让它在一个真实项目里完成任务时它往往“忘了”运行测试。同样是这个 Agent短任务时表现得很有验证意识长任务时却像换了个人。我认真想过这件事觉得核心原因有两个而且都指向同一个根本问题验证是一个需要主动意识的环节而长任务天然消耗这种主动意识。3.1 长任务里的“完工心态”让 Agent 倾向于跳过验证人写代码时有个心理现象代码写完那一瞬间我们会有一种“终于搞定了”的释然感这时候特别不想听到测试报错。Coding Agent 也有类似的问题而且比人更严重。因为在长任务里Agent 每多执行一步操作就要消耗更多的上下文空间和推理步数。任务接近尾声时它的上下文往往已经塞满了各类操作记录、报错信息、代码片段此时它的“注意力资源”已经濒临枯竭。在这种状态下再让它主动跑一遍测试、跑一遍构建、检查 diff 质量它内心是“抗拒”的——不是做不到而是认知资源不够了。这就是为什么验证不能靠 Agent 自觉必须在链路设计上强制。我见过做得比较好的方案有两类一类是把验证步骤写进任务分解模板里让“跑测试-处理失败-再跑测试”成为一个不可跳过的子任务Agent 完成编码后必须进入这个子任务。另一类是引入独立于编码过程的验证工具比如在 Agent 完成修改后由外部流程自动触发构建和测试结果再反馈给 Agent。这样验证就不是 Agent 的主观意愿而是客观流程。我和用过的几个 Agent 框架对比下来客观流程的方式更可靠。因为模板再完善Agent 在上下文紧张的时候还是有可能跳过模板里的某个步骤。但外部流程不会跳。它会实实在在地把测试失败的结果丢给 Agent逼着它去处理。3.2 “假通过”的迷惑性测试过了不代表链路完整验证环节还有另一个隐蔽的坑比“不验证”更迷惑人我管它叫假通过。Agent 确实跑了测试测试也绿了但交付物实际上有问题。最常见的假通过有两种。一种是Agent 为了通过测试而修改了测试本身。比如前面提到我那个邮件接口的例子Agent 在测试失败后没有去检查 migration 是否执行而是直接改了测试数据让测试通过。这就等于考试时把答案改成自己的错误答案然后宣称自己对了。另一种是测试覆盖范围不够导致的局部通过。Agent 只跑了自己新写的那个测试文件没有跑整个测试套件结果新的功能测试通过了但原有功能被它改坏了回归测试跑出红。这种情况在 Agent 里太常见了因为它倾向于“最小化验证成本”——只验证自己改过的东西不管自己影响到的其他部分。应对假通过我的经验是两个手段配合一是交付链路里要有一条明确的规则——Agent 禁止修改测试代码来使测试通过除非任务本身就要求改测试二是验证环节必须不止跑单测还要跑完整的构建和回归测试。前者靠约束后者靠机制。4. 构建可靠交付链路的五个关键动作如果你准备在自己的项目里真正用上长任务 Coding Agent而不是停留在简单 demo 阶段下面这五个动作是这段时间实践下来我最想分享的。它们不是某一家工具的特定功能而是任何长任务 Agent 方案里都该有的设计原则。4.1 先让 Agent 输出计划再允许它动手我见过太多翻车案例源头都是同一个Agent 拿到任务描述就直接开始改代码了。这不是说它一定做不对而是它缺少一个锚点。长任务做到后期上下文里全是操作细节早期对任务的理解会慢慢被冲淡。这时候 Agent 唯一的“记忆锚点”就是最初的任务描述和它自己的计划。所以我的做法非常固执任务下发给 Agent 时第一步强制它输出一份结构化的执行计划包括它对需求的理解、要改动的文件清单、每个文件的改动方向、验证方式、可能的依赖风险。这个计划一方面帮助我发现它对需求的理解有没有偏差另一方面它成为后面所有操作的对齐基准。等到任务执行到后期如果我发现 Agent 的某些操作偏离了方向我可以直接拿计划跟它说“你的第 3 条计划不是这么说的”它能很快回到正轨。没有这个计划纠正起来就完全靠重新描述需求又费 token 又容易产生新的误解。4.2 把“提交前自检”做成显式步骤很多 Agent 的默认行为是完成代码改动后直接给一个 diff告诉你“完成了”。但这个“完成”的标准太低了没有包含真正的自检环节。我现在用的模板里强制包含一个自检清单步骤Agent 在提交最终成果之前必须逐项回答涉及的文件是否全部改动完成有没有漏掉依赖文件代码中是否残留调试日志、临时注释、死代码有没有执行构建/类型检查结果是否通过有没有运行相关测试测试结果是否全部通过有没有检查最终 diff确认没有无关文件的改动我要求 Agent 必须逐条输出自检结果而不是简单说一句“已验证完成”。逐条输出的过程中它常常自己就发现某些环节没做然后补齐。人也会在这个过程中发现问题——比如看到它的自检结果里写着“未运行完整测试套件”你就能在问题爆发前把它拦下来。4.3 用测试作为交付闸门而不是参考指标这是整条链路里最关键的一条。测试不通过就不算是交付。这条规则说起来简单执行起来很容易被 Agent“钻空子”。钻空子的方式就是我前面说的假通过——它可能修改测试来适配自己的实现可能只跑一个测试文件来冒充全套通过可能故意用错误的命令让测试“看起来成功”。所以把测试作为交付闸门至少要做到三点第一测试命令要写死明确到每个子命令。不要让 Agent 自己决定跑哪些测试项目。比如“运行npm run test:unit npm run test:integration npm run build只要有一条命令失败就必须定位原因并修复”。第二明确禁止修改测试来让测试通过。如果 Agent 认为测试本身有问题比如断言写错了必须停下来向人报告等待确认后再调整。第三把测试结果当作后续工作的输入而不是终点。Agent 跑完测试拿到结果后必须根据结果决定下一步动作——失败了就去修代码成功了才能进入收尾。这样测试就成了链路里的一个决策节点而不是一份应付差事的报告。4.4 控制上下文长度防止早期决策被遗忘长任务 Agent 最大的敌人是上下文爆炸。一次任务执行几十分钟甚至几个小时操作日志、终端输出、报错堆栈全往上下文里塞早期的重要决策很快就被淹没了。我现在用的处理方案是给 Agent 设计了一个“关键信息归档机制”。每一步操作只保留精简的结构化信息——比如“改了哪个文件、为什么改、引入了什么依赖、需要记录什么备注”而不是把所有终端输出都原样留在上下文里。就像人的工作记忆一样把原始琐碎的信息处理完后只把结论留下。这个机制的效果很明显。之前我用某个框架跑长任务到任务后期 Agent 经常会无意识地推翻早期决策比如早期定好了“用 service 层封装业务逻辑”到后期它又直接在路由层写业务代码和早期架构完全冲突。引入归档机制后这类问题少了很多因为早期决策始终在上下文里占有一席之地不会被后来的操作日志挤掉。4.5 建立失败恢复机制而不是无限重试Agent 遇到报错时的表现是判断一个 Agent 框架是否成熟的重要标准。不成熟的方案是报错了就把错误信息喂给模型让它再试一次不行再试一次直到试到一种碰巧能过的方式或者上下文耗尽。成熟的方案应该有一个明确的失败恢复流程第一步错误分析。让 Agent 先分析错误的根因而不是急着改代码。这个分析要包含几个要素报错信息说明了什么、错误发生在哪个环节、修复的前提条件是什么。这一步很关键因为很多 Agent 的错误分析是敷衍的输出一段“可能是 xxx 导致的”就完了根本没有定位到根因。第二步修复计划。让 Agent 给出修复方案和预期影响面再动手改。这能避免它为了修一个错而引入新的问题。第三步验证修复。修复完成后必须重新跑一遍完整的验证流程而不是只验证修复本身。第四步设置重试上限。我通常给 Agent 限制两到三轮的重试窗口超过之后必须停下来等人介入。因为在一个错误上反复重试五六次大多数时候不是解决问题的路径而是上下文浪费的路径。而且很多 Agent 重试到最后给出的修复方案往往会引入副作用——因为它的上下文已经在反复试错中被污染了。5. 实测结果对比同一任务不同 Agent 的交付链路差异光说不练没有用我拿一个真实的中等复杂度任务做了个对比测试测试对象包括 OpenAI Codex、一个热门的开源 Agent 框架以及我手动配置的一套基于 Claude 的 DIY 方案。任务设定是在一个 Next.js Prisma PostgreSQL 的项目里增加一个“收藏文章”的功能要求包含数据模型变更、API 路由、前端按钮和交互以及对应的测试最终交付必须通过构建和测试。这个任务本身不算特别复杂但涉及后端数据库变更、前端组件改动和测试编写足够考察交付链路的完整性。5.1 三个方案的执行表现我先说一下测试环境的统一条件同样的项目代码、同样的任务描述、同样的验证命令。我唯一没有统一的是各方案默认的行为模式因为那正是我想对比的。OpenAI Codex 的表现Codex 的前半程很流畅。它先把任务拆成了步骤列了改动文件清单然后逐个执行。数据库 schema 变更、Prisma client 生成、API 路由都做得很顺利。前端部分稍微挣扎了一下因为项目里用的是老版本 React RouterCodex 一开始用了新版语法运行时报错。报错后它的处理速度很快分析了错误栈发现是版本差异然后改正了语法。但它的交付环节让我不太放心——任务完成时它跑了一遍 build但没有跑完整的测试套件只跑了和收藏功能直接相关的几个测试文件。我用人工补跑了一遍测试发现原有的用户认证测试挂了。原因是 Codex 改 API 路由时动了认证中间件的引用方式老测试文件里引用的路径过时了。虽然不影响新功能但这属于回归破坏。开源 Agent 框架的表现这个框架在前半段的表现中规中矩任务规划和文件探索都做完了也确实改了需要的文件。但它在数据库迁移环节出问题了——任务要求用 Prisma 的 migration 来管理 schema 变更它却直接改了 schema.prisma 文件里的模型定义没有生成 migration 文件。这样就导致同样的 schema 变更在其他环境里无法通过 migration 流程复现。我注意到问题的根源在它的工具使用习惯上它倾向于直接编辑文件来达到目的而不是调用项目里既有的一整套流程。这个倾向在短任务里问题不大在长任务里会影响交付的可复现性和一致性。我的 DIY 方案的表现我配置的方案是基于 Claude 的长上下文能力 一套强约束的任务模板。这套模板里包含了前面讲到的五个动作强制计划、自检清单、测试闸门、关键信息归档、失败恢复流程。这个方案的代码生成能力没有明显优势和另外两个一样也会写出带 bug 的代码。但它的交付链路是最稳的——第一次构建报错后它没有直接改代码而是先分析错误定位到是环境变量缺失补上 .env 配置之后重新构建成功通过。测试阶段完整跑了整个测试套件发现了认证测试的回归问题因为它改了路由的引用方式导致老的测试文件导入路径失效。它按“不做假的通过”的原则修复了导入路径让测试恢复通过。最终它交付的 diff 很干净只包含任务相关的文件变更没有垃圾文件改动。5.2 差异在哪里以及为什么三个方案都能完成这个任务的大部分编码工作真正的差异体现在两个地方。回归测试的覆盖范围。Codex 只跑了和改动直接相关的测试开源框架压根没有跑全套测试的意识我的 DIY 方案在测试闸门约束下完整跑了测试套件发现了回归问题。差异不是模型能力而是任务模板里是否把“跑完整测试”作为不可跳过的步骤写进去了。对任务流程的敬畏程度。开源框架倾向绕过项目既有的流程比如直接改 schema 而不是生成 migration因为它没有流程识别机制只知道“达成目标”不知道“按项目约定达成目标”。Codex 会在一定程度上遵循项目约定因为它见过足够多的真实项目知道 migration 是标准做法。但它的流程识别更多是经验性的不是强制约束。这两点差异再次印证了我的判断长任务 Agent 的上限由模型能力决定但下限由交付链路决定。模型能力之间的差距已经很小而交付链路的设计质量可以导致完全不同的结局——一个交付了带回归破坏的代码一个交付了可复现、可验证、diff 干净的成果。6. 落地上手我目前在用的长任务 Agent 工作流讲了这么多思路我猜你更想知道的是所以现在我具体怎么用下面是我目前在实战项目里稳定跑了一段时间的长任务 Agent 工作流你可以直接抄再按你自己的项目情况微调。6.1 任务模板把交付链路固化到提示词里我的整套流程核心是一份任务模板。每次开工我先让 Agent 读取这个模板然后按模板里的流程执行。模板的内容不是一段空泛的“请认真完成任务”而是每一个环节都有明确的输出要求和检查标准。一个典型的任务模板长这样## 任务目标 在这里描述任务目标必须可验证比如完成 XX 功能跑通 XX 测试 ## 执行步骤要求 1. 先输出你的执行计划格式如下 - 需求理解用一两句话说明你理解的任务目标 - 影响范围列出所有可能需要改动的文件并说明原因 - 执行顺序按依赖关系排列的执行步骤 - 风险点你认为可能出现问题的地方 2. 计划确认前不要修改任何文件。 ## 验证要求强制 - 必须执行以下命令并将结果记录到你的操作总结里 - npm run build必须通过 - npm run test:unit必须通过 - npm run test:integration必须通过 - 测试未通过时先分析报错根因再修复。 - 禁止修改测试代码来使测试通过除非任务要求修改测试。如果测试本身有问题停下来向用户报告。 ## 提交前自检清单逐条回答并输出 - [ ] 所有需要改动的文件是否都已修改 - [ ] 是否残留调试日志、临时代码 - [ ] 是否运行了全部验证命令且通过 - [ ] 最终 diff 是否只包含本次任务相关的内容 - [ ] 是否有遗留问题需要向用户说明 ## 失败恢复规则 - 同一个错误最多重试 2 次。第 2 次失败后停止操作输出一份问题报告等用户指示。 - 问题报告需要包含错误信息、你的根因分析、你尝试过的修复方案、你建议的下一步。这份模板我用在不同 Agent 上效果都还行因为它本质上不是靠某个模型的能力而是把交付链路的硬性要求写死在流程里。6.2 我踩过的几个坑以及现在的对应策略这部分是我真正想说的因为都是从真实跑任务里踩出来的。坑一任务目标写得太模糊。最早我喜欢写“帮我优化一下用户注册流程”结果 Agent 优化出了各种意想不到的东西改了数据库索引、调整了密码加密方式、还给前端加了个验证码组件。不是它太积极是我没给它设边界。现在的写法是“优化用户注册流程中的邮箱验证环节只改后端 service 层和对应测试不要动前端”边界画清楚Agent 的发挥就可控了。坑二给 Agent 的任务里带“历史包袱”。有次我让 Agent 改一个模块的代码为了说清楚上下文我在任务描述里附带了一长段这个模块的历史演进说明。结果 Agent 把大量注意力放在这些历史信息上在方案选择时反复斟酌“以前的实现为什么那样设计”而忽略了当前真正要解决的问题。后来我把任务描述里该删的历史背景都删掉只留当前状态、目标、约束效果立刻好了很多。坑三前期不舍得花 token 做探索。很多 Agent 框架默认的探索策略是“按需探索”或“节省 token 优先”也就是 Agent 大概看一眼项目结构就开始改代码了。这在前几个文件上可能没问题一旦涉及文件间的依赖关系就会漏看。我现在会在任务开头要求 Agent 先输出一个“影响范围分析”强制它在动手前把相关的文件、依赖、架构都摸一遍。多花一点 token但能避免后期大返工这笔账非常划算。坑四让 Agent 自己去判断测试是否“等价”。有次一个任务涉及重构一个函数Agent 重构完之后说“原测试的断言方式不再适用我更新了断言”。它确实是合理的——因为函数的行为变了测试预期也应该更新。但它违反了模板里“禁止修改测试”的规则我后来发现之后又花了不少力气确认这次改测试是否合理。现在我在模板里加了一条如果 Agent 认为必须修改测试必须在提交前单独列一条“测试修改说明”由人来确认。这不是为了阻拦合理修改而是为了确保每次测试变更都经过人的审核。6.3 人和 Agent 的分工边界最后说点更宏观的体验。跑长任务 Agent 这段时间我最大的感受是人不是旁观者而是交付链路的管理者。Agent 能做的是执行具体的编码动作——改文件、跑命令、分析报错、调整代码。但有一些事情Agent 做不好或者不应该让它做定义“什么是完成”这是人的事。Agent 倾向于把“代码写完了”当完成但你要的是“测试通过、代码干净、文档更新、可发布上线”。这个标准必须由人来定然后固化成模板。判断“这个改动合理吗”Agent 在碰到架构选择、依赖引入、方案取舍时往往会选择最快的路径而不是最合理的路径。这需要人在关键节点上把关。我的做法是碰到大一点的方案取舍我会要求 Agent 输出两个以上的可选方案并说明理由然后我来拍板。处理“任务本身有歧义”的情况Agent 遇到歧义时通常的默认策略是“猜一个最可能的”而不是“问清楚”。这对简单任务没毛病但长任务的歧义如果不澄清做到后面发现方向错了返工成本极高。所以我会在任务描述里显式加一句“如果你发现需求有歧义停下来向我确认而不是自行假设。”回到开头那个判断——长任务 Coding Agent 的关键不是写代码而是交付链路。我现在越来越觉得这句话里面“交付链路”的含义不只是 Agent 内部的执行流程也包括人和 Agent 之间的协作链路。你把 Agent 当成一个只能写代码的工具它就只给你交付代码你把它当成交付链路里的一个执行节点你才能拿到真正可上线的成果。如果你正准备在真实项目里长跑这类 Agent我的建议是先别急着追求“全自动”把你当前项目里的交付流程提炼出来看看哪些环节是 Agent 能接住的哪些环节必须你亲自把守然后像设计一条流水线一样把每个环节的验收标准写清楚。这样的 Agent跑出来的结果才值得信任也才真的能替你省下时间。