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

开始之前

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

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

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

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

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

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

Agent Skills 也是一层层载入的。每个技能的名称和描述从一开始就在系统提示词里，任务对得上时才载入它的 SKILL.md，旁边的其他文件要等某一步去读时才载入，技能脚本那一课讲得很细。正因如此，Anthropic 的 Agent Skills 文章说，一个技能能打包的上下文“实际上没有上限”。打包进去的脚本更进一步：智能体运行它时，脚本本身和它读取的 PDF 都不必载入上下文。

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

工具定义在还没有人读它一个字的时候，就已经占满了窗口。什么是上下文工程那一课算过 Anthropic 高级工具使用文章里的五台服务器 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%。

{
  "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"}。它的工具搜索指南建议把函数分组放进命名空间，每组少于 10 个。单独延迟载入的函数仍然会显示名称和描述，所以对它来说，延迟的主要是参数结构。

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

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

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

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

// 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 放在一起权衡。

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

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

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

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

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

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

放到你自己的仓库里，意思是只属于某个包的规则，应该写进那个包里的 CLAUDE.md，在别处干活的任务就不必为它付出上下文。每个文件里该写什么，CLAUDE.md 指南里有讲。

代码执行那篇文章的作者之一 Adam Jones，在 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 工程。智能体 harness 是模型外围的代码：循环、工具、权限和检查。正是这些代码，决定了上面这些上下文操作在什么时候发生。

常见问题

资料来源

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