一、什么是 CLAUDE.md？
1. 核心定位
我们平时写项目会用 README.md 给人 看项目说明，而 CLAUDE.md 是专门写给 Claude Code AI 看的项目规则手册 。只要文件放在项目根目录，每次打开 Claude Code 会话，AI 会自动读取、全程遵守里面的所有约束，完美解决两大痛点：
- 不用每次对话反复交代项目技术栈、代码规范、目录规则；
- 避免 AI 乱写代码、乱改文件、输出不符合项目风格的逻辑。
简单类比：
README.md= 新人开发手册（人类阅读）CLAUDE.md= AI 入职约束文档（Claude 自动加载）
2. 多层加载机制（关键知识点）
CLAUDE.md 支持四级作用域，就近目录优先级更高，规则会叠加生效：
表格
| 文件位置 | 生效范围 | 用途 |
|---|---|---|
~/.claude/CLAUDE.md |
全局所有项目 | 个人通用编码偏好（缩进、注释风格） |
项目根目录 ./CLAUDE.md |
当前整个仓库 | 团队共享、提交 Git，统一项目标准 |
子目录 xxx/CLAUDE.md |
仅该文件夹 | 模块专属规则（如前端 / 后端区分规范） |
.claude/CLAUDE.md |
项目私有配置 | 不提交 Git，存放本地专属指令 |
实战小技巧：根目录的
CLAUDE.md可以提交到代码仓库，团队所有人使用 Claude Code 时自动统一编码规范。
3. 标准文件该写哪些内容？
一份高质量 CLAUDE.md 包含 5 大模块，拒绝空洞话术（比如 "好好写代码"），全部写可落地、可校验的规则code.claude.com：
- 项目基础信息：项目用途、技术栈、业务目标
- 目录结构约定：各文件夹存放内容，禁止修改的文件
- 编码强制规范：缩进、命名、注释、语法、代码长度限制
- 工程命令：运行、测试、打包、调试指令（AI 执行工具时自动使用）
- AI 行为约束：文件读写限制、输出格式、禁止操作、沟通规则
二、前置操作：一键生成基础 CLAUDE.md
像截图里演示的一样，在 VS Code Claude Code 面板输入指令：
plaintext
bash
/initAI 会自动扫描当前项目结构，生成一份基础版 CLAUDE.md，我们再手动完善项目专属规则，不用从零手写。
三、实战演示：add-demo 加法工具完整项目（对应截图案例）
场景说明
截图中我们创建了 add-demo Node.js 简易项目，需求：编写加法工具函数，附带测试调用，全程通过 CLAUDE.md 约束 AI 行为，不再重复说明规则。
步骤 1：执行 /init 生成初始 CLAUDE.md
打开 VS Code Claude Code 侧边栏，输入 /init，AI 自动识别项目，生成基础配置文件，此时原始文件缺少精准约束，我们重写为标准规范版。
步骤 2：完整版 CLAUDE.md 模板（可直接复制使用）
markdown
markdown
# CLAUDE.md - add-demo 项目AI约束文档
## 1. 项目基础信息
- 项目名称：add-demo
- 技术栈：原生 Node.js，无框架、无 TS，纯 JavaScript
- 项目目标：封装通用加法工具函数，支持整数、浮点数运算，附带控制台测试用例
- 入口文件：index.js（唯一代码文件，所有逻辑统一写在此处）
## 2. 目录结构约束
项目仅2个核心文件，禁止新增其他 js 文件：
- index.js：业务代码、工具函数、测试示例
- CLAUDE.md：AI 规则配置文件
禁止自动创建 src、test、dist 等文件夹，保持极简结构。
## 3. JavaScript 编码强制规范
1. 缩进：2个空格，禁止 Tab
2. 函数：使用 function 声明，不使用箭头函数简写
3. 注释：函数上方单行注释说明功能，调用示例添加注释区分
4. 输出：测试代码统一使用 console.log，打印格式 `函数名(参数) = 计算结果`
5. 变量命名：小写驼峰，简单易懂，无复杂缩写
6. 禁止：添加多余依赖、引入第三方库、使用 ES Module import/export
## 4. 运行&调试命令
运行项目固定指令，修改代码后执行此命令验证：
```bash
node index.js5. AI 操作行为约束
- 写代码前先确认 index.js 文件，所有新增逻辑追加至文件末尾，不覆盖原有有效代码
- 修改文件前告知修改行数与内容，禁止静默覆盖全部代码
- 输出代码时附带简单说明，不输出无关多余解释
- 禁止修改 CLAUDE.md 文件本身，仅允许人类编辑此规则文档
- 任务完成后自动输出运行命令，提示用户验证结果
plaintext
scss
### 步骤3：发起需求，AI 自动遵守规则生成代码
输入自然语言需求：
> 写一个加法工具函数，支持两个数字相加，附带两组调用测试：整数相加、正负浮点数相加
此时 Claude Code 读取 `CLAUDE.md` 约束，自动生成符合规范的 `index.js`，和截图内代码完全一致：
```javascript
// 加法工具：返回两个数的和
function add(a, b) {
return a + b;
}
// 调用示例
console.log('add(1, 2) =', add(1, 2));
console.log('add(-5, 3.7) =', add(-5, 3.7));步骤 4：运行验证
AI 自动输出运行指令，终端执行：
bash
运行
node index.js输出结果：
plaintext
scss
add(1, 2) = 3
add(-5, 3.7) = -1.3实战优势对比（有无 CLAUDE.md 区别）
表格
| 无 CLAUDE.md | 配置 CLAUDE.md 后 |
|---|---|
| 每次对话都要说明：用原生 JS、不要新建文件夹、用 function 函数 | AI 自动读取规则，无需重复描述 |
| AI 可能生成箭头函数、新建 test 文件夹、引入模块 | 严格遵守缩进、命名、文件结构约束 |
| 生成代码无固定输出格式，测试打印杂乱 | 统一规范日志输出，符合项目约定 |
| 经常静默覆盖全部代码，丢失原有逻辑 | 修改前提示变更范围，追加代码而非覆盖 |
四、编写 CLAUDE.md 的避坑技巧
- 规则要具象，拒绝模糊描述错误：代码写规范一点、注释清晰；正确：JS 使用 2 空格缩进，每个函数顶部添加单行功能注释。
- 控制篇幅，只写 AI 必须知道的内容不用把完整业务文档全塞进去，只保留编码、文件、命令、行为约束，过长会稀释模型注意力。
- 区分项目规则和个人偏好 项目根目录文件写团队通用规范（可提交 Git）；全局
~/.claude/CLAUDE.md存放个人习惯。 - 及时迭代更新 项目新增技术栈、目录变更后，同步修改
CLAUDE.md，避免 AI 沿用旧规则生成错误代码。 - 搭配 /init 命令快速初始化 新项目直接执行
/init生成基础模板，再补充自定义约束，从零手写效率极低。
五、总结
CLAUDE.md 是 Claude Code 最高性价比的效率工具，本质是给 AI 提供持久化、会话共享的项目上下文 。以前每次和 AI 沟通都要重复交代项目规则，配置好一份规范的 CLAUDE.md 后，AI 会自动适配你的项目架构、代码风格、文件约束，大幅减少人工修正代码的成本。
本文配套的 Node.js 极简加法项目可直接复刻，你只需要复制文中 CLAUDE.md 模板到项目根目录，就能立刻体验规范约束带来的流畅 AI 编码流程。