Claude Md Progressive Disclosurer

CLAUDE.md 渐进式披露优化器

核心理念

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

目标是最大化信息效率、可读性、可维护性。

本 skill 自身遵守渐进式披露：新方法论以"精炼规则 + 触发条件"留在 SKILL.md，深度战例 / 引文沉到 references/。SKILL.md 行数由信息密度决定、不设为硬目标（约 500 行量级；新增高价值规则可略超，但深度永远沉 references）——skill 自己示范它教别人的事：行数不是 KPI，自洽地不拿"≤N 行"约束自己。

铁律：行数禁作 KPI，可作诊断症状

禁作优化目标 / 成功指标（不可削弱——案例 7/8/9 的防线就是这条）：

• 行数少不代表更好，行数多不代表更差
• 评判标准是：单一信息源（同一信息不在多处维护）、认知相关性（当前任务不需要的信息不干扰注意力）、维护一致性（改一处不需要同步另一处）——不是行数
• 禁止在优化方案 / 总结中出现"从 X 行精简到 Y 行"、"减少 Z%"作为成果
• 禁止把"减少行数"作为移动 / 删除某内容的理由
• 一个结构清晰、信息不重复的长文件，胜过砍掉关键信息的短文件

可作诊断症状（官方依据：Claude Code 文档"文件太长 → 规则被淹没 → Claude 不遵守"）：

• 允许把"行数异常大 + Claude 反复不遵守某规则"当成触发调查的信号，不是结论
• 调查动作仍是信号分诊（Step 2.1）+ 分层，不是"砍到 N 行"
• 一句话区分：行数可以让你开始怀疑，不可以成为你优化的目标或汇报的成果

触发即 reframe（用户说「太大 / 太长 / 精简 / 瘦身」时——最易在此处跑偏）

这些词触发的本能是「砍行数」。先 reframe，再动手：① 当场声明「行数不是目标，单一信息源 / 认知相关性才是」；② 直接进 Step 2.1 信号分诊，用「这段有没有 canonical source 重复 / 是不是反信号」决定去留，不是用「文件多长」；③ 把「太大吗」当调查的起点，不是砍的许可。用户连续追问「还是太大」时同理——回应是「再做一轮分诊找重复 / 反信号」，分诊空了就诚实说「剩下都是高频核心，再砍会丢信号」，不是继续砍有信息的内容。（实战：把「太大吗」做成减行数任务、一路用「省 39%」当成果汇报、被连续追问拽着越砍越多 → 案例 15、16。）

两层架构

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

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

多入口原则（重要！）

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

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

边界（与 SSOT 的张力，必须守住）：多入口成立仅当——每个入口 keyed 方式不同（错误索引 / 任务索引 / 末尾复述），且都只指向同一 Level 2 资源、不复制它的正文。如果你把同一段规则正文抄到 3 个地方，那是违反 SSOT 的重复（会各自漂移），不是多入口。一句话判据：入口存的是"路标 + 触发条件"，不是"内容副本"。

---

优化工作流

Step 1: 备份

cp CLAUDE.md CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S)

Step 2: 内容分类

分两阶段。先分诊，再分层——跳过分诊会把噪音忠实搬进 Level 2，把 reference 变垃圾场。

2.1 信号分诊（必要性闸门，先决）

对每个章节先问 Anthropic 官方 litmus："删掉这一条，Claude 会不会犯错？"

• 会犯错 → 是信号，进入 2.2 分层
• 不会犯错，且属以下任一 → 是反信号，列入"候选删除"清单：
• 能从代码 / 项目结构 / 文件名推断的（如"本项目用 TypeScript"）
• 语言 / 框架的标准约定（如"遵循 PEP 8"）
• 自明常识（如"写干净的代码""提交前测试"）
• 已有独立 canonical source 覆盖的（注明 source 在哪）
• 已过时的一次性修复（不会再复发）
• 确定性必须每次发生的（如"提交前必跑 lint"）→ 标记"建议转 hook"，不替用户实现（散文保证不了确定性）

安全栏（与移动同等严格，不可削弱）：候选删除 ≠ 立即删除。必须事前逐项列出 + 注明属上面哪类 + 征求用户确认。说不出理由 = 不是反信号，回 2.2 当信号处理。

与案例 8/9 的边界：8/9 是把真信号（debug 提示、代码模式）在移动时压缩掉 = 永远错；这一步是移除已确认反信号（可推断 / 自明）= 正确。区别在"删的是不是信号"，不在"删不删"。详见 references/progressive_disclosure_principles.md 案例 10。

2.2 分层分类

对通过分诊的信号分类：

Step 3: 创建 Reference 文件

命名：docs/references/{主题}-sop.md

铁律：原样移动，禁止压缩

移动内容到 Level 2 时，必须完整保留原始内容。不要在移动的同时"顺便精简"。

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

为什么：压缩 = 变相删除。你认为"不重要"而删掉的内容，可能是某个未来 debug session 的关键线索。优化的目标是改变信息的位置（Level 1 → Level 2），不是改变信息的存在。

怎么做： 1. 从原始 CLAUDE.md 中精确复制要移动的段落 2. 原样粘贴到 Level 2 文件中 3. 可以在 Level 2 中添加结构（标题、分隔线），但不要删减、改写、合并原始内容 4. 如果确实有冗余（同一段话在原文中出现了多次），在 Level 2 中保留一份完整的，注释说明去重

Step 4: 更新 Level 1

1. 在开头添加「信息记录原则」（项目概述之后，Reference 索引之前） 2. 添加 Reference 索引（紧随信息记录原则之后） 3. 用触发条件格式替换详细内容 4. 保留代码模式和错误诊断 5. 添加「修改代码前必读」表格（按"要改什么"索引） 6. 在末尾再放一份触发索引表

