claude-code-skills-reference/claude-md-progressive-disclosurer/references/progressive_disclosure_principles.md

实践案例与教训

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

---

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

背景

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

错误做法

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

结果

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

正确做法

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

内容	保留位置	判断依据
核心命令表	Level 1	高频使用，不应让 LLM 每次去查
懒加载代码模式	Level 1	需要直接复制，移走会导致重新推导
ABI 错误诊断	Level 1	完整症状→原因→修复流程
详细 SOP	Level 2	低频、有明确触发条件

教训

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

---

案例 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 自我约束，实现长期可持续。

---

信息量判断标准

信息不足的信号

信号	说明
LLM 反复问同样的问题	缺少关键规则
LLM 每次重新推导代码	缺少代码模式
用户反复提醒规则	规则没有足够强调
不知道读哪个 Level 2	触发条件不明确

信息过多的信号

信号	说明
大段低频流程在 Level 1	应移到 Level 2
同一内容重复出现	去重
边缘和常见情况混在一起	边缘移到 Level 2

---

Level 1 保留内容检查清单

内容类型	必须保留	可移走
信息记录原则	✅ 防止膨胀
Reference 索引（开头）	✅ 入口1
核心命令表	✅
铁律/禁令	✅
常见错误诊断（完整流程）	✅
代码模式（可直接复制）	✅
目录映射	✅
修改代码前必读	✅ 入口2
Reference 触发索引（末尾）	✅ 入口3
详细 SOP 步骤		✅
边缘情况处理		✅
历史决策记录		✅
性能数据		✅

---

案例 7：用行数当 KPI

错误做法

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

问题

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

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

正确做法

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

评估维度	问题
单一信息源	这段信息是否在别处已经有了？如果是，消除重复
认知相关性	这段信息在大多数开发场景下是否需要？如果不是，移到 Level 2
维护一致性	改一处是否需要同步另一处？如果是，消除重复

教训

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