claude-md-management

CLAUDE.md 管理

提供全面的 CLAUDE.md 文件管理能力，包括审查、质量评估和针对性改进。此技能通过维护高质量的文档文件，确保 Claude Code 拥有最佳项目上下文。

概述

CLAUDE.md 文件是向 Claude Code 会话提供项目专属上下文的主要机制。此技能管理 CLAUDE.md 文件的完整生命周期：发现、质量评估、报告和改进。它采用 5 阶段工作流，确保文档内容最新、可执行且简洁。

此技能依据 6 个维度的标准化质量标准评估 CLAUDE.md 文件：命令/工作流、架构清晰度、不显而易见的模式、简洁性、时效性和可执行性。每个文件都会获得一个分数（0-100）和字母等级（A-F），并附上具体的改进建议。

适用场景

在以下情况使用此技能：

• 用户明确要求“检查”“审查”“更新”“改进”“修复”或“维护”CLAUDE.md
• 用户提到“CLAUDE.md 质量”“文档审查”或“项目记忆优化”
• 新项目需要从头创建 CLAUDE.md
• 用户询问如何改进 Claude 对代码库的理解
• 文档内容已过时
• 开始处理新的代码库，需要了解现有文档
• 用户在会话中按下 #，将学到的内容纳入 CLAUDE.md

触发语句：“审查 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	单体仓库中的模块级上下文
子目录	任意嵌套位置	特定功能/领域的上下文

阶段 2：质量评估

对于每个 CLAUDE.md 文件，阅读 references/quality-criteria.md，并根据以下标准进行评估：

标准	权重	检查内容
命令/工作流	20 分	是否包含可用的构建/测试/部署命令？
架构清晰度	20 分	Claude 能否理解代码库结构？
不显而易见的模式	15 分	是否记录了易踩的坑和特殊行为？
简洁性	15 分	内容是否信息密集且没有填充内容？
时效性	15 分	内容是否反映代码库的当前状态？
可执行性	15 分	指令是否可执行并可直接复制粘贴？

**质量分数：**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]

阶段 4：针对性更新

输出报告后，先征求用户确认，再进行更新。

阅读 references/update-guidelines.md，了解详细的更新原则。

关键原则：

1. 仅提出有针对性的补充——命令、易踩的坑、模式、配置
2. 保持精简——避免显而易见的信息、通用建议和一次性修复
3. 展示差异——文件、变更（差异格式）、说明

差异格式：

### Update: ./CLAUDE.md
**Why:** [Brief explanation of why this helps]

```diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev
+ ```

### Phase 5: Apply Updates

After user approval, use Edit tool to apply changes. Preserve existing content structure.

## Examples

### Example 1: Quality Assessment

**User request:** "Check if my CLAUDE.md is good"

**Response:**
~~~markdown
## CLAUDE.md Quality Report

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

### File-by-File Assessment

#### 1. ./CLAUDE.md
**Score: 65/100 (Grade: C)**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | 10/20 | Only npm install documented |
| Architecture clarity | 15/20 | Basic tree, missing module relationships |
| Non-obvious patterns | 5/15 | No gotchas documented |
| Conciseness | 15/15 | Concise and dense |
| Currency | 10/15 | Some outdated paths |
| Actionability | 10/15 | Some vague instructions |

**Issues:**
- Missing test command
- Missing build command
- No documentation of auth flow complexity
- References to old src/structure

**Recommended additions:**
- Add Commands section with test/build
- Document auth module gotcha
- Update architecture paths

示例 2：从头创建

用户请求：“为这个 React 项目创建一个 CLAUDE.md”

回复：

I'll create a CLAUDE.md for your React project. Let me first analyze the codebase structure.

[Scans package.json, src/, and key config files]

## CLAUDE.md Quality Report

### Summary
- Files found: 0
- Creating new CLAUDE.md at project root

### Proposed CLAUDE.md Content:

# Project Name

## Commands

| Command | Description |
|---------|-------------|
| `npm install` | Install dependencies |
| `npm run dev` | Start dev server (Vite on port 5173) |
| `npm run build` | Production build |
| `npm run test` | Run Vitest tests |
| `npm run lint` | ESLint check |

## Architecture

src/ ├── components/ # 可复用的 UI 组件 ├── pages/ # 路由页面 ├── hooks/ # 自定义 React hooks ├── lib/ # 实用工具和 API 客户端 └── main.tsx # 入口点

## Gotchas

- Vite requires files in `public/` for static assets
- State updates in `useEffect` need proper dependency arrays

要创建此文件吗？

### Example 3: Update Proposal

**User request:** "Update my CLAUDE.md with what you learned"

**Response:**
```markdown
### Update: ./CLAUDE.md

**Why:** Discovered that tests require database setup which wasn't documented.

```diff
## Testing

+ **Prerequisites:** Start test database first with `docker-compose up -d test-db`
+ `npm run test` - Run all tests
+ `npm run test:unit` - Unit tests only (no DB required)

还发现 API_BASE_URL 存在问题：

## Environment

- `API_BASE_URL` - API endpoint (default: localhost:3000)
+ `API_BASE_URL` - API endpoint (required for production, defaults to http://localhost:3000 in dev)

要应用这些更改吗？

## Best Practices

1. **Always read references before acting**: Quality criteria, templates, and update guidelines contain essential details
2. **Report before editing**: Never modify CLAUDE.md without first presenting a quality report
3. **Preserve existing structure**: When updating, maintain the existing organization and style
4. **Be project-specific**: Only add information specific to this codebase, not generic advice
5. **Verify commands work**: Before suggesting commands, mentally or actually verify they execute correctly
6. **Use progressive disclosure**: Keep SKILL.md lean, reference detailed rubrics in separate files
7. **Score consistently**: Apply the same scoring standards across all files for fair comparison

## Constraints and Warnings

1. **Never modify without approval**: Always get user confirmation before editing CLAUDE.md files
2. **Don't remove content without asking**: If suggesting deletions, explicitly mark them and get approval
3. **Respect `.claude.local.md`**: These are personal settings; never suggest modifying them in shared docs
4. **Avoid generic advice**: Do not add "write good code" type content - focus on project-specific patterns
5. **Keep diffs concise**: Show only the actual changes, not entire file contents
6. **Verify file paths**: Ensure all referenced files exist before documenting them
7. **Score objectively**: Use the rubric consistently; don't inflate scores for incomplete documentation