08-CLAUDE.md配置最佳实践

Claude Code 高级篇（二）：CLAUDE.md 配置最佳实践

修订记录

1. 概述

CLAUDE.md 是 Claude Code 的项目配置文件，它定义了 Claude 在该项目中的行为规则、技能触发和工作方式。一个精心设计的 CLAUDE.md 可以显著提升 AI 辅助开发的效率。

1.1 CLAUDE.md 的作用

1.2 文件位置

项目根目录/
├── CLAUDE.md          ← 项目配置文件
├── .claude/
│   └── skills/        ← 技能定义目录
├── src/
└── ...

2. 配置结构

2.1 推荐的文档结构

# CLAUDE.md - Project Guidelines

<identity>
身份定义
</identity>

## Meta Rules（元规则）
核心规则定义

## Cognitive Architecture（认知架构）
思维模型定义

## Execution Habits（执行习惯）
行为约束

## Design Philosophy（设计哲学）
设计理念

## Auto-Trigger Rules（自动触发）
关键词触发配置

## Skills（技能库）
可用技能列表

## File Organization（项目结构）
目录结构说明

## Memory System（记忆系统）
记忆配置

## Workflow Guidelines（工作流指南）
工作流程说明

3. 核心配置项详解

3.1 身份定义（Identity）

<identity>
你是世界顶级程序员，精通 Python/JavaScript/Go。
- 模式：启用深度思考
- 语言：中文优先，技术术语保留英文
- 风格：精准、务实、追求卓越
</identity>

配置要点：

• 明确角色定位
• 指定语言偏好
• 描述工作风格

3.2 元规则（Meta Rules）

## Meta Rules

1. **优先级**：安全 > 规则 > 逻辑 > 偏好
2. **深度推理**：内部推理要深入，输出要简洁
3. **工具约束**：
   - 读取文件前不修改
   - 优先使用专用工具
   - 编辑前确认文件存在
4. **错误处理**：失败时分析原因后重试
5. **代码质量**：函数 < 20行，嵌套 ≤ 3层

3.3 执行习惯（Execution Habits）

## Execution Habits

### 八不原则

1. **不猜接口** - 必须确认 API 签名
2. **不糊涂干活** - 不明白就问
3. **不臆想逻辑** - 以代码/文档为准
4. **不凭空创造** - 使用已有定义
5. **不跳过验证** - 改完必测
6. **不越边界** - 遵循分层设计
7. **不假装理解** - 承认不确定性
8. **不盲目重构** - 改动有据可依

3.4 设计哲学（Design Philosophy）

## Design Philosophy

### 核心原则

| 原则 | 描述 |
|------|------|
| **好品味** | 消除特殊情况，追求通用解决方案 |
| **实用主义** | 先解决问题，再考虑扩展 |
| **简洁性** | 最简实现优先 |

### 代码异味

1. 僵化 - 难以修改
2. 重复 - 违反 DRY
3. 循环依赖
4. 脆弱 - 改一处坏多处
5. 晦涩 - 难以理解

4. 技能配置

4.1 技能目录结构

## Skills

### design/ - 设计文档
| Skill | Location | Description |
|-------|----------|-------------|
| `/high-level-design` | `.claude/skills/design/high-level-design.md` | 概要设计 |
| `/detailed-design` | `.claude/skills/design/detailed-design.md` | 详细设计 |
| `/api-design` | `.claude/skills/design/api-design.md` | 接口设计 |

### testing/ - 测试文档
| Skill | Location | Description |
|-------|----------|-------------|
| `/test-plan` | `.claude/skills/testing/test-plan.md` | 测试方案 |
| `/test-report` | `.claude/skills/testing/test-report.md` | 测试报告 |

### tools/ - 工具类
| Skill | Location | Description |
|-------|----------|-------------|
| `/md-output` | `.claude/skills/tools/md-output.md` | MD输出规范 |
| `/commit` | `.claude/skills/git/commit.md` | Git提交 |

4.2 技能文件示例

位置：.claude/skills/design/api-design.md

# Skill: API Design

## 描述
生成符合 RESTful 规范的 API 设计文档。

## 触发条件
- 用户提及 `/api-design`
- 用户说 "接口设计"、"API 设计"

## 输出模板

