CLAUDE.md Progressive Disclosure Optimizer

Core Philosophy

"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) - 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!)

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: Backup

bash

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

Step 2: Content Classification

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: Create Reference Files

Naming:

docs/references/{topic}-sop.md

Step 4: Update Level 1

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: Validation

bash

# 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

Level 1 Content Classification

🔴 Absolutely Cannot Be Moved

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

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. Detailed Format (Important References in Main Text)

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. Problem Trigger Table (Beginning/End Index)

markdown

## Reference Index (Check Here First When Encountering Problems)

| 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 |

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

markdown

## Must-Read Before Modifying Code

| 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 |

4. Inline Format (Brief References)

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

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

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

## Information Recording Principles (Mandatory for Claude)

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

### Level 1 (This File) Only Records

| 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/) Records

| 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

1. **Judge if it's frequently used**:
   - Yes → Write to CLAUDE.md (Level 1)
   - No → Write to the corresponding reference file (Level 2)

2. **References from Level 1 to Level 2 must include**:
   - Trigger conditions (when to read)
   - Content summary (what you'll gain from reading)

3. **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.

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

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 Index

| 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) ...

<!-- CLAUDE.md End (Place Another Copy) -->
## Reference Trigger Index

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

Principle 2: References Must Include Trigger Conditions

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.

Principle 3: Code Patterns Must Be Retained in Level 1

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

⚠️ Anti-Pattern 1: Over-Simplification

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.

⚠️ Anti-Pattern 2: References Without Trigger Conditions

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.

⚠️ Anti-Pattern 3: Moving Code Patterns

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.

⚠️ Anti-Pattern 4: Deleting Instead of Moving

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

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

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

❌ Excessive Signal

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

Project-Level vs User-Level

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

Quick Checklist

After optimization, check:

"Information Recording Principles" at the beginning of the document (Prevent future bloat)
Reference Index at the beginning of the document (Entry 1: Check here when encountering issues)
Complete core command list
Non-Negotiable Rules/Prohibitions with code examples
Common errors have complete diagnosis workflows (Symptom → Cause → Fix)
Code patterns are directly copyable
Directory Mapping (Function → File)
"Must-Read Before Modifying Code" table (Entry 2: Indexed by "What you want to modify")
Reference Trigger Index at the end of the document (Entry 3: Retrieval after long conversations)
Every Level 2 reference has trigger conditions
All referenced files exist

claude-md-progressive-disclosurer

NPX Install

Tags

SKILL.md Content (Chinese)

CLAUDE.md Progressive Disclosure Optimizer

Core Philosophy

Two-Tier Architecture

Multi-Entry Principle (Important!)

Optimization Workflow

Step 1: Backup

Step 2: Content Classification

Step 3: Create Reference Files

Step 4: Update Level 1

Step 5: Validation

Level 1 Content Classification

🔴 Absolutely Cannot Be Moved

🟡 Retain Summary + Trigger Conditions

🟢 Can Be Fully Moved

Reference Formats (Four Types)

1. Detailed Format (Important References in Main Text)

2. Problem Trigger Table (Beginning/End Index)

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

4. Inline Format (Brief References)

Four Core Principles

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

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

Principle 2: References Must Include Trigger Conditions

Principle 3: Code Patterns Must Be Retained in Level 1

Anti-Pattern Warnings

⚠️ Anti-Pattern 1: Over-Simplification

⚠️ Anti-Pattern 2: References Without Trigger Conditions

⚠️ Anti-Pattern 3: Moving Code Patterns

⚠️ Anti-Pattern 4: Deleting Instead of Moving

Information Volume Check

✅ Correct Information Volume

❌ Insufficient Signal

❌ Excessive Signal

Project-Level vs User-Level

Quick Checklist