claude-md-progressive-disclosurer

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。）

两层架构

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

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

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

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

渐进式披露不是一个文件内部的事，它在多个层同时发生：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 用自己的权威渲染器，不凭配置猜：

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

对通过分诊的信号分类：

| 问题 | 是 | 否 |

|------|----|-----|

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

✅ 正确：把 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](references/verification-recipes.md) 的“验证器校准与引用检查”。其中 shell 命令是辅助筛查：出现跳过项须逐项解释，打印成功或 exit 0 不替代未覆盖的判断。

5b. 内容完整性（最关键）

对每个从原始 CLAUDE.md 移走的章节，逐一检查：

1. 使用 Step 1 已记录的精确原始备份路径与哈希，不按文件名排序猜最早版本。Git 对照必须早于本次工作，路径相对仓根；不拿已经包含本次提交的 HEAD 自证。全局个人文件可以使用独立备份，无须假定它属于 Git 仓库。

1. 逐节对比：对原始文件的每个 ## 章节，确认其内容在以下位置之一完整存在：

• 新 CLAUDE.md 中（保留在 Level 1）
• 某个 Level 2 reference 文件中（完整移动）

📖 快速暴露整章遗漏的辅助脚本见 references/progressive_disclosure_principles.md 附录 C：触发场景——做下面逐节对比前的第一道筛查（脚本不替代人工逐节对比，只查章节标题是否存在）。

1. 逐项解释差异：原样移动应完整保留字节；同源去重须有可达的权威来源；事实纠错或已授权退役须引用当前依据与授权，并说明行为变化。无法指认到这几类的缺失就是回归，恢复后再验证。

不要用事后“故意删除”掩盖遗漏，也不要把已经被用户或现行权威推翻的旧规则补回现行规范。历史原文可由备份、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 索引 / 任务表 / 内联 / 详细引用时。

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

⚠️ @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：用三态优先级，不要"全标铁律"

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

✅/⚠️/🚫 可作为显示样式，不是经对照实验证明的最佳结构。没有足够证据把“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

---

信息量检验

✅ 正确的信息量

| 检验项 | 通过标准 |

|--------|---------|

| 日常任务 | 可发现所需命令，按现有项目惯例完成 |

| 常见错误 | 能按症状找到可信诊断流程 |

| 代码编写 | 需要的非默认模式可可靠获取 |

| 特定问题 | 知道何时读哪个 Level 2 |

| 触发索引 | 入口可达且不复制权威正文，位置/格式不作硬闸 |

❌ 不足的信号

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

❌ 过多的信号

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

---

项目级 vs 用户级

| 维度 | 用户级 | 项目级 |

|------|--------|--------|

| 位置 | ~/.claude/CLAUDE.md | 项目/CLAUDE.md |

| References | ~/.claude/references/ | docs/references/ |

| 信息范围 | 个人偏好、全局规则 | 项目架构、团队规范 |

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

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

| 内容特征 | 归属 | 不这样做的后果 |

|---|---|---|

| 项目名 / 部署目标 / 逐项目路径 / 项目凭据 | 项目级，绝不全局 | 无关项目被污染；没人按项目维护 → 路径/状态腐烂（典型 staleness） |

| 个人偏好、跨项目行为规则 | 用户级 | — |

| 团队规范、项目架构 | 项目级（入 VCS） | — |

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

---

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

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

快速检查清单

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