Claude Md Progressive Disclosurer

# CLAUDE.md 渐进式披露优化器

## 核心理念

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

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

> 本 skill 自身遵守渐进式披露：新方法论以"精炼规则 + 触发条件"留在 SKILL.md，深度与引文沉到 references/。SKILL.md 保持 ≤500 行（Anthropic skill 规范）——skill 自己示范它要求别人做的事。

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

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

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

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

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

### 两层架构

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

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

### 多入口原则（重要！）

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

| 入口 | 位置 | 触发场景 | 用户心态 |
|------|------|----------|----------|
| Reference 索引 | 开头 | 遇到错误/问题 | "出 bug 了，查哪个文档？" |
| 修改代码前必读 | 中间 | 准备改代码 | "我要改 X，要注意什么？" |
| Reference 触发索引 | 末尾 | 长对话定位 | "刚才说的那个文档是哪个？" |

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

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

---

## 优化工作流

### Step 1: 备份

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

对**通过分诊的信号**分类：

| 问题 | 是 | 否 |
|------|----|-----|
| 高频使用？ | 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），不是**改变信息的存在**。

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

### Step 4: 更新 Level 1

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

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

#### 5a. 引用文件存在性

```bash
# 检查引用文件存在
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. **逐节对比**：对原始文件的每个 `##` 章节