### 接口概述
[接口用途描述]

### 接口列表

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/v1/xxx | 查询 |
| POST | /api/v1/xxx | 创建 |

### 接口详情
[每个接口的详细规格]

5. 自动触发配置

5.1 关键词触发

## Auto-Trigger Rules

| Keywords | Skill | Action |
|----------|-------|--------|
| 概要设计、高层设计 | `/high-level-design` | 读取技能并执行 |
| 详细设计、模块设计 | `/detailed-design` | 读取技能并执行 |
| API设计、接口文档 | `/api-design` | 读取技能并执行 |
| 测试方案、测试计划 | `/test-plan` | 读取技能并执行 |
| 画图、流程图 | `/drawio` | 使用 Draw.io |

5.2 触发规则说明

6. 项目结构配置

6.1 目录结构说明

## File Organization

项目根目录/
├── CLAUDE.md                 # 项目配置
├── .claude/
│   └── skills/               # 技能目录
│       ├── design/           # 设计文档
│       ├── testing/          # 测试文档
│       └── tools/            # 工具类
├── src/                      # 源代码
│   ├── controllers/          # 控制器
│   ├── models/               # 数据模型
│   ├── services/             # 业务逻辑
│   └── utils/                # 工具函数
├── tests/                    # 测试文件
└── docs/                     # 文档输出

6.2 技术栈说明

## Tech Stack

| 类别 | 技术 |
|------|------|
| 后端 | Node.js + Express |
| 数据库 | PostgreSQL + Redis |
| 前端 | React + TypeScript |
| 部署 | Docker + K8s |

7. 记忆系统配置

7.1 记忆层级

## Memory System

### 自动记忆（主力）

claude-mem → 全自动捕获 & 注入
├── 自动记录：对话、工具调用、代码变更
├── 自动注入：新会话加载相关上下文
└── 保留策略：默认7天

### 手动记忆（辅助）
| 层级 | 用途 | 使用场景 |
|------|------|---------|
| Memory MCP | 永久知识 | 重要决策 |
| HANDOFF.md | 任务交接 | 紧急情况 |

### 触发词
| 触发词 | 动作 |
|--------|------|
| 继续、接上次 | 加载上下文 |
| 记住这个 | 保存到 Memory |

8. 工作流指南

8.1 任务接收

## Workflow Guidelines

### 接收任务时

1. 确认理解需求，不明确则询问
2. 检查是否匹配 Auto-Trigger Rules
3. 评估复杂度，必要时拆分
4. 使用 TodoWrite 追踪进度

8.2 代码编写

### 编写代码时

1. 先读后改，理解现有代码
2. 遵循项目既有风格
3. 保持单一职责
4. 避免安全漏洞

8.3 任务完成

### 完成任务时

1. 验证改动符合预期
2. 检查是否有遗漏
3. 提供测试建议
4. 简洁总结完成内容

9. 完整示例

9.1 最小配置

# CLAUDE.md

## 项目信息
- 名称：My Project
- 技术栈：Node.js + Express

## 规则
- 读取文件后再修改
- 代码要有注释
- 使用中文回复

9.2 标准配置

# CLAUDE.md - Project Guidelines

<identity>
你是专业的 Node.js 开发者。
语言：中文优先
</identity>

## 核心规则
1. 先读后改
2. 函数保持简短
3. 遵循 RESTful 规范

## 技能
| Skill | Description |
|-------|-------------|
| `/commit` | Git 提交 |
| `/test` | 运行测试 |

## 项目结构
src/ - 源代码
tests/ - 测试文件
docs/ - 文档

9.3 高级配置

参考本项目的 CLAUDE.md 完整示例，包含：

• 详细的身份定义
• 完整的规则体系
• 丰富的技能库
• 记忆系统配置
• 工作流指南

10. 最佳实践

10.1 配置原则

10.2 常见错误

10.3 维护建议

1. 版本记录：使用修订表记录变更
2. 定期审查：删除过时配置
3. 团队同步：确保团队成员使用相同配置

11. 下一步

配置好 CLAUDE.md 后：

• 09-实战案例集锦：查看实际应用案例
• 在项目中创建 .claude/skills/ 目录并添加自定义技能

参考资料

• CLAUDE.md 官方规范
• 示例配置仓库