# 按需载入上下文：某一步需要时，才载入文件、工具和结果

> 按需载入上下文，指的是智能体只保留引用，比如文件路径、存好的查询和链接，等某一步真正需要时，才去载入它们指向的内容。Claude Code 一开始就读入 CLAUDE.md 文件，其余的用 glob 和 grep 去找。工具搜索和 MCP 代码执行，把同一个思路用在了工具定义和工具结果上。

Mindket 编辑部 · 发布于 2026-11-06 · 更新于 2026-11-06 · https://mindket.com/cn/learn/context-engineering/just-in-time-context

## 要点

- 给智能体路径和查询，让它在某一步需要时自己去打开。
- 工具定义超过约 1 万个 token 时就改为延迟载入，只把最常用的几个留在窗口里。
- 大的结果在代码里先过滤，只打印模型必须看到的那几行。
- 每个任务都需要的规则放在前面，只属于某个包的规则搬进那个包里。

## 开始之前

你应该已经知道每个回合窗口里装了什么，这是[什么是上下文工程](https://mindket.com/cn/learn/context-engineering/what-is-context-engineering)那一课的内容；也知道窗口满了以后智能体怎样把状态带下去，这在[智能体记忆](https://mindket.com/cn/learn/context-engineering/agent-memory)那一课讲过。这一课讲另一半：一开始就少放一些进去。工具相关的例子默认你以前给模型定义过工具。

这里的**引用**，是指向数据的一个简短指针，比如一个文件路径、一条存好的查询或一个网址。**工具定义**是你发给模型的名称、描述和参数结构，模型靠它来调用工具。你发出去的每一个定义都占上下文，不管模型最后用没用这个工具。

## Claude Code 怎样找到它需要的东西

Claude Code 开工之前，并不会先给你的仓库建一个索引。它载入你启动它的那个文件夹以及上级各层文件夹里的 `CLAUDE.md`，然后随着任务推进，用 glob 模式找文件，用 grep 搜文件内容。目录树更深处的 `CLAUDE.md`，要等 Claude 读写它所在文件夹里的文件时才载入。面对大型数据库时，它会写有针对性的查询，把结果存起来，再用 `head` 和 `tail` 取样查看，完整的数据从来不进窗口。

Anthropic 的[上下文工程文章](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)把这叫作按需载入（just in time）的做法。智能体手里只拿着轻量的标识，比如文件路径、存好的查询和网页链接，到了某一步需要时，再用工具把它们指向的内容载入。文章认为，正是 grep 和 glob 让 Claude Code 避开了预先建好的搜索索引会过时的问题。

文件还没打开，名字就已经带着信息。文章举的例子是 `test_utils.py`：放在 `tests` 文件夹里，和放在 `src/core_logic/` 里的同名文件，用途并不一样。智能体一边探索，一边从文件大小看出复杂程度，从名字看出用途，从时间戳看出是否相关，每读一次，都决定下一步读什么。文章把这叫作渐进式披露。

Agent Skills 也是一层层载入的。每个技能的名称和描述从一开始就在系统提示词里，任务对得上时才载入它的 `SKILL.md`，旁边的其他文件要等某一步去读时才载入，[技能脚本那一课](https://mindket.com/cn/learn/agent-skills/skill-scripts-and-references)讲得很细。正因如此，Anthropic 的 [Agent Skills 文章](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)说，一个技能能打包的上下文“实际上没有上限”。打包进去的脚本更进一步：智能体运行它时，脚本本身和它读取的 PDF 都不必载入上下文。

| 上下文 | 何时载入 | 怎样载入 |
| --- | --- | --- |
| 启动文件夹及其上级各层的 `CLAUDE.md` | 启动时 | 自动整份读入 |
| 子文件夹里的 `CLAUDE.md` | Claude 读写该文件夹里的文件时 | 惰性载入 |
| 已安装的技能 | 启动时载入名称和描述，任务对得上时载入 `SKILL.md` | 附带的文件，只在某一步去读时载入 |
| 源代码文件 | 某一步需要时 | 先用 glob 和 grep 找到，再读 |
| 大块数据，比如一次查询的结果 | 从不整份载入 | 先存起来，再用 `head` 和 `tail` 取样 |

## 工具定义也等到需要时再载入

工具定义在还没有人读它一个字的时候，就已经占满了窗口。[什么是上下文工程](https://mindket.com/cn/learn/context-engineering/what-is-context-engineering)那一课算过 Anthropic [高级工具使用文章](https://www.anthropic.com/engineering/advanced-tool-use)里的五台服务器 MCP 配置：58 个工具，对话开始前就占掉约 5.5 万个 token。其中 GitHub 和 Slack 占了约 4.7 万。

工具搜索把这些定义变成了引用。你仍然把所有工具都发过去，只是把其中大部分标上 `defer_loading: true`。Claude 看到的只有搜索工具本身，加上你选择常驻的几个工具。它需要 GitHub 时就搜索“github”，只有匹配的定义才会展开放进窗口。下面的代码片段原样出自那篇文章，发表于 2025 年 11 月。

准确率也跟着上去了。在 Anthropic 内部的 MCP 评估里，打开工具搜索后，Opus 4 的得分是 74%，不打开时是 49%；Opus 4.5 是 88.1%，不打开时是 79.5%。

````json
{
  "tools": [
    // Include a tool search tool (regex, BM25, or custom)
    {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
    // Mark tools for on-demand discovery
    {
      "name": "github.createPullRequest",
      "description": "Create a pull request",
      "input_schema": {...},
      "defer_loading": true
    }
    // ... hundreds more deferred tools with defer_loading: true
  ]
}
````

- 平台自带一个正则搜索和一个 BM25 搜索，两者匹配的都是名称和描述。文章把 `search_customer_orders` 和 `query_db_orders` 放在一起对比：前者的描述写清了它搜什么、返回什么，后者只写了“Execute order query”，搜索能匹配的内容很少。
- 把最常用的三到五个工具留在窗口里，其余的都延迟载入。文章建议，工具定义超过 1 万个 token，或者工具有 10 个以上时，就用工具搜索。工具不多、每次会话都会用到时，多出来的这一步搜索得不偿失。
- OpenAI 的 Responses API 对 `gpt-5.4` 及之后的模型也提供同样的开关：`defer_loading: true` 加上 `{"type": "tool_search"}`。它的[工具搜索指南](https://developers.openai.com/api/docs/guides/tools-tool-search)建议把函数分组放进命名空间，每组少于 10 个。单独延迟载入的函数仍然会显示名称和描述，所以对它来说，延迟的主要是参数结构。

## 大的工具结果留在代码里，不进窗口

工具结果进来时要花 token，出去时还要再花一次。让智能体用普通的工具调用，把 Google Drive 里的一份会议记录抄进 Salesforce 的一条记录，全文就要经过模型两次：读文档时一次，写更新时又一次。Anthropic 的[MCP 代码执行文章](https://www.anthropic.com/engineering/code-execution-with-mcp)估算，一场两小时的销售会议，会因此多处理约 5 万个 token。

这篇文章把每台 MCP 服务器呈现为一个由代码文件组成的文件夹，一个工具对应一个文件，让智能体针对它们写代码。智能体列出 `./servers/`，只读任务需要的那几个工具文件，然后运行一段脚本，会议记录就在沙盒里从 Drive 搬到 Salesforce。只载入需要的定义，让 Anthropic 这个例子的 token 用量从 15 万降到了 2 千。另一种做法是加一个带详细程度参数的 `search_tools` 工具，从只返回名称到返回完整结构，不需要文件树也能做到同样的事。

大的结果也能这样缩小。用普通工具调用取一张 1 万行的表格，每一行都会进窗口。换成代码，智能体在执行环境里过滤，只打印五行：

````typescript
// Without code execution - all rows flow through context
TOOL CALL: gdrive.getSheet(sheetId: 'abc123')
        → returns 10,000 rows in context to filter manually

// With code execution - filter in the execution environment
const allRows = await gdrive.getSheet({ sheetId: 'abc123' });
const pendingOrders = allRows.filter(row =>
  row["Status"] === 'pending'
);
console.log(`Found ${pendingOrders.length} pending orders`);
console.log(pendingOrders.slice(0, 5)); // Only log first 5 for review
````

- 中间结果默认留在执行环境里，模型只看得到代码打印或返回的内容。文章还更进一步：让 MCP 客户端在数据到达模型之前，把邮箱、电话号码和姓名换成占位符。
- 跑通的代码可以存进 `./skills/` 文件夹，配上一个 `SKILL.md`，下次运行时直接导入，不用重写。
- 运行模型写的代码，需要一个带资源限制和监控的沙盒。直接调用工具就不需要这些，文章提醒要把这份额外开销和省下的 token 放在一起权衡。

**Anthropic 两个例子里的 token 用量：预先全部载入与按需载入** 每一对都是 Anthropic 工程文章里的同一个场景：一套 50 多个 MCP 工具，开和不开工具搜索；以及一项从 Google Drive 到 Salesforce 的任务。只在同一对之内比较。金色的柱子是按需载入。

- 工具搜索的例子：所有定义预先载入: 约 7.7 万个 token
- 工具搜索的例子：使用工具搜索: **约 8,700 个 token**
- MCP 的例子：载入全部工具定义: 150,000 个 token
- MCP 的例子：代码只读需要的工具: **2,000 个 token**

来源：[Anthropic Engineering: Introducing advanced tool use on the Claude Developer Platform](https://www.anthropic.com/engineering/advanced-tool-use) (2026-11-06 查阅)；[Anthropic Engineering: Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) (2026-11-06 查阅)

## 什么时候预先载入反而更好

按需载入要花时间。每一次搜索、每一次读文件，都是多出来的一个回合，文章说得很直白：运行时去探索，比直接取用预先算好的数据要慢。缺少好用的工具和指令时，智能体还会浪费上下文，比如用错工具、钻进死胡同，或者偏偏漏掉了那个关键文件。

所以 Claude Code 两种做法都用。每个任务都需要的规则放在 `CLAUDE.md` 里，一开始就载入，其余的等 glob 和 grep 去找。文章认为，这种混合做法可能更适合内容变化不大的场景，比如法律或金融工作。如果文档很少变化，速度又最要紧，[RAG 教程](https://mindket.com/cn/learn/rag/rag-tutorial)里搭的那种预先算好的检索，才是更快的路。

Anthropic 自己给的建议是“做能奏效的最简单的事”。先把所有东西都载入，量一量是什么占满了窗口，再从最大的那一块开始延迟载入。

## Boris Cherny 谈为什么有些 CLAUDE.md 晚一点才载入

Boris Cherny 是 Anthropic 的 Claude Code 作者，他在 2026 年 1 月 28 日[回复 Charles Frye](https://x.com/bcherny/status/2016339448863355206)，把文档里已经写了的一条规则讲得更明白。他按位置把这些文件分成两类：启动文件夹及其上方的在启动时载入，下方的要等 Claude 碰到它旁边的文件时才载入。他说可以把后者看作一种特殊的技能，团队这样设计，是为了单体仓库和其他大型仓库。

放到你自己的仓库里，意思是只属于某个包的规则，应该写进那个包里的 `CLAUDE.md`，在别处干活的任务就不必为它付出上下文。每个文件里该写什么，[CLAUDE.md 指南](https://mindket.com/cn/blog/claude-md-file)里有讲。

代码执行那篇文章的作者之一 Adam Jones，在 Agentic AI Foundation 频道上有[一场演讲](https://www.youtube.com/watch?v=o_2_s60ui48)。它讲的正是这一课里的两种开销：还没用到就载入的工具定义，以及要经过模型中转的工具结果。他也讲了渐进式披露，以及怎样用变量在工具之间传递结果。

> 上级目录里的 CLAUDE.md 会在启动时自动载入上下文
>
> Boris Cherny, Claude Code 的作者，Anthropic，引文为译文, [X](https://x.com/bcherny/status/2016339448863355206) (2026-11-06 查阅)

[![Boris Cherny（@bcherny）2026 年 1 月 28 日在 X 上回复 @charles_irl：怕文档里没讲清楚，上级目录的 CLAUDE.md 在启动时自动载入上下文；下级目录的 CLAUDE.md 是惰性载入，只有 Claude 读写它所在文件夹里的文件时才载入。](https://mindket.com/blog/shots/x-bcherny-lazy-claude-md.webp?v=46661e64b42b)](https://x.com/bcherny/status/2016339448863355206)

Boris Cherny 在 X 上，2026 年 1 月 28 日

[Code Execution with MCP: Fix Tool Token Bloat (Adam Jones, Anthropic)](https://www.youtube.com/watch?v=o_2_s60ui48)

Anthropic 的 Adam Jones 讲工具定义膨胀、工具结果膨胀和渐进式披露，2025 年 12 月发布在 Agentic AI Foundation 频道。

> X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 6 日，时间为 UTC。X 用“Show more”把帖子截短了。点击截图可到 X 上打开原帖。

## 常见错误

- 一个路径加一次 grep 就能找到关键部分，却把整份文件或整个查询结果贴进提示词。
- 把每个工具都延迟载入，连每个任务都要用的也不例外，结果每次运行都得先搜索一遍。
- 工具描述写得太短，搜索根本匹配不上，比如“Execute order query”。
- 代码执行的脚本把整个结果都打印出来，那 1 万行又回到了窗口里。
- 运行模型写的代码，却没有沙盒、资源限制和监控。
- 把只属于某个包的规则放在根目录的 `CLAUDE.md` 里，每个任务都得载入它们。
- 会话中途从 OpenAI 的 `tool_search_output` 里移除一个已载入的工具，却没料到缓存会失效。指南说，改动已载入的工具集合，会从那一刻起打断缓存。

## 自己试一试

- 数一数你的工具定义占多少 token，然后只留最常用的五个，其余改为延迟载入，再数一次。
- 在一个你熟悉的仓库里，问 Claude Code 某条报错信息是从哪里来的，记下它回答之前打开了哪些文件。
- 把某个文件夹专用的规则，从根目录的 `CLAUDE.md` 搬进那个文件夹自己的 `CLAUDE.md`。
- 找一个会返回长列表的 MCP 调用，改写成一段短脚本：先过滤，再打印前五条匹配结果。

## 下一门课：Harness 工程

上下文工程这门课到这里就结束了。你已经看过窗口里装的是什么，窗口满了为什么会拉低准确率，智能体怎样把状态带过窗口的边界，以及怎样从一开始就少载入一些。

下一门课是 [Harness 工程](https://mindket.com/cn/learn/harness-engineering/what-is-an-agent-harness)。智能体 harness 是模型外围的代码：循环、工具、权限和检查。正是这些代码，决定了上面这些上下文操作在什么时候发生。

## 自测一下

1. 在 Claude Code 里，子文件夹中的 CLAUDE.md 什么时候载入？

   A. 启动时，和根目录的文件一起
   B. 只有运行 /memory 时
   C. Claude 读写那个文件夹里的文件时
   D. 从不载入，只有根目录的文件会载入

   答案：C。 启动文件夹及其上级的文件在启动时载入，下级的则是惰性载入，等 Claude 在那个文件夹里干活时才载入。

2. 在 Anthropic 五台服务器的例子里，对话开始之前，58 个工具定义大约占了多少 token？

   A. 约 5.5 万
   B. 约 5 千
   C. 约 13.4 万
   D. 约 500

   答案：A。 GitHub、Slack、Sentry、Grafana 和 Splunk 加起来约 5.5 万个 token。13.4 万是 Anthropic 在自己的使用中见过的、工具定义在优化之前占用的 token 数。

3. 你的智能体取了一张 1 万行的表格，但只需要待处理的订单。怎样让其他行不进窗口？

   A. 换一个更大的上下文窗口
   B. 调用之后做一次压缩
   C. 让模型忽略其他行
   D. 在代码里过滤，只打印几行

   答案：D。 用代码执行时，这些行留在执行环境里，模型只看得到脚本打印出来的内容。

4. 哪种情况从工具搜索里得到的好处最少？

   A. 一套 200 个 MCP 工具
   B. 六个精简的工具，每次会话都会用到
   C. 占 4 万个 token 的工具定义
   D. 模型老是选错工具

   答案：B。 Anthropic 认为，工具不多、每次会话都会用到时，工具搜索用处不大，那一步搜索只会增加延迟。

## 常见问题

### 什么是按需载入上下文？

就是智能体在需要的那一刻才去取的上下文，而不是事先塞进提示词的上下文。Anthropic 2025 年 9 月发表的上下文工程文章介绍了这种做法，并以 Claude Code 为例。

### 按需载入上下文和 RAG 是一回事吗？

不是。经典的 RAG 在模型回答之前，用向量嵌入检索出文本片段。按需载入则让智能体在干活的过程中自己决定去取什么，用的是 grep 这类工具。Anthropic 看到的情况是，团队把它加在嵌入检索之上，而不是拿它取代检索。

### 工具搜索能不能由我自己来做，而不是交给服务商？

能。在 Claude 上，你可以用自己的方式搜索，比如基于向量嵌入，[Anthropic 的工具搜索 cookbook](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/tool_search_with_embeddings.ipynb) 就是这么做的。OpenAI 把这叫作客户端执行的工具搜索：模型发出一个 `tool_search_call`，由你的代码去查找，再返回一个 `tool_search_output`。OpenAI 建议，当该用哪些工具取决于项目或租户的状态时，就这样做。

### 工具搜索会打断提示词缓存吗？

本身不会。Anthropic 把延迟载入的工具排除在第一份提示词之外，系统提示词和常驻的工具仍然是一段稳定、可缓存的前缀。OpenAI 出于同样的原因，把找到的每个工具都追加在窗口末尾。

### AI 智能体里的渐进式披露是什么意思？

指智能体分层了解它的上下文：先是名称和一句简短描述，任务对得上时再看完整的说明，某一步需要时才去读额外的文件。Agent Skills 就是这样工作的，工具搜索对工具定义也是同样的做法。

## 资料来源

- [Anthropic Engineering: Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) (2026-11-06 查阅)
- [Anthropic Engineering: Introducing advanced tool use on the Claude Developer Platform](https://www.anthropic.com/engineering/advanced-tool-use) (2026-11-06 查阅)
- [Anthropic Engineering: Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) (2026-11-06 查阅)
- [Anthropic Engineering: Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) (2026-11-06 查阅)
- [Claude cookbooks: Tool search with embeddings](https://github.com/anthropics/claude-cookbooks/blob/main/tool_use/tool_search_with_embeddings.ipynb) (2026-11-06 查阅)
- [OpenAI API docs: Tool search](https://developers.openai.com/api/docs/guides/tools-tool-search) (2026-11-06 查阅)
- [X: Boris Cherny on how Claude Code loads CLAUDE.md files](https://x.com/bcherny/status/2016339448863355206) (2026-11-06 查阅)
- [YouTube: Agentic AI Foundation, Code Execution with MCP (Adam Jones, Anthropic)](https://www.youtube.com/watch?v=o_2_s60ui48) (2026-11-06 查阅)

[浏览 MCP 服务器](https://mindket.com/cn/mcp-servers)