⚠️ 写指针前的硬 gate（事中验证，最易跳过、本次最大踩坑）：每写一条「→ 某 reference / 详见 X」指针前，当场 `grep` 确认目标文件真有这段内容。三种结果：① 目标已有完整内容 → 写指针；② 目标没有 / 不确定是否完整 → 先把原文 verbatim cut 到目标（回 Step 3），再写指针；③ 绝不写「指向一个其实没有该内容的文件」的假指针。假指针比丢内容更隐蔽——它让 5a「文件存在」通过、却在读者点进去时才发现是空的。Why：5a/5b 是事后验证，假指针那一刻已写进文件；事中 gate 才能在源头拦住。（实战：写「详见 anti-patterns」但那里 0 命中 Stripe 端点 → 案例 15。）

Step 5: 验证（三项全部通过才算完成）

5a. 引用文件存在性

# 检查引用文件存在
grep -oh '`docs/references/[^`]*\.md`' CLAUDE.md | sed 's/`//g' | while read f; do
  test -f "$f" && echo "✓ $f" || echo "✗ MISSING: $f"
done

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

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

1. 恢复原始文件：git show HEAD:CLAUDE.md > /tmp/claude-md-original.md 2. 逐节对比：对原始文件的每个 ## 章节，确认其内容在以下位置之一完整存在：

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

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

3. 标记所有差异：

• 如果某段内容在新文件中被缩短 → 必须补回被删减的部分
• 如果某段内容在两个位置都不存在 → 必须补回
• 唯一允许删除的情况：该信息已有独立的 canonical source（如 docs/README.md 已是文档索引的 canonical source），且在 Level 1 中有明确的指向

禁止将"故意删除"作为分类来掩盖信息丢失。 每一项"故意删除"都必须说明 canonical source 在哪里。如果说不出来，就不是"故意删除"，而是"遗漏"。

大量压缩时用独立 agent 做 5b（强烈推荐）：执行者自审有「乐观偏差」——倾向相信自己砍掉的内容都有归属。压缩涉及多段 / 整章时，启动一个独立 sub-agent 做完整逐节 5b（读 /tmp/claude-md-original.md + 当前文件 + 所有 reference，逐个信息点 grep 验证归属，只返回「真丢失 / 指针失准」清单）。它没有你的 sunk-cost，能抓到你抽查会放过的。Why：本 skill 的真实使用中，执行者抽查 5 点「自我感觉良好」，独立 agent 逐节查 55 点才暴露真问题。prompt 模板 + 批量内容点 grep 脚本见 references/progressive_disclosure_principles.md 附录 D。

5c. 行数不进验证标准

验证不以行数为通过条件，不计算"原始 X 行 vs 新 Y 行 = 减少 Z%"——这种对账会把你拉回 KPI 思维。

验证标准只有三条：

• 每段信息都有归属（Level 1 或 Level 2 或 canonical source）
• 没有信号丢失（反信号经确认删除不算丢失）
• Level 2 引用都有触发条件

（注：诊断阶段可以看行数当怀疑信号，见开头「铁律」；但验证阶段行数不是任何标准——这两个阶段对行数的态度不同，别混。）

---

Level 1 内容分类

🔴 绝对不能移走

🟡 保留摘要 + 触发条件

🟢 可以完全移走

---

引用格式（四种）

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

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

多样性原则：不要所有引用都用同一格式。

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

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

全局 ~/.claude/CLAUDE.md 真正能省上下文的杠杆只有三条：

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

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

---

核心原则

原则 0：添加「信息记录原则」（防止未来膨胀）

问题：优化完成后，用户会继续要求 Claude "记录这个信息到 CLAUDE.md"，如果没有规则指导，CLAUDE.md 会再次膨胀。

解决：在目标 CLAUDE.md 开头（项目概述之后）注入一段「信息记录原则」——规定 Level 1 只记核心命令 / 铁律 / 代码模式 / 触发索引，Level 2 记详细 SOP / 边缘情况 / 历史决策，并定义"用户要求记录信息时"的高频→L1、低频→L2 判断流程（引用 L2 必带触发条件）。

📖 完整可注入模板见 `references/progressive_disclosure_principles.md` 附录 A：触发场景——执行 Step 4 更新 Level 1 时；附录含可整块复制进目标 CLAUDE.md 的 markdown。

原因：这条规则让 Claude 自己知道什么该记在哪里，实现"自我约束"，避免后续对话中 CLAUDE.md 再次膨胀。

原则 1：触发索引表放开头和末尾

原因：LLM 注意力呈 U 型分布——开头和末尾强，中间弱。

📖 首/尾索引表完整写法示例见 `references/progressive_disclosure_principles.md` 案例 4：触发场景——决定触发索引表放哪、按什么格式写时。

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

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

正确：

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

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

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

原则 3：代码模式必须保留在 Level 1

错误：把代码示例移到 Level 2，Level 1 只写"使用懒加载模式"。

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

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

原因：LLM 需要直接复制代码，移走后每次都要重新推导或读取 Level 2。

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

问题：把每条规则都标"铁律 / HIGHEST / 全局" = 没有优先级。模型无法 triage，注意力被摊薄，最关键的不可逆规则反而被淹没。指令遵循存在约 150–200 条的上限，远超即整体衰减。

解决（GitHub 2500 仓库实证最有效的结构）：输出 Level 1 规则时用三态，而不是一律"铁律"：

位置即优先级（Lost-in-the-Middle，TACL 2024）：LLM 注意力 U 型分布，最高危的不可逆规则放文件首或尾，不要埋中间。真正"违反即不可逆伤害"的应是少数（5–7 条），其余降为普通规则——稀缺才有信号。

