文档配置CLAUDE.md 配置

CLAUDE.md 配置完整指南：从基础到高级实践

CLAUDE.md是Claude Code的核心配置文件，它相当于项目的”说明书”，告诉Claude如何理解和处理你的代码库。一个好的CLAUDE.md可以显著提升AI的理解准确性和工作效率。

核心概念

CLAUDE.md的作用

  1. 上下文设置：为Claude提供项目背景、技术栈、架构信息
  2. 约束定义：设定开发规范、代码风格、质量标准
  3. 任务指导：提供明确的执行指令和优先级
  4. 知识传承：保存项目的重要决策和设计理念

为什么重要？

  • 减少沟通成本：避免重复解释项目背景
  • 提升准确性：使Claude更好地理解你的意图
  • 保持一致性：确保所有修改都符合项目规范
  • 加速开发：减少调试和返工时间

基础结构

一个完整的CLAUDE.md文件包含以下几个部分：

# CLAUDE.md
 
## 项目概述
[project]
 
## 技术栈
[stack]
 
## 开发指令
[commands]
 
## 架构和约束
[architecture]
 
## 当前任务
[tasks]

核心字段详解

1. 项目概述 (project)

作用：描述项目的基本信息和目标

关键信息：

  • 项目名称和版本
  • 业务目标和价值主张
  • 目标用户和使用场景
  • 项目状态和进展

示例：

## 项目概述
 
**项目名称**：TaskMaster Pro - 企业级任务管理系统  
**当前版本**：v2.1.3  
**项目状态**：生产环境运行，正在开发v2.2新功能
 
**业务目标**：为中小型团队提供简单高效的任务管理和协作解决方案  
**核心价值**：简单易用、实时协作、数据安全

2. 技术栈 (stack)

作用：列出项目使用的技术和工具

关键信息：

  • 前端框架和版本
  • 后端技术栈
  • 数据库和中间件
  • 部署和开发工具

示例：

## 技术栈
 
**前端**：
- Next.js 14.0 + TypeScript 5.0
- Tailwind CSS 3.3 + shadcn/ui
- Zustand 状态管理
- React Query 数据获取
 
**后端**：
- Node.js 20 + Express 4.18
- Prisma ORM + PostgreSQL 15
- Redis 7.0 缓存
- JWT 身份验证
 
**工具链**：
- 包管理器：pnpm
- 代码质量：ESLint + Prettier
- 测试框架：Jest + Testing Library
- CI/CD：GitHub Actions + Vercel

3. 开发指令 (commands)

作用：定义常用的开发命令和脚本

重要性：Claude可以自动执行这些命令，提高工作效率

示例：

## 开发指令
 
```bash
# 安装依赖
pnpm install
 
# 启动开发服务器
pnpm dev
 
# 运行测试
pnpm test
pnpm test:watch    # 监视模式
pnpm test:coverage # 覆盖率报告
 
# 代码质量检查
pnpm lint
pnpm lint:fix
pnpm type-check
 
# 数据库操作
pnpm db:migrate
pnpm db:seed
pnpm db:reset
 
# 构建和部署
pnpm build
pnpm start

### 4. 架构和约束 (architecture)

**作用**：定义代码组织结构和开发规范

**关键信息**：
- 目录结构说明
- 命名约定
- 代码风格指导
- 重要设计决策

**示例**：
```markdown
## 架构和约束

### 目录结构

src/ ├── components/ # 可复用组件 │ ├── ui/ # 基础UI组件 │ └── features/ # 业务组件 ├── pages/ # 页面组件 ├── lib/ # 工具函数和配置 ├── store/ # 状态管理 ├── types/ # TypeScript类型定义 └── api/ # API相关逻辑


### 命名约定
- **组件**：PascalCase（UserProfile.tsx）
- **文件**：kebab-case（user-profile.utils.ts）
- **变量**：camelCase（userName）
- **常量**：SCREAMING_SNAKE_CASE（API_BASE_URL）

### 代码风格
- 优先使用函数组件和自定义Hooks
- 组件尺寸保持在100行以内
- 使用显式类型定义，避免any
- 所有组件必须有对应的测试

5. 当前任务 (tasks)

作用：明确当前需要完成的任务和优先级

关键信息：

  • 任务描述和验收标准
  • 优先级和截止时间
  • 依赖关系和阻塞问题
  • 技术实现要点

示例：

## 当前任务
 
### 高优先级任务
 
1. **用户身份验证优化** ⚡️ 紧急
   - 实现JWT自动刷新机制
   - 添加双因素认证支持
   - 优化登录状态管理
   - **验收标准**：所有身份验证流程测试通过
   - **截止时间**：本周五
 
2. **任务拖拽功能完善** 🏆 重要
   - 实现任务列表间的拖拽排序
   - 添加拖拽动画效果
   - 优化移动端体验
   - **依赖**：等待react-beautiful-dnd升级
 
### 中优先级任务
 
3. **性能监控仪表板** 📈 常规
   - 集成Web Vitals监控
   - 添加错误追踪和报告
   - **技术方案**：使用Sentry + 自定义埋点

进阶配置

1. 环境相关配置

## 环境配置
 
### 开发环境
- **数据库**：PostgreSQL 15 本地实例
- **缓存**：Redis 7.0 本地实例
- **对象存储**：MinIO 本地服务
- **日志级别**：DEBUG
 
