4ea2c8b4de
Key insight from real-world optimization: - Optimizing once is not enough - need rules to prevent future bloat - Add "信息记录原则" section to teach Claude what goes where - This enables self-regulation: Claude knows Level 1 vs Level 2 placement Changes: - Add Principle 0: "信息记录原则" with template - Update workflow Step 4: add "信息记录原则" as first step - Update architecture diagram: show "信息记录原则" position - Update quick checklist: add verification item - Add Case 6 in references: missing self-regulation rules Now "四条核心原则" instead of "三条核心原则": 0. 信息记录原则（防止未来膨胀） 1. 触发索引表放开头和末尾 2. 引用必须有触发条件 3. 代码模式保留在 Level 1 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
5.6 KiB
5.6 KiB
实践案例与教训
本文档记录优化 CLAUDE.md 过程中的实际案例和教训。
案例 1：过度精简的失败
背景
某项目 CLAUDE.md 原有 2937 行，尝试优化。
错误做法
压缩到 165 行，移走了大部分内容。
结果
- ❌ 丢失代码模式，LLM 每次重新推导
- ❌ 丢失诊断流程，遇错不知查哪
- ❌ 丢失目录映射，找文件效率低
正确做法
保留 482 行，关键内容如下：
| 内容 | 保留位置 | 原因 |
|---|---|---|
| 核心命令表 | Level 1 | 高频使用 |
| 懒加载代码模式 | 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，注意什么？"）
正确做法
保留三个入口：
- 开头 Reference 索引 - 遇到问题时查
- 修改代码前必读 - 准备改代码时查
- 末尾触发索引 - 长对话后定位
教训
多入口指向同一资源 ≠ 重复信息。 就像书有目录、索引、快速参考卡。
案例 6：缺少信息记录原则
背景
优化完成后，CLAUDE.md 从 2937 行精简到 524 行，结构清晰。
问题
后续用户继续要求 Claude "把这个记录到 CLAUDE.md"，Claude 没有判断标准，只能照做。一个月后 CLAUDE.md 又膨胀回 1500+ 行。
错误做法
只优化内容，不添加规则。
正确做法
在 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 步骤 | ✅ | |
| 边缘情况处理 | ✅ | |
| 历史决策记录 | ✅ | |
| 性能数据 | ✅ |