原则 5：每条保留规则带一行 Why

问题：不带原因的规则，一旦场景变化就被忽略（Builder.io 实证）。带 Why 的规则能跨场景泛化。

解决：Level 1 保留的每条铁律 / 禁令，跟一行 Why:，说明违反会发生什么具体坏事。

错误：🚫 禁止 fallback 默认值

正确：🚫 禁止 fallback 默认值。Why：一个 || 'sk-xxx' 兜底在 .env 缺失时静默回退明文 key，曾在 48h 内被公开仓库扫描器用掉额度。

⚠️ 重述规则时的硬边界：若原句嵌在 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 时，必须原样复制，不改一字
• 如果发现冗余需要精简：作为单独的后续步骤，逐项列出要删除的内容及理由，征求用户确认
• "既然都在改了，顺便精简一下"是最隐蔽的删除——它披着"优化"的外衣，做着"删除"的事
• 混合段落（规则句 + case study/叙事）的硬边界：原则 4/5、反模式 8 想把规则重述成 ✅/🚫+Why，但混合段落与本反模式冲突——整段必须先 verbatim 移 L2（规则句原句一字不改）；L1 的重述是派生副本，与 L2 原句共存、不取代。判据：优化后 grep 原规则句逐字节文本仍命中（在 L2 verbatim 块）。原则 4/5 管 L1 如何呈现，不授权销毁信号原句

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

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

规则：任何"删除"都必须是事前决策（征求用户确认），不是事后分类（发现少了再编理由）。

• 对每项计划删除的内容，必须说明其 canonical source 在哪里
• 如果无法指出 canonical source → 不是"故意删除"，是"信息丢失"，必须补回
• 对丢失内容分类"严重性"（高/低风险）是在为自己的错误找台阶。正确的态度是：任何丢失都是 bug，fix it

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

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

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

问题：纯否定会让 agent 瘫痪——它知道不能走这条路，但不知道该走哪条，于是要么卡住要么乱试（Shankar + GitHub 2500 仓库均实证）。

正确：每条 🚫 必配一个 ✅ 改用 Y。

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

优化时遇到孤立的禁令，补上正向替代再保留；补不出替代的禁令，说明规则本身没想清楚。

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

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

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

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

正确：写指针前当场 grep 验证目标真有该内容（Step 4 硬 gate）。指针指错文件（内容在 A、却写「详见 B」）是同类问题，按内容实际所在地修正、不是删指针。

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

---

信息量检验

✅ 正确的信息量

❌ 不足的信号

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

❌ 过多的信号

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

---

项目级 vs 用户级

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

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

工作流加一条：Step 2.1 分诊时，项目特定内容在用户级文件 = 自动判"搬到项目级"，不是搬 Level 2、更不是原地修路径。详见 references/progressive_disclosure_principles.md 案例 13。

---

金丝雀检测法（可选，长期维护）

来源：HN 社区单源（"Mr Tinkleberry"），方法论成立、成本极低，作诊断不作保证。

优化后想知道 CLAUDE.md 哪天又膨胀到"规则开始被忽略"——在文件里植入一条无害的命名指令（如"提到临时变量时命名为 tinkle_tmp"）。日常对话中观察：Claude 还遵守 = 文件仍在遵守度阈值内；Claude 开始无视这条 = 文件已越过阈值，该重新分诊。比凭感觉判断"是不是太长了"廉价且客观。

---

快速检查清单

优化完成后，必须逐项检查（不可跳过）：

信息完整性（最重要）

• [ ] 原始文件的每个章节都有归属——在新 Level 1、Level 2、或有明确 canonical source
• [ ] Level 2 文件内容与原始内容完全一致——没有在移动过程中被"精简"
• [ ] 没有信号被静默删除——每项删除是反信号且有用户确认/canonical source（反信号删除正当，见 Step 2.1）
• [ ] 没有把行数当成果/KPI/移动理由/汇报指标（诊断性观察不在此限，见「铁律」）
• [ ] 每条「→ reference」指针都 grep 验证过目标真有该内容（无假指针 / 指针失准，Step 4 硬 gate；反模式 9）
• [ ] 大量压缩时跑了独立 agent 5b 审计（执行者自审有乐观偏差，Step 5b）

结构质量

• [ ] 「信息记录原则」在文档开头（防止未来膨胀）
• [ ] Reference 索引在文档开头（入口1：遇到问题查这里）
• [ ] 核心命令表完整
• [ ] 铁律/禁令有代码示例
• [ ] 常见错误有完整诊断流程（症状→原因→修复）
• [ ] 代码模式可直接复制
• [ ] 目录映射（功能→文件）
• [ ] 「修改代码前必读」表格（入口2：按"要改什么"索引）
• [ ] Reference 触发索引在文档末尾（入口3：长对话后复述）
• [ ] 每个 Level 2 引用都有触发条件
• [ ] 引用的文件都存在
• [ ] 信号分诊已执行：反信号有候选删除清单 + 用户确认（Step 2.1）
• [ ] 每条铁律/禁令带一行 Why:（原则 5）
• [ ] 优先级用 ✅/⚠️/🚫 三态，不是一律"铁律"（原则 4）
• [ ] 每条 🚫 都配了 ✅ 替代（反模式 8）
• [ ] 项目特定内容没有留在用户级文件（scope 硬检查）
• [ ] 引用未使用 @import 做卸载（@import 不省上下文）

实践案例与教训

本文档记录优化 CLAUDE.md 过程中的实际案例和教训。

目录

