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 文件中（完整移动）
快速暴露遗漏的辅助脚本：
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 索引（遇到问题先查这里）
|----------|------|---------|
| `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 转义、健康检查）。
多样性原则：不要所有引用都用同一格式。
四条核心原则
原则 0：添加「信息记录原则」（防止未来膨胀）
问题：优化完成后，用户会继续要求 Claude "记录这个信息到 CLAUDE.md"，如果没有规则指导，CLAUDE.md 会再次膨胀。
解决：在 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 但不写触发条件
原因：这条规则让 Claude 自己知道什么该记在哪里，实现"自我约束"，避免后续对话中 CLAUDE.md 再次膨胀。
原则 1：触发索引表放开头和末尾
原因：LLM 注意力呈 U 型分布——开头和末尾强，中间弱。
| 位置 |
作用 |
| 开头 |
对话开始时建立全局认知："有哪些 Level 2 可用" |
| 末尾 |
对话变长后复述提醒："现在应该读哪个 Level 2" |
## Reference 索引
|---------|------|---------|
<
