claude-md-progressive-disclosurer

CLAUDE.md 渐进式披露优化器

分析并优化用户的 CLAUDE.md 文件，在保留功能的同时减少上下文开销。

快速开始

1. 备份 原始文件
2. 审查 当前状态（列出所有章节及其行数）
3. 根据以下标准对每个章节进行分类
4. 提出 优化方案，并附上优化前后对比表
5. 在执行前验证信息完整性清单
6. 执行已批准的更改
7. 测试移动后的内容仍可查找

章节分类

分析每个章节并进行分类：

类别	标准	操作
保留在 CLAUDE.md 中	核心原则、简短规则（<10 行）、经常需要的信息	原样保留
移至 references/	详细流程、代码示例、故障排除指南	创建 ~/.claude/references/<name>.md
提取为技能	可复用工作流、脚本、特定领域知识	在技能仓库中创建技能
删除	与现有技能重复、已过时或不必要	确认后删除

大小指南的例外情况

即使章节超过 50 行，只要符合以下任一条件，也应保留在 CLAUDE.md 中：

例外情况	原因	示例
安全关键	忘记后果严重	部署协议、“绝不强制推送到 main”
高频使用	大多数对话中都会引用	核心开发模式、常用命令
容易违反	不可见时 Claude 往往会忽略	代码风格规则、权限要求
涉及安全	必须始终强制执行	生产环境访问限制、数据处理规则

经验法则：如果忘记规则可能导致生产事故、数据丢失或安全漏洞，无论长度如何，都应保持其可见。

优化工作流

步骤 0：备份原始文件

重要：进行任何更改前，务必先创建备份。

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

如果优化后发现问题：

# Restore from backup
cp ~/.claude/CLAUDE.md.bak.YYYYMMDD_HHMMSS ~/.claude/CLAUDE.md

步骤 1：审查当前状态

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

步骤 2：对每个章节进行分类

对于每个超过 20 行的章节，判断：

1. 使用频率：需要这些信息的频率如何？
2. 复杂度：是否包含代码块、表格或详细步骤？
3. 可复用性：其他用户能否从中受益并将其作为技能使用？

步骤 3：提出更改

按以下格式提供优化方案：

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

步骤 3.5：执行前验证清单

重要：执行任何更改前，务必验证信息完整性。

对于每个要移动或修改的章节：

1. 提取关键项目进行验证：

   • 凭据／密码／API 密钥
   • 关键规则（“绝不执行 X”“始终执行 Y”）
   • 特定值（端口、IP、URL、路径）
   • 经常引用的代码片段
   • 对其他章节的交叉引用

2. 创建验证清单：

   ## 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. 检查交叉引用：

   • 如果章节 A 引用了章节 B，确保移动后链接仍然有效
   • 必要时，将相对路径更新为绝对路径

步骤 4：执行更改

获得用户批准且验证清单已完成后：

1. 在 ~/.claude/references/ 中创建参考文件
2. 更新 CLAUDE.md，为已移动的内容添加指引
3. 如适用，创建技能
4. 验证每个清单项目都存在于新位置
5. 报告最终行数

步骤 5：优化后测试

验证 Claude 仍能找到已移动的内容：

1. 测试可查找性——提出需要使用已移动内容才能回答的问题：

   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. 验证指引功能——确保每个 “See reference.md” 链接都有效：

   # 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. 与备份进行比较——确保没有意外删除：

   diff ~/.claude/CLAUDE.md.bak.* ~/.claude/CLAUDE.md | grep "^<" | head -20
   

4. 记录结果：

   ## 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/references/ 时：

# [Section Title]

[Full original content, possibly enhanced with additional examples]

CLAUDE.md 指引格式

将已移动的章节替换为：

## [Section Title]

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

最佳实践

• 让核心原则清晰可见：像“绝不要做 X”这样的规则应保留在 CLAUDE.md 中
• 将相关参考资料归为一组：把相关的小节合并到一个参考文件中
• 保留快捷命令：将常用命令片段保留在 CLAUDE.md 中
• 优化后进行测试：确保 Claude 仍能找到移走的信息

常见模式

模式：基础设施／凭据

之前：完整的 API 示例、部署脚本、服务器列表 之后：添加一行指向 ~/.claude/references/infrastructure.md 的链接

模式：代码生成规则

之前：包含示例的 50 多行编码规范 之后：保留项目符号规则，将示例移至参考资料中

模式：可复用工作流

之前：将完整脚本嵌入 CLAUDE.md 中 之后：提取为包含 scripts/ 目录的技能

项目级与用户级 CLAUDE.md

此技能适用于这两种类型，但策略有所不同：

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

方面	方法
参考资料位置	~/.claude/references/
范围	个人偏好、全局规则
共享方式	不共享，仅供个人使用
目标大小	理想情况下为 100-200 行

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

方面	方法
参考资料位置	项目根目录中的 docs/ 或 .claude/
范围	项目特定模式、架构
共享方式	提交到 git，与团队共享
目标大小	300-600 行可接受（需要更多项目背景信息）

主要区别

1. 参考路径：项目级文件使用相对路径（docs/best-practices/）
2. Git 注意事项：项目参考资料与代码一起进行版本控制
3. 团队一致性：项目 CLAUDE.md 应体现团队共识
4. 更新频率：项目级文件会随着代码演进而更频繁地变更

项目级指针格式

## [Section Title]

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

注意：对于项目 CLAUDE.md，优先使用 docs/ 而非隐藏目录，以便团队成员查找。

附带的参考资料

• references/progressive_disclosure_principles.md — progressive disclosure 设计原则的详细说明