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 文字。

   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 分层分类

对通过分诊的信号分类：

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 文件中
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 的“验证器校准与引用检查”。其中 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 内容分类

🔴 常驻候选：先看当前任务是否需要

🟡 保留摘要 + 触发条件

🟢 可以完全移走

引用格式（四种）

四种引用格式各服务不同场景；规范的"触发条件"写法见下方 原则 2（已含可复制示例）。

📖 四种格式的完整可复制模板见 references/progressive_disclosure_principles.md 附录 B：触发场景——产出 Reference 索引 / 任务表 / 内联 / 详细引用时。

格式选择：使用能让读者可靠找到内容的最简单格式；不为“多样性”混用格式。

⚠️ @import 不省上下文（技术正确性，最易踩）

@path import 在启动时全量展开载入——拆成 @import 只改善组织，不减少任何上下文（官方 memory 文档原文）。"我把内容拆进 @import 了所以优化了"是假优化。

常用的减负方式包括以下三种；还可按当前宿主支持情况评估 paths 规则或显式 scope 排除，不把此列表当穷尽枚举：

1. 把非通用内容移到项目级 CLAUDE.md（全局文件会被无关项目加载）
2. 留纯文字指针（"需要时 Read references/xxx.md"，不是 @），让模型按需拉
3. 转 skill（描述常驻、正文按需）

本 skill 产出的引用一律用反引号路径，禁止用 @import 做卸载。详见 references/progressive_disclosure_principles.md 案例 11。

核心原则

原则 0：更新现有信息归属规则

先看目标是否已经说明信息放在哪里。仅补本次需要而缺失的触发、归属和维护来源，不机械添加一整章。references/progressive_disclosure_principles.md 附录 A 是可裁剪模板，供确实需要补齐归属规则时使用。

原则 1：索引位置服从检索需要

默认保留一个清晰入口。只有存在不同查找路径或实测漏读时才增加多入口；每个入口只指向同一权威正文。Lost in the Middle 研究不能直接证明所有现代模型都需要在指令文件首尾复制索引，也不能给出通用最优位置。案例 4 保留一种布局经验，使用时以当前任务验证。

原则 2：引用必须有触发条件

错误：详见 native-modules-sop.md

正确：

**📖 何时读 `native-modules-sop.md`**：
- 遇到 `ERR_DLOPEN_FAILED` 错误
- 需要添加新的原生模块

> 包含：ABI 机制、懒加载模式、手动修复命令

原因：没有触发条件，LLM 不知道什么时候该去读。

原则 3：保留任务实际需要的代码模式

在已确认该模式需要常驻的任务中，只写“使用懒加载模式”却丢掉完整实现是错误的；应保留下面的可复制例。

正确：Level 1 保留完整的可复制代码：

// ✅ 正确：懒加载，只在需要时加载
let _Database = null;
function getDatabase() {
  if (!_Database) {
    _Database = require("better-sqlite3");
  }
  return _Database;
}

适用条件：此例只在该代码模式高频且存在可靠性收益时常驻。若只对某个组件或偶发任务适用，保留触发入口并完整放入对应 reference；不要把所有项目代码例子复制到全局层。

原则 4：用三态优先级，不要"全标铁律"

把所有规则标成最高优先级会掩盖实际边界。先消除在同一场景给出相反动作的规则，再明确必须、禁止、可选及各自触发与停止条件；标签或位置不能覆盖真实宿主的指令优先级。

堆叠强调词（加粗、CRITICAL、MUST、「铁律」「绝对禁止」、惩罚威胁）属于同一问题。Anthropic 官方提示建议指出新模型会因此过度触发；改写时换成平常语气，写清适用条件和原因，规则的边界与停止点保持不变。

✅/⚠️/🚫 可作为显示样式，不是经对照实验证明的最佳结构。没有足够证据把“150–200 条规则”“只保留 5–7 条高危规则”设为现代 GPT/Claude 的通用上限。数量与位置相关研究的适用范围见 reference 开头的证据表；以当前宿主上的实际行为裁决。