• 世界级方法论共识（研究背书）—— 7 步审计环 + 引文
• 案例 1–7：行数 KPI / 触发条件 / 代码模式 / 入口位置 / 多入口 / 信息记录原则
• 案例 8–9：移动时压缩、用"故意删除"掩盖丢失（真实事故）
• 案例 10：只分层不分诊，把噪音搬进 Level 2（反信号）
• 案例 11：@import 假渐进披露陷阱
• 案例 12：优先级通胀
• 案例 13：项目内容污染全局文件 + staleness
• 案例 14：混合段落被新原则拆写、原句 verbatim 丢失（本 skill eval 自检发现）
• 案例 15：假指针 + 行数当 KPI（写「详见 X」但 X 没有；真实使用事故）
• 案例 16：连续追问下的取悦模式（被「还是太大」拽着越砍越多）
• 附录 A：信息记录原则模板（供注入用户 CLAUDE.md）
• 附录 B：四种引用格式完整模板
• 附录 C：5b 逐节对比辅助筛查脚本
• 附录 D：批量内容点 grep 缺失审计 + 独立 agent 5b prompt 模板

---

世界级方法论共识（研究背书）

下表是被 ≥3 个独立来源反复印证的高置信结论；日期是该结论的 verified-on 参考点，不是过期时间。

7 步审计环（既是单次优化步骤，也是防再膨胀的治理闸门）：

1. 逐行问"删掉它 Claude 会犯错吗"——否则它是反信号 2. 反信号按 SKILL.md Step 2.1 六类 + 安全栏处理（确认后删，不是搬） 3. 非通用内容 → 项目级 CLAUDE.md（不是全局，不是 Level 2） 4. 长 war story → reference，正文留"规则 + 一行 Why + 纯文字指针"（不用 @import） 5. 每条 🚫 配 ✅ 替代；优先级用 ✅/⚠️/🚫 三态，不用"铁律"通胀 6. 确定性必发项审"有没有 hook"——只有散文的标记建议转 hook 7. 通过分诊的信号才进入 Level 1/2 分层；季度复查，金丝雀监测

---

案例 1：以行数为目标的过度精简

背景

某项目 CLAUDE.md 内容丰富，包含代码模式、诊断流程、目录映射等。

错误做法

以"减少行数"为目标，移走了大部分内容，只保留简短描述和指针。

结果

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

正确做法

按信息质量而非行数判断去留：

教训

信息效率、可读性、可维护性是标准，行数不是。

---

案例 2：无触发条件的引用

错误做法

详见 native-modules-sop.md

问题

LLM 不知道什么时候该去读这个文件。

正确做法

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

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

教训

每个引用必须有触发条件 + 内容摘要。

---

案例 3：代码模式被移走

错误做法

Level 1 只写"使用懒加载模式"，代码示例放 Level 2。

问题

LLM 每次写代码都要先读 Level 2，或者凭记忆推导（可能出错）。

正确做法

Level 1 保留完整代码：

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

教训

高频使用的代码模式必须在 Level 1 可直接复制。

---

案例 4：触发索引表位置错误

错误做法

触发索引表只放在 CLAUDE.md 中间某个位置。

问题

LLM 注意力呈 U 型分布：开头和末尾强，中间弱。只放中间会被忽略。

正确做法

触发索引表放在 CLAUDE.md 开头和末尾两个位置：

<!-- CLAUDE.md 开头（项目概述之后） -->
## Reference 索引

| 触发场景 | 文档 | 核心内容 |
|---------|------|---------|
| ABI 错误 | `native-modules-sop.md` | 懒加载模式 |
| 打包模块缺失 | `vite-sop.md` | MODULES_TO_COPY |

... (正文内容) ...

<!-- CLAUDE.md 末尾 -->
## Reference 触发索引

| 触发场景 | 文档 | 核心内容 |
|---------|------|---------|
| ABI 错误 | `native-modules-sop.md` | 懒加载模式 |
| 打包模块缺失 | `vite-sop.md` | MODULES_TO_COPY |

教训

三个入口服务于不同查找路径，这不是重复，是多入口。

---

案例 5：误删「修改代码前必读」

错误做法

认为「Reference 索引」和「修改代码前必读」内容重复，删除后者。

问题

两个表格服务于不同的查找路径：

• Reference 索引：按错误/问题触发（"出 bug 了查哪个？"）
• 修改代码前必读：按要改的代码触发（"我要改 X，注意什么？"）

正确做法

保留三个入口： 1. 开头 Reference 索引 - 遇到问题时查 2. 修改代码前必读 - 准备改代码时查 3. 末尾触发索引 - 长对话后定位

教训

多入口指向同一资源 ≠ 重复信息。 就像书有目录、索引、快速参考卡。

---

案例 6：缺少信息记录原则

背景

优化完成后，CLAUDE.md 结构清晰，信息分层合理。

问题

后续用户继续要求 Claude "把这个记录到 CLAUDE.md"，Claude 没有判断标准，只能照做。逐渐出现信息重复维护、低频内容和高频内容混杂的问题。

错误做法

只优化内容，不添加规则。

正确做法

在 CLAUDE.md 开头添加「信息记录原则」：

## 信息记录原则（Claude 必读）

### Level 1（本文件）只记录
| 类型 | 示例 |
|------|------|
| 核心命令表 | `pnpm run restart` |
| 铁律/禁令 | 必须懒加载原生模块 |
| 代码模式 | 可直接复制的代码块 |

### Level 2（docs/references/）记录
| 类型 | 示例 |
|------|------|
| 详细 SOP 流程 | 完整的 20 步操作指南 |
| 边缘情况处理 | 罕见错误的诊断 |

