核验日期：2026-07-08

内容来源：Anthropic Engineering 官方技术博客。本文先作为 Claude Code 专区后台草稿入库，发布前应由内容人员复核标题、摘要、图片、来源链接与是否需要补充本站实践说明。

长时间运行智能体的有效运行框架

智能体在跨越多个上下文窗口工作时仍面临挑战。我们从人类工程师身上获得启发，为长时间运行的智能体创建更有效的运行框架。

来源：https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
发布日期：2025-11-26

随着 AI 智能体变得更有能力，开发者越来越多地要求它们承担复杂任务，这些任务需要持续数小时甚至数天的工作。然而，让智能体在多个上下文窗口之间持续取得一致进展，仍然是一个开放问题。

长时间运行智能体的核心挑战在于，它们必须以离散会话的方式工作，而每个新会话开始时都不记得之前发生过什么。想象一个由轮班工程师组成的软件项目，每位新工程师上岗时都不知道上一班发生了什么。由于上下文窗口有限，并且大多数复杂项目无法在单个窗口内完成，智能体需要一种方式来跨越编码会话之间的断点。

我们开发了一个两部分解决方案，使 Claude Agent SDK 能够有效跨越多个上下文窗口工作：一个在首次运行时设置环境的初始化智能体，以及一个编码智能体，它的任务是在每个会话中取得增量进展，同时为下一个会话留下清晰产物。你可以在配套的 quickstart 中找到代码示例。

长时间运行智能体问题

Claude Agent SDK 是一个强大的通用智能体运行框架，擅长编码，也擅长其他需要模型使用工具来收集上下文、规划和执行的任务。它具备上下文管理能力，例如压缩，这让智能体可以在不耗尽上下文窗口的情况下处理任务。理论上，在这种设置下，智能体应当可以在任意长的时间内持续做有用的工作。

然而，压缩并不够。开箱即用时，即使是像 Opus 4.5 这样的前沿编码模型，在 Claude Agent SDK 上跨多个上下文窗口循环运行，如果只给它一个高层提示，例如“构建一个 claude.ai 的克隆版”，也无法构建出生产质量的 Web 应用。

Claude 的失败表现为两种模式。第一，智能体倾向于一次做太多事情，本质上是在尝试一次性完成整个应用。通常，这会导致模型在实现过程中耗尽上下文，让下一个会话面对一个半实现且没有文档说明的功能。随后智能体不得不猜测之前发生了什么，并花大量时间试图让基础应用重新正常工作。即使有压缩，这种情况也会发生，因为压缩并不总是能向下一个智能体传递完全清晰的指令。

第二种失败模式通常发生在项目后期。在某些功能已经构建完成之后，后续某个智能体实例会四处查看，看到已经取得了一些进展，然后宣布任务完成。

这把问题分解成两个部分。首先，我们需要设置一个初始环境，为给定提示所需的所有功能奠定基础，让智能体能够逐步、逐功能地工作。其次，我们应该提示每个智能体朝目标取得增量进展，同时在会话结束时让环境处于干净状态。这里的“干净状态”指的是适合合并到主分支的代码状态：没有重大 bug，代码有条理且文档完善，通常情况下，开发者可以很容易地开始处理新功能，而无需先清理无关混乱。

在内部实验时，我们用一个两部分方案解决这些问题：

1. 初始化智能体：第一个智能体会话使用专门提示，要求模型设置初始环境：一个 init.sh 脚本、一个用于记录智能体已完成工作的 claude-progress.txt 文件，以及一个显示添加了哪些文件的初始 git commit。
2. 编码智能体：之后的每个会话都会要求模型取得增量进展，然后留下结构化更新。1

这里的关键洞见是找到一种方法，让智能体在以全新上下文窗口启动时，能够快速理解工作状态。这通过 claude-progress.txt 文件和 git 历史共同实现。这些实践的灵感来自对高效软件工程师日常工作的观察。

环境管理

在更新后的 Claude 4 提示指南中，我们分享了多上下文窗口工作流的一些最佳实践，包括一种使用“为第一个上下文窗口设置不同提示”的运行框架结构。这个“不同提示”会要求初始化智能体设置环境，包含未来编码智能体高效工作所需的全部必要上下文。这里，我们会更深入地介绍这种环境的一些关键组件。

功能列表

为了解决智能体一次性构建整个应用，或过早认为项目已完成的问题，我们提示初始化智能体编写一份完整的功能需求文件，对用户的初始提示进行扩展。在 claude.ai 克隆版示例中，这意味着超过 200 个功能，例如“用户可以打开一个新聊天、输入查询、按下回车，并看到 AI 回复”。这些功能最初都被标记为“失败”，这样后续编码智能体就能清楚地看到完整功能应是什么样子。

{
    "category": "functional",
    "description": "New chat button creates a fresh conversation",
    "steps": [
      "Navigate to main interface",
      "Click the 'New Chat' button",
      "Verify a new conversation is created",
      "Check that chat area shows welcome state",
      "Verify conversation appears in sidebar"
    ],
    "passes": false
  }

复制

我们提示编码智能体只能通过更改 passes 字段的状态来编辑这个文件，并使用语气强烈的指令，例如“删除或编辑测试是不可接受的，因为这可能导致功能缺失或存在 bug。”经过一些实验后，我们决定使用 JSON，因为与 Markdown 文件相比，模型不太可能不恰当地修改或覆盖 JSON 文件。