原则 5：原因帮助决策时才补充

简短原因在帮助理解适用边界时有用；工程文章的建议不构成“所有规则必须附一行 Why”的实验证明。

对不直观的限制补充具体后果；已经明确的规则不再重复解释，不复制事故过程或编造历史。

错误：🚫 禁止 fallback 默认值

正确：必需凭据缺失时显式报错；不要回退到内置密钥，以免误连其他环境。

⚠️ 重述规则时的硬边界：若原句嵌在 case study 混合段落里，原则 4/5 不得直接改写原句——见反模式 6（先整段 verbatim 移 L2，案例 14）。

反模式警告

⚠️ 反模式 1：以行数为目标的过度精简

案例：为了"减少行数"，移走了代码模式、诊断流程、目录映射

结果：

• 丢失代码模式，LLM 每次重新推导
• 丢失诊断流程，遇错不知查哪
• 丢失目录映射，找文件效率低

正确：保留所有高频使用的内容。优化的判断标准是信息是否重复维护、是否与当前任务无关，而不是"文件太长"。

⚠️ 反模式 2：无触发条件的引用

案例：详见 xxx.md

问题：LLM 不知道何时加载，要么忽略，要么每次都读。

正确：触发条件 + 内容摘要。

⚠️ 反模式 3：移走代码模式

案例：把常用代码示例移到 Level 2

问题：LLM 每次写代码都要先读 Level 2，增加延迟和 token 消耗。

正确：高频使用的代码模式保留在 Level 1。

⚠️ 反模式 4：删除而非移动

案例：删除"不重要"的章节

问题：信息丢失，未来需要时无处可查。

正确：有效的低频内容完整移到 Level 2 并保留触发；过时规则按明确依据和授权纠错或退役，不伪装成原样迁移。

⚠️ 反模式 5：用行数当 KPI

案例：优化方案写"从 2000 行精简到 500 行，减少 75%"

问题：把行数当成功指标，会驱动错误决策——为了凑数字而砍掉有用的信息。

正确：用信息质量评估优化效果——信息是否有重复？维护负担是否降低？LLM 是否能更快找到需要的信息？

⚠️ 反模式 6：移动时压缩（变相删除）

规则：移动是移动，精简是精简。这是两个独立操作，不要同时执行。

• 移动内容到 Level 2 时，必须原样复制，不改一字
• 去重、纠错或退役单独声明与核验，依本次及既有授权执行；只把尚缺的实质选择交给用户
• "既然都在改了，顺便精简一下"是最隐蔽的删除——它披着"优化"的外衣，做着"删除"的事
• 混合段落：在原样迁移模式下先完整保留原段落，再生成 L1 的检索入口；逐项核对条件、数值、否定词和停止点。历史原文与现行规则分开标注，不能让过时原文与新决定同时冒充权威。已授权的纠错/退役不受“旧规则永不改写”约束，但必须有独立基线和准确 diff。 ⚠️ 这条判据别用 grep 验（Step 5.0 表第 4 行实测）：原句多行时 grep -F 把它拆成多个 pattern 按行 OR， 丢了半段照样报命中 —— 它会为一次有损搬运出具无罪证明。用整串子串判断： 把原句存进临时文件，用 Path("orig").read_bytes() in Path("target").read_bytes() 检查连续完整字节匹配；先从 pathlib 导入 Path。 原则 4/5 管 L1 如何呈现，不授权销毁信号原句

完整案例分析见 references/progressive_disclosure_principles.md 案例 8、案例 14

⚠️ 反模式 7：用"故意删除"掩盖信息丢失

规则：每项删除或行为变化在修改前说明依据与授权，不能发现少了之后才编理由。

• 同源去重指出现有权威源和可达入口。
• 纠错或已授权退役指出较新的权威事实/用户裁定；失效内容不必继续作为运行时规则保存。
• 没有上述依据的丢失是回归，恢复并验证；不能用“低风险”掩盖。