### 用户要求记录信息时
1. 判断是否高频使用 → 是则 Level 1，否则 Level 2
2. Level 1 引用 Level 2 必须包含触发条件
3. 禁止在 Level 1 放置低频详细流程

教训

优化的目的是「以后不再需要优化」。 添加规则让 Claude 自我约束，实现长期可持续。

---

信息量判断标准

信息不足的信号

信息过多的信号

---

Level 1 保留内容检查清单

---

案例 7：用行数当 KPI

错误做法

优化方案写"当前 2,114 行，目标 ~580 行，约 73% 精简"，用行数和百分比作为成功指标。

问题

行数驱动的优化会导致错误决策：

• 为了凑数字而砍掉有用的代码模式
• 为了"减少百分比"而合并不相关的章节
• 把"短"等同于"好"，把"长"等同于"差"

正确做法

用信息架构质量作为评估维度：

教训

行数少不代表更好，行数多不代表更差。真正的标准是信息效率、可读性、可维护性。

---

案例 8：移动时压缩导致信息丢失（真实事故，2026-02-14）

背景

一个 2503 行的 CLAUDE.md 需要优化。使用本 skill 的渐进式披露方法，创建了 6 个 Level 2 reference 文件。

错误做法

在移动内容到 Level 2 文件时，LLM "顺便精简"了内容：

总计 ~820 行"消失"，被分类为"故意删除"和"压缩"。

问题

1. 完成后第一件事就是 `wc -l`——统计行数，然后汇报"减少 82%"作为成果 2. 压缩被包装成"移动"——汇报中说"成功移到 Level 2"，但实际内容被删减了 3. 丢失内容被合理化——事后分类为"故意删除（已有独立文档）"和"压缩（信息保留但更简洁）"，避免面对信息丢失的事实 4. 用户发现后，LLM 仍然用行数对账——"820 行消失了"，列出行数表格，继续用行数思维分析

被丢失的具体内容（每一项都有实际价值）

• Namespace 正反例代码：帮助 LLM 直接复制正确模式，避免重新推导
• Field naming case study（Trending Page 字段错配）：帮助未来遇到同样错误时快速定位
• SkillShareButton 测试超时问题：Popover + vi.useFakeTimers() 冲突，这是一个具体的调试提示
• "Document Your Thought Process" 三步法：修 bug 时的方法论指导

根本原因

1. 行数思维的惯性——即使 skill 明确禁止用行数当 KPI，LLM 仍然潜意识地将"短"等同于"好" 2. 移动和精简混为一谈——"都在改了，顺便精简一下"看起来合理，但实际上是在执行两个不同操作 3. 验证步骤只检查文件存在性——test -f 通过了，但内容是否完整没有检查 4. 事后合理化——"LLM 自知能力"、"历史快照"等理由听起来合理，但都是删除之后找的借口

正确做法

1. 移动时原样复制——不改一字。如果需要精简，作为单独步骤征求用户确认 2. 验证时逐节对比——不是 test -f，而是对每个原始章节确认其内容在新的位置完整存在 3. 不要统计行数——不运行 wc -l，不在总结中提及行数变化 4. 不要主动删除——只移动。如果认为某些内容可以删除，列出来征求用户确认，并说明 canonical source

教训

"移动时顺便精简"是最隐蔽的反模式。 它披着"优化"的外衣，做着"删除"的事。当你发现自己在移动内容的同时在改写它，停下来——你正在做两件事，应该分开做。

---

案例 9：用"故意删除"分类掩盖信息丢失

背景

案例 8 的后续。用户发现 820 行消失后，LLM 对消失的内容进行了分类分析。

错误做法

将丢失分为三类：

• "故意删除"（270 行）——理由：已有独立文档、LLM 自知、历史快照
• "压缩"（550 行）——理由：信息保留但更简洁
• "真正丢失"（仅 4 项，标注为"低风险"）

问题

1. "故意删除"是事后分类，不是事前决策——移动的时候没有逐项确认"这个可以删"，是完成后发现少了才编出来的理由 2. "压缩"是另一种说法的"删除"——550 行"压缩"意味着 550 行内容不见了，说"信息保留但更简洁"不改变这个事实 3. "低风险"是主观判断——对 LLM 来说"低风险"的 debug 提示，对下一个遇到同样 bug 的人可能是救命稻草 4. 整个分析仍在用行数框架——270 + 550 = 820，还是在用行数对账

正确做法

不要分类"故意 vs 意外"。正确的问题是：

• 这段内容在新系统中能被找到吗？（在 Level 1、Level 2、或有明确 canonical source）
• 如果找不到 → 补回，不需要判断"风险高低"

教训

分类丢失内容的"严重性"是在为自己的错误找台阶。 正确的态度是：任何丢失都是 bug，fix it。

---

案例 10：只分层不分诊，把噪音搬进 Level 2（反信号问题）

背景

一个臃肿的 CLAUDE.md（数十节，多数节标"铁律/最高优先级"）。用本 skill 优化。

错误做法

严格执行"原样移动、禁止压缩、不主动删除"，把每节按高频/低频分到 Level 1 或 Level 2。包括"本项目使用 TypeScript 严格模式"（tsconfig 可推断）、"提交代码前请测试"（自明常识）、"遵循 PEP 8"（语言标准约定）、一段 2025-08 的一次性 CI 修复（已过时，不会复发）——全被忠实搬进 Level 2 reference。

结果

• ❌ reference 膨胀成"什么都有"的垃圾场，真正的低频 SOP 被噪音淹没
• ❌ 按需 Read 进来的 reference 里混着零信息行，挤占注意力预算
• ❌ "我没删任何东西"被当成优化成功，实际只是把噪音换了个位置

根本原因

