目录
- [Claude Code提示词入门：CLAUDE.md编写完全指南 🎯](#Claude Code提示词入门：CLAUDE.md编写完全指南 🎯)
-
- [📌 目录](#📌 目录)
- [1. 什么是CLAUDE.md](#1. 什么是CLAUDE.md)
- [2. 为什么CLAUDE.md这么重要](#2. 为什么CLAUDE.md这么重要)
-
- [2.1 没有CLAUDE.md会怎样？](#2.1 没有CLAUDE.md会怎样？)
- [2.2 有了CLAUDE.md会怎样？](#2.2 有了CLAUDE.md会怎样？)
- [2.3 核心价值](#2.3 核心价值)
- [3. CLAUDE.md的加载机制](#3. CLAUDE.md的加载机制)
-
- [3.1 加载优先级](#3.1 加载优先级)
- [3.2 加载规则](#3.2 加载规则)
- [3.3 继承与覆盖](#3.3 继承与覆盖)
- [4. CLAUDE.md核心结构详解](#4. CLAUDE.md核心结构详解)
-
- [4.1 标准结构模板](#4.1 标准结构模板)
- [4.2 各字段详解](#4.2 各字段详解)
-
- [📋 项目画像](#📋 项目画像)
- [⚡ 常用命令](#⚡ 常用命令)
- [📝 编码规范](#📝 编码规范)
- [⚠️ 注意事项](#⚠️ 注意事项)
- [5. 不同项目类型的模板](#5. 不同项目类型的模板)
-
- [5.1 React前端项目](#5.1 React前端项目)
- 目录规范
- 组件规范
- 状态管理
- API请求
- 架构分层
- 代码规范
- 数据库规范
- 错误处理
- 目录结构
- 代码规范
- 命名规范
- 类型提示
- 架构分层
- 编码规范
- 测试规范
-
- [7.2 错误2：缺少代码示例](#7.2 错误2：缺少代码示例)
- [7.3 错误3：没有更新](#7.3 错误3：没有更新)
- [7.4 错误4：忽略环境差异](#7.4 错误4：忽略环境差异)
Claude Code提示词入门：CLAUDE.md编写完全指南 🎯
📅 更新于：2026年5月 | ✍️ 原创文章，转载请注明出处
📌 目录
1. 什么是CLAUDE.md
CLAUDE.md 是 Claude Code 的项目级记忆文件，类似于：
| 工具 | 对应文件 | 作用 |
|---|---|---|
| Git | .gitignore |
版本控制配置 |
| ESLint | .eslintrc.js |
代码规范配置 |
| Docker | Dockerfile |
容器构建配置 |
| Claude Code | CLAUDE.md |
AI行为与项目上下文配置 |
简单来说，CLAUDE.md 就是你给 Claude Code 写的"项目说明书"，让它在你的代码库里工作时：
- ✅ 知道项目的技术栈和架构
- ✅ 遵循你的编码规范
- ✅ 了解常用命令和工作流
- ✅ 避免犯低级错误
2. 为什么CLAUDE.md这么重要
2.1 没有CLAUDE.md会怎样？
bash
# 没有CLAUDE.md时，Claude可能会：
❌ 用npm命令操作你的yarn项目
❌ 创建不符合项目风格的变量名
❌ 不知道你的测试框架是vitest还是jest
❌ 把代码放在错误的目录结构里
❌ 每次对话都要重复说明项目背景2.2 有了CLAUDE.md会怎样？
bash
# 有CLAUDE.md后，Claude会：
✅ 自动使用正确的包管理器
✅ 沿用项目的命名风格
✅ 运行正确的测试命令
✅ 按照约定的目录结构组织代码
✅ 记住项目的关键信息2.3 核心价值
| 维度 | 价值 |
|---|---|
| 效率 | 减少重复解释，每次对话直接进入正题 |
| 一致性 | 保证AI生成的代码符合项目规范 |
| 准确性 | 基于真实项目上下文，减少幻觉 |
| 协作 | 团队共享CLAUDE.md，统一AI行为 |
3. CLAUDE.md的加载机制
Claude Code 会按照特定顺序加载配置文件，理解这个机制很重要：
3.1 加载优先级
📁 系统级（全局）
└── ~/.claude/CLAUDE.md # 所有项目通用的个人偏好
📁 项目级（仓库根目录）
└── ./CLAUDE.md # 项目特定的配置（最常用）
📁 目录级（子目录）
└── ./src/CLAUDE.md # 特定模块的配置
📁 自定义命令
└── .claude/commands/*.md # 可复用的提示词模板3.2 加载规则
| 文件位置 | 何时加载 | 用途 |
|---|---|---|
~/.claude/CLAUDE.md |
每次对话 | 个人偏好（语言、风格） |
./CLAUDE.md |
进入项目目录时 | 项目配置（主要配置） |
./src/CLAUDE.md |
在该目录下工作时 | 模块级补充配置 |
.claude/commands/*.md |
执行 /command 时 |
自定义命令模板 |
3.3 继承与覆盖
全局配置（基础）
└── 项目配置（覆盖全局）
└── 目录配置（补充项目）关键点：更具体的配置会覆盖更通用的配置，但不会完全替换，而是合并。
4. CLAUDE.md核心结构详解
一个完整的CLAUDE.md通常包含以下部分：
4.1 标准结构模板
markdown
# CLAUDE.md
> 给Claude Code使用的工作手册。
## 项目画像
- 项目名、定位、技术栈
## 常用命令
- 编译、测试、启动等命令
## 架构分层
- 目录结构说明
## 编码规范
- 命名约定、代码风格
## 注意事项
- 特殊规则、踩坑记录4.2 各字段详解
📋 项目画像
markdown
## 项目画像
- **项目名**: my-awesome-app
- **定位**: 企业级管理后台
- **技术栈**: React 18 + TypeScript + Vite + Ant Design
- **包管理器**: pnpm（不要用npm或yarn）
- **Node版本**: >= 18.0.0作用：让Claude快速了解项目基本情况，避免使用错误的工具链。
⚡ 常用命令
markdown
## 常用命令
```bash
# 安装依赖
pnpm install
# 本地开发
pnpm dev
# 构建
pnpm build
# 测试
pnpm test # 运行所有测试
pnpm test:watch # 监听模式
pnpm test -- --grep "xxx" # 运行特定测试
# 代码检查
pnpm lint
pnpm lint:fix**作用**：Claude可以直接使用正确的命令，不用每次询问。
#### 🏗️ 架构分层
```markdown
## 架构分层
src/
├── api/ # API请求封装
├── components/ # 通用组件
│ ├── ui/ # 基础UI组件
│ └── business/ # 业务组件
├── hooks/ # 自定义Hook
├── pages/ # 页面组件
│ ├── dashboard/ # 仪表盘
│ └── settings/ # 设置页
├── stores/ # 状态管理（Zustand）
├── styles/ # 全局样式
└── utils/ # 工具函数作用：让Claude知道代码应该放在哪里，保持目录结构一致。
📝 编码规范
markdown
## 编码规范
### 命名约定
- 组件：PascalCase（如 `UserProfile.tsx`）
- Hook：camelCase，use前缀（如 `useAuth.ts`）
- 工具函数：camelCase（如 `formatDate.ts`）
- 常量：UPPER_SNAKE_CASE
### 代码风格
- 使用函数式组件，不要用class组件
- 优先使用TypeScript，避免any
- 状态管理用Zustand，不要用Redux
- 样式用Tailwind CSS，不要写CSS文件
### 导入顺序
1. React相关
2. 第三方库
3. 项目组件
4. 工具函数
5. 类型定义作用：保证生成的代码符合团队规范。
⚠️ 注意事项
markdown
## 注意事项
### 必须做
- ✅ 所有API请求都要有错误处理
- ✅ 组件必须有TypeScript类型定义
- ✅ 新功能必须附带单元测试
### 禁止做
- ❌ 不要使用 `any` 类型
- ❌ 不要直接修改state
- ❌ 不要在组件里写业务逻辑，抽到hook里
- ❌ 不要使用 `console.log`，用统一的logger
### 踩坑记录
- 登录接口返回的token在response.data.token里，不是response.token
- 表格组件用ProTable，不要用原生Table作用：记录容易犯错的地方，避免重复踩坑。
5. 不同项目类型的模板
5.1 React前端项目
markdown
# CLAUDE.md
> React前端项目工作手册
## 项目画像
- **技术栈**: React 18 + TypeScript + Vite + Tailwind CSS
- **UI库**: Ant Design 5.x
- **状态管理**: Zustand
- **包管理器**: pnpm
- **路由**: React Router v6
## 常用命令
```bash
pnpm install # 安装依赖
pnpm dev # 本地开发（端口3000）
pnpm build # 构建生产版本
pnpm test # 运行测试
pnpm lint # ESLint检查目录规范
- 页面组件 →
src/pages/ - 通用组件 →
src/components/ - 自定义Hook →
src/hooks/ - API请求 →
src/api/ - 工具函数 →
src/utils/ - 状态管理 →
src/stores/
组件规范
tsx
// ✅ 正确：函数式组件 + TypeScript
interface UserCardProps {
name: string;
age: number;
}
const UserCard: React.FC<UserCardProps> = ({ name, age }) => {
return <div>{name}, {age}岁</div>;
};
// ❌ 错误：不要这样写
class UserCard extends React.Component { ... }状态管理
tsx
// 使用Zustand，不要用Redux
import { create } from 'zustand';
interface AuthStore {
token: string | null;
setToken: (token: string) => void;
}
const useAuthStore = create<AuthStore>((set) => ({
token: null,
setToken: (token) => set({ token }),
}));API请求
tsx
// 统一使用src/api/request.ts封装的axios实例
import { request } from '@/api/request';
// ✅ 正确
const getUser = () => request.get('/api/user');
// ❌ 错误：不要直接用axios
import axios from 'axios';
axios.get('/api/user');### 5.2 Node.js后端项目
```markdown
# CLAUDE.md
> Node.js后端项目工作手册
## 项目画像
- **技术栈**: Node.js 20 + Express + TypeScript
- **ORM**: Prisma
- **数据库**: PostgreSQL
- **缓存**: Redis
- **测试**: Jest + Supertest
- **包管理器**: pnpm
## 常用命令
```bash
pnpm dev # 启动开发服务器
pnpm build # 编译TypeScript
pnpm start # 启动生产服务器
pnpm test # 运行测试
pnpm prisma:generate # 生成Prisma客户端
pnpm prisma:migrate # 运行数据库迁移
pnpm prisma:studio # 打开Prisma Studio架构分层
src/
├── controllers/ # 控制器（处理请求）
├── services/ # 服务层（业务逻辑）
├── repositories/ # 数据访问层
├── models/ # 数据模型
├── middlewares/ # 中间件
├── routes/ # 路由定义
├── utils/ # 工具函数
└── types/ # TypeScript类型代码规范
控制器
typescript
// controllers/user.controller.ts
export const getUser = async (req: Request, res: Response) => {
try {
const { id } = req.params;
const user = await UserService.getUserById(id);
res.json({ code: 0, data: user });
} catch (error) {
res.status(500).json({ code: -1, message: error.message });
}
};服务层
typescript
// services/user.service.ts
export class UserService {
static async getUserById(id: string) {
const user = await prisma.user.findUnique({ where: { id } });
if (!user) {
throw new Error('用户不存在');
}
return user;
}
}数据库规范
- 使用Prisma进行数据库操作
- 所有查询都要有错误处理
- 敏感字段（密码等）不要返回给前端
- 使用事务保证数据一致性
错误处理
typescript
// 统一错误响应格式
{
code: -1, // 0成功，-1失败
message: '错误信息',
data: null
}### 5.3 Python后端项目
```markdown
# CLAUDE.md
> Python后端项目工作手册
## 项目画像
- **技术栈**: Python 3.11 + FastAPI + SQLAlchemy
- **数据库**: PostgreSQL
- **缓存**: Redis
- **测试**: pytest
- **包管理器**: uv（不要用pip）
## 常用命令
```bash
# 依赖管理
uv sync # 安装依赖
uv add <package> # 添加依赖
# 开发
uv run uvicorn main:app --reload # 启动开发服务器
uv run pytest # 运行测试
uv run pytest -x -v # 详细模式，失败即停
# 数据库
uv run alembic upgrade head # 运行迁移
uv run alembic revision --autogenerate -m "xxx" # 生成迁移目录结构
app/
├── api/ # API路由
│ └── v1/ # API版本
├── core/ # 核心配置
├── crud/ # 数据库操作
├── models/ # SQLAlchemy模型
├── schemas/ # Pydantic模型
├── services/ # 业务逻辑
└── utils/ # 工具函数代码规范
API路由
python
# api/v1/users.py
from fastapi import APIRouter, Depends
from app.schemas.user import UserCreate, UserResponse
from app.services.user import UserService
router = APIRouter()
@router.post("/users", response_model=UserResponse)
async def create_user(
user_in: UserCreate,
service: UserService = Depends()
):
return await service.create(user_in)Pydantic模型
python
# schemas/user.py
from pydantic import BaseModel, EmailStr
class UserCreate(BaseModel):
name: str
email: EmailStr
password: str
class UserResponse(BaseModel):
id: int
name: str
email: str
class Config:
from_attributes = True命名规范
- 文件名：snake_case（
user_service.py） - 类名：PascalCase（
UserService） - 函数名：snake_case（
get_user_by_id） - 常量：UPPER_SNAKE_CASE（
MAX_RETRY_COUNT）
类型提示
python
# ✅ 正确：使用类型提示
def get_user(user_id: int) -> Optional[User]:
return db.query(User).filter(User.id == user_id).first()
# ❌ 错误：不要省略类型
def get_user(user_id):
return db.query(User).filter(User.id == user_id).first()### 5.4 Java后端项目
```markdown
# CLAUDE.md
> Java后端项目工作手册
## 项目画像
- **项目名**: bi-platform
- **定位**: 数据资产平台后端
- **技术栈**: Java 21 + Spring Boot 3.3.5 + MyBatis-Plus
- **数据库**: MySQL + Redis
- **构建工具**: Maven
## 常用命令
```bash
# 编译
mvn clean package -DskipTests
# 测试
mvn clean test
mvn -Dtest=UserServiceTest test # 单个测试类
mvn -Dtest=UserServiceTest#testCreate test # 单个测试方法
# 启动
mvn spring-boot:run
mvn spring-boot:run -Dspring-boot.run.jvmArguments="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005"架构分层
com.example.app
├── controller # 控制器层
├── service # 服务层
│ └── impl # 服务实现
├── mapper # 数据访问层
├── entity # 数据库实体
├── dto # 数据传输对象
│ ├── request # 请求DTO
│ └── response # 响应DTO
├── config # 配置类
├── exception # 异常处理
└── util # 工具类编码规范
命名约定
- 类名：PascalCase（
UserService） - 方法名：camelCase（
getUserById） - 常量：UPPER_SNAKE_CASE（
MAX_PAGE_SIZE） - 包名：全小写（
com.example.app）
依赖注入
java
// ✅ 正确：构造器注入
@Service
public class UserService {
private final UserRepository userRepository;
public UserService(UserRepository userRepository) {
this.userRepository = userRepository;
}
}
// ❌ 错误：字段注入
@Service
public class UserService {
@Autowired
private UserRepository userRepository;
}Controller规范
java
@RestController
@RequestMapping("/api/users")
public class UserController {
@PostMapping
public ApiResponse<UserDTO> create(@RequestBody @Valid UserCreateRequest request) {
// 实现
}
@GetMapping("/{id}")
public ApiResponse<UserDTO> getById(@PathVariable Long id) {
// 实现
}
}测试规范
- 使用JUnit 5 + Mockito + AssertJ
- Service层必须有单元测试
- Controller层测试验证接口契约
java
@ExtendWith(MockitoExtension.class)
class UserServiceTest {
@Mock
private UserRepository userRepository;
@InjectMocks
private UserService userService;
@Test
void shouldCreateUser() {
// given
// when
// then
}
}---
## 6. 编写最佳实践
### 6.1 DO - 推荐做法
| 实践 | 示例 | 原因 |
|------|------|------|
| ✅ 使用Markdown格式 | `## 常用命令` | Claude能更好理解结构 |
| ✅ 提供代码示例 | 包含正确/错误对比 | 减少歧义 |
| ✅ 说明"为什么" | "用pnpm因为更快" | 帮助Claude理解意图 |
| ✅ 保持简洁 | 每个要点1-2行 | 避免信息过载 |
| ✅ 使用表格对比 | 功能对比表 | 清晰易读 |
| ✅ 定期更新 | 添加踩坑记录 | 保持配置有效 |
### 6.2 DON'T - 避免做法
| 错误做法 | 示例 | 问题 |
|----------|------|------|
| ❌ 写太长 | 上千行的配置 | Claude会忽略部分内容 |
| ❌ 太模糊 | "写好代码" | 没有可执行性 |
| ❌ 自相矛盾 | "用React" + "不用JSX" | 让Claude困惑 |
| ❌ 过时信息 | 还在写React 17 | 产生错误代码 |
| ❌ 硬编码 | 写死IP地址 | 应该用环境变量 |
### 6.3 长度建议
| 项目规模 | 建议行数 | 说明 |
|----------|----------|------|
| 小型项目 | 30-50行 | 基本配置即可 |
| 中型项目 | 50-150行 | 包含架构和规范 |
| 大型项目 | 150-300行 | 详细分模块说明 |
| 超大型项目 | 拆分多个文件 | 使用目录级CLAUDE.md |
---
## 7. 常见错误与避坑
### 7.1 错误1：信息过多
```markdown
# ❌ 错误示例：信息过载
## 项目介绍
这是一个非常复杂的项目，包含了很多很多功能，
我们使用了各种各样的技术，包括但不限于...
（写了500字介绍）
markdown
# ✅ 正确示例：简洁明了
## 项目画像
- **定位**: 电商平台后端
- **技术栈**: Java 21 + Spring Boot 3 + MyBatis-Plus
- **数据库**: MySQL + Redis7.2 错误2：缺少代码示例
markdown
# ❌ 错误示例：太抽象
## 命名规范
请使用正确的命名规范
markdown
# ✅ 正确示例：有具体示例
## 命名规范
- 类名：PascalCase（`UserService`）
- 方法名：camelCase（`getUserById`）
- 常量：UPPER_SNAKE_CASE（`MAX_RETRY_COUNT`）7.3 错误3：没有更新
markdown
# ❌ 错误示例：过时配置
## 技术栈
- React 17（已升级到18）
- Redux（已换成Zustand）
- Webpack（已换成Vite）解决方案：每次技术栈变更后，同步更新CLAUDE.md。
7.4 错误4：忽略环境差异
markdown
# ❌ 错误示例：硬编码
## 常用命令
npm run dev # 你的项目用的是yarn
markdown
# ✅ 正确示例：明确说明
## 常用命令
```bash
# 使用yarn（不要用npm）
yarn dev
yarn build
yarn test---
## 8. 总结
### 8.1 CLAUDE.md的核心价值
| 价值 | 说明 |
|------|------|
| 🚀 **效率提升** | 减少重复解释，每次对话直接进入正题 |
| 🎯 **行为一致** | 保证AI生成的代码符合项目规范 |
| 🧠 **上下文记忆** | Claude能"记住"项目的关键信息 |
| 👥 **团队协作** | 共享配置，统一AI行为标准 |
### 8.2 快速开始清单
如果你还没有CLAUDE.md，按这个清单来：
- [ ] 创建 `CLAUDE.md` 文件在项目根目录
- [ ] 填写项目画像（技术栈、包管理器）
- [ ] 添加常用命令（开发、测试、构建）
- [ ] 说明目录结构和代码规范
- [ ] 添加注意事项和踩坑记录
- [ ] 提交到Git仓库，团队共享
### 8.3 下篇预告
> 📌 **下一篇**：我们将深入探讨Claude Code交互式提示词技巧------如何在对话中写出让AI精准执行的指令，包括上下文管理、分步指令、约束条件等高级用法。
---
## 📚 参考资料
1. [Anthropic官方文档 - Claude Code](https://docs.anthropic.com/en/docs/claude-code) - 2026年5月
2. [Claude Code GitHub仓库](https://github.com/anthropics/claude-code) - 官方示例
3. [CLAUDE.md最佳实践](https://docs.anthropic.com/en/docs/claude-code/memory) - 官方指南
---
> 💬 **你在使用CLAUDE.md时遇到过什么问题？欢迎在评论区分享你的经验！**
>
> 📌 如果这篇文章对你有帮助，别忘了点赞收藏，关注我获取更多Claude Code实战技巧！