Harness Engineering：让 Coding Agent 可靠完成长程任务

Coding Agent 在处理目标明确、规模可控的任务时已经表现出色，但在实际的工程化场景中，面对复杂的长程任务时会遇到显著挑战。例如，将 21 个前端模块的 JavaScript 文件批量迁移到 TypeScript，或对数十个模块进行全量代码审查并批量修复问题——这类任务涉及成百上千个文件，运行时间可能跨越多个会话，Token 消耗高达数千万。在缺乏系统性设计的情况下，Agent 往往会遭遇上下文耗尽、中断后难以恢复、以及规模扩大后行为失控等问题。

概述

解决这些挑战需要四项核心设计原则。任务拆解将大任务划分为 Agent 能在单次会话内独立完成的子任务，避免上下文无限膨胀。子任务应具有明确的输入、输出和约束条件，确保每个单元可以独立理解、独立执行和独立验证。并行执行通过多路 Agent 同时处理不同的子任务，将整体耗时从串行的数小时压缩到一小时以内。而可续传机制则将任务进度持久化到文件系统，使得任何一次中断后都能从断点继续，而非从头重来。

分析

子任务的边界设计根据任务间关系的不同可分为三种模式。完全无依赖的任务可以直接并行处理，各自处理互不干扰的文件。有依赖关系的任务需要通过拓扑排序确定执行顺序，被依赖的叶子节点必须先执行。有冲突的任务则需要通过 Git Worktree 进行物理隔离，各自修改互不干扰，冲突被推迟到合并阶段统一处理。错误处理遵循“最小范围原则”：子任务内的错误在当前会话内闭环解决，不将问题带到后续阶段；阶段间的交接必须干净，已完成的部分与失败项明确标记。

状态持久化是长程任务编排中最核心的设计——即「File As Progress」理念。所有进度状态必须持久化到文件系统，不依赖 Agent 的记忆或会话上下文。任务的每个状态（TODO、IN_PROGRESS、DONE、FAILED）都应该是自描述的，仅凭当前状态就能决定下一步做什么。恢复逻辑不需要回放历史，只需要读取状态文件，就能推导出续传策略。检测 IN_PROGRESS 残留时，通过检查预期产出文件是否存在、内容是否合法来判断任务是“真的在跑”还是“跑到一半挂了”。

多层重试机制将失败进行分层处理。子 Agent 因网络异常等原因异常退出时，恢复同一个会话从断点继续。子 Agent 正常完成但产出不满足校验条件时，开新会话并将错误信息作为上下文针对性修复，限制 2-3 次重试。主 Agent 层面则对失败文件重新分组调度。三层重试逐层递进，将重试成本与任务复杂度进行合理匹配。

如有侵权，请联系删除。