claude-md-progressive-disclosurer

어떤 스킬인가요?

Optimize CLAUDE.md files using progressive disclosure: reduce bloat, move details to references, extract reusable patterns into skills, improve context efficiency. Use when CLAUDE.md is too long or needs restructuring.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

Security scan passed
Scanned at: 2025-12-11T20:19:33.266025
Tool: gitleaks + pattern-based validation
Content hash: 864b1b4fa2851e26012b06cd3bcb5eb8810ab2cfd3240ba5b48af1895ad182ce

# Progressive Disclosure Principles for CLAUDE.md

## Core Concept

Progressive disclosure is a design pattern that sequences information based on need. For CLAUDE.md:

- **Level 1 (Always loaded)**: CLAUDE.md core content (~100-200 lines ideal)
- **Level 2 (On-demand)**: `~/.claude/references/` files
- **Level 3 (Skill-triggered)**: Skills with their own SKILL.md and resources

## Token Economics

Every line in CLAUDE.md consumes context tokens on EVERY conversation. Moving 100 lines to references saves tokens on conversations that don't need that information.

**Example calculation**:
- CLAUDE.md with 500 lines ≈ 2000 tokens per conversation
- Optimized 150 lines ≈ 600 tokens per conversation
- 10 conversations/day = 14,000 tokens saved daily

## What Belongs in CLAUDE.md

### Must Include
- Identity/persona instructions
- Critical safety rules ("never do X")
- Frequently-referenced short rules
- Tool preferences (ast-grep, difft, uv)
- Directory/path conventions

### Should Move to References
- Detailed API examples (>5 lines of code)
- Troubleshooting guides with multiple steps
- Infrastructure credentials and procedures
- Deployment workflows
- Database schemas

### Should Become Skills
- Reusable workflows with scripts
- Domain-specific knowledge bases
- Complex multi-step procedures
- Anything another user might benefit from

## Section Size Guidelines

| Lines | Recommendation |
|-------|----------------|
| 1-10 | Keep in CLAUDE.md |
| 11-30 | Consider consolidating or moving |
| 31-50 | Strongly consider moving to references |
| 50+ | Move to references or extract to skill |

### Exceptions (Keep Regardless of Size)

**Do NOT move** even if >50 lines:

| Category | Reason | Examples |
|----------|--------|----------|
| **Safety-critical** | Severe consequences if forgotten | Deployment protocols, production access rules |
| **High-frequency** | Used in most conversations | Core commands, common patterns |
| **Easily violated** | Claude ignores when not visible | Style rules, permission checks |
| **Security-sensitive** | Must always be enforced | Data handling, access restrictions |

**Rule**: If forgetting causes production incidents, data loss, or security breaches → keep visible.

## Reference File Organization

```
~/.claude/
├── CLAUDE.md                    # Core principles only
└── references/
    ├── infrastructure.md        # Servers, APIs, credentials paths
    ├── coding_standards.md      # Detailed code examples
    ├── troubleshooting.md       # Common issues and solutions
    └── domain_knowledge.md      # Project-specific information
```

## Anti-Patterns

### 1. Embedded Scripts
**Bad**: 100-line Python script in CLAUDE.md
**Good**: Script in skill's `scripts/` directory

### 2. Duplicate Documentation
**Bad**: Same info in CLAUDE.md and a skill
**Good**: Single source of truth with pointers

### 3. Rarely-Used Details
**Bad**: Edge-case procedures in CLAUDE.md
**Good**: Edge cases in references, linked when relevant

### 4. Version-Specific Instructions
**Bad**: "If using v2.3, do X; if v2.4, do Y"
**Good**: Current version only, archive old versions

## Measuring Success

After optimization, verify:

1. **Line count reduction**: Target 50%+ reduction
2. **Information preserved**: All functionality still accessible
3. **Discoverability**: Claude finds moved content when needed
4. **Maintenance**: Easier to update individual reference files

### Verification Methods

#### 1. Information Preservation Check

Before executing, create a checklist of key items from each moved section:

```markdown
| Key Item | Original Line | New Location | Verified |
|----------|---------------|--------------|----------|
| Server IP | L123 | infra.md:15 | [ ] |
| Password | L200 | infra.md:42 | [ ] |
| Critical rule | L45 | Kept | [ ] |
```

#### 2. Discoverability Test

After optimization, test with real queries:

