题记：本文编译自 Anthropic 工程师 @trq212 发表的技术长文《Lessons from Building Claude Code: Seeing like an Agent》，文章总结了构建 Claude Code 过程中积累的工具设计方法论，从 AskUserQuestion 工具的三次迭代、Todo 演化为 Task 的背后逻辑，到渐进式披露这个设计模式，信息密度很高。原文链接：https://x.com/trq212/status/2027463795355095314。

正在构建 AI Agent 的人，大都会卡在同一个问题上：该给模型什么工具？

工具太少，Agent 能做的事受限；工具太多，模型反而不知道用哪个，甚至会在不该用的时候乱用。Claude Code 的工程师 Thariq 把这个问题研究了将近一年，陆续更换和迭代了多个工具，最近整理出了一篇总结。我觉得值得认真读，不只是因为这篇文章谈的是 Claude Code，更是因为里面的思路对任何人构建 Agent 都有参考价值。

工具设计的起点：以模型能力为锚

原文里有个简单但容易理解的类比：如果让你解一道难的数学题，你想要什么工具？

纸笔是起点，能手算，但速度慢。计算器快，但要知道怎么使用它的高级功能。最强大的自然是计算机，可以写代码来解，但前提是你会编程。工具的档次不同，能解决的问题就不一样，而且工具必须匹配使用者的能力。

给 Agent 设计工具，逻辑一样。原文的核心观点是：你需要给模型能力匹配的工具，而匹配的标准，来自你对模型能力的观察和理解。这需要持续关注它的输出，看它在哪里卡壳、哪里游刃有余，然后针对性地调整工具设计。

说起来简单，实践里很难。下面这几个案例能说明具体是怎么做的。

AskUserQuestion：三次迭代才找到正解

Claude Code 本来可以直接在对话里问用户问题，但这种自由格式的问答摩擦感很强。Anthropic 想降低这个成本，提升模型和用户之间的信息传递效率。

第一次尝试是在ExitPlanTool 里加一个问题数组，让模型同时输出计划和问题。实现最简单，但逻辑上有个矛盾：如果用户的回答和计划冲突了，模型要不要重新调用ExitPlanTool？这个方案废了。

第二次改输出格式，让 Claude Code 用特定的 Markdown 格式来提问，比如带选项的 bullet list，前端解析后展示成 UI 组件。思路挺好，执行不稳定。Claude Code 会在末尾多写几句话、换一种格式、或者漏掉选项。靠模型自律输出结构化内容，在复杂上下文里根本靠不住。

第三次，单独做了一个工具。Claude Code 可以在任何时候调用，但尤其适合在 Plan Mode 阶段。工具触发时弹出 Modal，展示问题和选项，阻塞 Agent 执行循环，等用户回答完再继续。

这个方案的关键在于把格式约束放进了工具 Schema，而不是寄希望于模型自觉。Claude Code 也更愿意调用这个工具，因为调用动作本身就是结构化的，不需要它猜格式。

这个迭代过程挺有代表性的。很多人以为提示词写清楚，模型就会乖乖按格式输出。真实情况是，这种稳定性在复杂场景下很脆弱。把格式约束建进工具才是根本解法。

Todo 变成 Task：工具要跟着模型一起进化

Claude Code 刚上线时，模型跑着跑着就会忘记自己在做什么。早期的解决方案是TodoWrite 工具，让 Claude Code 开始时列出待办，边做边打勾。为了防止它还是遗忘，每五轮对话插一条系统提醒。

这套机制在当时有效。但在模型能力变强后，新问题来了。

Opus 4.5 不需要频繁提醒，但系统提示的存在让它以为必须严格按 Todo 执行，不能灵活调整计划。模型被工具套住了，而工具反而限制 Claude Code 的能力。同时，子 Agent 协作的场景越来越多，几个 Agent 怎么共享一个 Todo 列表？TodoWrite 完全没考虑这个场景。

