CLAUDE.md 使用指南，从创建、加载到规则生效 -Yòuyou

CLAUDE.md 是什么

CLAUDE.md 是 Claude Code 的项目级指令文件，用于向 AI 提供项目背景、开发规范以及工作约定。

作为前端开发者，我们对 .eslintrc、.prettierrc、tsconfig.json 这些文件已经非常熟悉了。

我们不想每次写代码时，都去告诉 ESLint 不要使用 var，让 Prettier 使用两个空格缩进，让 TypeScript 开启严格模式。
我们希望这些事情只需要配置一次，后面工具就会按照约定执行。

CLAUDE.md 其实也是类似的思路，只不过从传统的开发工具变成了 Claude Code。

配置文件类比

前端熟悉的	CLAUDE.md 类似的
`package.json` 的 `scripts`	CLAUDE.md 的常用命令（`pnpm dev`、`pnpm test`）
`README.md`	项目概述和技术栈
`.editorconfig`	编码风格和命名约定
`.eslintignore`	`.claude/rules/` 的 `paths` 按目录限定规则
`~/.npmrc`（用户级 npm 配置）	`~/.claude/CLAUDE.md`（用户级，所有项目生效）

本质上做的是同一件事——把规范写成配置文件，让工具自动遵守。

为什么写了规则，Claude 仍可能违反

但是这里一定要注意，两者有一个明显的区别。

ESLint 执行的是确定性的规则，违反了就是违反了。而 Claude Code，它需要理解我们的要求，再结合上下文做出判断。
比如我们告诉它「不要修改无关代码」，它会尽量遵守，但并不代表它一定不会修改。

所以，我更愿意把 CLAUDE.md 理解为一份写给 AI 开发助手的项目协作约定，而不是传统意义上的配置文件。

并且在我看来，建立初步认识时把 CLAUDE.md 理解成「给 AI 看的 ESLint 配置」也不为过。

CLAUDE.md 的层级与作用范围

三个层级及优先级

CLAUDE.md 不只有一个文件，就像 Git 有全局配置和项目配置一样，CLAUDE.md 也有自己的作用范围:

层级	位置	作用范围	谁能用	典型内容
组织级	`/Library/Application Support/ClaudeCode/CLAUDE.md`（macOS）	整个组织的所有机器	IT 部署	公司编码规范、安全策略
用户级	`~/.claude/CLAUDE.md`	你设备上的所有项目	只有你自己	个人编码偏好、常用工具
项目级	`./CLAUDE.md` 或 `./.claude/CLAUDE.md`	当前项目使用	可以共享给团队	技术栈、代码规范、常用命令

配置优先级遵循 越具体的优先级越高。 项目级 > 用户级 > 组织级，冲突时以更具体的那个层级为准。

另外还有一个本地覆盖层 .claude/CLAUDE.local.md，配置好后，让 Git 忽略它，只在你自己机器上生效，用于存放个人在项目中的偏好。

实际使用场景

层级	大致内容
组织级	公司要求所有开发者使用 AI 修改代码时，不得擅自提交代码或推送到远程仓库 → 写在组织级 CLAUDE.md
用户级	你习惯让 Claude Code 用中文回答，修改代码时尽量复用现有组件 → 写在 ~/.claude/CLAUDE.md，所有项目通用。
项目级	你正在维护一个 Vue 3 + TypeScript 项目，统一使用 pnpm，不允许使用 any → 写在项目根目录的 CLAUDE.md，团队成员都能用。
本地覆盖层	团队都用 pnpm dev 启动项目，但你本地还得先启动 Redis → 写在 CLAUDE.local.md，只对你当前这个项目生效

简单理解：公司的规矩放组织级，自己的习惯放用户级，项目的要求放项目级，自己需要的特殊配置放本地。

CLAUDE.md 创建方法

AI 时代，我更推荐直接让 Claude 帮你生成。你也可以自己新建一个文件慢慢写，但毕竟都用上 AI 了，没必要什么都自己动手。

手动创建就是直接在项目根目录新建一个 CLAUDE.md 文件。它本质上就是一个 Markdown 文件，没有什么特殊语法要求。

使用 /init 自动生成（推荐）

进入项目目录，启动 Claude Code，输入：

/init

Claude Code 会分析当前项目，读取 package.json、配置文件以及部分源码，了解项目使用了什么技术、目录是怎么组织的、有哪些常用命令，然后生成一份 CLAUDE.md。