```
Test: "How do I deploy to production?"
Expected: Should find deployment steps in reference file

Test: "What's the database password?"
Expected: Should find in infrastructure reference

Test: "Can I force push to main?"
Expected: Should find rule (ideally still in CLAUDE.md)
```

#### 3. Pointer Verification Script

```bash
# Check all referenced files exist
grep -oh '`[^`]*\.md`' ~/.claude/CLAUDE.md | \
  sed 's/`//g' | while read f; do
    test -f "$f" && echo "✓ $f" || echo "✗ MISSING: $f"
  done
```

#### 4. Backup Comparison

```bash
# See what was removed
diff ~/.claude/CLAUDE.md.bak.* ~/.claude/CLAUDE.md | grep "^<"
```

---
name: claude-md-progressive-disclosurer
description: "Optimize CLAUDE.md files using progressive disclosure: reduce bloat, move details to references, extract reusable patterns into skills, improve context efficiency. Use when CLAUDE.md is too long or needs restructuring."
---

# CLAUDE.md Progressive Disclosure Optimizer

Analyze and optimize user CLAUDE.md files to reduce context overhead while preserving functionality.

## Quick Start

1. **Backup** the original file first
2. **Audit** the current state (list all sections with line counts)
3. **Classify** each section using the criteria below
4. **Propose** optimizations with before/after comparison table
5. **Verify** information completeness checklist before executing
6. **Execute** approved changes
7. **Test** that moved content remains discoverable

## Section Classification

Analyze each section and classify:

| Category | Criteria | Action |
|----------|----------|--------|
| **Keep in CLAUDE.md** | Core principles, short rules (<10 lines), frequently needed | Keep as-is |
| **Move to references/** | Detailed procedures, code examples, troubleshooting guides | Create `~/.claude/references/<name>.md` |
| **Extract to skill** | Reusable workflows, scripts, domain-specific knowledge | Create skill in skills repository |
| **Remove** | Duplicates existing skills, outdated, or unnecessary | Delete after confirmation |

### Exceptions to Size Guidelines

Even if a section is >50 lines, **KEEP in CLAUDE.md** if any of these apply:

| Exception | Reason | Example |
|-----------|--------|---------|
| **Safety-critical** | Consequences of forgetting are severe | Deployment protocols, "never force push to main" |
| **High-frequency** | Referenced in most conversations | Core development patterns, common commands |
| **Easy to violate** | Claude tends to ignore when not visible | Code style rules, permission requirements |
| **Security-sensitive** | Must be always enforced | Production access restrictions, data handling rules |

**Rule of thumb**: If forgetting the rule could cause production incidents, data loss, or security breaches, keep it visible regardless of length.

## Optimization Workflow

### Step 0: Backup Original File

**CRITICAL**: Always create a backup before any changes.

```bash
# Create timestamped backup
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S)

# For project-level CLAUDE.md
cp CLAUDE.md CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S)
```

If issues found after optimization:
```bash
# Restore from backup
cp ~/.claude/CLAUDE.md.bak.YYYYMMDD_HHMMSS ~/.claude/CLAUDE.md
```

### Step 1: Audit Current State

```
Task Progress:
- [ ] Create backup (Step 0)
- [ ] Read ~/.claude/CLAUDE.md
- [ ] Count total lines
- [ ] List all ## sections with line counts
- [ ] Identify sections >20 lines
```

### Step 2: Classify Each Section

For each section >20 lines, determine:

1. **Frequency**: How often is this information needed?
2. **Complexity**: Does it contain code blocks, tables, or detailed steps?
3. **Reusability**: Could other users benefit from this as a skill?

### Step 3: Propose Changes

Present optimization plan in this format:

```markdown
## Optimization Proposal

**Current**: X lines
**After**: Y lines (Z% reduction)

| Section | Lines | Action | Destination |
|---------|-------|--------|-------------|
| Section A | 50 | Move to references | ~/.claude/references/section_a.md |
| Section B | 80 | Extract to skill | skill-name/ |
| Section C | 5 | Keep | - |
```

### Step 3.5: Pre-execution Verification Checklist

**CRITICAL**: Before executing any changes, verify information completeness.

For each section being moved or modified:

1. **Extract key items** to verify:
   - Credentials/passwords/API keys
   - Critical rules ("never do X", "always do Y")
   - Specific values (ports, IPs, URLs, paths)
   - Code snippets that are frequently referenced
   - Cross-references to other sections

2. **Create verification checklist**:
   ```markdown
   ## Verification Checklist for [Section Name]

   | Key Item | Original Location | New Location | Verified |
   |----------|-------------------|--------------|----------|
   | Server IP 47.96.x.x | Line 123 | infrastructure.md:15 | [ ] |
   | "Never push to main" rule | Line 45 | Kept in CLAUDE.md | [ ] |
   | Login credentials | Line 200 | api-login.md:30 | [ ] |
   ```

3. **Check cross-references**:
   - If Section A references Section B, ensure links work after moving
   - Update any relative paths to absolute paths if needed

### Step 4: Execute Changes

After user approval AND verification checklist complete:

1. Create reference files in `~/.claude/references/`
2. Update CLAUDE.md with pointers to moved content
3. Create skills if applicable
4. **Verify each checklist item exists in new location**
5. Report final line count

### Step 5: Post-optimization Testing

Verify that Claude can still discover moved content:

1. **Test discoverability** - Ask questions that require moved content:
   ```
   Test queries to run:
   - "How do I connect to the production database?"
   - "What are the deployment steps for [service]?"
   - "Show me the credentials for [system]"
   ```

2. **Verify pointer functionality** - Each "See `reference.md`" link should work:
   ```bash
   # Check all referenced files exist
   grep -oh '`~/.claude/references/[^`]*`' ~/.claude/CLAUDE.md | \
     sed 's/`//g' | while read f; do
       eval test -f "$f" && echo "✓ $f" || echo "✗ MISSING: $f"
     done
   ```

3. **Compare with backup** - Ensure no unintended deletions:
   ```bash
   diff ~/.claude/CLAUDE.md.bak.* ~/.claude/CLAUDE.md | grep "^<" | head -20
   ```

4. **Document results**:
   ```markdown
   ## Optimization Results

   | Metric | Before | After |
   |--------|--------|-------|
   | Total lines | X | Y |
   | Reduction | - | Z% |
   | References created | - | N files |
   | Skills extracted | - | M skills |

   **Verification**: All N checklist items verified ✓
   **Testing**: All K test queries returned correct information ✓
   ```

## Reference File Format

When moving content to `~/.claude/references/`:

```markdown
# [Section Title]

[Full original content, possibly enhanced with additional examples]
```

## CLAUDE.md Pointer Format

Replace moved sections with:

```markdown
## [Section Title]

[One-line summary]. See `~/.claude/references/[filename].md`
```

## Best Practices

- **Keep core principles visible**: Rules like "never do X" should stay in CLAUDE.md
- **Group related references**: Combine small related sections into one reference file
- **Preserve quick commands**: Keep frequently-used command snippets in CLAUDE.md
- **Test after optimization**: Ensure Claude can still find moved information

## Common Patterns

### Pattern: Infrastructure/Credentials
**Before**: Full API examples, deployment scripts, server lists
**After**: One-line pointer to `~/.claude/references/infrastructure.md`

### Pattern: Code Generation Rules
**Before**: 50+ lines of coding standards with examples
**After**: Keep bullet-point rules, move examples to references

### Pattern: Reusable Workflows
**Before**: Complete scripts embedded in CLAUDE.md
**After**: Extract to skill with scripts/ directory

## Project-Level vs User-Level CLAUDE.md

This skill handles both types, but strategies differ:

### User-Level (`~/.claude/CLAUDE.md`)

| Aspect | Approach |
|--------|----------|
| **Reference location** | `~/.claude/references/` |
| **Scope** | Personal preferences, global rules |
| **Sharing** | Not shared, personal only |
| **Size target** | 100-200 lines ideal |

### Project-Level (`/path/to/project/CLAUDE.md`)

| Aspect | Approach |
|--------|----------|
| **Reference location** | `docs/` or `.claude/` in project root |
| **Scope** | Project-specific patterns, architecture |
| **Sharing** | Committed to git, shared with team |
| **Size target** | 300-600 lines acceptable (more project context needed) |

### Key Differences

1. **Reference paths**: Use relative paths for project-level (`docs/best-practices/`)
2. **Git considerations**: Project references are versioned with code
3. **Team alignment**: Project CLAUDE.md should reflect team consensus
4. **Update frequency**: Project-level changes more often as code evolves

### Project-Level Pointer Format

```markdown
## [Section Title]

[Summary]. See `docs/06-best-practices/[topic].md`
```

**Note**: For project CLAUDE.md, prefer `docs/` over hidden directories for discoverability by human team members.

## Bundled Reference

- `references/progressive_disclosure_principles.md` — progressive disclosure の設計原則の詳細