CLAUDE.md 渐进式披露优化器

核心理念

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

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

铁律：禁止用行数作为评价指标

• 行数少不代表更好，行数多不代表更差

• 优化的评判标准是：单一信息源（同一信息不在多处维护）、认知相关性（当前任务不需要的信息不干扰注意力）、维护一致性（改一处不需要同步另一处）

• 禁止在优化方案中出现"从 X 行精简到 Y 行"、"减少 Z%"等表述

• 一个结构清晰、信息不重复的长文件，比一个砍掉关键信息的短文件更好

• 禁止在工作流任何阶段运行 wc -l 或统计行数——这会潜意识地将"行数少"当成目标

• 禁止在完成后的总结中提及行数变化——即使不是主要指标，提及行数也会暗示"行数减少=成功"

两层架构

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

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

多入口原则（重要！）

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

入口 位置 触发场景 用户心态

Reference 索引 开头 遇到错误/问题 "出 bug 了，查哪个文档？"

修改代码前必读 中间 准备改代码 "我要改 X，要注意什么？"

Reference 触发索引 末尾 长对话定位 "刚才说的那个文档是哪个？"

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

优化工作流

Step 1: 备份

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

Step 2: 内容分类

对每个章节分类：

问题 是 否

高频使用？ Level 1 ↓

违反后果严重？ Level 1 ↓

有代码模式需要直接复制？ Level 1 保留模式 ↓

有明确触发条件？ Level 2 + 触发条件 ↓

历史/参考资料？ Level 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），不是改变信息的存在。

怎么做：

• 从原始 CLAUDE.md 中精确复制要移动的段落

• 原样粘贴到 Level 2 文件中

• 可以在 Level 2 中添加结构（标题、分隔线），但不要删减、改写、合并原始内容

• 如果确实有冗余（同一段话在原文中出现了多次），在 Level 2 中保留一份完整的，注释说明去重

Step 4: 更新 Level 1

• 在开头添加「信息记录原则」（项目概述之后，Reference 索引之前）

• 添加 Reference 索引（紧随信息记录原则之后）

• 用触发条件格式替换详细内容

• 保留代码模式和错误诊断

• 添加「修改代码前必读」表格（按"要改什么"索引）

• 在末尾再放一份触发索引表

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 移走的章节，逐一检查：

恢复原始文件：git show HEAD:CLAUDE.md > /tmp/claude-md-original.md

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

• 新 CLAUDE.md 中（保留在 Level 1）

• 某个 Level 2 reference 文件中（完整移动）

快速暴露遗漏的辅助脚本：

对原始文件的每个 ## 章节标题，检查它在新文件或 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

⚠️ 这个脚本不能替代人工逐节对比——它只检查章节标题是否存在，不检查内容是否完整。但它能快速暴露整个章节被遗漏的情况，作为人工对比前的第一道筛查。

标记所有差异：

• 如果某段内容在新文件中被缩短 → 必须补回被删减的部分

• 如果某段内容在两个位置都不存在 → 必须补回

• 唯一允许删除的情况：该信息已有独立的 canonical source（如 docs/README.md 已是文档索引的 canonical source），且在 Level 1 中有明确的指向

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

5c. 禁止行数审计

在验证阶段不要统计行数。不要 wc -l 。不要计算"原始 X 行 vs 新 Y 行"。这些数字会扭曲你的判断。

验证的标准是：

• 每段信息都有归属（Level 1 或 Level 2 或 canonical source）

• 没有信息丢失

• Level 2 引用都有触发条件

Level 1 内容分类

🔴 绝对不能移走

内容类型 原因

核心命令 高频使用

铁律/禁令 违反后果严重，必须始终可见

代码模式 LLM 需要直接复制，避免重新推导

错误诊断 完整的症状→原因→修复流程

目录映射 帮助 LLM 快速定位文件

触发索引表 帮助 LLM 在长对话中定位 Level 2

🟡 保留摘要 + 触发条件