于是换成了 Task 工具。Task 支持依赖关系，子 Agent 可以互相通知状态，模型可以修改和删除任务，也可以主动新建。它更像是 Agent 之间的协调机制，而不是单纯的备忘录。

原文里说的这句话我觉得值得记住：“随着模型能力提升，那些原本帮助模型的工具，可能反而开始限制它。定期重新审视之前的假设很重要。”

这不只是 Claude Code 的问题。任何长期运行的 Agent 系统都会面临这个问题，因为你依赖的基座模型在变，但工具往往不会跟着变。

搜索工具：从被动接收到主动探索

最早，Claude Code 用 RAG 向量数据库来给 Claude Code 提供上下文。RAG 快、能处理大量文件，但它需要额外的索引和配置，并且也不够稳定。更重要的是，上下文是你喂给 Claude Code 的，而不是它自己找的。

后来加了Grep 工具，这个变化看起来很小，背后的设计理念转变挺大的。RAG 是外部系统决定 Claude Code 应该看什么，Grep 是让 Claude 自己决定自己需要看什么。模型越来越强，后者效果越来越好。Claude Code 逐渐学会了按需构建自己的上下文。

在 Agent Skills 上，这个思路被正式化为渐进式披露（Progressive Disclosure）。Skill 文件可以引用其他文件，模型可以递归地读取，层层展开。不是一次性把所有信息都摆在模型面前，而是让它按需探索。

一年下来，Claude Code 从基本不会自主构建上下文，进化到能在多层文件里精确找到自己需要的信息。

渐进式披露：不用加工具也能扩展能力

Claude Code 现在大约有 20 个工具，团队经常在自问：它们真的都需要吗？每加一个工具，模型就多一个要考虑的选项，决策负担上升。

比如，用户问 Claude Code 怎么添加 MCP、Slash Command 是什么，Claude Code 可能就答不上来，因为这些信息没在系统提示里。要不要把所有文档塞进系统提示？空间浪费，而且用户很少问这类问题，不值得一直放那儿。

他们的最终解法是做了一个专门的 Claude Code 指南 子 Agent，当你问 Claude Code 关于自身使用的问题时，它会调用这个子 Agent。子 Agent 有详细的搜索策略，知道去哪里找什么，只返回真正需要的答案。

这是渐进式披露的另一个形态：不加工具，而是加子 Agent，把专业问题交给专业的执行者。需要时才激活，不需要时不占用主 Agent 的注意力。

写在最后

给模型设计工具，不只是技术，更是一种艺术，没有一套通用规则，要看用的是什么模型、Agent 的目标是什么、运行环境是什么。

从最简单的方案开始，观察模型在哪里用得好、哪里卡壳，然后针对性地改。工具是模型能力的放大器，模型能力变了，放大器也得跟着换。

有意思的是，这篇文章本身就用了渐进式披露的写法。没有一上来就给结论，而是通过三个迭代案例，让读者自己摸出规律来。作者确实做到了“像 Agent 一样思考”。

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。

题记：本文编译自 Cursor 官方博客《Scaling long-running autonomous coding》，作者是 Cursor 研究团队的 Wilson Lin。原文分享了他们让数百个编程智能体连续自主运行数周的实验经验。本文在翻译基础上做了整理和补充。

前几天社交媒体上被 Cursor 的多智能体实验刷屏了。Cursor 的 CEO Michael Truell 发了一个 AI 狂造浏览器的帖子直接炸锅，浏览量突破 600 万：他们用 GPT-5.2 驱动数百个智能体，连续跑了一周，吐出 300 多万行代码，从零撸了一个浏览器渲染引擎。

结果呢？很多人跑去验证，瞬间被打脸。bug 一堆不说，功能上离 Chrome/WebKit 还差十万八千里。但即便如此，也有很多人给出很高的评价。比如 Stripe CEO Patrick Collison 评价说：

