Back to Details

claude-md-progressive-disclosurer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CLAUDE.md Progressive Disclosure Optimizer

CLAUDE.md 渐进式披露优化工具

Analyze and optimize user CLAUDE.md files to reduce context overhead while preserving functionality.
分析并优化用户的CLAUDE.md文件，在保留功能的同时减少上下文开销。

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
  1. 备份原始文件
  2. 审计当前状态（列出所有章节及行数）
  3. 分类每个章节（遵循以下标准）
  4. 提出优化方案，包含前后对比表
  5. 验证信息完整性清单后再执行更改
  6. 执行已批准的修改
  7. 测试已迁移内容的可发现性

Section Classification

章节分类

Analyze each section and classify:
CategoryCriteriaAction
Keep in CLAUDE.mdCore principles, short rules (<10 lines), frequently neededKeep as-is
Move to references/Detailed procedures, code examples, troubleshooting guidesCreate 
~/.claude/references/<name>.md
Extract to skillReusable workflows, scripts, domain-specific knowledgeCreate skill in skills repository
RemoveDuplicates existing skills, outdated, or unnecessaryDelete after confirmation
分析每个章节并进行分类：
类别判断标准操作
保留在CLAUDE.md中核心原则、简短规则（少于10行）、高频需求内容保持原样
移至references/详细流程、代码示例、故障排查指南创建
~/.claude/references/<name>.md
提取为Skill可复用工作流、脚本、领域特定知识在技能仓库中创建Skill
移除与现有Skill重复、过时或非必要内容确认后删除

Exceptions to Size Guidelines

篇幅规则的例外情况

Even if a section is >50 lines, KEEP in CLAUDE.md if any of these apply:
ExceptionReasonExample
Safety-criticalConsequences of forgetting are severeDeployment protocols, "never force push to main"
High-frequencyReferenced in most conversationsCore development patterns, common commands
Easy to violateClaude tends to ignore when not visibleCode style rules, permission requirements
Security-sensitiveMust be always enforcedProduction 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.
即使章节超过50行，若符合以下任一条件，仍需保留在CLAUDE.md中：
例外类型原因示例
安全关键型遗忘会导致严重后果部署协议、「禁止强制推送到main分支」
高频使用型大多数对话中都会引用核心开发模式、常用命令
易违反型Claude未直接可见时容易忽略代码风格规则、权限要求
安全敏感型必须始终强制执行生产环境访问限制、数据处理规则
经验法则：若遗忘规则可能导致生产事故、数据丢失或安全漏洞，无论篇幅长短都需保持可见。

Optimization Workflow

优化工作流

Step 0: Backup Original File

步骤0：备份原始文件

CRITICAL: Always create a backup before any changes.
bash
undefined
重要提示：进行任何更改前务必创建备份。
bash
undefined

Create timestamped backup

创建带时间戳的备份

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

For project-level CLAUDE.md

针对项目级CLAUDE.md

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

If issues found after optimization:
```bash
cp CLAUDE.md CLAUDE.md.bak.$(date +%Y%m%d_%H%M%S)

若优化后出现问题：
```bash

Restore from backup

从备份恢复

cp ~/.claude/CLAUDE.md.bak.YYYYMMDD_HHMMSS ~/.claude/CLAUDE.md
undefined
cp ~/.claude/CLAUDE.md.bak.YYYYMMDD_HHMMSS ~/.claude/CLAUDE.md
undefined

Step 1: Audit Current State

步骤1：审计当前状态

Task Progress:
- [ ] Create backup (Step 0)
- [ ] Read ~/.claude/CLAUDE.md
- [ ] Count total lines
- [ ] List all ## sections with line counts
- [ ] Identify sections >20 lines
任务进度：
- [ ] 创建备份（步骤0）
- [ ] 读取~/.claude/CLAUDE.md
- [ ] 统计总行数
- [ ] 列出所有##章节及行数
- [ ] 识别超过20行的章节

Step 2: Classify Each Section

步骤2：分类每个章节

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?
针对每个超过20行的章节，判断：
  1. 使用频率：该信息需要多久引用一次？
  2. 复杂度：是否包含代码块、表格或详细步骤？
  3. 可复用性：其他用户是否能从该内容中受益并将其作为Skill？

Step 3: Propose Changes

步骤3：提出修改方案

Present optimization plan in this format:
markdown
undefined
按以下格式呈现优化计划：
markdown
undefined

Optimization Proposal

优化提案

Current: X lines After: Y lines (Z% reduction)
SectionLinesActionDestination
Section A50Move to references~/.claude/references/section_a.md
Section B80Extract to skillskill-name/
Section C5Keep-
undefined
当前状态：X行 优化后：Y行（减少Z%）
章节行数操作目标位置
章节A50移至参考文件~/.claude/references/section_a.md
章节B80提取为Skillskill-name/
章节C5保留-
undefined

Step 3.5: Pre-execution Verification Checklist

步骤3.5：执行前验证清单

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
重要提示：执行任何更改前，务必验证信息完整性。
针对每个要迁移或修改的章节：
  1. 提取关键内容进行验证：
    • 凭证/密码/API密钥
    • 关键规则（「切勿执行X」、「必须执行Y」）
    • 特定值（端口、IP、URL、路径）
    • 高频引用的代码片段
    • 指向其他章节的交叉引用
  2. 创建验证清单：
    markdown
    ## [章节名称]验证清单