### 生产环境
- **数据库**：AWS RDS PostgreSQL
- **缓存**：AWS ElastiCache Redis
- **CDN**：CloudFlare
- **监控**：Datadog + Sentry

2. 团队协作规范

## 团队协作
 
### Git 工作流
- **主分支**：`main` (只接受PR)
- **开发分支**：`develop` (日常开发)
- **功能分支**：`feature/task-id-description`
- **修复分支**：`hotfix/critical-bug-description`
 
### 代码审查要求
- 所有PR必须经过至少2人审查
- 自动化测试必须通过
- 代码覆盖率不低于85%
- 新功能必须包含文档和测试
 
### 发版流程
1. 从feature分支向develop提交PR
2. 通过代码审查后合并
3. 在develop分支测试稳定后合并到main
4. 从 main 分支创建 release tag

3. 性能和安全规范

## 性能要求
 
### Web Vitals 标准
- **LCP**: < 2.5s (最大内容绘制)
- **FID**: < 100ms (首次输入延迟)
- **CLS**: < 0.1 (累积布局偏移)
- **FCP**: < 1.8s (首次内容绘制)
 
### API 性能
- 所有API响应时间 < 200ms
- 数据库查询优化（使用索引和缓存）
- 实现分页和懒加载
 
### 安全规范
- 所有用户输入必须验证和清理
- 敏感数据加密存储
- 实现RBAC权限控制
- 定期进行安全扫描

实际案例

以下是一个真实项目的CLAUDE.md示例：

# CLAUDE.md
 
本文件为Claude Code 提供项目上下文和开发指导。
 
## 项目概述
 
**EcoShop** - 环保电商平台  
**当前版本**：v1.2.0  
**项目状态**：MVP已上线，正在开发v1.3新功能
 
**业务目标**：为消费者提供可持续的购物选择，推广环保理念  
**目标用户**：18-35岁关注环保的年轻消费者
 
## 技术栈
 
**前端** (Next.js 14 + TypeScript):
- UI框架：Tailwind CSS + Headless UI
- 状态管理：Zustand + React Query
- 表单处理：React Hook Form + Zod
- 支付集成：Stripe.js
 
**后端** (Node.js + Express):
- 数据库：PostgreSQL + Prisma ORM
- 身份验证：Passport.js + JWT
- 文件存储：AWS S3
- 邮件服务：SendGrid
 
## 开发指令
 
```bash
# 安装依赖
npm install
 
# 环境准备
cp .env.example .env.local
npm run db:setup
 
# 开发服务
npm run dev        # 前端开发服务 (3000)
npm run dev:api    # API服务 (3001)
npm run dev:full   # 同时启动前后端
 
# 测试和质量
npm test           # 单元测试
npm run test:e2e   # E2E测试
npm run lint       # 代码检查
npm run type-check # 类型检查
 
# 数据库
npm run db:migrate
npm run db:seed    # 初始化测试数据
npm run db:studio  # Prisma Studio

架构和约束

目录结构

eco-shop/
├── apps/
│   ├── web/           # Next.js 前端应用
│   └── api/           # Express API 服务
├── packages/
│   ├── ui/            # 共享 UI 组件
│   ├── utils/         # 共享工具函数
│   └── types/         # 共享 TypeScript 类型
└── docs/             # 项目文档

代码规范

  • ESLint + Prettier 强制代码风格
  • 组件尺寸 < 150行，复杂逻辑抽取为Custom Hooks
  • API 设计 RESTful 风格，使用资源名词复数
  • 类型安全 严格模式，禁止 any 类型

数据模型设计

  • 用户系统 User, Profile, Address
  • 商品系统 Product, Category, Inventory
  • 订单系统 Order, OrderItem, Payment
  • 评价系统 Review, Rating

当前任务

紧急任务 (本周完成)

  1. 支付流程优化 ⚡️

    • 修复Stripe支付失败后的订单状态问题
    • 实现支付失败的自动重试机制
    • 验收: 支付成功率 > 95%
    • 相关文件: apps/api/src/services/payment.ts

  2. 用户体验优化 🏆

    • 商品详情页加载速度优化 (< 2s)
    • 移动端购物车交互优化
    • 技术要点: 图片懒加载 + CDN 缓存

计划任务 (下周开始)

  1. 商品推荐系统 📈

    • 基于用户购买历史的协同过滤
    • 集成第三方推荐API (TBD)
    • 前置条件: 用户行为数据收集完善

  2. 管理后台完善 🔧

    • 商品批量导入功能
    • 订单统计仪表板
    • 技术方案: React Admin + Chart.js

最佳实践建议

1. CLAUDE.md 维护

  • 定期更新：至少每周review一次
  • 版本控制：与Git一起管理，重大更新做标记
  • 团队同步：重要更改后及时通知团队成员

2. 内容组织技巧

  • 粒度控制：太细致会冒凗，太算略会模糊
  • 语言简洁：使用项目统一的术语和命名
  • 示例丰富：提供具体的代码示例和配置

3. 常见问题避免

  • 过时信息：定期清理已完成的任务
  • 模糊要求：任务描述要具体可量化
  • 缺少上下文：不要假设 Claude 了解背景信息

总结：CLAUDE.md 是你和 AI 之间沟通的桥梁。一个好的 CLAUDE.md 可以大幅提升开发效率和代码质量。记住，越详细越准确的信息，意味着越好的开发体验。

配置概览Claude 配置
关于我