完整案例分析见 references/progressive_disclosure_principles.md 案例 9

⚠️ 反模式 8：纯否定规则（不给替代）

案例：🚫 不要用 X —— 没说改用什么。

问题：缺少必要替代路径可能让执行者不知下一步；这是一项可验证的可执行性问题，不是所有否定句都会导致模型失败。

正确：存在已知且获授权的替代路径时写清；有效的停止/禁止规则不因没有替代方案而失效。

🚫 不要用全局 mutable 单例存请求状态
✅ 改用显式参数传递或 request-scoped context

遇到禁令先保留其真实边界；只有当前证据支持时补替代动作，不能编造 fallback，也不能据此删掉必要禁令。

⚠️ 但若禁令原句嵌在 case study 混合段落里，先按反模式 6 整段 verbatim 移 L2，再在 L1 派生重述——不可改写原句（案例 14）。

⚠️ 反模式 9：假指针（指向不存在的内容）

案例：移走一段内容后写「详见 X.md」，但 X.md 里根本没有这段——指针指向空。

问题：比直接丢内容更隐蔽。5a「文件存在」会通过（X.md 确实存在），但内容不在那里；读者点进去才发现，且此时已无从知道原文是什么。本质是反模式 6（移动时压缩）+ 反模式 7（掩盖丢失）的组合：内容被砍 + 用一个看似合规的指针掩盖。

正确：写指针前当场验证目标真有该内容（Step 4 硬 gate；验「在不在」用 grep -F 抽特异串，验「整段完整」必须用 python3 子串判断——grep 会给假阳性，见 verification-recipes.md 的判据陷阱表）。指针指错文件（内容在 A、却写「详见 B」）是同类问题，按内容实际所在地修正、不是删指针。

完整案例分析见 references/progressive_disclosure_principles.md 案例 15

信息量检验

✅ 正确的信息量

❌ 不足的信号

• LLM 反复问同样的问题
• LLM 每次重新推导代码模式
• 用户需要反复提醒规则

❌ 过多的信号

• 大段低频详细流程在 Level 1
• 完全相同的内容在多处（注意：多入口指向同一资源 ≠ 重复）
• 边缘情况和常见情况混在一起

项目级 vs 用户级

硬检查：scope 错放（官方层级文档裁定）

用户级 ~/.claude/CLAUDE.md 会被所有项目加载，只能放普遍适用的东西。优化时对每节做 scope 检查：

Step 2.1 先判断内容职责：具体项目状态/实现细节进入其项目 SSOT；跨项目导航可以保留带触发条件的指针。发现项目名不自动授权搬迁或删除，也不能把全局路由指针误判为项目事实。详见 references/progressive_disclosure_principles.md 案例 13。

金丝雀检测法（仅作诊断候选）

单条无害命名指令只能探测该指令在该样例是否可见/被执行，不能证明整份文件在“遵循度阈值内”，也不能证明失败源自文件过长。只有用户需要这类诊断时才在隔离样例里使用；不自动向全局契约植入无关规则。优先验证真实任务中应该遵循与不应触发的行为。

快速检查清单

• 用户目标、授权范围、准确原文/候选 diff、依据与未验证项已明确；没有重复请求已有授权。
• 原样移动保持字节；纠错、去重、退役分别有依据，不以“零损失”恢复失效规则。
• 每个引用的目标内容真实存在，触发、scope 与权威来源清楚；无假指针或双重现行规则。
• 所用判据已用健康/失败样例校准，工具错误和未覆盖项没有伪装成成功。
• 当前宿主实际加载面已检查；代表性任务验证了本次行为，未测的模型/分支如实标注。
• 必要的独立审阅按当前协作契约执行；修复后检查相关范围，达到停止条件即收尾。
• 没有把 bytes、行数、reviewer 数量、命名金丝雀或脚本 OK 当业务结果。
• 全局文件只承载跨项目职责；未自动新增模板章节、memory、hook、Skill 或监控。