跳到主要内容

CLAUDE.md 至上

什么是 CLAUDE.md？​

CLAUDE.md 是 Claude Code 的核心配置文件，位于项目根目录。它就像是给 Claude 的一份项目手册，定义了项目的上下文、规则、约定和期望。

这不仅仅是一个配置文件，更是人机协作的桥梁。

为什么 CLAUDE.md 如此重要？​

1. 上下文即力量​

Claude Code 的能力很大程度上取决于它对项目的理解。一个精心编写的 CLAUDE.md 可以：

  • 🧠 建立项目认知：让 Claude 深入理解项目目标和结构
  • 🎯 设定工作标准：定义代码质量和风格要求
  • ⚡ 提升执行效率：避免重复解释和错误方向
  • 🛡️ 确保一致性：团队成员共享同一套协作规则

2. 从混乱到秩序​

没有 CLAUDE.md 的项目：

> 帮我重构这个函数

Claude: 这个函数是做什么的？用什么框架？有什么约定？
你: 这是一个 React 组件，我们用 TypeScript...
Claude: 好的，还有其他规则吗？
你: 我们用函数式组件，不要用类组件...
Claude: 了解，测试框架是？
你: Jest... (循环往复)

有 CLAUDE.md 的项目：

> 帮我重构这个函数

Claude: 好的，基于项目配置，我会使用函数式组件、TypeScript 类型、遵循你的命名约定，并添加相应的 Jest 测试。开始重构...

CLAUDE.md 的结构​

基础模板​

# 项目名称

## 项目概述
[项目的简短描述和主要目标]

## 技术栈
- 前端：React 18 + TypeScript
- 状态管理：Redux Toolkit
- 样式：Styled Components
- 测试：Jest + React Testing Library
- 构建：Vite

## 项目结构

src/ ├── components/ # 可复用组件 ├── pages/ # 页面组件 ├── hooks/ # 自定义 Hooks ├── services/ # API 服务 ├── store/ # Redux store ├── types/ # TypeScript 类型 ├── utils/ # 工具函数 └── styles/ # 样式文件


## 编码规范
- 使用函数式组件 + Hooks
- 所有组件必须有 TypeScript 类型
- 使用 ESLint + Prettier 格式化
- 组件名使用 PascalCase
- 文件名使用 kebab-case
- 优先使用命名导出

## 测试要求
- 所有组件必须有单元测试
- 覆盖率要求：>80%
- 测试文件命名：`*.test.tsx`

## Git 工作流
- 使用 feature branch
- 提交信息格式：`type(scope): description`
- PR 需要通过所有检查

## 注意事项
- API 调用必须有错误处理
- 敏感信息使用环境变量
- 新功能需要更新文档

高级配置技巧​

1. 模块化配置​

对于大型项目，可以将配置分成多个部分：

# 我的大型应用

## 核心信息
[基本项目信息]

## 架构决策记录 (ADR)

### ADR-001: 状态管理选择
我们选择 Redux Toolkit 而不是 Context API，因为：
- 复杂的状态逻辑
- 需要时间旅行调试
- 团队熟悉 Redux 生态

### ADR-002: API 层设计
使用 RTK Query 进行数据获取：
- 自动缓存和同步
- 内置 loading/error 状态
- TypeScript 优先

## 开发工作流

### 新功能开发流程
1. 创建 feature branch：`feature/功能名`
2. 使用 TDD 方法：先写测试，再实现
3. 确保 TypeScript 无错误
4. 运行完整测试套件
5. 提交 PR 并请求代码审查

### 代码审查检查清单
- [ ] TypeScript 类型正确
- [ ] 测试覆盖新功能
- [ ] 错误处理完善
- [ ] 性能考虑（memo, callback 等）
- [ ] 可访问性支持

2. 上下文丰富化​

## 业务上下文

### 目标用户
- 主要：25-40岁的专业人士
- 设备：移动端优先，桌面端支持
- 使用场景：通勤时间、办公间隙

### 核心功能
1. **用户认证**：OAuth2 + JWT
2. **数据同步**：实时同步，离线支持
3. **通知系统**：推送 + 邮件提醒

### 性能要求
- 首屏加载：<2秒
- 交互响应：<100ms
- 支持 1000+ 并发用户

3. 团队协作规范​

## 团队约定

### 命名规范
- **组件**：`UserProfile.tsx`
- **Hook**：`useUserData.ts`
- **Service**：`userService.ts`
- **Type**：`UserType.ts`

### 错误处理模式
```typescript
// API 调用统一错误处理
try {
  const data = await userService.getProfile();
  return { data, error: null };
} catch (error) {
  logger.error('Failed to get user profile', error);
  return { data: null, error: error.message };
}

代码审查标准​

  • 功能正确性 ✅
  • 代码可读性 ✅
  • 性能影响 ✅
  • 安全考虑 ✅

## 实战案例分析

### 案例 1：重构失败

**问题**：没有明确的 CLAUDE.md 配置
```bash
> 重构用户认证模块

# Claude 的困惑：
# - 使用什么认证方案？
# - 现有代码风格是什么？
# - 需要保持向后兼容吗？
# - 测试要求是什么？

结果：重构方向与项目要求不符，需要多次返工。

案例 2：重构成功​

配置：详细的 CLAUDE.md

## 认证系统配置
- 使用 JWT + Refresh Token
- 支持多种登录方式：邮箱、第三方 OAuth
- Session 管理：Redis 存储
- 安全要求：2FA 支持，密码策略强制

## 现有认证模块
- `src/auth/` 目录包含所有认证相关代码
- `AuthContext` 提供全局认证状态
- `authService` 处理 API 调用
- `authUtils` 提供认证工具函数

执行：

> 重构用户认证模块，改进安全性并添加 2FA 支持

结果：Claude 准确理解需求，一次性完成高质量重构。

动态配置策略​

1. 渐进式完善​

从简单开始，逐步丰富：

第 1 周：基础结构

# 项目名
- React + TypeScript
- 使用函数式组件

第 1 个月：详细规范

# 项目名
[详细的技术栈、文件结构、编码规范]

第 3 个月：深度上下文

# 项目名
[包含业务逻辑、架构决策、团队约定]

2. 团队协作​

  • 📝 版本控制：CLAUDE.md 纳入 Git 管理
  • 🔄 定期更新：随项目发展同步更新
  • 👥 团队共识：确保所有成员理解和遵守
  • 🔍 定期审查：检查配置的有效性和准确性

最佳实践总结​

✅ 做的对的事​

  1. 具体而明确：避免模糊描述
  2. 保持更新：随项目演进更新配置
  3. 包含示例：提供代码示例和模式
  4. 文档化决策：记录重要的架构和技术选择
  5. 团队一致：确保团队成员共享配置

❌ 要避免的陷阱​

  1. 过度详细：不要写成小说，保持简洁实用
  2. 过时信息：定期清理无用或错误的信息
  3. 个人偏好：避免过度个性化的配置
  4. 忽略业务：技术配置要结合业务需求
  5. 静态思维：配置要能适应项目变化

掌握了 CLAUDE.md 的精髓后，你可以继续学习 计划模式，了解如何处理复杂的多步骤任务。