渐进式披露
Progressive Disclosure。一种针对大模型上下文容量有限而设计的信息组织原则：不把全部知识一次性塞给模型，而是先给”目录/索引”，让模型在需要具体内容时再按需去对应文件里读取。翔宇的比喻是”把目录给你，你需要的时候自己去目录里查百科全书，但不能把百科全书直接给它”。
简介
渐进式披露是 Claude Code / Agent Skills 生态里的核心工程原则，翔宇在实战教程中把它列为新手必须”一直记在脑子里”的五条理念之一。它的出发点是一个硬约束：大模型的上下文窗口（token 容量）是有限的，就像一个人一天只能记住有限的事情。如果把所有教程、规范、凭据、架构文档一股脑塞进上下文，模型会”上下文溢出、记不住、混淆”，性能反而下降。
渐进式披露的解法是把知识分层组织成”索引 + 细节”：常驻上下文的只有一份轻量目录（告诉模型”有哪些东西、放在哪”），细节文档平时不加载，模型判断需要时才顺着目录去打开对应文件。这样既保持了约束密度（模型知道去哪找），又避免了上下文一次性被撑满。这一原则同时体现在 Claude Code 的 CLAUDE.md 记忆系统、Agent Skill 的三层加载机制和翔宇自建的 .knowledge 目录里。
关键信息
- 英文：Progressive Disclosure
- 类型：上下文工程 / 信息架构原则
- 要解决的问题：大模型上下文容量有限，全量注入导致溢出、混淆、性能下降
- 核心手法：目录/索引常驻 + 细节文档按需加载
- 典型载体：CLAUDE.md（项目/用户记忆）、
docs/与.knowledge/目录、Agent Skill 三层结构 - 相关概念：上下文工程、目录即状态、Skill、CLAUDE.md 行为驱动设计、内容工程化、Claude Code 五大组件
核心特性
1. 目录不是百科全书
渐进式披露最形象的表达：“我把目录给你，你需要的时候你自己在目录里面学百科全书去，但是你不能把百科全书直接给他。“CLAUDE.md 应当写成一份索引——列出”基础信息 + 按需参考的文档路径”，而不是把架构、工作流、接口全文塞进去占满上下文窗口。
2. 分层按需加载
在 Claude Code 里，记忆的加载顺序是覆盖式的：从当前目录向上遍历、合并所有找到的 CLAUDE.md；而子目录的 CLAUDE.md 只有在访问该目录时才加载。翔宇因此刻意不用官方的 root 目录（怕每次都被加载占上下文），而是自己在 docs/ 里控制 Agent 文档，需要时才让模型进入读取。这与 Agent Skill 的三层加载机制（name+description → SKILL.md → references/scripts/assets）同构。
3. 服务于上下文管理与最高性能
渐进式披露的最终目的是上下文管理——只有精细管理上下文，才能让大模型时刻处于最高性能状态。翔宇强调要”精打细算、时刻关注自己的上下文”：一次新对话里系统提示词、系统工具、MCP、记忆文件都要花 token，把不必要的细节挡在窗口外，才能给真正的工作留出足够容量。
4. 配合知识文档化
渐进式披露和知识文档化是一体两面：把经验、教程、标准、凭据写成本地文档存进环境（相当于给模型一块”外挂记忆硬盘”），再用目录索引让模型按需检索。翔宇的用户记忆里挂了 .knowledge 目录（43 篇教程、2 个标准、9 个方法指南、15 个凭据），模型需要某个凭据或规范时，顺着目录检索即可，不必每次手动喂给它。
不同素材中的观点
- 2026-07-21-youtube-xiangyu-claude-code-video-app：翔宇把渐进式披露列为学习 Claude Code 的五条核心理念之一，紧接在”理解大模型有容量上限”之后。他反复用”目录 vs 百科全书”比喻，并落到三个具体载体：①CLAUDE.md 项目/用户记忆写成索引而非全文；②
docs/与.knowledge目录按需加载，故意不用官方root自动加载目录；③用/context命令实时查看新对话的 token 占用（系统提示词、系统工具、MCP ~10%、记忆文件 ~1.3%，剩余约 64%），据此判断真正可用的工作空间。核心结论：渐进式披露服务于上下文管理，上下文管理服务于让模型保持最高性能。
实用信息
落地方法
- CLAUDE.md 写成目录：只写基础信息 + “按需参考文档”的路径清单，不写全文架构/工作流。
- 细节拆进子目录：把架构、接口、规范、凭据拆到
docs/、.knowledge/等子目录，模型访问时才加载。 - 用
/context监控：定期查看上下文占用，判断可用工作空间，及时/compact或/clear。 - 知识先文档化：把重复用到的经验/凭据/规范写成文件存进环境，再用目录索引它们。
常见误区
- 把 CLAUDE.md 当说明书写全：全量注入反而降低模型性能（呼应”5000 行 agents.md 反而变笨”的观察）。
- 滥用官方自动加载目录：
root等每次加载的目录会持续占用上下文，需权衡。 - 只文档化不建索引：文档再全，模型不知道去哪找也等于没有——目录索引是渐进式披露的关键。