claude-md-progressive-disclosurer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CLAUDE.md 渐进式披露优化器

CLAUDE.md Progressive Disclosure Optimizer

核心理念

Core Philosophy

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

目标是最大化 LLM 工作效能，而非最小化行数。

"Find the smallest set of high-signal tokens to maximize the probability of desired outcomes." — Anthropic

The goal is to maximize LLM working efficiency, NOT minimize line count.

两层架构

Two-Tier Architecture

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

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

Level 1 (CLAUDE.md) - Loaded in every conversation
├── Information Recording Principles ← Self-constraints to prevent future bloat
├── Reference Index (beginning)     ← Entry 1: Check here when encountering issues
├── Core Command List
├── Non-Negotiable Rules/Prohibitions (with code examples)
├── Common Error Diagnosis (Symptom → Cause → Fix)
├── Code Patterns (directly copyable)
├── Directory Mapping (Function → File)
├── Must-Read Before Modifying Code ← Entry 2: Check here before modifying code
└── Reference Trigger Index (end) ← Entry 3: Retrieval after long conversations

多入口原则（重要！）

Multi-Entry Principle (Important!)

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

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

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

The same Level 2 resource can have multiple entries to serve different lookup paths:

Entry	Location	Trigger Scenario	User Mindset
Reference Index	Beginning	Encountering errors/issues	"There's a bug, which document should I check?"
Must-Read Before Modifying Code	Middle	Preparing to modify code	"I need to change X, what should I note?"
Reference Trigger Index	End	Positioning in long conversations	"Which document was mentioned earlier?"

This is not duplication, it's multi-entry. Just like a book has a table of contents (by chapter), an index (by keyword), and a quick reference card (by task).

优化工作流

Optimization Workflow

Step 1: 备份

Step 1: Backup

bash

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

bash

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

Step 2: 内容分类

Step 2: Content Classification

对每个章节分类：

问题	是	否
高频使用？	Level 1	↓
违反后果严重？	Level 1	↓
有代码模式需要直接复制？	Level 1 保留模式	↓
有明确触发条件？	Level 2 + 触发条件	↓
历史/参考资料？	Level 2	考虑删除

Classify each section:

Question	Yes	No
Frequently used?	Level 1	↓
Severe consequences if violated?	Level 1	↓
Contains code patterns for direct copying?	Keep pattern in Level 1	↓
Has clear trigger conditions?	Level 2 + Trigger Conditions	↓
Historical/reference material?	Level 2	Consider deletion

Step 3: 创建 Reference 文件

Step 3: Create Reference Files

命名：

docs/references/{主题}-sop.md

Naming:

docs/references/{topic}-sop.md

Step 4: 更新 Level 1

Step 4: Update Level 1

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

Add "Information Recording Principles" at the beginning (after project overview, before Reference Index)
Add Reference Index (immediately after Information Recording Principles)
Replace detailed content with trigger condition format
Retain code patterns and error diagnosis
Add "Must-Read Before Modifying Code" table (indexed by "What you want to modify")
Place another trigger index table at the end

Step 5: 验证

Step 5: Validation

bash

undefined

bash

undefined

检查引用文件存在

Check if referenced files exist

grep -oh '

[^

]*.md

' CLAUDE.md | sed 's/

//g' | while read f; do test -f "$f" && echo "✓ $f" || echo "✗ MISSING: $f" done

---

grep -oh '

[^

]*.md

' CLAUDE.md | sed 's/

//g' | while read f; do test -f "$f" && echo "✓ $f" || echo "✗ MISSING: $f" done

---

Level 1 内容分类

Level 1 Content Classification

🔴 绝对不能移走

🔴 Absolutely Cannot Be Moved

内容类型	原因
核心命令	高频使用
铁律/禁令	违反后果严重，必须始终可见
代码模式	LLM 需要直接复制，避免重新推导
错误诊断	完整的症状→原因→修复流程
目录映射	帮助 LLM 快速定位文件
触发索引表	帮助 LLM 在长对话中定位 Level 2