你也可以在命令后面加上自己的要求：

/init 使用中文生成，重点说明项目架构、公共组件和常用开发命令

这样生成的内容会更符合自己的阅读习惯。

/init 的交互式模式（更推荐）：

设置环境变量后，/init 会变成多步骤交互流程：

export CLAUDE_CODE_NEW_INIT=true

交互模式下 /init 会：

询问你要设置哪些配置（CLAUDE.md、Skills、Hooks）
用子代理深入扫描代码库
针对不确定的地方问你补充信息
生成方案让你确认后再写入

不过这里有个问题：

Claude Code 能看懂你的代码，但不一定懂你们团队的规矩。

比如它能从 package.json 里发现项目使用 pnpm，却不一定知道团队为什么禁止修改某个公共组件。

这些藏在开发者脑子里的经验，还是需要我们自己补充。

所以正确的工作流是：

/init 生成基础版本 → 你手动补充 Claude 发现不了的规则 → 日常迭代

使用 Claude 来帮你维护

/init 只负责「从零到一」，后续的维护靠日常积累：

比如某次让 Claude Code 修改一个 Vue 组件，结果它顺手把其他地方的代码也重构了。

你可以直接告诉它：

把下面这条规则补充到 CLAUDE.md：
 
修复 Bug 时，只修改与当前问题相关的代码，
不要擅自重构其他模块。

下次遇到类似任务，它就能参考这条约定。

当然，也不是每次犯错都要往里面加一条规则，否则文件迟早变成一本开发手册。

最好只保留那些经常遇到、能够在不同任务中反复使用的约定。

没有代码的新项目如何初始化

/init 比较适合已经有代码的项目，因为 Claude Code 可以直接分析现有实现。

但如果项目刚创建，连 package.json 都没有，那也没什么可分析的。

这时候直接告诉 Claude 你的项目计划就行：

帮我创建一个 Vue 3 组件库项目，并生成 CLAUDE.md。要求：
- Vue 3.4 + TypeScript 5.3 + Vite 5.0 + pnpm
- 禁止用 any 类型
- 组件用 <script setup> 语法
- 用 Vitest 做测试，UnoCSS 做样式
- 提交代码前必须跑 lint 和 test

等项目逐渐完善，再通过 /init 或直接对话更新 CLAUDE.md。

我的使用建议

有现成项目，就先用 /init 生成初稿；没有代码，就直接描述需求让 Claude 创建。

至于后续维护，我更倾向于在日常开发中慢慢积累。

毕竟一开始写得再详细，也不一定能覆盖实际遇到的问题。

与其花半天时间研究怎么写一份完美的 CLAUDE.md，不如先用起来，等 Claude 真正犯了某个值得避免的错误，再考虑把它变成一条长期约定。

CLAUDE.md 加载过程

Claude Code 启动时遵循向上逐级查找，它会从当前工作目录开始，沿着目录结构向上查找 CLAUDE.md 文件。

比如你的项目目录是这样的:

workspace/
├── CLAUDE.md
└── admin/
    ├── CLAUDE.md
    └── src/

如果你在 admin/ 目录下启动 Claude Code，它不仅会读取 admin/CLAUDE.md，还会读取上一级的 workspace/CLAUDE.md。
除此之外，用户级的 ~/.claude/CLAUDE.md 也会加载。

这就意味着，CLAUDE.md 并不是只能放在项目根目录，它也可以通过目录层级来组织。

比如一个 Monorepo 项目，根目录放一些通用约定，前端和后端子项目再分别维护自己的规则。

这样就不用把所有要求都塞进同一个文件里了。

子目录的规则

除了向上查找，Claude Code 也支持子目录中的 CLAUDE.md。

不过这里有个区别：子目录的 CLAUDE.md 通常不会在启动时全部加载，而是在 Claude 访问对应目录的文件时按需加载。

比如：

src/
├── components/
│   └── CLAUDE.md
└── api/
    └── CLAUDE.md

当 Claude 处理 components/ 下的文件时，就可以读取对应的组件开发约定。

这样一来，组件规范和接口规范就可以分开管理，互不干扰。

用 `.claude/rules/` 拆分规则

如果项目比较复杂，CLAUDE.md 可能会越写越长。

Claude Code 提供了一个 .claude/rules/ 目录，专门用来拆分这些规则。

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    ├── api.md
    └── testing.md

更有意思的是，rules 还支持通过 paths 指定规则适用于哪些文件。

