Claude Code提示词入门：CLAUDE.md编写完全指南

目录Claude Code提示词入门CLAUDE.md编写完全指南 目录1. 什么是CLAUDE.md2. 为什么CLAUDE.md这么重要2.1 没有CLAUDE.md会怎样2.2 有了CLAUDE.md会怎样2.3 核心价值3. CLAUDE.md的加载机制3.1 加载优先级3.2 加载规则3.3 继承与覆盖4. CLAUDE.md核心结构详解4.1 标准结构模板4.2 各字段详解 项目画像⚡ 常用命令 编码规范⚠️ 注意事项5. 不同项目类型的模板5.1 React前端项目目录规范组件规范状态管理API请求架构分层代码规范控制器服务层数据库规范错误处理目录结构代码规范API路由Pydantic模型命名规范类型提示架构分层编码规范命名约定依赖注入Controller规范测试规范7.2 错误2缺少代码示例7.3 错误3没有更新7.4 错误4忽略环境差异Claude Code提示词入门CLAUDE.md编写完全指南 更新于2026年5月 | ✍️ 原创文章转载请注明出处 目录什么是CLAUDE.md为什么CLAUDE.md这么重要CLAUDE.md的加载机制CLAUDE.md核心结构详解不同项目类型的模板编写最佳实践常见错误与避坑总结1. 什么是CLAUDE.mdCLAUDE.md 是 Claude Code 的项目级记忆文件类似于工具对应文件作用Git.gitignore版本控制配置ESLint.eslintrc.js代码规范配置DockerDockerfile容器构建配置Claude CodeCLAUDE.mdAI行为与项目上下文配置简单来说CLAUDE.md 就是你给 Claude Code 写的项目说明书让它在你的代码库里工作时✅ 知道项目的技术栈和架构✅ 遵循你的编码规范✅ 了解常用命令和工作流✅ 避免犯低级错误2. 为什么CLAUDE.md这么重要2.1 没有CLAUDE.md会怎样# 没有CLAUDE.md时Claude可能会❌ 用npm命令操作你的yarn项目 ❌ 创建不符合项目风格的变量名 ❌ 不知道你的测试框架是vitest还是jest ❌ 把代码放在错误的目录结构里 ❌ 每次对话都要重复说明项目背景2.2 有了CLAUDE.md会怎样# 有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 标准结构模板# CLAUDE.md 给Claude Code使用的工作手册。 ## 项目画像 - 项目名、定位、技术栈 ## 常用命令 - 编译、测试、启动等命令 ## 架构分层 - 目录结构说明 ## 编码规范 - 命名约定、代码风格 ## 注意事项 - 特殊规则、踩坑记录4.2 各字段详解 项目画像## 项目画像 - **项目名**: my-awesome-app - **定位**: 企业级管理后台 - **技术栈**: React 18 TypeScript Vite Ant Design - **包管理器**: pnpm不要用npm或yarn - **Node版本**: 18.0.0作用让Claude快速了解项目基本情况避免使用错误的工具链。⚡ 常用命令## 常用命令 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知道代码应该放在哪里保持目录结构一致。 编码规范## 编码规范 ### 命名约定 - 组件PascalCase如 UserProfile.tsx - HookcamelCaseuse前缀如 useAuth.ts - 工具函数camelCase如 formatDate.ts - 常量UPPER_SNAKE_CASE ### 代码风格 - 使用函数式组件不要用class组件 - 优先使用TypeScript避免any - 状态管理用Zustand不要用Redux - 样式用Tailwind CSS不要写CSS文件 ### 导入顺序 1. React相关 2. 第三方库 3. 项目组件 4. 工具函数 5. 类型定义作用保证生成的代码符合团队规范。⚠️ 注意事项## 注意事项 ### 必须做 - ✅ 所有API请求都要有错误处理 - ✅ 组件必须有TypeScript类型定义 - ✅ 新功能必须附带单元测试 ### 禁止做 - ❌ 不要使用 any 类型 - ❌ 不要直接修改state - ❌ 不要在组件里写业务逻辑抽到hook里 - ❌ 不要使用 console.log用统一的logger ### 踩坑记录 - 登录接口返回的token在response.data.token里不是response.token - 表格组件用ProTable不要用原生Table作用记录容易犯错的地方避免重复踩坑。5. 不同项目类型的模板5.1 React前端项目# 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/组件规范// ✅ 正确函数式组件 TypeScript interface UserCardProps { name: string; age: number; } const UserCard: React.FCUserCardProps ({ name, age }) { return div{name}, {age}岁/div; }; // ❌ 错误不要这样写 class UserCard extends React.Component { ... }状态管理// 使用Zustand不要用Redux import { create } from zustand; interface AuthStore { token: string | null; setToken: (token: string) void; } const useAuthStore createAuthStore((set) ({ token: null, setToken: (token) set({ token }), }));API请求// 统一使用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类型代码规范控制器// controllers/user.controller.tsexportconstgetUserasync(req:Request,res:Response){try{const{id}req.params;constuserawaitUserService.getUserById(id);res.json({code:0,data:user});}catch(error){res.status(500).json({code:-1,message:error.message});}};服务层// services/user.service.tsexportclassUserService{staticasyncgetUserById(id:string){constuserawaitprisma.user.findUnique({where:{id}});if(!user){thrownewError(用户不存在);}returnuser;}}数据库规范使用Prisma进行数据库操作所有查询都要有错误处理敏感字段密码等不要返回给前端使用事务保证数据一致性错误处理// 统一错误响应格式{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路由# api/v1/users.pyfromfastapiimportAPIRouter,Dependsfromapp.schemas.userimportUserCreate,UserResponsefromapp.services.userimportUserService routerAPIRouter()router.post(/users,response_modelUserResponse)asyncdefcreate_user(user_in:UserCreate,service:UserServiceDepends()):returnawaitservice.create(user_in)Pydantic模型# schemas/user.pyfrompydanticimportBaseModel,EmailStrclassUserCreate(BaseModel):name:stremail:EmailStr password:strclassUserResponse(BaseModel):id:intname:stremail:strclassConfig:from_attributesTrue命名规范文件名snake_caseuser_service.py类名PascalCaseUserService函数名snake_caseget_user_by_id常量UPPER_SNAKE_CASEMAX_RETRY_COUNT类型提示# ✅ 正确使用类型提示defget_user(user_id:int)-Optional[User]:returndb.query(User).filter(User.iduser_id).first()# ❌ 错误不要省略类型defget_user(user_id):returndb.query(User).filter(User.iduser_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 -DtestUserServiceTest test # 单个测试类 mvn -DtestUserServiceTest#testCreate test # 单个测试方法 # 启动 mvn spring-boot:run mvn spring-boot:run -Dspring-boot.run.jvmArguments-agentlib:jdwptransportdt_socket,servery,suspendn,address5005架构分层com.example.app ├── controller # 控制器层 ├── service # 服务层 │ └── impl # 服务实现 ├── mapper # 数据访问层 ├── entity # 数据库实体 ├── dto # 数据传输对象 │ ├── request # 请求DTO │ └── response # 响应DTO ├── config # 配置类 ├── exception # 异常处理 └── util # 工具类编码规范命名约定类名PascalCaseUserService方法名camelCasegetUserById常量UPPER_SNAKE_CASEMAX_PAGE_SIZE包名全小写com.example.app依赖注入// ✅ 正确构造器注入ServicepublicclassUserService{privatefinalUserRepositoryuserRepository;publicUserService(UserRepositoryuserRepository){this.userRepositoryuserRepository;}}// ❌ 错误字段注入ServicepublicclassUserService{AutowiredprivateUserRepositoryuserRepository;}Controller规范RestControllerRequestMapping(/api/users)publicclassUserController{PostMappingpublicApiResponseUserDTOcreate(RequestBodyValidUserCreateRequestrequest){// 实现}GetMapping(/{id})publicApiResponseUserDTOgetById(PathVariableLongid){// 实现}}测试规范使用JUnit 5 Mockito AssertJService层必须有单元测试Controller层测试验证接口契约ExtendWith(MockitoExtension.class)classUserServiceTest{MockprivateUserRepositoryuserRepository;InjectMocksprivateUserServiceuserService;TestvoidshouldCreateUser(){// given// when// then}}--- ## 6. 编写最佳实践 ### 6.1 DO - 推荐做法 | 实践 | 示例 | 原因 | |------|------|------| | ✅ 使用Markdown格式 | ## 常用命令 | Claude能更好理解结构 | | ✅ 提供代码示例 | 包含正确/错误对比 | 减少歧义 | | ✅ 说明为什么 | 用pnpm因为更快 | 帮助Claude理解意图 | | ✅ 保持简洁 | 每个要点1-2行 | 避免信息过载 | | ✅ 使用表格对比 | 功能对比表 | 清晰易读 | | ✅ 定期更新 | 添加踩坑记录 | 保持配置有效 | ### 6.2 DONT - 避免做法 | 错误做法 | 示例 | 问题 | |----------|------|------| | ❌ 写太长 | 上千行的配置 | Claude会忽略部分内容 | | ❌ 太模糊 | 写好代码 | 没有可执行性 | | ❌ 自相矛盾 | 用React 不用JSX | 让Claude困惑 | | ❌ 过时信息 | 还在写React 17 | 产生错误代码 | | ❌ 硬编码 | 写死IP地址 | 应该用环境变量 | ### 6.3 长度建议 | 项目规模 | 建议行数 | 说明 | |----------|----------|------| | 小型项目 | 30-50行 | 基本配置即可 | | 中型项目 | 50-150行 | 包含架构和规范 | | 大型项目 | 150-300行 | 详细分模块说明 | | 超大型项目 | 拆分多个文件 | 使用目录级CLAUDE.md | --- ## 7. 常见错误与避坑 ### 7.1 错误1信息过多 markdown # ❌ 错误示例信息过载 ## 项目介绍 这是一个非常复杂的项目包含了很多很多功能 我们使用了各种各样的技术包括但不限于... 写了500字介绍# ✅ 正确示例简洁明了 ## 项目画像 - **定位**: 电商平台后端 - **技术栈**: Java 21 Spring Boot 3 MyBatis-Plus - **数据库**: MySQL Redis7.2 错误2缺少代码示例# ❌ 错误示例太抽象 ## 命名规范 请使用正确的命名规范# ✅ 正确示例有具体示例 ## 命名规范 - 类名PascalCaseUserService - 方法名camelCasegetUserById - 常量UPPER_SNAKE_CASEMAX_RETRY_COUNT7.3 错误3没有更新# ❌ 错误示例过时配置 ## 技术栈 - React 17已升级到18 - Redux已换成Zustand - Webpack已换成Vite解决方案每次技术栈变更后同步更新CLAUDE.md。7.4 错误4忽略环境差异# ❌ 错误示例硬编码 ## 常用命令 npm run dev # 你的项目用的是yarn# ✅ 正确示例明确说明 ## 常用命令 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实战技巧