Mobile overview changes

2026-02-18 12:25:53 +00:00
parent 8b79f7b273
commit 9baa6e605b
56 changed files with 3956 additions and 7000 deletions
@@ -0,0 +1,4 @@
+Security scan passed
+Scanned at: 2025-12-11T20:19:33.266025
+Tool: gitleaks + pattern-based validation
+Content hash: 864b1b4fa2851e26012b06cd3bcb5eb8810ab2cfd3240ba5b48af1895ad182ce
@@ -0,0 +1,10 @@
+{
+  "version": 2,
+  "name": "claude-md-progressive-disclosurer",
+  "owner": "daymade",
+  "repo": "claude-code-skills",
+  "path": "claude-md-progressive-disclosurer",
+  "branch": "main",
+  "sha": "4f20e980d6f0c88856b5b1dbadbdcf94108de0c2",
+  "source": "manual"
+}
@@ -0,0 +1,478 @@
+---
+name: claude-md-progressive-disclosurer
+description: |
+  Optimize CLAUDE.md files using progressive disclosure.
+  Goal: Maximize information efficiency, readability, and maintainability.
+  Use when: User wants to optimize CLAUDE.md, information is duplicated across files, or LLM repeatedly fails to follow rules.
+---
+
+# 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: 备份
+
+```bash
+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），不是**改变信息的存在**。
+
+**怎么做**：
+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. **逐节对比**：对原始文件的每个 `##` 章节，确认其内容在以下位置之一完整存在：
+   - 新 CLAUDE.md 中（保留在 Level 1）
+   - 某个 Level 2 reference 文件中（完整移动）
+
+   **快速暴露遗漏的辅助脚本**：
+
+   ```bash
+   # 对原始文件的每个 ## 章节标题，检查它在新文件或 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
+   ```
+
+   > ⚠️ 这个脚本**不能替代人工逐节对比**——它只检查章节标题是否存在，不检查内容是否完整。但它能快速暴露**整个章节被遗漏**的情况，作为人工对比前的第一道筛查。
+
+3. **标记所有差异**：
+   - 如果某段内容在新文件中被缩短 → **必须补回被删减的部分**
+   - 如果某段内容在两个位置都不存在 → **必须补回**
+   - 唯一允许删除的情况：**该信息已有独立的 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. 详细格式（正文中的重要引用）
+
+```markdown
+**📖 何时读 `docs/references/xxx-sop.md`**：
+- [具体错误信息，如 `ERR_DLOPEN_FAILED`]
+- [具体场景，如"添加新的原生模块时"]
+
+> 包含：[关键词 1]、[关键词 2]、[代码模板]。
+```
+
+### 2. 问题触发表格（开头/末尾索引）
+
+```markdown
+## Reference 索引（遇到问题先查这里）
+
+| 触发场景 | 文档 | 核心内容 |
+|----------|------|---------|
+| `ERR_DLOPEN_FAILED` | `native-modules-sop.md` | ABI 机制、懒加载 |
+| 打包后 `Cannot find module` | `vite-sop.md` | MODULES_TO_COPY |
+```
+
+### 3. 任务触发表格（修改代码前必读）
+
+```markdown
+## 修改代码前必读
+
+| 你要改什么 | 先读这个 | 关键陷阱 |
+|-----------|---------|---------|
+| 原生模块相关 | `native-modules-sop.md` | 必须懒加载；electron-rebuild 会静默失败 |
+| 打包配置 | `packaging-sop.md` | DMG contents 必须用函数形式 |
+```
+
+### 4. 内联格式（简短引用）
+
+```markdown
+完整流程见 `database-sop.md`（FTS5 转义、健康检查）。
+```
+
+**多样性原则**：不要所有引用都用同一格式。
+
+---
+
+## 四条核心原则
+
+### 原则 0：添加「信息记录原则」（防止未来膨胀）
+
+**问题**：优化完成后，用户会继续要求 Claude "记录这个信息到 CLAUDE.md"，如果没有规则指导，CLAUDE.md 会再次膨胀。
+
+**解决**：在 CLAUDE.md 开头（项目概述之后）添加「信息记录原则」：
+
+```markdown
+## 信息记录原则（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" |
+
+```markdown
+<!-- 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 |
+```
+
+### 原则 2：引用必须有触发条件
+
+**错误**：`详见 native-modules-sop.md`
+
+**正确**：
+```markdown
+**📖 何时读 `native-modules-sop.md`**：
+- 遇到 `ERR_DLOPEN_FAILED` 错误
+- 需要添加新的原生模块
+
+> 包含：ABI 机制、懒加载模式、手动修复命令
+```
+
+**原因**：没有触发条件，LLM 不知道什么时候该去读。
+
+### 原则 3：代码模式必须保留在 Level 1
+
+**错误**：把代码示例移到 Level 2，Level 1 只写"使用懒加载模式"。
+
+**正确**：Level 1 保留完整的可复制代码：
+```javascript
+// ✅ 正确：懒加载，只在需要时加载
+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 引用都有触发条件
+- [ ] 引用的文件都存在
@@ -0,0 +1,319 @@
+# 实践案例与教训
+
+本文档记录优化 CLAUDE.md 过程中的实际案例和教训。
+
+---
+
+## 案例 1：以行数为目标的过度精简
+
+### 背景
+某项目 CLAUDE.md 内容丰富，包含代码模式、诊断流程、目录映射等。
+
+### 错误做法
+以"减少行数"为目标，移走了大部分内容，只保留简短描述和指针。
+
+### 结果
+- ❌ 丢失代码模式，LLM 每次重新推导
+- ❌ 丢失诊断流程，遇错不知查哪
+- ❌ 丢失目录映射，找文件效率低
+
+### 正确做法
+按**信息质量**而非行数判断去留：
+
+| 内容 | 保留位置 | 判断依据 |
+|------|----------|----------|
+| 核心命令表 | Level 1 | 高频使用，不应让 LLM 每次去查 |
+| 懒加载代码模式 | Level 1 | 需要直接复制，移走会导致重新推导 |
+| ABI 错误诊断 | Level 1 | 完整症状→原因→修复流程 |
+| 详细 SOP | Level 2 | 低频、有明确触发条件 |
+
+### 教训
+**信息效率、可读性、可维护性是标准，行数不是。**
+
+---
+
+## 案例 2：无触发条件的引用
+
+### 错误做法
+```markdown
+详见 native-modules-sop.md
+```
+
+### 问题
+LLM 不知道什么时候该去读这个文件。
+
+### 正确做法
+```markdown
+**📖 何时读 `native-modules-sop.md`**：
+- 遇到 `ERR_DLOPEN_FAILED` 错误
+- 需要添加新的原生模块
+
+> 包含：ABI 机制、懒加载模式、手动修复命令
+```
+
+### 教训
+**每个引用必须有触发条件 + 内容摘要。**
+
+---
+
+## 案例 3：代码模式被移走
+
+### 错误做法
+Level 1 只写"使用懒加载模式"，代码示例放 Level 2。
+
+### 问题
+LLM 每次写代码都要先读 Level 2，或者凭记忆推导（可能出错）。
+
+### 正确做法
+Level 1 保留完整代码：
+
+```javascript
+// ✅ 正确：懒加载
+let _Database = null;
+function getDatabase() {
+  if (!_Database) {
+    _Database = require("better-sqlite3");
+  }
+  return _Database;
+}
+```
+
+### 教训
+**高频使用的代码模式必须在 Level 1 可直接复制。**
+
+---
+
+## 案例 4：触发索引表位置错误
+
+### 错误做法
+触发索引表只放在 CLAUDE.md 中间某个位置。
+
+### 问题
+LLM 注意力呈 U 型分布：开头和末尾强，中间弱。只放中间会被忽略。
+
+### 正确做法
+触发索引表放在 CLAUDE.md **开头和末尾两个位置**：
+
+```markdown
+<!-- 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 开头添加「信息记录原则」：
+
+```markdown
+## 信息记录原则（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 |
+| **维护一致性** | 改一处是否需要同步另一处？如果是，消除重复 |
+
+### 教训
+**行数少不代表更好，行数多不代表更差。真正的标准是信息效率、可读性、可维护性。**
+
+---
+
+## 案例 8：移动时压缩导致信息丢失（真实事故，2026-02-14）
+
+### 背景
+一个 2503 行的 CLAUDE.md 需要优化。使用本 skill 的渐进式披露方法，创建了 6 个 Level 2 reference 文件。
+
+### 错误做法
+在移动内容到 Level 2 文件时，LLM "顺便精简"了内容：
+
+| 原始章节 | 原始内容 | Level 2 中保留 | 丢失 |
+|---------|---------|---------------|------|
+| Git 工作流 SOP | 560 行（含脚本源码、决策树） | 342 行 | 218 行 |
+| Feature docs | ~400 行（含 case study） | 300 行 | ~100 行 |
+| Namespace SOP | ~130 行（含正反例、检查清单） | 简化到铁律 | ~80 行 |
+| Field naming | ~33 行（含防错指南、case study） | 简化到字段表 | ~33 行 |
+
+总计 ~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。