比如我们只希望接口开发规范对 src/api/ 下的 TypeScript 文件生效：

---
paths:
  - 'src/api/**/*.ts'
---
 
# API 开发规范
 
- 优先使用项目已有的请求封装
- 统一处理接口异常
- 不要在组件中直接编写请求逻辑

这样，当 Claude 处理匹配路径的文件时，就会加载对应规则。

如果没有配置 paths，规则默认会作为通用规则加载。

其实这套加载机制最有价值的地方，就是让我们可以按范围管理规则。

个人习惯放用户级，项目约定放根目录，某个模块有特殊要求，就放到对应子目录或者 .claude/rules/。

不需要让 Claude 每次都背着整个项目的开发手册，只需要在合适的时候，让它看到合适的规则。

CLAUDE.md 编写指南

不需要面面俱到，只写 Claude 经常做错的部分才有价值。官方也同样建议控制在 200 行以内。

我的理解是：代码里能直接看出来的东西，没必要反复解释；Claude 容易做错、又无法从代码中判断的事情，才值得重点写。

一般可以从下面几个方面考虑:

项目概述

## 项目概述
 
一个基于 Vue 3 的后台管理系统。
技术栈：Vue 3.4+ | TypeScript 5.3+ | Vite 5.0+ | pnpm 8+

写具体版本号，不要只写「Vue 3」。Claude 会根据版本选择不同的 API。

编码规范

## 编码规范
 
- Vue 组件统一使用 <script setup>
- 禁止使用 any，优先定义明确的类型
- 优先复用现有组件和工具函数
- 事件处理函数统一使用 handle 前缀
- 新增接口必须使用已有的请求封装

CLAUDE.md 更适合记录那些工具不容易检查，但团队又很在意的事情。

禁止事项

我个人觉得，这部分甚至比编码规范更重要。

因为实际使用 Claude Code 时，最头疼的往往不是它不会写，而是它太积极了。

明明只是修复一个 Bug，它顺手重构了整个组件；明明项目已经有工具函数，它又重新写了一份。

比「应该怎么做」更重要的是「不要做什么」：

## 禁止事项
 
- 禁止直接修改 props（Vue 单向数据流）
- 禁止在组件中使用全局样式，必须 scoped
- 禁止使用已废弃 API（如 `::v-deep`）
- 不要在未经确认的情况下重构公共组件
- 不要删除或覆盖现有配置文件
- 遇到不明确的业务逻辑，先询问再修改

常用命令

告诉 Claude 项目怎么启动、怎么测试。

## 常用命令
 
- pnpm dev：启动开发环境
- pnpm build：生产环境构建
- pnpm lint：代码检查
- pnpm test：执行测试

项目结构

这部分我不建议把整个 src 目录复制进去。项目一大，目录可能有几百个，既没有阅读价值，也很容易过时。

只需要告诉 Claude 那些不容易发现的关键入口即可。

- src/api/：接口请求
- src/components/：公共组件
- src/views/：业务页面
- src/stores/：全局状态
- src/utils/：公共工具函数

如果项目本身的目录命名已经足够清晰，甚至可以省略这一部分。

CLAUDE.md 不是写给 Claude 的项目百科全书，而是一份帮助它少犯错的备忘录。

与其写 500 行 Claude 不一定能有效利用的规则，不如留下几十行真正能影响它行为的内容。

CLAUDE.md 编写原则

其实很多时候，不是 Claude 完全不听话，而是我们自己写的规则太模糊。

比如「保持代码简洁」「遵循最佳实践」，这些话看起来没什么问题，但什么叫简洁？什么又算最佳实践？

原则一：规则要具体，最好能验证

差：说了等于没说，不知道做到什么程度算「好」

- 保持代码简洁
- 使用合理的命名
- 遵循最佳实践

好：有明确的判断标准，可以验证，做没做完一目了然

- Vue 组件文件使用 PascalCase，如 UserTable.vue
- 工具函数文件使用 camelCase，如 formatDate.ts
- 单个组件超过 300 行时，优先考虑拆分

重点是让规则有明确的判断依据，而不是让 Claude 自己理解什么叫「最佳实践」。

原则二：说为什么，不只说是什么

差：只告诉 Claude 不准做，Claude 遇到特殊情况可能会忽略

- 不要随意修改公共组件

好：告诉它为什么不能这么做，Claude 遇到类似场景会举一反三

