做 Agent，请必须学会渐进式披露
公众号名称：三元同学
作者名称：三元同学
发布时间：2026-05-15 10:23
OpenAI 团队今年发了一篇文章，叫 Harness Engineering，讲的是他们用 Codex 从零搭了一个内部产品——百万行代码，零行人写，全部由 Agent 生成。三个工程师，五个月，1500 个 PR。
这个数字看上去挺震撼的。但真正让我注意的，不是这个产出量，而是他们在过程中踩的一个大坑。
他们一开始做了一件几乎所有 Agent 开发者都会做的事——写了一个巨大的 AGENTS.md，把所有的规则、约束、架构原则、编码规范全塞进去。
然后随着不断的迭代，整个开发团队就炸了。
一个巨大的 AGENTS.md 是怎么变成灾难的
OpenAI 团队在文章里原话说的是 “it failed in predictable ways”——以一种可以预见的方式失败了。他们总结了四条原因，我用人话跟大家解释清楚。
主要是两个方面的问题，对人和对 Agent 来说为维护成本都变高了。
上下文窗口就这么大，你塞了一堆规则进去，真正干活的空间就被挤掉了。Agent 本来该看的是当前任务、相关代码、需要参考的文档，结果它的注意力全被那 200 条”重要规则”分散了。
而且你想想，200 条规则全标成高优先级，对 Agent 来说跟没有优先级有什么区别？它分不清哪条是此刻必须遵守的、哪条跟当前任务八竿子打不着，只能瞎猜。
还有一个更实际的问题——这种巨大的指令文件腐烂（Rot）速度极快。代码天天在变，架构也在演进，但那个文件没人想去更新。写的时候觉得”以后会维护的”，三周之后就成了陈旧规则的坟场。Agent 不知道哪些还有效、哪些早就过时了，人类自己也搞不清楚。
那么怎么办？
OpenAI 的解法：目录，不是百科全书
痛定思痛，OpenAI 团队做了一个关键转变——把 AGENTS.md 从”百科全书”变成了”目录”。
新的 AGENTS.md 只有大约 100 行，不再试图把所有规则写进去，而是只告诉 Agent：“你需要知道的东西在哪里”。
真正的知识库放在一个结构化的 docs/ 目录里：设计文档、架构文档、产品规格、质量评分、安全规范……每个都是独立的文件，有清晰的分类和索引。
他们把这个模式叫做 Progressive Disclosure（渐进式披露）：Agent 从一个小的、稳定的入口开始，被教会在需要的时候去找更深层的信息，而不是一开始就被所有东西淹没。
这不是 OpenAI 独创的想法，但他们在实战中验证了它的威力—一个百万行代码的项目，如果不做渐进式披露，Agent 根本跑不动，到了不得不上的地步。
渐进式披露到底在说什么
我尝试用一句话讲清楚：不是少给 Agent 信息，而是在对的时间给对的信息。
这个概念其实不新。交互设计领域早就有渐进式披露——比如说 iPhone 不会一打开就把所有设置项铺给你，它先给你一个简洁的首页，你需要的时候再一层层进去。这其实很好理解。
放到 Agent 开发里，逻辑完全一样：
-
启动时，只给 Agent 一个轻量级的”地图”
-
Agent 根据当前任务判断需要什么
-
按需加载具体的信息
当你真的去看那些做得好的 Agent 系统，你会发现渐进式披露这个模式无处不在。它不是某一个产品的设计选择，而是所有成熟 Agent 系统不约而同走向的方向。
场景一：Skills 的三层加载
Claude Code 的 Skills 系统面临一个很现实的问题：如果你装了 100 个 Skills，不可能把所有内容都塞进上下文。
它的解法是三层渐进式加载。
第一层，启动时只加载每个 Skill 的 frontmatter——名字、描述、什么时候用。每个 Skill 大概 100 token，100 个加起来也就 10,000 token。这些信息足够 Agent 判断”这个 Skill 跟当前任务有没有关系”。
第二层，Agent 判断某个 Skill 相关了，才加载它的完整内容——最佳实践、代码示例、常见陷阱。
第三层，Skill 目录下还有参考文件和脚本，这些只有在真正需要的时候才用 Read 工具去读。
对比一下：如果走全量加载的路子（比如 MCP Server），100 个工具的 Schema 一上来就吃掉几万 token，还没开始干活，上下文已经塞了一大半。
Skills 的初始 Token 消耗可能只有全量加载的 1/50，几乎可以忽略不计了。
场景二：工具系统的延迟加载
工具也有同样的问题。Claude Code 有 30 多个内置工具，再加上用户接入的 MCP Server，工具数量轻松破 50。每个工具的 JSON Schema 平均 500-800 token，50 个工具光定义就吃掉 25,000-40,000 token。
更要命的是，研究数据表明工具从 10 个涨到 50 个，模型的选择准确率从 90% 掉到不到 50%。工具越多，模型越傻。
Claude Code 的解法叫 Deferred Tool Loading。把工具分成两组：核心工具（Read、Write、Bash 这些几乎每次都用的）永远加载；低频工具（WebSearch、NotebookEdit 之类的）只在 prompt 里放一个名字列表。
Agent 需要某个低频工具时，先调一个叫 ToolSearch 的元工具搜索，拿到完整定义后再使用。
本质上跟 Skills 的思路一模一样：先给地图，按需取详情。
场景三：知识库的三级缓存
Karpathy 今年提的编译知识库（LLM Wiki）也是同一个思路。
他设计了一个三级缓存体系：
index.md 常驻在 prompt 里，大概 2500 字符，是整个知识库的目录。每个 wiki 页面一行，包含链接和一句话摘要。Agent 每次会话都能看到”我有什么知识”，但不需要把所有内容都装进来。
需要详细信息时，Agent 通过 index.md 定位到相关的 wiki 页面，按需读取。大部分时候这一层就够了。
只有 wiki 页面的信息不够详细时，才回到最底层的原始文档。
Karpathy 用完后表示，中等规模下（几百个 wiki 页面），这套机制”出奇地好用”，不需要向量数据库，一个 index.md 加 grep 就够了。
这是一套心法
说到这里你可能发现了，渐进式披露这个东西，在 Agent 开发的各个层面都在出现：
-
OpenAI 的目录式 AGENTS.md
-
Karpathy 的三级缓存知识库
-
Claude Code 的 ToolSearch 延迟加载
-
Skills 的三层渐进加载
它不是某个框架的 feature，不是某个产品的设计选择，而是一种思维方式。
一个成熟的 Agent 开发者，脑子里永远在问一个问题：此刻，Agent 需要知道什么？不需要知道什么？
大多数人的直觉是往里面加东西——Agent 表现不好，那就多给它一些规则、多加几个工具、多塞一些参考文档。但加到一定程度之后，效果开始反转。
真正的杠杆不在于你给了 Agent 多少信息，而在于你能不能做到在对的时间，只给它需要的那一份。
这件事说起来容易，做起来需要对整个 Agent 系统有全局的理解——你得知道上下文窗口是怎么分配的，prompt cache 是怎么工作的，工具列表变化对推理的影响，知识检索的成本和收益。
但一旦你建立了这个思维方式，你做出来的 Agent 系统，在效果、成本、可维护性上都会跟没有这个意识的人拉开一个量级的差距。
说实话，我觉得这是 Agent 开发领域少数几个”知道了就回不去”的认知升级。
如果你现在的 Agent 项目里有一个巨大的系统 prompt 或者 AGENTS.md，今天可能是个好时机停下来想想：这里面的东西，是不是都需要 Agent 在每次对话开始时就看到？
我是三元同学，带你从专业视角理解 AI，学习 AI Agent，欢迎关注、点赞、留言，我们下期再见。
Original 三元同学 三元同学
内容效果不满意？点此反馈