CLAUDE.md 完整解析 + VS Code Claude Code 项目实战一、什么是 CLAUDE.md？ 1.

一、什么是 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

/init

AI 会自动扫描当前项目结构，生成一份基础版 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

# 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.js

5. AI 操作行为约束

写代码前先确认 index.js 文件，所有新增逻辑追加至文件末尾，不覆盖原有有效代码
修改文件前告知修改行数与内容，禁止静默覆盖全部代码
输出代码时附带简单说明，不输出无关多余解释
禁止修改 CLAUDE.md 文件本身，仅允许人类编辑此规则文档
任务完成后自动输出运行命令，提示用户验证结果

plaintext


### 步骤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

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 编码流程。