Content Type	Reason
Core Commands	Frequently used
Non-Negotiable Rules/Prohibitions	Severe consequences if violated, must always be visible
Code Patterns	LLM needs to directly copy, avoid re-derivation
Error Diagnosis	Complete Symptom → Cause → Fix workflow
Directory Mapping	Helps LLM quickly locate files
Trigger Index Table	Helps LLM locate Level 2 in long conversations

🟡 保留摘要 + 触发条件

🟡 Retain Summary + Trigger Conditions

内容类型	Level 1	Level 2
SOP 流程	触发条件 + 关键陷阱	完整步骤
配置示例	最常用的 1-2 个	完整配置
API 文档	常用方法签名	完整参数说明

Content Type	Level 1	Level 2
SOP Processes	Trigger conditions + key pitfalls	Complete steps
Configuration Examples	1-2 most commonly used	Full configuration
API Documentation	Common method signatures	Complete parameter descriptions

🟢 可以完全移走

🟢 Can Be Fully Moved

内容类型	原因
历史决策记录	低频访问
性能数据	参考性质
技术债务清单	按需查看
边缘情况	有明确触发条件时再加载

Content Type	Reason
Historical Decision Records	Low-frequency access
Performance Data	Reference nature
Technical Debt List	On-demand viewing
Edge Cases	Load only when clear trigger conditions exist

引用格式（四种）

Reference Formats (Four Types)

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

1. Detailed Format (Important References in Main Text)

markdown

**📖 何时读 `docs/references/xxx-sop.md`**：
- [具体错误信息，如 `ERR_DLOPEN_FAILED`]
- [具体场景，如"添加新的原生模块时"]

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

markdown

**📖 When to read `docs/references/xxx-sop.md`**:
- [Specific error message, e.g., `ERR_DLOPEN_FAILED`]
- [Specific scenario, e.g., "when adding new native modules"]

> Includes: [Keyword 1], [Keyword 2], [Code Template].

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

2. Problem Trigger Table (Beginning/End Index)

markdown

undefined

markdown

undefined

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

Reference Index (Check Here First When Encountering Problems)

触发场景	文档	核心内容
`ERR_DLOPEN_FAILED`	`native-modules-sop.md`	ABI 机制、懒加载
打包后 `Cannot find module`	`vite-sop.md`	MODULES_TO_COPY

undefined

Trigger Scenario	Document	Core Content
`ERR_DLOPEN_FAILED`	`native-modules-sop.md`	ABI mechanism, lazy loading
`Cannot find module` after packaging	`vite-sop.md`	MODULES_TO_COPY

undefined

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

3. Task Trigger Table (Must-Read Before Modifying Code)

markdown

undefined

markdown

undefined

修改代码前必读

Must-Read Before Modifying Code

你要改什么	先读这个	关键陷阱
原生模块相关	`native-modules-sop.md`	必须懒加载；electron-rebuild 会静默失败
打包配置	`packaging-sop.md`	DMG contents 必须用函数形式

undefined

What You Want to Modify	Read This First	Key Pitfalls
Native module related	`native-modules-sop.md`	Must use lazy loading; electron-rebuild fails silently
Packaging configuration	`packaging-sop.md`	DMG contents must use function form

undefined

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

4. Inline Format (Brief References)

markdown

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

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

markdown

Complete process see `database-sop.md` (FTS5 escaping, health checks).

Diversity Principle: Do not use the same format for all references.

四条核心原则

Four Core Principles

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

Principle 0: Add "Information Recording Principles" (Prevent Future Bloat)

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

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

markdown

undefined

Problem: After optimization, users will continue to ask Claude to "record this information into CLAUDE.md". Without guiding rules, CLAUDE.md will bloat again.

Solution: Add "Information Recording Principles" at the beginning of CLAUDE.md (after project overview):

markdown

undefined

信息记录原则（Claude 必读）

Information Recording Principles (Mandatory for Claude)

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

This document uses a progressive disclosure architecture to optimize LLM working efficiency.

Level 1（本文件）只记录

Level 1 (This File) Only Records

类型	示例
核心命令表	`pnpm run restart`
铁律/禁令	必须懒加载原生模块
常见错误诊断	症状→原因→修复（完整流程）
代码模式	可直接复制的代码块
目录导航	功能→文件映射
触发索引表	指向 Level 2 的入口

