从构建 Claude Code 中汲取的经验教训：像代理一样思考

原文：https://x.com/trq212/status/2027463795355095314本文对Thariq的讲解做了详细的补充，让读者详细理解他们在设计Claude Code所做的取舍与优化。核心都是在 Tools 工具管理上根据当前瓶颈找到新的方式去解决瓶颈任务管理 tool 设...

原文：https://x.com/trq212/status/2027463795355095314 本文对Thariq的讲解做了详细的补充，让读者详细理解他们在设计Claude Code所做的取舍与优化。

核心都是在 Tools 工具管理上根据当前瓶颈找到新的方式去解决瓶颈

任务管理 tool 设计演进 -> 模型搜索能力 tool 设计演进 -> 如何避免 tools 带来的上下文负担

Claude Code 的 任务管理演进

Image

Claude Code 在 任务锚定上做的工程演进

阶段一：TodoWrite — 弥补模型短板早期模型容易"迷失"在长任务中，TodoWrite 本质上是把"工作记忆"外化成一个可视化的状态机。工具的存在是为了补偿模型自身的不足——注意力漂移、遗忘目标。阶段二：System Reminders — 打补丁发现 TodoWrite 还不够，又加了每5轮的系统提醒。这是个典型的"打补丁"策略，说明工具本身的设计还没有真正解决问题，而是在工具之外再加一层兜底机制。阶段三：Task Tool — 重新定位工具的职责随着模型能力提升，发现了两个新问题：提醒机制反而产生了认知锁定——模型误以为必须严格遵循列表，失去了灵活调整的能力多智能体场景下，Todo 是单线程设计，无法支持跨 subagent 的协作和状态共享Task Tool 的设计哲学因此发生了根本转变：从"帮助模型记住要做什么"转向"帮助 agents 之间互相沟通"。支持依赖关系、跨 agent 更新、动态增删，都是为多智能体协调而生的原语。

几个值得注意的工程洞察

工具可能成为能力天花板。当模型变强后，过去的辅助工具反而变成了约束。这是一个反直觉但重要的结论：给弱模型设计的工具，可能会压制强模型的潜力。

Claude Code的搜索

RAG的局限

RAG的工作方式是：先把代码库建立向量索引，当你提问时，系统自动检索"最相关"的代码片段，然后塞给Claude作为上下文。

这样就会带来一些问题：

• RAG返回的上下文是静态的，返回的上下文内容是由RAG来决定的，这让Claude Code处于被动的状态。而在现实场景中，Claude Code需要具备主观能动性，比如代码的链路追踪，当阅读函数A，函数A调用了函数B，Claude Code根据链路一步步获取所需要的代码，这种探索是动态、迭代的，而RAG是做不到这一点的。
• RAG的维护成本，需要维护索引，补充新的数据建立新索引，代码更新后索引过期，部署等等都是成本问题
• RAG只截取"片段"，可能丢失关键的上下文（比如某个类的完整结构、某个文件的import依赖关系）。

Claude Code的探索与改进

所以我们现在需要一个“Agentic”的Claude Code，具备主观能动性，动态、迭代的探索，于是Claude Code自然而然给予了Claude Code grep 去主动探索你的代码库而不是依赖第三方，grep 让Claude具备了动态、迭代的探索能力，这种能力透露出“渐进式”的思想，并且可以发现给Claude Code合适的工具是一件ROI很高的方式，于是Claude Code提出了 Agent Skills，skills拓宽了CC的探索能力，让CC具备了不同了工具去探索，比如query DB or use API。

Claude Code工具使用探索

Claude Code有约20个工具，每增加一个工具，模型在每次推理时就多一个选项要考虑。这不只是性能问题，更是认知负担问题——工具越多，模型越容易选错、用错，或者在不该用工具的时候犹豫。

所以团队的核心约束是：工具的边际成本很高，不能随意添加。

演进的三个阶段

阶段一：System Prompt（被放弃）

把Claude Code的自身文档塞进system prompt。

问题：用户极少询问Claude Code本身的用法（MCP怎么配、slash command是什么），这些信息大部分时候是"死重"。它会造成context rot——无关信息稀释了真正重要的上下文，干扰Claude完成主任务（写代码）。

阶段二：给Claude一个文档链接（有改进但不够）

Claude可以自己去加载文档查找答案。

问题：Claude的搜索策略太"贪心"——它会加载大量文档页面来确保找到答案，但其实只需要一个精准的答案。结果是上下文窗口被文档内容撑大，效率很低。

阶段三：Claude Code Guide子智能体（当前方案）

专门构建一个子智能体，只在用户问Claude Code自身相关问题时被调用。这个子智能体有专门优化的指令：如何高效搜索文档、返回什么粒度的信息。

这其实是软件工程里关注点分离（Separation of Concerns） 原则在LLM系统中的体现：

• 主智能体专注写代码
• Guide子智能体专注文档检索和自我知识
• 两者通过明确的触发条件解耦