- 修改公共组件前必须先确认，
  因为这些组件被多个业务模块复用，
  直接修改可能影响其他页面。

告诉 AI 原因，是为了让它理解规则背后的意图，而不只是记住一句话。

原则三：用示例代替模糊描述

差：只有文字要求

- 组件 Props 必须使用 TypeScript 类型定义

好：直接给出参考写法

组件 Props 统一使用以下写法：
 
interface Props {
title: string
disabled?: boolean
}
 
defineProps<Props>()
 
不要使用 defineProps({ title: String })

不过也没必要把大段代码复制进去，只保留能够说明规则的关键部分就够了。

原则四：多关注「不要做什么」

差：重复 Claude 本来就知道的事情

- 编写高质量代码
- 合理封装公共组件
- 注意代码可维护性

好：明确那些容易踩坑的地方

## 禁止事项
 
- 不要修改与当前任务无关的代码
- 不要擅自引入新的第三方依赖
- 不要未经确认就重构公共组件
- 不要为了修复 Bug 删除原有功能

Claude 的默认行为已经很强了，它知道怎么写「正常」的代码。CLAUDE.md 的价值主要在纠正它做错的部分。所以「禁止事项」往往比「应该做的」更重要。

与其告诉 Claude 一百遍「要写好代码」，不如明确告诉它「哪些事情不要自作主张」。

原则五：控制长度

官方建议 200 行以内。超过这个长度，Claude 的遵守率会明显下降。不是写得越多越好，而是写对的部分才有效。

哪些地方 Claude 经常做错，就补充哪些规则；哪些规则已经没用了，就及时删除。

毕竟我们的目的不是写出一份完美的配置文件，而是让 Claude 在实际开发中少犯错。

规则没有生效时如何排查

写好了 CLAUDE.md，不代表 Claude 就一定会乖乖照做。如果发现规则没有生效，可以从下面几个方面排查：

Claude 没遵守规则：先用 /memory 检查对应的 CLAUDE.md 有没有被加载。如果文件都没加载，写再多规则也没用。如果已经加载，就要看看规则是不是写得太模糊了。
规则互相冲突：比如用户级要求使用 pnpm，项目级却要求使用 npm。Claude 可能无法稳定判断该遵守哪条，最好检查不同层级的规则，避免互相矛盾。
规则太多，遵守效果变差：CLAUDE.md 不是越长越好。200 行可以作为一个精简参考，而不是硬性限制。如果文件越来越臃肿，可以删除重复内容，或者拆分到 .claude/rules/ 中按需加载。

tags	tutorial, claudecode, projectinstruction
aliases	—

Yòuyou

探索

CLAUDE.md 使用指南，从创建、加载到规则生效

CLAUDE.md 是什么

配置文件类比

为什么写了规则，Claude 仍可能违反

CLAUDE.md 的层级与作用范围

三个层级及优先级

实际使用场景

CLAUDE.md 创建方法

使用 /init 自动生成（推荐）

使用 Claude 来帮你维护

没有代码的新项目如何初始化

我的使用建议

CLAUDE.md 加载过程

子目录的规则

用 `.claude/rules/` 拆分规则

CLAUDE.md 编写指南

项目概述

编码规范

禁止事项

常用命令

项目结构

CLAUDE.md 编写原则

原则一：规则要具体，最好能验证

原则二：说为什么，不只说是什么

原则三：用示例代替模糊描述

原则四：多关注「不要做什么」

原则五：控制长度

规则没有生效时如何排查

关系图谱

目录

Yòuyou

探索

CLAUDE.md 使用指南，从创建、加载到规则生效

CLAUDE.md 是什么

配置文件类比

为什么写了规则，Claude 仍可能违反

CLAUDE.md 的层级与作用范围

三个层级及优先级

实际使用场景

CLAUDE.md 创建方法

使用 /init 自动生成（推荐）

使用 Claude 来帮你维护

没有代码的新项目如何初始化

我的使用建议

CLAUDE.md 加载过程

子目录的规则

用 .claude/rules/ 拆分规则

CLAUDE.md 编写指南

项目概述

编码规范

禁止事项

常用命令

项目结构

CLAUDE.md 编写原则

原则一：规则要具体，最好能验证

原则二：说为什么，不只说是什么

原则三：用示例代替模糊描述

原则四：多关注「不要做什么」

原则五：控制长度

规则没有生效时如何排查

关系图谱

目录

用 `.claude/rules/` 拆分规则