> 用Claude Code开发项目，有一个文件你必须知道——CLAUDE.md。它解决的问题是：你不用每次开新对话都重新解释项目背景，Claude每次都能在正确框架里工作。很多人不知道，知道的人大多没写好。这篇把完整最佳实践整理出来。
---
为什么CLAUDE.md值得认真写
Claude最大的限制是：没有跨对话的长期记忆。每次新对话，它对你的项目一无所知。
没有CLAUDE.md时，每次对话的开头都像这样：
我们用React + TypeScript + Zustand，后端Node.js，数据库PostgreSQL，用Airbnb ESLint规则，不要用Redux，不要在PR里引入新依赖……每次都要说一遍，很烦，而且容易遗漏。CLAUDE.md把这些信息固化，Claude每次自动读取，不需要你重复。
---
完整的CLAUDE.md结构
1. 项目概述
一句话说清楚这个项目是什么、解决什么问题、目标用户是谁。不要写两段话，一句话足够。
示例：
这是一个面向内容创作者的多平台发布工具，用户一次写作，发布到微博、微信公众号、今日头条等多个平台。2. 技术栈
前后端语言、框架、主要依赖、数据库、部署环境，全部列清楚。有禁用的技术要明确写出来。
示例：
前端：React 18 + TypeScript 5.0 + Vite状态管理：Zustand（严禁使用Redux）样式：Tailwind CSS后端：Node.js + Express数据库：PostgreSQL + Prisma ORM测试：Vitest + React Testing Library部署：Vercel（前端）+ Railway（后端）3. 代码规范
命名约定、文件结构约定、测试规范，写清楚避免Claude用不一致的风格生成代码。
示例：
组件：PascalCase（UserProfile.tsx）Hooks：use前缀小驼峰（useUserData.ts）工具函数：小驼峰（formatDate.ts）常量：全大写下划线（MAX_RETRY_COUNT）测试文件：与源文件同级，命名为 xxx.test.ts4. 禁止事项（最重要）
这是整个CLAUDE.md里最关键的部分。告诉Claude不能做什么，有时候比告诉它做什么更重要。
示例：
- 不要修改 /src/core/ 目录下的文件，除非明确被要求- 不要提交没有对应测试的新功能代码- 不要使用 any 类型，必须有明确的TypeScript类型- 不要在未讨论的情况下引入新的npm依赖- 不要直接操作DOM，使用React状态管理5. 关键文件说明
告诉Claude哪些文件特别重要，修改前需要先理解完整逻辑。
示例：
src/auth/AuthContext.tsx：认证逻辑核心，修改前请先理解完整流程src/api/client.ts：所有API请求的基础客户端，修改需要测试所有端点prisma/schema.prisma：数据库schema，修改需要生成并验证迁移文件6. 常见任务指南
项目里最频繁的操作应该怎么做，统一规范。
示例：
添加新组件：在src/components/下创建，导出类型，在index.ts里re-export添加新API端点：在src/routes/下添加，在app.ts里注册，必须有Joi验证添加数据库字段：修改schema.prisma，运行npx prisma migrate dev，更新相关类型---
进阶用法：多级CLAUDE.md
Claude Code支持多级CLAUDE.md文件：
- 根目录 /CLAUDE.md：整个项目的全局规范
- 子目录 /src/auth/CLAUDE.md：认证模块的特殊说明
- 子目录 /src/api/CLAUDE.md：API层的接口设计规范
对大型项目非常实用，不同模块可以有不同的上下文粒度。
---
@import语法：引用已有文档
如果项目已有设计规范或API文档，不需要复制内容，直接引用：
@import ./docs/api-design-guide.md@import ./docs/component-guidelines.mdClaude会在需要时自动读取这些文件，保持内容单一来源。
---
加一个「工作模式说明」
这是容易被忽略但很有用的部分：告诉Claude在不同情况下应该怎么响应。
- 我问「这是怎么工作的」→ 先给我两句话摘要，再展开- 我让你「修改某个功能」→ 先展示diff，等我确认再执行- 遇到不确定的地方 → 直接问我，不要假设这几行加进去，Claude的行为风格会明显更贴合你的工作习惯。
---
如何维护CLAUDE.md
CLAUDE.md不是写一次就完的文件，要和项目一起迭代：
技术栈变了 → 更新技术栈部分。
Claude重复犯某类错误 → 把对应的禁止事项加进去。比如Claude总是生成 any 类型，就加一条「禁止使用any类型」。
引入了新的重要模块 → 更新关键文件说明。
把CLAUDE.md纳入版本控制，让整个团队共享同一套AI使用规范，保持一致性。
---
一份可以直接复制的模板
# [项目名称]## 项目概述[一句话说清楚项目是什么]## 技术栈- 前端：[框架 + 语言]- 状态管理：[工具]（禁用：[禁用的工具]）- 后端：[框架]- 数据库：[数据库 + ORM]## 代码规范- [命名规则]- [文件结构约定]## 禁止事项- 不修改 [关键目录]- 不引入新依赖（需先讨论）- 不使用 [禁用模式]## 关键文件- [文件路径]：[说明]## 工作模式- 问「怎么工作的」→ 先摘要再展开- 修改功能 → 先展示diff再执行- 不确定 → 直接问我把这个模板填进你的项目根目录，从下一个对话开始，Claude就知道该怎么和你配合了。