This work by @cursor_ai is, I think, the coolest AI breakthrough since GPT-4. (And there are plenty of candidates!)

Django 联合创始人 Simon Willison 也亲自验证了这个浏览器项目。他在 macOS 上成功编译运行，google.com 和他自己的博客都能渲染出来。虽然还有明显的渲染问题，但页面可读、大体正确。他的评价是“Honestly those are very impressive!”。有意思的是，Simon 在年初预测“到 2029 年会有人用 AI 辅助编程构建完整浏览器”，结果可能预测错了三年。

抛开浏览器项目本身的争议不谈，Cursor 在博客里分享的多智能体协作设计和踩坑经验，对大型代码仓库的 AI 协作开发还是很有参考价值的。我仔细读了原文，整理翻译出来分享给大家。

单个智能体的局限

现在的编程智能体处理聚焦性任务已经没什么问题了，但面对复杂项目时速度还是太慢。为了解决速度问题，自然的想法是并行跑多个智能体，但怎么协调它们的工作是个难题。

Cursor 团队最初的直觉是，提前做详细规划太死板了。大项目的路径本身就是模糊的，一开始很难知道怎么分工最合理。所以他们选择了动态协调的方式，即让智能体根据其他智能体当前在做什么，自己决定接下来要做的事。

协调有多难

Cursor 最早的方案是给所有智能体平等的地位，让它们通过一个共享文件来自我协调。每个智能体会检查其他智能体在做什么，认领一个任务，更新自己的状态。为了防止两个智能体抢同一个任务，加了锁机制。

这个方案不出意外地失败了，失败的方式还挺有意思：

• 智能体经常把锁拿着不放，或者干脆忘了释放。即便锁机制工作正常，它也会变成瓶颈。20 个智能体跑起来，实际吞吐量可能只相当于两三个，大部分时间都在等锁。

• 整个系统还特别脆弱，智能体可能在持有锁的时候崩溃，可能尝试获取自己已经持有的锁，或者干脆不拿锁就直接更新协调文件。

之后，他们又尝试用乐观并发控制来替代锁。智能体可以随意读取状态，写入时如果发现状态已经变了就会失败。这种方式更简单、更健壮，但还有更深层的问题。

没有层级结构的情况下，智能体变得更倾向于规避风险。它们会回避困难任务，只做小的、安全的改动。没有哪个智能体愿意承担难题或者端到端的实现。结果就是工作在原地打转，长时间没有实质进展。

规划者与执行者

既然协调方案走不通，Cursor 有继续尝试了其他方案。下一个尝试的是角色分离，即 Agent 不再是扁平结构，而是建立一个有明确分工的流水线：

• 规划者（Planner） 负责持续探索代码库、创建任务、生成子规划者来负责特定区域，并让规划本身也变成并行和递归的。

• 执行者（Worker） 负责领取任务，专注于完成任务。执行者不需要和其他执行者协调，也不用操心全局。就是埋头干活，干完了就提交代码，领下一个任务。

每个周期结束时，有一个裁判智能体（Judge Agent） 来判断是否继续，下一轮迭代重新开始。这个方案解决了大部分协调问题，让他们能够扩展到非常大的项目，而不会让单个智能体陷入局部视野。

实战：狂跑一周造了个浏览器

为了测试这套系统，他们设了一个很有野心的目标：从零开始构建一个网页浏览器。

智能体跑了将近一周，写出了分布在 1000 多个文件的 100 万行代码，并把它开源了，源码可以在 GitHub 上看到：fastrender。

尽管代码库规模很大，新加入的智能体仍然能理解它并做出有意义的贡献。数百个执行者同时运行，向同一个分支提交代码，冲突却很少。

另一个实验是在 Cursor 自己的代码库里做框架迁移，把 Solid 原地迁移到 React。这个任务跑了三周多，改动量是 +266K/-193K 行。虽然最终代码还需要仔细审查，但已经通过了 CI 和早期检查。

