# Claude Md Expert

> 创建、更新和优化 CLAUDE.md 配置文件。当用户请求初始化 CLAUDE.md、改进项目配置、添加编码规范、或询问"如何让 Claude 记住这个设置"时触发。

- Skill: `wwsun/claude-md-expert` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wwsun/claude-md-expert`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wwsun/claude-md-expert/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wwsun (https://skillmd.com/u/wwsun)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wwsun/claude-md-expert

---


# CLAUDE.md 管理指南

## 核心原则

### 少即是多

- **控制指令数量**：前沿 LLM 能可靠遵循约 150-200 条指令，Claude Code 系统提示已占用约 50 条
- **长度限制**：根目录 CLAUDE.md 建议 < 300 行，越短越好（参考：HumanLayer 仅 60 行）
- **通用性优先**：只包含每个会话都需要的信息，避免任务特定内容

### 三要素内容

| 类型     | 描述               | 示例                         |
| :------- | :----------------- | :--------------------------- |
| **WHAT** | 技术栈、项目结构   | 框架版本、目录布局、包管理器 |
| **WHY**  | 项目目的、设计决策 | 业务背景、架构选择原因       |
| **HOW**  | 开发流程、验证方式 | 构建命令、测试步骤、部署流程 |

## 渐进式披露

将详细文档拆分到独立文件：

```
agent_docs/
├── building.md          # 构建指南
├── testing.md           # 测试规范
├── code_conventions.md  # 代码规范
└── architecture.md      # 架构说明
```

在 CLAUDE.md 中引用：

```markdown
## 扩展文档

需要时参阅：

- `agent_docs/building.md` - 构建和部署
- `agent_docs/testing.md` - 测试相关
```

## 避免的反模式

1. **不要用作 linter**：代码风格用 ESLint/Prettier 处理
2. **不要自动生成**：`/init` 产出仅供参考，需手工精炼
3. **不要堆砌命令**：只保留最常用的关键命令
4. **不要放代码片段**：易过时，改用文件引用 `file:///path#L10-20`

## 模板

```markdown
# 项目名

简短的项目描述。

## 常用命令

- `pnpm dev` - 开发服务器
- `pnpm build` - 生产构建
- `pnpm test` - 运行测试

## 代码规范

- ES 模块语法 (import/export)
- 解构导入
- TypeScript 严格模式

## 工作流程

- 修改代码后运行 typecheck
- 提交前确保测试通过

## 扩展文档

详细信息见 `agent_docs/` 目录。
```

## 文件位置层级

| 位置                     | 范围 | 用途                       |
| :----------------------- | :--- | :------------------------- |
| `~/.claude/CLAUDE.md`    | 全局 | 个人通用偏好               |
| `项目根/CLAUDE.md`       | 项目 | 团队共享配置（提交到 git） |
| `项目根/CLAUDE.local.md` | 项目 | 个人本地配置（gitignore）  |
| `子目录/CLAUDE.md`       | 模块 | 特定模块上下文             |

## 工作流程

1. **评估现状**：检查是否存在 CLAUDE.md
2. **收集需求**：了解用户需要记录什么
3. **分类内容**：区分通用 vs 任务特定信息
4. **精简表达**：用最少的文字传达清楚
5. **迭代优化**：鼓励用户使用 `#` 快捷键实时补充规则

## 使用 # 快捷键

在 Claude Code 中按 `#` 键可快速添加指令到 CLAUDE.md：

Claude 会自动将此添加到对应的 CLAUDE.md 文件。