Claude Md Progressive Disclosurer

CLAUDE.md 渐进式披露优化器

核心理念

"找到最小的高信号 token 集合，最大化期望结果的可能性。" — Anthropic

目标是让指令在实际任务中被正确加载、找到并执行。 信息效率、可读性与可维护性服务于这个结果；文件大小、审阅次数和脚本绿灯都不能替代行为证据。

本 skill 在主文保留决策与执行入口，验证命令和历史材料按触发读取。官方篇幅建议用于发现可拆分内容，不是通过/失败阈值；用户需要的是正确行为，不是达到一个行数。

执行边界与验收

• 先固定当前目标文件、消费它的宿主、授权范围、用户可见结果与停止条件。诊断/审计请求只读；明确要求优化或修复时，执行范围内的本地可逆修改与必要验证。发布、不可逆操作和范围扩张按当前用户授权处理，已答过的同一事项不反复确认。
• “零信息损失”约束仍有效的契约与原样迁移，不要求旧错误永久留在现行规范里。每项改动先标为：保留/原样移动、同源去重、依据现行权威纠错，或待用户裁决的退役/边界变更。已有明确裁定按其执行；不能把“优化”当作撤销未获授权契约的许可。
• 提案或验收正文给出：当前原文 → 候选文本/准确 diff → 依据 → 行为后果 → 未验证之处。先做出可审阅的本地结果，再请求尚缺的决策；不能只贴改后版本或让用户自行翻文件拼差异。
• 依据分为当前宿主/官方契约、原始研究、用户长期契约、实测样例和待验证假设。标出研究的模型、任务、样本与限制；不能把旧模型结果、公司实践或单次成功改写成 GPT/Claude 全系通用阈值。
• 先修会改变当前任务决策的冲突、失效规则、权限歧义、假指针或真实截断。只有在问题确实是常驻负担时，才用测量贡献度安排减负顺序；不因文件最大就先改它，也不为缩小指令而新建 hook、监控或 Skill。
• 验收是：授权范围内的改动完整且无误、真实宿主加载路径正确、代表性任务符合预期。完成必要检查后停止；仅因新改动、失败或未决疑点扩大验证。普通小修改不自动加独立审阅，复杂且缺少机械裁判的改动按当前协作契约做一次有界审阅。

当前依据与适用边界见 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。）

两层架构

下图是项目级布局示例，不是要求每个文件补齐的模板。全局层只留跨项目决策约束；命令、代码、诊断和目录导航按实际任务频率与可靠检索路径分配。

Level 1 (CLAUDE.md) - 每次对话都加载
├── 信息记录原则               ← 防止未来膨胀的自我约束
├── Reference 索引（开头）     ← 入口1：遇到问题查这里
├── 核心命令表
├── 铁律/禁令（含代码示例）
├── 常见错误诊断（症状→原因→修复）
├── 代码模式（可直接复制）
├── 目录映射（功能→文件）
├── 修改代码前必读             ← 入口2：改代码前查这里
└── Reference 触发索引（末尾） ← 入口3：长对话后复述

Level 2 (references/) - 按需即时加载
├── 详细 SOP 流程
├── 边缘情况处理
├── 完整配置示例
└── 历史决策记录

但「两层」只是文件层——先选载体，再选层级

渐进式披露不是一个文件内部的事，它在多个层同时发生：MCP 懒加载工具、RAG 按需取知识、 Skills 描述常驻正文按需、以及 Claude Code 的动态工具选择（工具索引层的渐进式披露）。 只在 CLAUDE.md 内部搬 L1↔L2，等于把下表四种载体里的两种（常驻 L1 / reference）当成全部。

先问载体，再问层级。 判据是模型能否在决策前找到这条规则，以及现有机制能否覆盖所需条件。下表是候选路由，不证明机制已存在，也不授权安装新机制。

两条轴的定义：

• 触发自报 = 动手前那一刻，命令/文件名/关键词里就写着「我要做这件事」—— 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 的“替代机制探针”；未完成实证时不得缩成“已由 X 覆盖”。

多入口原则（重要！）

同一 Level 2 资源可以有多个入口，服务于不同查找路径：

这不是重复，是多入口。 就像书有目录（按章节）、索引（按关键词）、快速参考卡（按任务）。

边界（与 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 用自己的权威渲染器，不凭配置猜：

   codex debug prompt-input 'startup-instruction-audit' |
     jq -r '.[] | [.role, ([.content[]? | select(.type == "input_text") | .text] | join("") | utf8bytelength)] | @tsv'

同时读各条 developer message 的开头，区分全局指令、项目指令、Skill catalog、hook/plugin 注入；单量 CLAUDE.md 会漏掉常驻 Skill 描述和 hook 文字。

1. 分节字节表：按 heading 统计 bytes/lines；父节包含子节，只在同层比较，不能相加当总量。体积用于定位，不直接决定改动顺序；优先级仍由当前失败、错误代价、任务相关性与可验证收益决定。
2. 行长分布：>1KB 的巨型行是「规则+战例焊死在一个 bullet」的签名（实战：4.4% 的行承载 35.6% 的字节）
3. 载入语义与上限：逐宿主实测，禁把历史版本的默认值当当前不变量。当前 Codex 的 project_doc_max_bytes 是项目层级文档的累计预算；全局用户指令可走另一条加载路径，不能拿该值推断它是否截断。先查 ~/.codex/config.toml，再以同 cwd 的 codex debug prompt-input 实际字节为裁决。历史上确有 96 KiB 配置配合旧加载行为导致 164KB 文件尾部 41% 不可见的事故，但它只证明「必须实测」，不证明今天仍按 32 KiB 或同一路径截断。确认真截断后，在当前授权内选择能恢复所需内容可见的最小修复；修改预算、重组文件、增加监控是不同动作，不自动捆绑。
4. 常驻触发器审计：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 分层分类

对通过分诊的信号分类：

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 时，必须完整保留原始内容。不要在移动的同时"顺便精简"。

✅ 正确：把 100 行原封不动搬到 Level 2（100 行 → Level 2 100 行）
❌ 错误：把 100 行"精简"到 60 行搬到 Level 2（100 行 → Level 2 60 行，40 行消失）

范围：本步骤只做原样迁移，因此不在搬运时暗改语义。去重、事实纠错和已授权退役分别声明与验证；保留有效契约不等于把失效规则继续标成现行规范。

怎么做：

1. 从原始 CLAUDE.md 中精确复制要移动的段落
2. 原样粘贴到 Level 2 文件中