Type	Example
Core Command List	`pnpm run restart`
Non-Negotiable Rules/Prohibitions	Must lazy load native modules
Common Error Diagnosis	Complete Symptom → Cause → Fix workflow
Code Patterns	Directly copyable code blocks
Directory Navigation	Function → File mapping
Trigger Index Table	Entries pointing to Level 2

Level 2（docs/references/）记录

Level 2 (docs/references/) Records

类型	示例
详细 SOP 流程	完整的 20 步操作指南
边缘情况处理	罕见错误的诊断
完整配置示例	所有参数的说明
历史决策记录	为什么这样设计

Type	Example
Detailed SOP Processes	Complete 20-step operation guides
Edge Case Handling	Diagnosis of rare errors
Full Configuration Examples	Explanations of all parameters
Historical Decision Records	Why this design was chosen

用户要求记录信息时

When Users Request to Record Information

判断是否高频使用：
- 是 → 写入 CLAUDE.md（Level 1）
- 否 → 写入对应 reference 文件（Level 2）
Level 1 引用 Level 2 必须包含：
- 触发条件（什么情况该读）
- 内容摘要（读了能得到什么）
禁止：
- 在 Level 1 放置低频的详细流程
- 引用 Level 2 但不写触发条件


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

Judge if it's frequently used:
- Yes → Write to CLAUDE.md (Level 1)
- No → Write to the corresponding reference file (Level 2)
References from Level 1 to Level 2 must include:
- Trigger conditions (when to read)
- Content summary (what you'll gain from reading)
Prohibited:
- Placing low-frequency detailed processes in Level 1
- Referencing Level 2 without writing trigger conditions


**Reason**: This rule lets Claude know what to record where, achieving "self-constraint" and preventing CLAUDE.md from bloating again in subsequent conversations.

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

Principle 1: Place Trigger Index Tables at the Beginning and End

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

位置	作用
开头	对话开始时建立全局认知："有哪些 Level 2 可用"
末尾	对话变长后复述提醒："现在应该读哪个 Level 2"

markdown

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

Reason: LLM attention follows a U-shaped distribution—strong at the beginning and end, weak in the middle.

Position	Function
Beginning	Establish global awareness at the start of the conversation: "Which Level 2 resources are available"
End	Remind retrieval after long conversations: "Which Level 2 should be read now"

markdown

<!-- CLAUDE.md Beginning (After Project Overview) -->

Reference 索引

Reference Index

触发场景	文档	核心内容
ABI 错误	`native-modules-sop.md`	懒加载模式
打包模块缺失	`vite-sop.md`	MODULES_TO_COPY

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

Trigger Scenario	Document	Core Content
ABI errors	`native-modules-sop.md`	Lazy loading mode
Missing packaged modules	`vite-sop.md`	MODULES_TO_COPY

... (Main Content) ...

Reference 触发索引

Reference Trigger Index

触发场景	文档	核心内容
ABI 错误	`native-modules-sop.md`	懒加载模式
打包模块缺失	`vite-sop.md`	MODULES_TO_COPY

undefined

Trigger Scenario	Document	Core Content
ABI errors	`native-modules-sop.md`	Lazy loading mode
Missing packaged modules	`vite-sop.md`	MODULES_TO_COPY

undefined

原则 2：引用必须有触发条件

Principle 2: References Must Include Trigger Conditions

错误：

详见 native-modules-sop.md

正确：

markdown

**📖 何时读 `native-modules-sop.md`**：
- 遇到 `ERR_DLOPEN_FAILED` 错误
- 需要添加新的原生模块

> 包含：ABI 机制、懒加载模式、手动修复命令

原因：没有触发条件，LLM 不知道什么时候该去读。

Incorrect:

See native-modules-sop.md for details

Correct:

markdown

**📖 When to read `native-modules-sop.md`**:
- Encountering `ERR_DLOPEN_FAILED` errors
- Needing to add new native modules

> Includes: ABI mechanism, lazy loading mode, manual repair commands

Reason: Without trigger conditions, the LLM doesn't know when to load it—either ignores it or reads it every time.

原则 3：代码模式必须保留在 Level 1

Principle 3: Code Patterns Must Be Retained in 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。

Incorrect: Move code examples to Level 2, leaving only "Use lazy loading mode" in Level 1.

Correct: Retain complete copyable code in Level 1:

javascript

// ✅ Correct: Lazy loading, load only when needed
let _Database = null;
function getDatabase() {
  if (!_Database) {
    _Database = require("better-sqlite3");
  }
  return _Database;
}

Reason: The LLM needs to directly copy code; moving it would require reading Level 2 every time, increasing latency and token consumption.

反模式警告

Anti-Pattern Warnings

⚠️ 反模式 1：过度精简

⚠️ Anti-Pattern 1: Over-Simplification

案例：把 2937 行压缩到 165 行

结果：

丢失代码模式，每次重新推导
丢失诊断流程，遇错不知查哪
丢失目录映射，找文件效率低

正确：保留所有高频使用的内容，即使行数较多。

Case: Compressing 2937 lines to 165 lines

Result:

Loss of code patterns, requiring re-derivation every time
Loss of diagnosis workflows, unsure which document to check when errors occur
Loss of directory mapping, low efficiency in finding files

Correct: Retain all frequently used content, even if it results in more lines.

⚠️ 反模式 2：无触发条件的引用

⚠️ Anti-Pattern 2: References Without Trigger Conditions

案例：

详见 xxx.md

问题：LLM 不知道何时加载，要么忽略，要么每次都读。

正确：触发条件 + 内容摘要。

Case:

See xxx.md for details

Problem: The LLM doesn't know when to load it—either ignores it or reads it every time.

Correct: Include trigger conditions + content summary.

⚠️ 反模式 3：移走代码模式

⚠️ Anti-Pattern 3: Moving Code Patterns

案例：把常用代码示例移到 Level 2

问题：LLM 每次写代码都要先读 Level 2，增加延迟和 token 消耗。

正确：高频使用的代码模式保留在 Level 1。

Case: Moving commonly used code examples to Level 2

Problem: The LLM has to read Level 2 every time it writes code, increasing latency and token consumption.

Correct: Retain frequently used code patterns in Level 1.

⚠️ 反模式 4：删除而非移动

⚠️ Anti-Pattern 4: Deleting Instead of Moving

案例：删除"不重要"的章节

问题：信息丢失，未来需要时无处可查。

正确：移到 Level 2，保留触发条件。

Case: Deleting "unimportant" sections

Problem: Information is lost, with nowhere to look when needed in the future.

Correct: Move to Level 2 and retain trigger conditions.

信息量检验

Information Volume Check

✅ 正确的信息量

✅ Correct Information Volume

检验项	通过标准
日常命令	不需要读 Level 2
常见错误	有完整诊断流程
代码编写	有可复制的模式
特定问题	知道读哪个 Level 2
触发索引	在文档末尾，表格形式

Check Item	Pass Standard
Daily Commands	No need to read Level 2
Common Errors	Have complete diagnosis workflows
Code Writing	Have copyable patterns
Specific Issues	Know which Level 2 to read
Trigger Index	At the end of the document, in table form

❌ 不足的信号

❌ Insufficient Signal

LLM 反复问同样的问题
LLM 每次重新推导代码模式
用户需要反复提醒规则

The LLM repeatedly asks the same questions
The LLM re-derives code patterns every time
Users need to repeatedly remind rules

❌ 过多的信号

❌ Excessive Signal

大段低频详细流程在 Level 1
完全相同的内容在多处（注意：多入口指向同一资源 ≠ 重复）
边缘情况和常见情况混在一起

Large sections of low-frequency detailed processes in Level 1
Identical content in multiple places (Note: Multi-entry pointing to the same resource ≠ duplication)
Edge cases mixed with common cases

项目级 vs 用户级

Project-Level vs User-Level

维度	用户级	项目级
位置	`~/.claude/CLAUDE.md`	`项目/CLAUDE.md`
References	`~/.claude/references/`	`docs/references/`
行数参考	100-300	300-600

Dimension	User-Level	Project-Level
Location	`~/.claude/CLAUDE.md`	`Project/CLAUDE.md`
References	`~/.claude/references/`	`docs/references/`
Line Count Reference	100-300	300-600