第三个实验是改进一个即将发布的产品。Cursor 利用一个长期运行的 Agent 使用 Rust 重写了视频渲染模块，性能提升了 25 倍，还加上了平滑缩放和平移功能，带有自然的弹簧过渡和运动模糊效果。这段代码已经合并，很快会上线生产环境。

除此之外，Cursor 还有几个正在持续运行的项目，规模也都不小：

• Java LSP：7400 次提交，55 万行代码
• Windows 7 模拟器：14600 次提交，120 万行代码
• Excel：12000 次提交，160 万行代码

他们学到了什么

这些实验消耗了数万亿个 token，系统效率还谈不上完美，但效果远超预期。Cursor 团队从中得到了一些有意思的发现。

1. 模型选择对长时间任务影响很大。他们发现 GPT-5.2 明显更适合自主工作，更能遵循指令、保持专注、避免偏离、实现得更精确完整。而 Opus 4.5 则倾向于更早停下来，在方便的时候走捷径，很快就把控制权交回去。GPT-5.2 做规划比 GPT-5.1-Codex 更好，尽管后者是专门为编程训练的。所以他们现在针对不同角色选用最合适的模型，而不是一个模型打天下。

2. 有意思的是，很多改进来自移除复杂性，而不是增加复杂性。他们最初设计了一个整合者角色来做质量控制和冲突解决，结果发现它制造的瓶颈比解决的问题更多。执行者本身就有能力处理冲突，多加一层反而添乱。

3. 他们最初试图照搬分布式计算和组织设计的模式，但发现并不是所有模式都适用于智能体。合适的结构介于两者之间：太少会导致冲突、重复劳动和偏离；太多则会带来脆弱性。最好的系统往往比预期的更简单。

4. 还有一点值得注意：提示词比架构和模型更重要。系统行为很大程度上取决于如何给智能体写提示词。让它们协调好、避免病态行为、在长时间内保持专注，需要大量实验。框架和模型当然重要，但提示词才是关键。

当然，多智能体协调的问题并未完全解决，在整个业界仍然是个难题。当前的设计基本能用，但离最优还差得远。比如规划者应该在任务完成时被唤醒来规划下一步，而不是干等着；智能体偶尔会跑太久；为了对抗偏离和局部视野，仍然需要定期重新开始。

不过核心问题的答案已经比你想象的乐观得多：能不能通过投入更多智能体来扩展自主编程？能。数百个智能体可以在同一个代码库上协作数周，在超大规模的项目上取得真正的进展。Cursor 表示，这里开发的技术最终会融入 Cursor 的智能体功能。

写在最后

Cursor 这篇文章里有几个点挺有意思的。

角色分离这件事，其实和人类团队管理的道理相通。扁平结构看起来很民主，但在智能体协作中反而会导致风险规避和内耗。有明确的规划者和执行者分工，系统的潜力反而能释放出来。

另一个印象深刻的是“简单比复杂好”。他们移除整合者角色反而效果更好，这提醒我们不要过度设计。很多时候加一层抽象不是解决问题，而是制造新问题。

还有提示词工程的重要性。即便有了好的架构和模型，如果提示词写得不好，智能体还是会出各种问题。Anthropic 之前在《Building effective agents》里也强调过类似观点，工具定义和提示词规范需要投入大量工程关注，这往往比架构设计更影响最终效果。

当然，文章也有一些没展开的地方，比如具体的提示词是怎么写的？规划者和执行者之间的任务粒度怎么划分？裁判智能体的判断标准是什么？这些细节还需要更多实践来验证。

相关资源

• 原文链接：https://cursor.com/blog/scaling-agents
• 浏览器项目源码：https://github.com/wilsonzlin/fastrender
• Building effective agents：https://www.anthropic.com/engineering/building-effective-agents

欢迎长按下面的二维码关注Feisky 公众号，了解更多云原生和 AI 知识。