claude-md-improver

CLAUDE.md 改进器

审计、评估并改进代码库中的 CLAUDE.md 文件，确保 Claude Code 拥有最佳的项目上下文。

此技能可以写入 CLAUDE.md 文件。 在呈现质量报告并获得用户批准后，它会用有针对性的改进来更新 CLAUDE.md 文件。

工作流

阶段 1：发现

查找仓库中所有 CLAUDE.md 文件：

find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50

文件类型与位置：

类型	位置	用途
项目根目录	./CLAUDE.md	主要项目上下文（检入 git，与团队共享）
本地覆盖	./.claude.local.md	个人/本地设置（被 gitignore，不共享）
全局默认	~/.claude/CLAUDE.md	所有项目的用户级默认值
包特定	./packages/*/CLAUDE.md	monorepo 中的模块级上下文
子目录	任意嵌套位置	功能/领域特定的上下文

注意： Claude 会自动发现父目录中的 CLAUDE.md 文件，使 monorepo 设置自动生效。

阶段 2：质量评估

对每个 CLAUDE.md 文件，根据质量标准进行评估。详见 references/quality-criteria.md 获取详细评分标准。

快速评估清单：

标准	权重	检查
已记录的命令/工作流	高	是否存在构建/测试/部署命令？
架构清晰度	高	Claude 能否理解代码库结构？
非显而易见的模式	中	是否记录了陷阱和怪异之处？
简洁性	中	没有冗长的解释或显而易见的信息？
时效性	高	是否反映当前代码库状态？
可操作性	高	指令是否可执行，而非含糊不清？

质量评分：

• A (90-100)：全面、最新、可操作
• B (70-89)：覆盖良好，有轻微缺口
• C (50-69)：基本信息，缺少关键部分
• D (30-49)：稀疏或过时
• F (0-29)：缺失或严重过时

阶段 3：质量报告输出

务必在进行任何更新之前输出质量报告。

格式：

## CLAUDE.md Quality Report

### Summary
- Files found: X
- Average score: X/100
- Files needing update: X

### File-by-File Assessment

#### 1. ./CLAUDE.md (Project Root)
**Score: XX/100 (Grade: X)**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | X/20 | ... |
| Architecture clarity | X/20 | ... |
| Non-obvious patterns | X/15 | ... |
| Conciseness | X/15 | ... |
| Currency | X/15 | ... |
| Actionability | X/15 | ... |

**Issues:**
- [List specific problems]

**Recommended additions:**
- [List what should be added]

#### 2. ./packages/api/CLAUDE.md (Package-specific)
...

阶段 4：有针对性的更新

输出质量报告后，在更新前询问用户确认。

更新指南（关键）：

1. 仅提出有针对性的添加 - 专注于真正有用的信息：

   • 分析期间发现的命令或工作流
   • 代码中发现的陷阱或非显而易见的模式
   • 之前不清楚的包关系
   • 有效的测试方法
   • 配置怪异之处

2. 保持最小化 - 避免：

   • 重述代码中显而易见的内容
   • 已涵盖的通用最佳实践
   • 不太可能再次发生的一次性修复
   • 一行足以说明时却使用冗长解释

3. 展示差异 - 对于每项更改，展示：

   • 要更新哪个 CLAUDE.md 文件
   • 具体的添加内容（作为差异或引用块）
   • 简要说明为何这有助于未来的会话

差异格式：

### Update: ./CLAUDE.md

**Why:** Build command was missing, causing confusion about how to run the project.

```diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev  # Start development server on port 3000
+ ```

### Phase 5: Apply Updates

After user approval, apply changes using the Edit tool. Preserve existing content structure.

## Templates

See [references/templates.md](references/templates.md) for CLAUDE.md templates by project type.

## Common Issues to Flag

1. **Stale commands**: Build commands that no longer work
2. **Missing dependencies**: Required tools not mentioned
3. **Outdated architecture**: File structure that's changed
4. **Missing environment setup**: Required env vars or config
5. **Broken test commands**: Test scripts that have changed
6. **Undocumented gotchas**: Non-obvious patterns not captured

## User Tips to Share

When presenting recommendations, remind users:

- **`#` key shortcut**: During a Claude session, press `#` to have Claude auto-incorporate learnings into CLAUDE.md
- **Keep it concise**: CLAUDE.md should be human-readable; dense is better than verbose
- **Actionable commands**: All documented commands should be copy-paste ready
- **Use `.claude.local.md`**: For personal preferences not shared with team (add to `.gitignore`)
- **Global defaults**: Put user-wide preferences in `~/.claude/CLAUDE.md`

## What Makes a Great CLAUDE.md

**Key principles:**
- Concise and human-readable
- Actionable commands that can be copy-pasted
- Project-specific patterns, not generic advice
- Non-obvious gotchas and warnings

**Recommended sections** (use only what's relevant):
- Commands (build, test, dev, lint)
- Architecture (directory structure)
- Key Files (entry points, config)
- Code Style (project conventions)
- Environment (required vars, setup)
- Testing (commands, patterns)
- Gotchas (quirks, common mistakes)
- Workflow (when to do what)