原文链接：https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

发布于25/11/26，以下为AI翻译。

有效的长程智能体框架

随着 AI 智能体能力增强，开发者正要求其处理耗时数小时甚至数天的复杂任务。然而，如何让智能体在多个上下文窗口中保持连贯进度，仍是一个难题。

长程智能体的核心挑战在于其工作模式是离散的：每个新会话都像“失忆”一样重新开始。想象一个轮班制的软件项目，每位新工程师对前序工作一无所知。由于上下文窗口有限，且复杂项目无法在单次会话中完成，智能体需要一种机制来衔接不同的编码会话。

我们为 Claude Agent SDK 开发了一套双重方案：初始化智能体负责首轮环境搭建；编码智能体负责在每轮会话中增量推进，并为下个会话留下清晰产物。代码示例见快速入门。

长程智能体难题

Claude Agent SDK 是一个强大的通用智能体框架，擅长编码、工具调用、信息采集、规划及执行。它具备上下文压缩等管理能力，理论上可支持智能体无限期工作。

然而，仅靠压缩是不够的。即便像 Opus 4.5 这样的顶尖模型，若只给一个“克隆 claude.ai”的高层指令，在多窗口循环中也难以构建出生产级的 Web 应用。

Claude 的失败表现为两种模式。首先，智能体倾向于“毕其功于一役”。这常导致上下文在中途耗尽，留下未完成且无文档的功能。后续智能体只能靠猜，浪费大量时间修复基础功能。即便有上下文压缩，也无法保证能向下个智能体传递清晰指令。

第二种模式通常出现在项目后期。后续智能体看到已有进展，便会草率宣布任务完成。

我们将问题分解为两部分：

首先，搭建基础环境，为所有需求奠定基础，引导智能体逐步开发；

其次，要求智能体在会话结束时保持环境整洁。所谓“整洁”，指代码达到可合并至主分支的标准：无重大 Bug、逻辑清晰、文档齐全，方便后续开发者直接开始新功能。

在内部实验中，我们采用了以下方案：

1. 初始化智能体：首个会话使用专用提示词配置环境，包括 init.sh 脚本、记录日志的 claude-progress.txt 以及记录文件变更的初始 Git 提交。
2. 编码智能体：后续会话负责增量开发并留下结构化更新。¹

核心洞察在于：通过 claude-progress.txt 和 Git 历史，让智能体在开启新窗口时快速理解现状。这种做法借鉴了高效软件工程师的日常实践。

环境管理

在更新后的 Claude 4 提示词指南中，我们分享了多窗口工作流的最佳实践，包括使用专用提示词初始化环境。以下是关键组件的深度解析。

功能清单

为防止智能体急于求成或过早完工，我们要求初始化智能体根据需求编写详尽的功能清单。在克隆 claude.ai 的例子中，清单包含 200 多项功能（如“用户可开启新对话、输入查询、按回车并看到响应”）。初始状态均标为“失败”，为后续开发提供清晰蓝图。

我们要求编码智能体仅修改 JSON 文件中的 passes 字段，并严禁删除或编辑测试项。

实验证明，使用 JSON 格式比 Markdown 更能防止模型误改文件。

增量推进

在初始框架下，编码智能体被要求每次仅开发一个功能。这种增量模式是解决“贪多嚼不烂”的关键。

此外，智能体必须在修改后保持环境整洁。

最佳实践是要求其提交 Git（附带描述性信息）并在进度文件中写下总结。这让智能体能利用 Git 回滚错误，恢复至可用状态。

这些方法提高了效率，避免了智能体因猜测现状而浪费时间修复基础应用。

测试

另一个主要失败模式是：在未充分测试的情况下标记功能已完成。若无明确提示，Claude 虽会进行单元测试或 curl 命令，但常忽略端到端（E2E）的有效性。

在构建 Web 应用时，若明确提示使用浏览器自动化工具模拟真实用户操作，Claude 的端到端验证表现优异。

提供测试工具显著提升了性能，使智能体能发现并修复仅凭代码难以察觉的 Bug。

挑战依然存在，如视觉限制和自动化工具的局限。例如，Claude 无法通过 Puppeteer 识别浏览器原生弹窗，导致相关功能更易出错。

快速上手

准备就绪后，每个编码智能体都会执行以下步骤来找准定位：

1. 运行 pwd 确认工作目录。
2. 阅读 Git 日志和进度文件，了解近期进展。
3. 阅读功能清单，选择优先级最高的待办项。

这种方法节省了 Token，因为智能体无需自行摸索测试方法。此外，要求初始化智能体编写 init.sh 脚本来启动服务器并在开发前运行基础测试也大有裨益。

在克隆项目中，智能体总是先启动服务器，用 Puppeteer 验证核心流程（发消息、收响应）。这确保了它能立即发现并修复现有 Bug，而不是在错误的基础上开发新功能。

典型会话的开头如下：

[Assistant] 我将先了解项目现状。
[Tool Use] <bash - pwd>
[Tool Use] <read - claude-progress.txt>
[Tool Use] <read - feature_list.json>
[Assistant] 检查 Git 日志以查看近期工作。
[Tool Use] <bash - git log --oneline -20>
[Assistant] 检查是否有 init.sh 脚本来重启服务器。
<启动开发服务器>
[Assistant] 太棒了！现在我将访问应用并验证基础功能。
<测试基础功能>
[Assistant] 验证显示基础功能正常。核心聊天、主题切换、对话加载和错误处理均运行良好。现在我将全面审查 tests.json 以确定下一步开发目标。
<开始开发新功能>

智能体失败模式与解决方案

未来工作

本研究展示了长程智能体框架的一种方案，但仍有开放性问题。

关键在于：是单一通用智能体更好，还是多智能体协作（如专门的测试、QA、清理智能体）更优？

此外，该演示针对 Web 开发。未来我们将探索将其推广至科研、金融建模等其他长程任务领域。

致谢

作者：Justin Young。特别感谢 David Hershey, Prithvi Rajasakeran, Jeremy Hadfield, Naia Bouscal, Michael Tingley, Jesse Mu, Jake Eaton, Marius Buleandara, Maggie Vo, Pedram Navid, Nadine Yasser, 和 Alex Notov 的贡献。

本成果凝聚了 Anthropic 多个团队的心血，特别是代码强化学习和 Claude Code 团队。欢迎感兴趣的候选人申请：anthropic.com/careers。

脚注

1. 此处称为“不同智能体”仅因其初始提示词不同。系统提示词、工具集和框架完全一致。