增量进展

在有了这个初始环境脚手架后，下一轮编码智能体会被要求一次只处理一个功能。事实证明，这种增量方法对于解决智能体一次做太多事情的倾向至关重要。

一旦开始增量工作，仍然必须确保模型在做出代码更改后，让环境保持干净状态。在我们的实验中，我们发现引出这种行为的最佳方式，是要求模型用描述性 commit message 将进展提交到 git，并在进度文件中写下进展摘要。这让模型可以使用 git 回滚糟糕的代码更改，并恢复代码库的可工作状态。

这些方法也提高了效率，因为它们消除了智能体不得不猜测之前发生过什么、并花时间试图让基础应用重新正常工作的需要。

测试

我们观察到的最后一个主要失败模式，是 Claude 倾向于在没有适当测试的情况下将功能标记为完成。缺少明确提示时，Claude 往往会修改代码，甚至使用单元测试或针对开发服务器的 curl 命令进行测试，但没有意识到该功能端到端并不能工作。

在构建 Web 应用的情况下，一旦明确提示 Claude 使用浏览器自动化工具，并像人类用户一样进行所有测试，它通常能很好地端到端验证功能。

Claude 通过 Puppeteer MCP 服务器测试 claude.ai 克隆版时截取的屏幕截图。

为 Claude 提供这类测试工具显著提升了表现，因为智能体能够识别并修复仅从代码本身并不明显的 bug。

仍有一些问题存在，例如 Claude 的视觉能力限制，以及浏览器自动化工具的限制，使其难以识别所有类型的 bug。例如，Claude 无法通过 Puppeteer MCP 看到浏览器原生 alert 模态框，因此依赖这些模态框的功能往往会更容易出现 bug。

快速进入状态

在以上所有机制就位后，每个编码智能体都会被提示执行一系列步骤来了解情况，其中一些非常基础，但仍然有帮助：

1. 运行 pwd 查看你正在工作的目录。你只能编辑这个目录中的文件。
2. 阅读 git 日志和进度文件，了解最近处理了什么。
3. 阅读功能列表文件，选择尚未完成的最高优先级功能来处理。

这种方法会在每个会话中为 Claude 节省一些 token，因为它不必自己弄清楚如何测试代码。让初始化智能体编写一个可以运行开发服务器的 init.sh 脚本也很有帮助，然后在实现新功能之前先跑一遍基础端到端测试。

在 claude.ai 克隆版的例子中，这意味着智能体总是先启动本地开发服务器，并使用 Puppeteer MCP 开始一个新聊天、发送一条消息并收到回复。这确保 Claude 可以快速识别应用是否处于损坏状态，并立即修复任何已有 bug。如果智能体反而直接开始实现新功能，很可能会让问题变得更糟。

考虑到所有这些，一个典型会话会以下列 assistant 消息开始：

[Assistant] I'll start by getting my bearings and understanding the current state of the project.
[Tool Use] <bash - pwd>
[Tool Use] <read - claude-progress.txt>
[Tool Use] <read - feature_list.json>
[Assistant] Let me check the git log to see recent work.
[Tool Use] <bash - git log --oneline -20>
[Assistant] Now let me check if there's an init.sh script to restart the servers.
<Starts the development server>
[Assistant] Excellent! Now let me navigate to the application and verify that some fundamental features are still working.
<Tests basic functionality>
[Assistant] Based on my verification testing, I can see that the fundamental functionality is working well. The core chat features, theme switching, conversation loading, and error handling are all functioning correctly. Now let me review the tests.json file more comprehensively to understand what needs to be implemented next.
<Starts work on a new feature>

复制

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

问题	初始化智能体行为	编码智能体行为
Claude 过早宣布整个项目已经完成。	设置功能列表文件：基于输入规格，建立一个结构化 JSON 文件，其中包含端到端功能描述列表。	在会话开始时读取功能列表文件。选择一个单一功能开始处理。
Claude 让环境处于有 bug 或进展未记录的状态。	写入初始 git 仓库和进度笔记文件。	会话开始时阅读进度笔记文件和 git commit 日志，并在开发服务器上运行基础测试，以捕获任何未记录的 bug。会话结束时写入 git commit 和进度更新。
Claude 过早将功能标记为完成。	设置功能列表文件。	自行验证所有功能。只有在仔细测试后，才将功能标记为“passing”。
Claude 必须花时间弄清楚如何运行应用。	编写一个可以运行开发服务器的 init.sh 脚本。	会话开始时读取 init.sh。

总结长时间运行 AI 智能体中的四种常见失败模式和解决方案。

未来工作

这项研究展示了一组可能的长时间运行智能体运行框架解决方案，使模型能够跨多个上下文窗口取得增量进展。不过，仍然存在一些开放问题。

最值得注意的是，目前仍不清楚单个通用编码智能体是否在跨上下文场景中表现最佳，或者能否通过多智能体架构获得更好表现。看起来，测试智能体、质量保障智能体或代码清理智能体等专门化智能体，有可能在软件开发生命周期的子任务上表现得更好。

此外，这个演示针对全栈 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 RL 和 Claude Code 团队。欢迎有兴趣做出贡献的候选人访问 anthropic.com/careers 申请。

脚注

1. 在这里我们把它们称为不同的智能体，只是因为它们有不同的初始用户提示。除此之外，系统提示、工具集和整体智能体运行框架都是相同的。