从 Claude Code 学上下文设计

Agent 的能力上限，经常不是模型决定的，而是上下文决定的。

同一个模型，拿到不同上下文，会表现得像两个系统。没有上下文时，它只能靠训练数据和猜测回答；上下文清楚时，它才有机会像一个真的在现场工作的工程师。

上下文不是越多越好

很多人做 Agent 的第一反应是把所有东西都塞进去：项目介绍、历史对话、文档、文件、错误日志、用户偏好。

这样做的问题是，Agent 会被噪音淹没。

真正有效的上下文设计，要解决的是三个问题：

• 当前任务最需要什么信息？
• 哪些信息是长期稳定的？
• 哪些信息应该等需要时再读取？

上下文不是仓库，而是工作台。工作台上只应该放当前任务需要的东西。

Claude Code 的启发

Claude Code 里最值得学习的上下文设计，不是它能读很多文件，而是它会先理解项目规则。

比如：

• 当前目录是什么项目
• AGENTS.md 或项目指令写了什么
• 包管理器和构建命令是什么
• git 工作区是否干净
• 用户刚刚提出的最新要求是什么

这些信息先于具体代码。因为它们定义了 Agent 的行动边界。

我会把上下文分成四层

第一层是全局上下文。

它描述项目长期稳定的信息：产品定位、技术栈、目录约定、编码风格、部署方式。这类信息适合放在项目级指令里，比如 AGENTS.md、README 或系统配置。

第二层是任务上下文。

它描述本次任务的目标、限制和验收标准。比如“重构首页为玻璃风格”“不能破坏现有内容管线”“需要部署到生产环境”。

第三层是环境上下文。

它来自现场观察：文件内容、命令输出、构建错误、页面截图、git diff。这类上下文应该按需读取，不应该一次性全塞进提示词。

第四层是历史上下文。

它记录之前做过的关键决策：为什么选择这个方案，哪些尝试失败了，哪些约定以后要复用。

上下文装配要有顺序

我更倾向于让 Agent 按这个顺序装配上下文：

Project rules -> User goal -> Relevant files -> Runtime evidence -> Prior decisions

先读规则，是为了不乱动。 再读目标，是为了不跑偏。 再读文件，是为了理解真实结构。 再看运行结果，是为了用证据修正判断。 最后沉淀决策，是为了下次不用从零开始。

什么时候不该加载上下文

有些上下文看起来有用，但实际上会干扰判断。

比如：

• 和当前任务无关的历史讨论
• 过早读取整个代码库
• 没有来源的总结
• 已经过时的项目说明
• 还没有验证的模型推断

Agent 应该知道自己看到的信息可信度不同。真实文件和命令输出，比二手总结更可靠。

应用到自己的项目

如果我要给 OpenClaw 设计上下文系统，我会让主 Agent 负责上下文装配，而不是让每个子 Agent 自己乱查。

主 Agent 应该决定：

• 子 Agent 需要哪些项目规则
• 需要传哪些文件片段
• 哪些工具结果可以复用
• 哪些历史记忆值得注入
• 哪些信息必须实时查询

这样做的好处是，子 Agent 更专注，主 Agent 对全局一致性负责。

一个实用原则

上下文设计的目标不是让 Agent “知道很多”，而是让它“少猜一点”。

只要一个上下文能减少猜测、降低误操作、提升验证质量，它就是有价值的。否则，它只是 token 噪音。