CLAUDE.md 文件配置指南

通过 CLAUDE.md 文件定义项目规范和约束，让 Claude Code 更好地理解和遵守项目要求。

什么是 CLAUDE.md

CLAUDE.md 是 Claude Code 的项目配置文件，它会在每次对话开始时自动加载，作为系统提示的一部分。通过合理配置这个文件，可以：

定义项目特定的编码规范
设置技术栈和框架约束
制定代码质量标准
规范开发工作流程
记录架构决策

核心配置模板

基础模板结构

# 项目名称

## 项目概述

[简要描述项目目的、核心功能和目标用户]

## 技术栈

- 前端：[框架和主要库]
- 后端：[语言和框架]
- 数据库：[数据库类型]
- 部署：[部署平台]

## 项目结构

\```
project/
├── src/ # 源代码
├── tests/ # 测试文件
├── docs/ # 文档
└── scripts/ # 脚本文件
\```

## 开发规范

[项目特定的编码规范]

## 注意事项

[项目特定的注意事项和限制]

完整配置示例

# CLAUDE.md - 项目配置文件

## 通用规则（所有项目必须遵守）

### 沟通语言

- 永远使用简体中文进行思考和对话
- 代码注释使用英文，文档使用中文

### 文档管理

- 正式文档写到 `docs/` 目录
- 讨论方案写到 `discuss/` 目录
- README 保持简洁，详细文档独立存放

## 代码架构规范

### 文件大小限制

- Python/JavaScript/TypeScript：每个文件不超过 300 行
- Java/Go/Rust：每个文件不超过 400 行
- 每个文件夹中的文件不超过 8 个
- 超出限制需要重构或拆分

### 代码质量指标

避免以下代码坏味道：

1. **僵化性**：系统难以变更
2. **冗余性**：重复代码过多
3. **循环依赖**：模块相互依赖
4. **脆弱性**：改动引发连锁问题
5. **晦涩性**：代码意图不明
6. **数据泥团**：数据项总是一起出现
7. **过度设计**：不必要的复杂性

## 技术栈约束

### 前端技术栈

- React 19+ (不使用 18 或更低版本)
- Next.js 15.4+ (不使用 14 或更低版本)
- Tailwind CSS v4 (不使用 v3)
- TypeScript 优先，避免 JavaScript
- 禁止使用 CommonJS，只用 ES Modules

### 后端技术栈

- Node.js 18+
- 使用 TypeScript
- Express/Fastify 作为 Web 框架
- Prisma 作为 ORM

### Python 项目

- 使用 uv 管理依赖（不用 pip/poetry/conda）
- 虚拟环境目录名：`.venv`
- 强类型定义，避免使用 dict
- 项目根目录保持简洁

## 开发工作流

### 脚本管理

- 所有脚本放在 `scripts/` 目录
- 使用 `.sh` 脚本进行启停操作
- 不直接使用 npm/pnpm/python 命令
- 脚本失败必须立即修复

### 日志管理

- 配置文件输出日志
- 统一输出到 `logs/` 目录
- 包含时间戳和日志级别
- 错误日志单独存放

### 测试要求

- 单元测试覆盖率 > 80%
- 关键功能必须有集成测试
- 测试文件放在 `tests/` 目录
- 使用 CI/CD 自动运行测试

## 命名规范

### 文件命名

- 组件：PascalCase（如 UserProfile.tsx）
- 工具函数：camelCase（如 formatDate.ts）
- 常量文件：UPPER_SNAKE_CASE（如 API_CONSTANTS.ts）
- 样式文件：kebab-case（如 user-profile.css）

### 变量命名

- 变量/函数：camelCase
- 常量：UPPER_SNAKE_CASE
- 类/接口：PascalCase
- 私有属性：\_camelCase

## Git 工作流

### 分支策略

- main：生产环境代码
- develop：开发环境代码
- feature/\*：功能分支
- hotfix/\*：紧急修复分支

### 提交规范

- feat: 新功能
- fix: 修复问题
- docs: 文档更新
- style: 代码格式调整
- refactor: 重构代码
- test: 测试相关
- chore: 构建/工具变动

## API 设计规范

### RESTful 原则

- GET：获取资源
- POST：创建资源
- PUT：更新资源（全量）
- PATCH：更新资源（部分）
- DELETE：删除资源

### 响应格式

\```json
{
"success": true,
"data": {},
"message": "操作成功",
"timestamp": "2024-01-01T00:00:00Z"
}
\```

### 错误处理

\```json
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "错误描述",
"details": {}
}
}
\```

## 安全规范

### 敏感信息

- 不在代码中硬编码密钥
- 使用环境变量管理配置
- `.env` 文件不提交到 Git
- 定期更新依赖包

### 数据验证

- 前端和后端都进行数据验证
- 使用 schema 验证库（如 zod）
- SQL 查询使用参数化
- 防止 XSS 和 CSRF 攻击

## 性能优化

### 前端优化

- 图片懒加载
- 代码分割
- 缓存策略
- 虚拟滚动（大列表）

### 后端优化

- 数据库查询优化
- 使用缓存（Redis）
- API 响应压缩
- 并发控制

## 部署配置

### 环境变量

- development：开发环境
- staging：测试环境
- production：生产环境

### 容器化

- 使用 Docker 进行部署
- 多阶段构建优化镜像大小
- 使用 docker-compose 编排服务

## 监控与日志

### 监控指标

- API 响应时间
- 错误率
- 资源使用率
- 用户行为分析

### 日志级别

- ERROR：错误信息
- WARN：警告信息
- INFO：一般信息
- DEBUG：调试信息

## 特别注意事项

⚠️ **重要提醒**：

1. 识别到代码问题立即提出
2. 不确定时主动询问用户
3. 保持代码整洁和可维护性
4. 遵守项目既定规范

项目类型专用模板

React/Next.js 项目

## React/Next.js 项目规范

### 组件规范

- 使用函数组件 + Hooks
- 组件文件与组件同名
- 一个文件一个组件
- Props 使用 TypeScript 接口定义

### 状态管理

- 简单状态：useState
- 复杂状态：useReducer
- 全局状态：Context API / Zustand
- 服务端状态：TanStack Query

### 样式方案

- Tailwind CSS v4 为主
- CSS Modules 作为补充
- 避免内联样式
- 响应式设计优先

### 性能优化

- 使用 React.memo 避免不必要渲染
- useMemo/useCallback 优化计算
- 动态导入实现代码分割
- 图片使用 next/image 组件

Python 项目

## Python 项目规范

### 项目结构

\```
project/
├── src/
│ ├── **init**.py
│ ├── main.py
│ ├── models/
│ ├── services/
│ └── utils/
├── tests/
├── .venv/
└── pyproject.toml
\```

### 依赖管理

- 使用 uv 管理所有依赖
- pyproject.toml 定义项目配置
- requirements.txt 用于生产部署
- requirements-dev.txt 用于开发依赖

### 类型注解

- 所有函数必须有类型注解
- 使用 dataclass 定义数据结构
- 配合 mypy 进行类型检查
- 避免使用 Any 类型

### 异步编程

- 优先使用 async/await
- 使用 asyncio 管理并发
- 数据库操作使用异步驱动
- HTTP 请求使用 httpx

微服务项目

## 微服务架构规范

### 服务划分

- 按业务领域划分服务
- 每个服务独立部署
- 服务间通过 API 通信
- 共享代码通过包管理

### API 网关

- 统一入口管理
- 认证授权
- 限流熔断
- 请求路由

### 服务通信

- HTTP/REST：同步调用
- 消息队列：异步通信
- gRPC：高性能场景
- WebSocket：实时通信

### 数据管理

- 每个服务独立数据库
- 避免跨服务事务
- 使用事件驱动保持一致性
- 实现幂等性操作