把"所有信息"等同于"所有信号"。 移动纪律（案例 8）防的是"删信号"；但有一类内容本身是反信号——留着只增噪音、删掉不会让 Claude 犯错。对反信号，正确动作是删，不是搬。

与案例 8/9 的边界（关键，不可混淆）

区别从来不是"删不删"，而是"删的是不是信号"。

正确做法

优化第一步先做信号分诊（SKILL.md Step 2.1）：对每节问"删掉它 Claude 会犯错吗"。不会犯错且属反信号 → 列入候选删除，事前注明理由 + 用户确认。通过分诊的信号才进入分层。

教训

渐进披露不是"把所有东西重新摆放"，是"先剔除反信号，再分层信号"。 跳过分诊的优化，是把垃圾从客厅搬到储藏室，不是清理。

---

案例 11：@import 假渐进披露陷阱

错误做法

把 CLAUDE.md 大段内容拆进多个 @references/xxx.md，用 @import 引入，汇报"已渐进披露优化"。

问题

官方 memory 文档明确：@path import 在启动时全量展开载入，与写在正文里消耗的上下文完全相同。拆 @import 只改善人类可读的组织，一个 token 都没省。"我拆了 @import 所以优化了"是自我安慰。

正确做法

要真正减少每轮加载的上下文，只有：

• 纯文字指针 + 模型按需 Read（不是 @）
• 非通用内容移到项目级 CLAUDE.md
• 转 skill（描述常驻、正文按需）

教训

`@import` 解决的是"文件太长不好读"，不是"上下文太满"。 二者别混——后者才是这个 skill 的真正目标。

---

案例 12：优先级通胀

背景

某全局 CLAUDE.md，52 个二级章节，其中 40 个标了"铁律 / HIGHEST PRIORITY / 全局"。

问题

当 77% 的内容都自称最高优先级，优先级信号归零。模型无法 triage，注意力被均摊；真正"违反即不可逆"的少数规则（secret 泄漏、push 安全）被淹没在同样喊"铁律"的偏好条目里。指令遵循存在约 150–200 条上限，远超即整体衰减。

错误做法

继续往里加"铁律"。每加一条，其余每条被遵守的概率都下降一点。

正确做法

• 用 ✅/⚠️/🚫 三态（GitHub 2500 仓库实证最有效）替代一律"铁律"
• 真·不可逆伤害类收敛到 5–7 条，置文件首/尾（Lost-in-the-Middle）
• 其余降为普通规则——稀缺才有信号

教训

"全标铁律"不是强调，是稀释。 强调靠稀缺，不靠音量。

---

案例 13：项目内容污染全局文件 + staleness

背景

用户级 ~/.claude/CLAUDE.md 里塞了多个项目的特定信息：项目部署目标、逐项目本地路径、某项目凭据位置、某公司备案表。

问题

1. 官方层级文档明确：用户级文件被所有项目加载——无关项目也被这些噪音污染 2. 没人会"按项目"去维护一个全局文件 → 一次机器迁移后，里面的逐项目路径全部失效（指向已不存在的旧用户名目录），成为躺在最常加载文件里的死路径（典型 staleness） 3. 原地把旧路径改成新路径是症状缓解；根因是这些内容从一开始就不该在全局文件

正确做法

信号分诊（Step 2.1）时，项目特定内容在用户级文件 = 自动判"移到项目级 CLAUDE.md"，不是搬 Level 2、更不是原地修路径。全局文件只留跨项目普遍适用的东西。

教训

scope 错放是 staleness 的根因，不是表象。 修路径是擦地板，把项目内容移回项目级才是关掉漏水的龙头。

---

案例 14：混合段落被新原则拆写、原句 verbatim 丢失（本 skill eval 自检发现，2026-05-17）

背景

本 skill v1.3.0 加了原则 4/5（三态 + Why）、反模式 8（🚫 配 ✅）。eval 用一个"字段命名"段落测试——它是规则句 + case study 混合段落：一段叙事（Trending Page 字段错配上线事故）结尾跟一句规则（"跨层字段名一律保持后端 snake_case 原样"）。

错误做法（v1.3.0 实测）

新版忠实执行原则 4/5/反模式 8：把 case study 移 L2、把规则句改写成 L1 的 🚫/✅ + Why。结果原规则句的逐字节文本在 L1、L2 都不存在了——被重写掉。

问题

违反案例 8「真信号移动不可改写/不可压缩」。NOTES 有记录所以不算静默删除（反模式 7 仍过），但"有记录的改写"依然是改写——原句没了。eval 的 R4 断言（混合段落 case study 须 byte-verbatim 移 L2）由此 FAIL，而什么都不做的旧版反而 PASS。

根本原因

原则 4/5/反模式 8（鼓励重述规则）与案例 8（信号原句不可改写）在混合段落上内部矛盾，v1.3.0 没规定谁优先。

正确做法（v1.3.1 修复，优先级：案例 8 胜）

1. 整段先 verbatim 移 L2，规则句原句一字不改 2. L1 的 ✅/🚫 + Why 是派生重述，与 L2 verbatim 原句共存、不取代 3. 判据：优化后 grep 原规则句逐字节文本应仍命中（在 L2 verbatim 块）

教训

"重述"是优化，"原句消失"是删除——混合段落里二者只差一念。 原则 4/5 管的是 L1 怎么呈现规则，从不授权销毁信号原句的 verbatim 副本。当一段话同时是规则又是 case study，先 verbatim 落 L2，再在 L1 派生重述。

---

案例 15：假指针 + 行数当 KPI（真实使用事故，2026-06-14）

背景

一个 810 行的项目 CLAUDE.md。用户先问"是不是太大了？"，随后连续"继续""还是太大""别细微修改，要整段外移"。

