长任务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 上遇到的翻车情况，大概可以归成五类：

1. 需求漂移：任务做到一半，Agent 开始“自由发挥”，加了需求里没提过的功能，或者把原有行为改变了。不是因为大模型笨，而是长上下文中原始需求被后续的中间思考稀释了。

2. 验证缺失：写完代码不跑测试、不执行构建就宣布完成。这个是最常见的，尤其是任务接近尾声时，Agent 有一种“终于写完了”的急切感，会倾向于相信自己的代码没问题，而不是去验证。

3. 死循环重试：遇到报错后，反复用同一种方法重试，报错信息变了但策略没变。典型的表现是试图通过“再跑一次”碰运气，而不是停下来分析根因。

4. 上下文截断失忆：操作日志太长导致早期的关键决策被截断或忽略，Agent 在后期做出和早期决策完全矛盾的变更。

5. 忘了收尾：代码写完了，但忘了处理依赖、忘了更新文档、忘了清理调试日志、忘了运行最终的完整测试套件。功能看起来完成了，交付质量却很粗糙。

这五个症状里，只有第一个多少和模型能力沾点边，其余四个都是交付链路设计的问题。也就是说，换一个更强的模型并不能解决大部分长任务翻车问题——你得把交付链路本身设计好。

2. 交付链路拆解：从任务下达到可交付成果之间，藏着哪些暗沟

很多团队的 Coding Agent 方案是一步步长出来的：今天加个代码补全，明天让它改 bug，后天开始让它做跨模块需求。做到长任务阶段就会突然发现，问题不再是你“喂”给它的指令清不清楚，而是整套链条上有没有断点。

我把一条完整的交付链路拆成七个环节，每一次长任务失败，都能归因到其中至少一个环节出了问题：

2.1 交付链路的七个环节

这里我想特别强调一下第五和第六个环节——构建验证和测试验证，它们是交付链路里最容易被省略、但代价最大的两步。

有一个心理层面的原因值得琢磨：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 Router，Codex 一开始用了新版语法，运行时报错。报错后它的处理速度很快，分析了错误栈，发现是版本差异，然后改正了语法。

但它的交付环节让我不太放心——任务完成时，它跑了一遍 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，跑出来的结果才值得信任，也才真的能替你省下时间。