| 关键内容 | 原始位置 | 新位置 | 是否已验证 |
|----------|-------------------|--------------|----------|
| 服务器IP 47.96.x.x | 第123行 | infrastructure.md:15 | [ ] |
| 「禁止推送到main分支」规则 | 第45行 | 保留在CLAUDE.md中 | [ ] |
| 登录凭证 | 第200行 | api-login.md:30 | [ ] |
  3. 检查交叉引用：
    • 若章节A引用章节B，确保迁移后链接仍可用
    • 必要时将相对路径更新为绝对路径

Step 4: Execute Changes

步骤4：执行更改

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
获得用户批准并完成验证清单后：
  1. 在
    ~/.claude/references/
    中创建参考文件
  2. 更新CLAUDE.md，添加指向已迁移内容的指针
  3. 按需创建Skill
  4. 验证清单中的每个内容项都存在于新位置
  5. 报告最终行数

Step 5: Post-optimization Testing

步骤5：优化后测试

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 ✓
验证Claude仍能发现已迁移的内容：
  1. 测试可发现性 - 提出需要使用已迁移内容的问题：
    建议执行的测试查询：
- "我如何连接到生产数据库？"
- "[服务]的部署步骤是什么？"
- "显示[系统]的凭证"
  2. 验证指针功能 - 每个「查看
    reference.md
    」链接都应可用：
    bash
    # 检查所有引用文件是否存在
grep -oh '`~/.claude/references/[^`]*`' ~/.claude/CLAUDE.md | \
  sed 's/`//g' | while read f; do
    eval test -f "$f" && echo "✓ $f" || echo "✗ 缺失：$f"
  done
  3. 与备份对比 - 确保没有意外删除内容：
    bash
    diff ~/.claude/CLAUDE.md.bak.* ~/.claude/CLAUDE.md | grep "^<" | head -20
  4. 记录结果：
    markdown
    ## 优化结果

| 指标 | 优化前 | 优化后 |
|--------|--------|-------|
| 总行数 | X | Y |
| 减少比例 | - | Z% |
| 创建的参考文件数 | - | N个 |
| 提取的Skill数 | - | M个 |

**验证**：所有N项清单内容已验证 ✓
**测试**：所有K项测试查询返回正确信息 ✓

Reference File Format

参考文件格式

When moving content to 
~/.claude/references/
:
markdown
undefined
将内容移至
~/.claude/references/
时遵循以下格式：
markdown
undefined

[Section Title]

[章节标题]

[Full original content, possibly enhanced with additional examples]
undefined
[完整原始内容，可酌情添加更多示例]
undefined

CLAUDE.md Pointer Format

CLAUDE.md指针格式

Replace moved sections with:
markdown
undefined
用以下内容替换已迁移的章节：
markdown
undefined

[Section Title]

[章节标题]

[One-line summary]. See 
~/.claude/references/[filename].md
undefined
[一行摘要]。查看
~/.claude/references/[filename].md
undefined

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
  • 核心原则保持可见：类似「切勿执行X」的规则应保留在CLAUDE.md中
  • 相关参考内容分组：将小型相关章节合并到一个参考文件中
  • 保留快速命令：将高频使用的命令片段保留在CLAUDE.md中
  • 优化后测试：确保Claude仍能找到已迁移的信息

Common Patterns

常见模式

Pattern: Infrastructure/Credentials

模式：基础设施/凭证

Before: Full API examples, deployment scripts, server lists After: One-line pointer to 
~/.claude/references/infrastructure.md
优化前：完整API示例、部署脚本、服务器列表 优化后：一行指针指向
~/.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
优化前：50+行带示例的编码标准 优化后：保留要点规则，将示例移至参考文件

Pattern: Reusable Workflows

模式：可复用工作流

Before: Complete scripts embedded in CLAUDE.md After: Extract to skill with scripts/ directory
优化前：完整脚本嵌入在CLAUDE.md中 优化后：提取为带scripts/目录的Skill

Project-Level vs User-Level CLAUDE.md

项目级与用户级CLAUDE.md的区别

This skill handles both types, but strategies differ:
本Skill支持两种类型的文件，但策略有所不同：

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

用户级（
~/.claude/CLAUDE.md
）

AspectApproach
Reference location
~/.claude/references/
ScopePersonal preferences, global rules
SharingNot shared, personal only
Size target100-200 lines ideal
维度处理方式
参考文件位置
~/.claude/references/
适用范围个人偏好、全局规则
共享方式不共享，仅个人使用
理想篇幅100-200行

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

项目级（
/path/to/project/CLAUDE.md
）

AspectApproach
Reference location
docs/
or 
.claude/
in project root
ScopeProject-specific patterns, architecture
SharingCommitted to git, shared with team
Size target300-600 lines acceptable (more project context needed)
维度处理方式
参考文件位置项目根目录下的
docs/
或
.claude/
适用范围项目特定模式、架构
共享方式提交至git，与团队共享
可接受篇幅300-600行（需更多项目上下文）

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
  1. 参考路径：项目级使用相对路径（
    docs/best-practices/
    ）
  2. Git考量：项目参考文件随代码版本化
  3. 团队对齐：项目CLAUDE.md应反映团队共识
  4. 更新频率：项目级文件随代码演进更频繁更新

Project-Level Pointer Format

项目级指针格式

markdown
undefined
markdown
undefined

[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.
[摘要]。查看
docs/06-best-practices/[topic].md

**注意**：对于项目级CLAUDE.md，优先使用`docs/`而非隐藏目录，以便团队成员更容易发现。

Bundled Reference

内置参考文件

  • references/progressive_disclosure_principles.md
    — progressive disclosure の設計原則の詳細
  • references/progressive_disclosure_principles.md
    — 渐进式披露设计原则的详细内容