内容类型 Level 1 Level 2

SOP 流程 触发条件 + 关键陷阱 完整步骤

配置示例 最常用的 1-2 个 完整配置

API 文档 常用方法签名 完整参数说明

🟢 可以完全移走

内容类型 原因

历史决策记录 低频访问

性能数据 参考性质

技术债务清单 按需查看

边缘情况 有明确触发条件时再加载

引用格式（四种）

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

📖 何时读 docs/references/xxx-sop.md：

• [具体错误信息，如 ERR_DLOPEN_FAILED]
• [具体场景，如"添加新的原生模块时"]

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

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

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

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

修改代码前必读

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

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

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

四条核心原则

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

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

解决：在 CLAUDE.md 开头（项目概述之后）添加「信息记录原则」：

信息记录原则（Claude 必读）

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

Level 1（本文件）只记录

Level 2（docs/references/）记录

用户要求记录信息时

1. 判断是否高频使用：

   • 是 → 写入 CLAUDE.md（Level 1）
   • 否 → 写入对应 reference 文件（Level 2）

2. Level 1 引用 Level 2 必须包含：

   • 触发条件（什么情况该读）
   • 内容摘要（读了能得到什么）

3. 禁止：

   • 在 Level 1 放置低频的详细流程
   • 引用 Level 2 但不写触发条件

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

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

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

位置 作用

开头 对话开始时建立全局认知："有哪些 Level 2 可用"

末尾 对话变长后复述提醒："现在应该读哪个 Level 2"

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

Reference 索引

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

<!-- CLAUDE.md 末尾（再放一份） -->

Reference 触发索引

原则 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。

反模式警告

⚠️ 反模式 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 时，必须原样复制，不改一字

• 如果发现冗余需要精简：作为单独的后续步骤，逐项列出要删除的内容及理由，征求用户确认

• "既然都在改了，顺便精简一下"是最隐蔽的删除——它披着"优化"的外衣，做着"删除"的事

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

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

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

• 对每项计划删除的内容，必须说明其 canonical source 在哪里

• 如果无法指出 canonical source → 不是"故意删除"，是"信息丢失"，必须补回

• 对丢失内容分类"严重性"（高/低风险）是在为自己的错误找台阶。正确的态度是：任何丢失都是 bug，fix it

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

信息量检验

✅ 正确的信息量

检验项 通过标准

日常命令 不需要读 Level 2

常见错误 有完整诊断流程

代码编写 有可复制的模式

特定问题 知道读哪个 Level 2

触发索引 在文档末尾，表格形式

❌ 不足的信号

• LLM 反复问同样的问题

• LLM 每次重新推导代码模式

• 用户需要反复提醒规则

❌ 过多的信号

• 大段低频详细流程在 Level 1

• 完全相同的内容在多处（注意：多入口指向同一资源 ≠ 重复）

• 边缘情况和常见情况混在一起

项目级 vs 用户级

维度 用户级 项目级

位置 ~/.claude/CLAUDE.md

项目/CLAUDE.md

References ~/.claude/references/

docs/references/

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

快速检查清单

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

信息完整性（最重要）

• 原始文件的每个章节都有归属——在新 Level 1、Level 2、或有明确 canonical source

• Level 2 文件内容与原始内容完全一致——没有在移动过程中被"精简"

• 没有任何内容被静默删除——每项删除都有用户确认或明确的 canonical source

• 没有在任何阶段统计或提及行数变化

结构质量

• 「信息记录原则」在文档开头（防止未来膨胀）

• Reference 索引在文档开头（入口1：遇到问题查这里）

• 核心命令表完整

• 铁律/禁令有代码示例

• 常见错误有完整诊断流程（症状→原因→修复）

• 代码模式可直接复制

• 目录映射（功能→文件）

• 「修改代码前必读」表格（入口2：按"要改什么"索引）

• Reference 触发索引在文档末尾（入口3：长对话后复述）

• 每个 Level 2 引用都有触发条件

• 引用的文件都存在