Optimize, slim, or restructure CLAUDE.md/AGENTS.md with progressive disclosure and zero information loss. Use when the user explicitly asks to audit, 精简, 瘦身, 重构, split, or diagnose adherence problems in instruction files. Profiles the whole resident startup surface, allocates rules among prose, path

CLAUDE.md 渐进式披露优化器核心理念 "找到最小的高信号 token 集合，最大化期望结果的可能性。" — Anthropic 目标是让指令在实际任务中被正确加载、找到并执行。信息效率、可读性与可维护性服务于这个结果；文件大小、审阅次数和脚本绿灯都不能替代行为证据。本 skill 在主文保留决策与执行入口，验证命令和历史材料按触发读取。官方篇幅建议用于发现可拆分内容，不是通过/失败阈值；用户需要的是正确行为，不是达到一个行数。执行边界与验收先固定当前目标文件、消费它的宿主、授权范围、用户可见结果与停止条件。诊断/审计请求只读；明确要求优化或修复时，执行范围内的本地可逆修改与必要验证。发布、不可逆操作和范围扩张按当前用户授权处理，已答过的同一事项不反复确认。 “零信息损失”约束仍有效的契约与原样迁移，不要求旧错误永久留在现行规范里。每项改动先标为：保留/原样移动、同源去重、依据现行权威纠错，或待用户裁决的退役/边界变更。已有明确裁定按其执行；不能把“优化”当作撤销未获授权契约的许可。提案或验收正文给出：当前原文 → 候选文本/准确 diff → 依据 → 行为后果 → 未验证之处。先做出可审阅的本地结果，再请求尚缺的决策；不能只贴改后版本或让用户自行翻文件拼差异。依据分为当前宿主/官方契约、原始研究、用户长期契约、实测样例和待验证假设。标出研究的模型、任务、样本与限制；不能把旧模型结果、公司实践或单次成功改写成 GPT/Claude 全系通用阈值。先修会改变当前任务决策的冲突、失效规则、权限歧义、假指针或真实截断。只有在问题确实是常驻负担时，才用测量贡献度安排减负顺序；不因文件最大就先改它，也不为缩小指令而新建 hook、监控或 Skill。验收是：授权范围内的改动完整且无误、真实宿主加载路径正确、代表性任务符合预期。完成必要检查后停止；仅因新改动、失败或未决疑点扩大验证。普通小修改不自动加独立审阅，复杂且缺少机械裁判的改动按当前协作契约做一次有界审阅。当前依据与适用边界见 [references/progressive disclosure principles.md](references/progressive disclosure principles.md) 开头；核查外部机制或研究结论时读取，历史案例不覆盖这里的现行契约。用户问「有哪些最佳实践」或要求参考外部做法时，先读那张证据表作答；是否需要重新调研，按表下的刷新规则判断。铁律：行数禁作 KPI，可作诊断症状禁作优化目标 / 成功指标（不可削弱——案例 7/8/9 的防线就是这条）：行数少不代表更好，行数多不代表更差评判标准是：单一信息源（同一信息不在多处维护）、认知相关性（当前任务不需要的信息不干扰注意力）、维护一致性（改一处不需要同步另一处）——不是行数禁止在优化方案 / 总结中出现"从 X 行精简到 Y 行"、"减少 Z%"作为成果禁止把"减少行数"作为移动 / 删除某内容的理由一个结构清晰、信息不重复的长文件，胜过砍掉关键信息的短文件可作诊断症状（官方依据：Claude Code 文档"文件太长 → 规则被淹没 → Claude 不遵守"）：允许把"行数异常大 + Claude 反复不遵守某规则"当成触发调查的信号，不是结论调查动作仍是信号分诊（Step 2.1）+ 分层，不是"砍到 N 行" 一句话区分：行数可以让你开始怀疑，不可以成为你优化的目标或汇报的成果触发即 reframe（用户说「太大 / 太长 / 精简 / 瘦身」时——最易在此处跑偏）这些词触发的本能是「砍行数」。先 reframe，再动手：① 确认用户要改善的实际症状与已有授权；② 按 Step 2.0 做相关测量，再进 Step 2.1 信号分诊，用「这段有没有 canonical source 重复 / 是不是反信号」决定去留，不是用「文件多长」；③ 把「太大吗」当调查的起点，不是砍的许可。用户连续追问「还是太大」时同理——回应是「再做一轮分诊找重复 / 反信号」，分诊空了就诚实说「剩下都是高频核心，再砍会丢信号」，不是继续砍有信息的内容。（实战：把「太大吗」做成减行数任务、一路用「省 39%」当成果汇报、被连续追问拽着越砍越多 → 案例 15、16。）两层架构下图是项目级布局示例，不是要求每个文件补齐的模板。全局层只留跨项目决策约束；命令、代码、诊断和目录导航按实际任务频率与可靠检索路径分配。但「两层」只是文件层——先选载体，再选层级渐进式披露不是一个文件内部的事，它在多个层同时发生：MCP 懒加载工具、RAG 按需取知识、 Skills 描述常驻正文按需、以及 Claude Code 的动态工具选择（工具索引层的渐进式披露）。只在 CLAUDE.md 内部搬 L1↔L2，等于把下表四种载体里的两种（常驻 L1 / reference）当成全部。先问载体，再问层级。判据是模型能否在决策前找到这条规则，以及现有机制能否覆盖所需条件。下表是候选路由，不证明机制已存在，也不授权安装新机制。违规可恢复违规不可恢复触发自报（我知道我要做 X） Skill / 带触发条件的 reference 可机械判定时考虑现有拦截机制；保留必要授权规则触发不自报，但「时刻」工具事件可观测按需 reference；需要事前提醒时评估注入评估 hook 提醒与最小常驻约束；语义判断仍需模型或用户触发不自报，且无可观测时刻按错误代价和任务频率决定是否常驻必要的常驻 L1 约束两条轴的定义：触发自报 = 动手前那一刻，命令/文件名/关键词里就写着「我要做这件事」—— aliyun ... 、写 .tf 、跑打包。skill 的描述匹配能接住这类。「时刻」可观测 ≠ 触发自报。这是第三行存在的全部理由：「我在修测试」不自报「我正要删功能」，但 Write 一个 .py 文件是一个工具事件， hook 能在那一刻开火。规则的语义 hook 判断不了，但时刻它看得见 —— 于是 hook 只负责报时刻、把规则怼到面前，判断仍归模型。即使存在可挂载事件，跨项目授权与用户决策原则仍可能需要常驻。不能仅凭“可挂 hook”认定可以移走。 Hook 两种形态：拦截器只在宿主支持阻断的事件和可判定条件下拒绝操作；注入器在支持的事件返回上下文提醒。触发、执行成功、提醒可见和模型遵守是四件事，不能互相代证。已加载的提醒仍占上下文；注册了 hook 不等于零成本、全覆盖或始终存活。对不可逆且只能语义判断的规则，保留必要的常驻授权句；现有注入机制可以提醒，但不替代授权或阻断。规则正文保留唯一现行来源，历史记录明确标为历史。宿主区别：Claude 的 @import 是展开加载， .claude/rules/ 无条件规则也常驻； paths: 规则依赖匹配文件的读取，不能当作所有工具事件的触发器。Codex 的 AGENTS 层级、override/fallback 与加载预算另行核对。用当前官方文档与真实宿主读回裁决，不把一个宿主的行为外推给另一个，也不自动开启 memory。核查替代机制时：先读真实注册与实现，再用无副作用的健康输入和危险形态样例双向校准，记录事件/matcher、结果与覆盖边界。周期性机制还须核对最近成功时间。详细 payload、shell 陷阱和探针模板见 [references/verification recipes.md](references/verification recipes.md) 的“替代机制探针”；未完成实证时不得缩成“已由 X 覆盖”。多入口原则（重要！）同一 Level 2 资源可以有多个入口，服务于不同查找路径：入口位置触发场景用户心态 Reference 索引开头遇到错误/问题 "出 bug 了，查哪个文档？" 修改代码前必读中间准备改代码 "我要改 X，要注意什么？" Reference 触发索引末尾长对话定位 "刚才说的那个文档是哪个？" 这不是重复，是多入口。就像书有目录（按章节）、索引（按关键词）、快速参考卡（按任务）。边界（与 SSOT 的张力，必须守住）：多入口成立仅当 ——每个入口 keyed 方式不同（错误索引 / 任务索引 / 末尾复述），且都只指向同一 Level 2 资源、不复制它的正文。如果你把同一段规则正文抄到 3 个地方，那是违反 SSOT 的重复（会各自漂移），不是多入口。一句话判据：入口存的是"路标 + 触发条件"，不是"内容副本"。优化工作流 Step 1: 固定原始基线（写入前）只读审计先读取，不因“先备份”改变目标环境。开始已授权修改前，记录精确源路径及解析后的真实目标；备份完整文件与涉及的 reference，保存路径、字节哈希和时间。使用唯一备份名，不覆盖旧备份。后续 5b 使用这次明确记录的路径，禁止从目录里按最早/最新文件名猜基线。目标在 Git 中时可用本次工作前的不可变 ref 与仓根相对路径取原文；先确认包含未提交内容的现状是否也需要保存。个人全局文件不必在 Git 中，独立备份同样适用。备份保护被保存的字节，不自动证明其他文件可恢复。 Step 2: 内容分类分三阶段：按当前症状测量、依权威分诊、按触发分层。诊断无关的整机盘点不属于本步骤；不能把低信号内容机械搬成一座 reference 垃圾场。 2.0 热点测量（先于一切提案——性能优化的第一课）先确定用户要修的是不遵循、冲突、加载错误还是上下文负担，再量相关信号。案例 19 的大文件曾是实测热点，但不能推出所有任务都按 bytes 排序。 scripts/profile claude md.py 只描述单文件内部，不测规则遵循或整套启动延迟；做加载/体积诊断时再盘点下列启动面。 1. 宿主真实注入面：Claude 用 /context 看类别占比、 /memory 看实际加载的 memory/instruction 文件；需要持续观测加载事件时用官方 InstructionsLoaded hook。Codex 用自己的权威渲染器，不凭配置猜：同时读各条 developer message 的开头，区分全局指令、项目指令、Skill catalog、hook/plugin 注入；单量 CLAUDE.md 会漏掉常驻 Skill 描述和 hook 文字。 Claude 的 /context 把 auto memory 的 MEMORY.md 与 CLAUDE.md 一并计入 Memory files。官方 memory 文档写明它每次会话加载前 200 行或 25KB（先到为准），开关是设置项 autoMemoryEnabled 或环境变量 CLAUDE CODE DISABLE AUTO MEMORY=1 。它由模型自己写入，常与用户写的指令重复或矛盾（例如用户规定经验落文档，auto memory 却仍开着），按冲突处理。把 memory 条目迁进文档是另一个 Skill 的职责，经 claude code ops router 路由到 claude migrate memory to doc ；本 Skill 只负责把它列为加载面和冲突来源。 2. 分节字节表：按 heading 统计 bytes/lines；父节包含子节，只在同层比较，不能相加当总量。体积用于定位，不直接决定改动顺序；优先级仍由当前失败、错误代价、任务相关性与可验证收益决定。 3. 行长分布： 1KB 的巨型行是「规则+战例焊死在一个 bullet」的签名（实战：4.4% 的行承载 35.6% 的字节） 4. 载入语义与上限：逐宿主实测，禁把历史版本的默认值当当前不变量。当前 Codex 的 project doc max bytes 是项目层级文档的累计预算；全局用户指令可走另一条加载路径，不能拿该值推断它是否截断。先查 ~/.codex/config.toml ，再以同 cwd 的 codex debug prompt input 实际字节为裁决。历史上确有 96 KiB 配置配合旧加载行为导致 164KB 文件尾部 41% 不可见的事故，但它只证明「必须实测」，不证明今天仍按 32 KiB 或同一路径截断。确认真截断后，在当前授权内选择能恢复所需内容可见的最小修复；修改预算、重组文件、增加监控是不同动作，不自动捆绑。 5. 常驻触发器审计：Skill frontmatter description 会进入常驻 catalog；generic 纠偏句、普通质量词或维护动作若写成触发词，会让 Skill 和 Stop hook 自激活。逐条查描述是否只声明明确任务意图，并检查 hook 是否会在最终回答阶段临时创造一个开工前本不存在的新 obligation。描述按官方上限保持 ≤1024 字符；不用列完整方法论。 Claude 侧若某些 instruction 文件对当前项目永远无关，可用官方 claudeMdExcludes 显式排除；它是 scope 配置，不是拿 @import 假装省上下文。路径相关规则优先放 .claude/rules/ 的 paths: 条件载体。 ⚠️ 测量仪器自身的两个坑（都实测踩过，脚本已内建规避；先在已知答案的样本上校准，见案例 17/19）： heading 正则必须感知 code fence ——fence 里的注释会被当成标题，凭空造出不存在的大节（实测造出过一个假的 45.9KB 节，热点排序整个失真）不把 bytes/chars 当 token 。CJK 的历史样本比率不能推广到所有文件和模型；没有当前 tokenizer 或宿主实测就省略估算。明确提供经验比率时标 est. ，同时记录比率来源与适用样本。 2.1 信号分诊（必要性闸门，先决）对每个章节先问 Anthropic 官方 litmus： "删掉这一条，Claude 会不会犯错？" 会犯错 → 是信号，进入 2.2 分层不会犯错，且属以下任一 → 是反信号，列入"候选删除"清单：能从代码 / 项目结构 / 文件名推断的（如"本项目用 TypeScript"）语言 / 框架的标准约定（如"遵循 PEP 8"）自明常识（如"写干净的代码""提交前测试"）已有独立 canonical source 覆盖的（注明 source 在哪）已过时的一次性修复（不会再复发）需要确定执行的检查（如提交前 lint）→ 核对现有 hook/CI/工作流是否覆盖。给出载体候选、触发时机、覆盖与遗漏；不能因“需要确定性”就预设 hook，也不能把 Skill 描述匹配当成确定性保证。此审计不自动授权实现新机制。安全栏：候选删除不等于已获授权。逐项给出原文、依据和行为变化；未被当前用户指令、既有裁定或现行权威决定的取舍留给用户。已有明确裁定不重复问；不确定的必要性保留 unknown，不能把“模型应该知道”当证据。与案例 8/9 的边界：8/9 是把真信号（debug 提示、代码模式）在移动时压缩掉 = 永远错；这一步是移除已确认反信号（可推断 / 自明）= 正确。区别在"删的是不是信号"，不在"删不删"。详见 references/progressive disclosure principles.md 案例 10。 2.2 分层分类对通过分诊的信号分类：问题是否高频使用？ Level 1 ↓ 违反后果严重？ Level 1 ↓ 每轮任务都需要且难以可靠检索的代码模式？ Level 1 保留最小模式 ↓ 有明确触发条件？ Level 2 + 触发条件 ↓ 历史/参考资料？ Level 2 考虑删除 Step 3: 创建 Reference 文件只有当前任务已授权修改时才执行。 profile claude md.py 只读； sink sections.py 一运行就写备份、reference 和源文件，没有 dry run。先读其 help 与精确 spec，再检查所有目标、恢复边界；共享围栏解析器 scripts/markdown headings.py 是内部实现，无独立 CLI。脚本的 OK 只证明所列机械检查通过。命名： docs/references/{主题} sop.md 铁律：原样移动，禁止压缩移动内容到 Level 2 时，必须完整保留原始内容。不要在移动的同时"顺便精简"。范围：本步骤只做原样迁移，因此不在搬运时暗改语义。去重、事实纠错和已授权退役分别声明与验证；保留有效契约不等于把失效规则继续标成现行规范。怎么做： 1. 从原始 CLAUDE.md 中精确复制要移动的段落 2. 原样粘贴到 Level 2 文件中 3. 可以在 Level 2 中添加结构（标题、分隔线），但不要删减、改写、合并原始内容 4. 如果确实有冗余（同一段话在原文中出现了多次），在 Level 2 中保留一份完整的，注释说明去重整节批量下沉的机械流程（≥3 节时脚本化，禁手搬）多节手搬容易造成行号漂移或遗漏。用 scripts/sink sections.py （spec 驱动；实战一次通过 10 节 / 119KB，整串验证 10/10 零丢失）：按精确标题行定界提取原文（fence 感知）→ verbatim 追加到目标 reference（带日期 provenance header，新文件配 intro）→ 自底向上替换 L1 压缩版（行号不失效）→ 每节整串子串验证（grep 对多行原文按行 OR、会放过丢半段的搬运，必须 python in 整串判断）→ 验证失败恢复源文件，保留 reference 追加以便核查。它不是跨文件事务；I/O 中途失败后先检查源备份和各目标，不盲目重跑以免重复追加。两条硬规则：拒写 symlink 目标（含父目录）：目标路径任一环节是 symlink（文件本身、或父目录 ——文件级 islink 检查会被目录级 symlink 静默穿透，独立审阅实测打穿过），"本地追加"实际在改 link 指向的那个仓（触发它的版本 bump / commit 义务，且那个仓可能 public）。脚本按 realpath ≠ abspath 判定并 abort，特意跨 link（如 macOS /tmp ）用 allow symlinked target 显式放行；正确动作是落一个本地兄弟文件 + provenance 注明「与 symlink 源后续合并」先全部提取、后统一替换：提取按原始行号一次做完，替换自底向上——两步交错会让未处理节的行号漂移。压缩版 snippet 必须在代码围栏外恰好保留一次完整 start heading 行（写前检查，写后复验；正文子串不算标题）；用作定界的标题在源文件里必须唯一（重名 abort） Step 4: 更新 Level 1 1. 保留当前有效的跨任务约束，更新实际受本次改动影响的既有入口。 2. 迁移细节后写明何时读、读哪里、能得到什么。 3. 代码模式、诊断和目录导航按 Step 2.2 的任务频率与检索可靠性放置。 4. 有真实查找需求时使用问题索引、任务表或内联链接，不为凑模板重复首尾索引。 5. 只有目标确实缺少且本次范围需要时才补最小信息记录原则；不自动注入整套治理章程。 ⚠️ 写指针前的硬 gate（事中验证，最易跳过、本次最大踩坑）：每写一条「→ 某 reference / 详见 X」指针前，当场确认目标文件真有这段内容。 ⚠️ 验的方式看你要验什么（verification recipes.md 的判据陷阱表已实测）：只验「这段在不在」→ 抽 3–5 个特异串用 grep F 查即可；要验「整段完整搬过去了」→ 不能用 grep —— 原句多行时 grep F 按行 OR，丢半段照样报命中，必须用 python3 整串子串判断。三种结果：① 目标已有完整内容 → 写指针；② 目标没有 / 不确定是否完整 → 先把原文 verbatim cut 到目标（回 Step 3），再写指针；③ 绝不写「指向一个其实没有该内容的文件」的假指针。假指针比丢内容更隐蔽——它让 5a「文件存在」通过、却在读者点进去时才发现是空的。Why：5a/5b 是事后验证，假指针那一刻已写进文件；事中 gate 才能在源头拦住。（实战：写「详见 anti patterns」但那里 0 命中 Stripe 端点 → 案例 15。） Step 5: 验证结构、加载与任务结果 5.0–5a. 校准判据与检查引用先在已知健康与失败样例上校准将使用的判据，区分未命中、仪器错误和不可判定；解析真实路径后验证链接目标的实际内容。标题或文件存在只证明能找到入口，不能证明整段内容完整。原样迁移用原始 bytes 整串匹配；只查关键词不能证明无丢失。执行链接检查、跨 shell 校准或完整性验证时，读取 [references/verification recipes.md](references/verification recipes.md) 的“验证器校准与引用检查”。其中 shell 命令是辅助筛查：出现跳过项须逐项解释，打印成功或 exit 0 不替代未覆盖的判断。 5b. 内容完整性（最关键）对每个从原始 CLAUDE.md 移走的章节，逐一检查： 1. 使用 Step 1 已记录的精确原始备份路径与哈希，不按文件名排序猜最早版本。Git 对照必须早于本次工作，路径相对仓根；不拿已经包含本次提交的 HEAD 自证。全局个人文件可以使用独立备份，无须假定它属于 Git 仓库。 2. 逐节对比：对原始文件的每个章节，确认其内容在以下位置之一完整存在：新 CLAUDE.md 中（保留在 Level 1）某个 Level 2 reference 文件中（完整移动） 📖 快速暴露整章遗漏的辅助脚本见 references/progressive disclosure principles.md 附录 C ：触发场景——做下面逐节对比前的第一道筛查（脚本不替代人工逐节对比，只查章节标题是否存在）。 3. 逐项解释差异：原样移动应完整保留字节；同源去重须有可达的权威来源；事实纠错或已授权退役须引用当前依据与授权，并说明行为变化。无法指认到这几类的缺失就是回归，恢复后再验证。不要用事后“故意删除”掩盖遗漏，也不要把已经被用户或现行权威推翻的旧规则补回现行规范。历史原文可由备份、Git 历史或标注清楚的事故资料保留。压缩重述的保真审计（L1 留了压缩版时必查）：压缩最容易丢的不是整段——是限定词。实战（案例 19）：原句「public + 0 stars/forks 且用户明确授权」被压成「0 stars 且明确授权」，6 个字符消失，一道闸门的条件字面上放宽了一半；同场审计还抓到「自称只省略战例、实际连 4 条可执行判据也省了」的申报口径不符。两个审计动作：① 对每条压缩重述，把操作性子句（条件 / 数值 / 枚举 / hook 名 / 否定词）与原句逐词 diff——整段丢失 5b 能抓，一个 "/forks" 只有子句级 diff 能抓；② 全文跑 expected hunks only 检查——difflib 比对基线，每个非 equal hunk 必须指认到一条已声明的改动，指认不了的就是计划外差异。独立审阅按当前协作契约触发：普通小修改且机械检查足以裁决时，不自动派 reviewer；复杂、高风险且缺少独立机械判据的修改，冻结原始基线与最终候选，做一次有界 fresh context 审阅，禁 fork 和嵌套派发。需要逐节保真审阅时可用 references/progressive disclosure principles.md 附录 D 的模板。 finding 是待验证假设，先用原始字节、准确 diff、链接内容或真实任务裁决。完成相关修复与检查即停止；只有新增高风险语义问题无法机械裁决或用户明确要求，才扩大审阅。记录已执行的方法、finding 处置及未验证项；遵循现有私有知识仓/项目 SSOT 的记录约定，不为普通指令小修改另造治理项目。 5c. 行数不进验证标准验证不以行数为通过条件，不计算"原始 X 行 vs 新 Y 行 = 减少 Z%"——这种对账会把你拉回 KPI 思维。必要结构检查：每项原内容有保留、迁移、去重、纠错或已授权退役的明确处置没有信号丢失（反信号经确认删除不算丢失） Level 2 引用都有触发条件再检查真实结果：在相同宿主/cwd 核对改前改后的实际加载内容与来源，检查 override、import、symlink 和预算。用与本次问题对应的代表性任务检验行为，保留应该遵循与不应触发的对照；报告模型、宿主、样本数和执行限制。一次成功、只初始化未跑模型、或工具成功回执都不能证明稳定的遵循率提升。模型受配额/网络限制没有执行时，写“未验证”，不改测量名称冒充成功。（注：诊断阶段可以看行数当怀疑信号，见开头「铁律」；但验证阶段行数不是任何标准——这两个阶段对行数的态度不同，别混。） Level 1 内容分类 🔴 常驻候选：先看当前任务是否需要内容类型原因核心命令当前范围高频且不能从现有入口可靠发现时保留授权/关键禁令保留决策前必须可见的适用范围、条件与停止点代码模式高频且重推导有可复现风险时保留最小例；否则按任务路由错误诊断保留入口和关键陷阱，完整 SOP 可按症状加载目录映射只留无法从文件结构可靠推断的导航触发索引根据实际查找需求设置，不强制固定位置或表格 🟡 保留摘要 + 触发条件内容类型 Level 1 Level 2 SOP 流程触发条件 + 关键陷阱完整步骤配置示例最常用的 1 2 个完整配置 API 文档常用方法签名完整参数说明 🟢 可以完全移走内容类型原因历史决策记录低频访问性能数据参考性质技术债务清单按需查看边缘情况有明确触发条件时再加载引用格式（四种）四种引用格式各服务不同场景；规范的"触发条件"写法见下方原则 2 （已含可复制示例）。格式用途触发场景详细格式正文中的重要引用单条 reference 需展开说明何时读问题触发表格开头/末尾 Reference 索引按"错误/问题"查任务触发表格「修改代码前必读」按"要改什么"查内联格式简短引用正文一句话带过 📖 四种格式的完整可复制模板见 references/progressive disclosure principles.md 附录 B ：触发场景——产出 Reference 索引 / 任务表 / 内联 / 详细引用时。格式选择

claude-md-progressive-disclosurer