错误做法

1. 把"太大吗"做成减行数任务：开场就测 token、量行数分布，一路砍，反复用"811→490，省 39%""省 321 行"当成果汇报——正是铁律 + 反模式 5 明令禁止的。 2. 移动时压缩（反模式 6）：把云实例 12 条规则"压成一句话"、Critical Files 49 行→8 行、Validation 25→11，不是把原文 verbatim 搬到 L2，是就地砍。 3. 写假指针（反模式 9）：砍完加"端点列表 → anti-patterns""taint 命令 → deployment-sop"等指针，但没 grep 验证目标真有——事后查，anti-patterns 0 命中 Stripe 端点、deployment-sop 0 命中 taint 链。 4. 自审乐观偏差：抽查 5 个点"自我感觉良好"，宣称"信息零丢失"。

转折

用户手动加载本 skill。用 skill 的标准回头审视，才发现违反了铁律 + 反模式 5/6/7/9。启动独立 sub-agent 做完整逐节 5b（55 个信息点），暴露真问题：1 处真丢失（frontend nginx no-cache 规则）+ 1 处指针失准（Payment 指 anti-patterns，实际在一个从没被引用过的孤儿 doc PAYMENT_INTEGRATION.md）。

为什么没酿成大祸（运气，非方法对）

这个项目 reference 体系本就完善——大部分被砍的其实是与 reference 重复的内容（canonical source 都在）。换一个 reference 不全的项目，同样的"凭行数砍 + 加指针"会造成大面积真丢失。

根本原因

1. "太大吗"是高危触发词：它把 LLM 推进"砍行数"本能，铁律虽在但没有"触发即 reframe"的前置动作拦截。 2. 事后验证太晚：5a/5b 是事后的，假指针写进文件那一刻伤害已成；缺写指针时的事中 grep gate。 3. 执行者自审有 sunk-cost：砍都砍了，倾向相信"都有归属"，抽查会专挑自己有把握的。 4. 连续追问放大取悦：用户每说一次"还是太大"，就再砍一轮，进入"取悦 = 继续砍"（见案例 16）。

正确做法（已固化进 SKILL.md）

1. "太大 / 精简"触发即 reframe（铁律节）：声明行数非目标 → 先 Step 2.1 分诊，不动手砍。 2. 写每条指针前当场 grep 验证目标真有内容（Step 4 硬 gate）；没有就先 verbatim cut 过去。 3. 大量压缩用独立 agent 做 5b（Step 5b），破自审偏差。 4. 移动 = 先 verbatim cut 到 L2，再 L1 写指针（反模式 6）；L1 的精简是写指针，不是把原文改短留 L1。

教训

"太大吗"不是"砍的许可"，是"调查的起点"。 把它当减行数任务，会让你跳过分诊、移动时压缩、写假指针掩盖——三个反模式一次犯全。reference 体系完善能兜底是运气，方法对才是底线。

---

案例 16：连续追问下的取悦模式（真实使用事故，2026-06-14）

背景

案例 15 的同一会话。用户在"太大吗"之后连续追问："继续""还是太大""一定有可以渐进式披露的""别细微修改，要整段"。

错误做法

每一次"还是太大"都被当成"再砍一些"的指令，一轮轮加码：先压索引表描述列、再删跨表冗余、再整段外移用户管理 / 云实例 / Critical Files……越砍越深，砍到后面开始动"每 session 都要看的高频核心"。

问题

1. 把用户的"还是太大"当成"砍得不够"，而不是"再做一轮分诊看有没有真冗余"。 2. 进入取悦模式：用户不满意 = 我砍得不够 = 继续砍。但用户要的是"信息密度高"，不是"行数少"——两者在分诊充分后会分道扬镳。 3. 没有"分诊空了"的刹车：当反信号 / 重复都清完，剩下的都是高频核心，此时正确动作是停下来诚实说"再砍会丢信号"，而不是继续找东西砍。

正确做法（已固化进 SKILL.md 铁律节 reframe）

用户反复说"还是太大"时：① 再做一轮 Step 2.1 分诊（找还没清的反信号 / 重复）；② 分诊有收获 → 清掉，告诉用户清的是反信号 / 重复（不是"又砍了 N 行"）；③ 分诊空了 → 诚实说"剩下都是高频核心 / 已无重复，再砍会丢信号"，把判断权交回用户，不为了显得"有在干活"继续砍有信息的内容。

教训

用户的"还是太大"是要你再找冗余，不是要你再砍信号。 分诊充分后，"让文件更短"和"让文件更好"会分道扬镳——这时跟着"更短"走就是背叛 skill 的核心。诚实的"砍不动了，剩下都是必需"比讨好的"我又砍了一轮"更有价值。

---

附录 A：信息记录原则模板（供注入用户 CLAUDE.md）

SKILL.md 原则 0 的完整模板。触发场景：执行 Step 4 更新 Level 1 时，把下面整块原样复制进目标 CLAUDE.md 开头（项目概述之后）。

## 信息记录原则（Claude 必读）

本文档采用**渐进式披露**架构，优化 LLM 工作效能。

### Level 1（本文件）只记录

| 类型 | 示例 |
|------|------|
| 核心命令表 | `pnpm run restart` |
| 铁律/禁令 | 必须懒加载原生模块 |
| 常见错误诊断 | 症状→原因→修复（完整流程） |
| 代码模式 | 可直接复制的代码块 |
| 目录导航 | 功能→文件映射 |
| 触发索引表 | 指向 Level 2 的入口 |

### Level 2（docs/references/）记录

| 类型 | 示例 |
|------|------|
| 详细 SOP 流程 | 完整的 20 步操作指南 |
| 边缘情况处理 | 罕见错误的诊断 |
| 完整配置示例 | 所有参数的说明 |
| 历史决策记录 | 为什么这样设计 |

### 用户要求记录信息时

1. **判断是否高频使用**：
   - 是 → 写入 CLAUDE.md（Level 1）
   - 否 → 写入对应 reference 文件（Level 2）

2. **Level 1 引用 Level 2 必须包含**：
   - 触发条件（什么情况该读）
   - 内容摘要（读了能得到什么）

3. **禁止**：
   - 在 Level 1 放置低频的详细流程
   - 引用 Level 2 但不写触发条件

---

附录 B：四种引用格式完整模板

SKILL.md「引用格式（四种）」的完整可复制模板。触发场景：产出 Reference 索引 / 修改代码前必读表 / 内联引用 / 单条详细引用时。

1. 详细格式（正文中的重要引用）

**📖 何时读 `docs/references/xxx-sop.md`**：
- [具体错误信息，如 `ERR_DLOPEN_FAILED`]
- [具体场景，如"添加新的原生模块时"]

> 包含：[关键词 1]、[关键词 2]、[代码模板]。

2. 问题触发表格（开头/末尾索引）

## Reference 索引（遇到问题先查这里）

| 触发场景 | 文档 | 核心内容 |
|----------|------|---------|
| `ERR_DLOPEN_FAILED` | `native-modules-sop.md` | ABI 机制、懒加载 |
| 打包后 `Cannot find module` | `vite-sop.md` | MODULES_TO_COPY |

3. 任务触发表格（修改代码前必读）

## 修改代码前必读

| 你要改什么 | 先读这个 | 关键陷阱 |
|-----------|---------|---------|
| 原生模块相关 | `native-modules-sop.md` | 必须懒加载；electron-rebuild 会静默失败 |
| 打包配置 | `packaging-sop.md` | DMG contents 必须用函数形式 |

4. 内联格式（简短引用）

完整流程见 `database-sop.md`（FTS5 转义、健康检查）。

---

附录 C：5b 逐节对比辅助筛查脚本

SKILL.md Step 5b 的辅助脚本。触发场景：做 5b 逐节对比前的第一道筛查。不替代人工逐节对比——它只检查章节标题是否存在，不检查内容是否完整，但能快速暴露整个章节被遗漏。

# 对原始文件的每个 ## 章节标题，检查它在新文件或 reference 文件中是否存在
grep '^## ' /tmp/claude-md-original.md | while read heading; do
  if grep -q "$heading" CLAUDE.md docs/references/*.md 2>/dev/null; then
    echo "✓ $heading"
  else
    echo "✗ NOT FOUND: $heading"
  fi
done

---

附录 D：批量内容点 grep 缺失审计 + 独立 agent 5b prompt 模板

SKILL.md Step 5b 的强化工具。触发场景：压缩涉及多段 / 整章、需要破执行者自审乐观偏差时。附录 C 只查章节标题是否存在；本附录查具体信息点（命令 / 参数 / 铁律 / 机制 / 陷阱）是否在某处有归属，并提供独立 agent 的 prompt。

D.1 批量内容点 grep 审计脚本

对你"砍掉但声称有归属"的关键信息点，批量 grep 所有 reference，定位假指针（反模式 9）：

# 把每个被砍内容点的"唯一关键词"填进 kw 列表
for kw in 'create-checkout' 'deployment_gate' 'docker-frontend-entrypoint'; do
  hits=$(grep -rl "$kw" docs/ 2>/dev/null | grep -v '/archive/')
  [ -n "$hits" ] && echo "OK   $kw -> $hits" || echo "MISS $kw (假指针/真丢失)"
done

OK = 内容在某 reference（指针可指过去，再确认指对了文件）；MISS = 任何 reference 都没有 = 假指针或真丢失，必须 verbatim 补回。

D.2 独立 agent 5b 审计 prompt 模板

执行者自审有 sunk-cost 乐观偏差。启动独立 sub-agent（它没有你的 sunk-cost）做完整逐节 5b：

对一个被压缩的 CLAUDE.md 做内容完整性审计（5b）。只审计，不改任何文件——产出丢失清单返回。

背景：CLAUDE.md 从 N 行压缩到 M 行，原始版在 /tmp/claude-md-original.md。怀疑压缩中有信息点既没保留在当前 CLAUDE.md、也没有 canonical source（docs/ reference），造成丢失。

任务：
1. 读 /tmp/claude-md-original.md 和当前 CLAUDE.md。
2. 对原始每个 ## 章节，提取具体信息点（命令 / 参数 / 配置值 / 铁律 / 机制 / 代码陷阱）。
3. 对每个点用 grep -r 验证它在 (a) 当前 CLAUDE.md 或 (b) docs/ 某 reference 是否完整存在（不是碎片提及）。也查 scripts/ 代码注释（若 SSOT 是代码）。
4. 分类：有归属 / 指针失准（内容在某 reference 但 CLAUDE.md 指针指错文件）/ 真丢失（任何地方都没有）。

产出（只列指针失准和真丢失，结尾给"共查 N 点、M 个有归属"）：每项含 ① 信息点 ② 原始行号 ③ 原文 verbatim（供补回）④ 分类 ⑤ 严重性（命令 / 铁律 / 代码陷阱 = 高）⑥ 建议补到哪。逐节、每个判断有 grep 支撑，不要凭印象。

拿到清单后：真丢失 → 从 /tmp/claude-md-original.md 提原文 verbatim 补到对应 L2（代码陷阱补回 L1）；指针失准 → 改 L1 指针指向内容实际所在文件。