CLAUDE.md完全指南：三层级加载机制与最佳写法技巧

很多人在使用 Claude Code 时都会创建 CLAUDE.md 文件，但据观察，90%的用户其实并不清楚这个文件的加载机制到底是怎样的。本文基于官方文档和实际验证，带你彻底搞懂 CLAUDE.md 的层级结构、加载规则和写作技巧。

CLAUDE.md 到底是什么

CLAUDE.md 本质上就是一个纯文本文件，你在里面写的指令，Claude 每次对话都会自动读取一遍。它的核心价值在于：把你不想每次重复说的话写进去。

但有一个非常重要的认知需要纠正：CLAUDE.md 不是系统提示词（System Prompt），它是作为用户消息注入的。也不要把它当作强制配置——Claude 会尽量遵循其中的指令，但不保证百分之百执行。

那什么时候该往里面写内容？官方给出了四个触发场景：

Claude 第二次犯同样的错误时
Code Review 中反复出现的问题
只对某部分代码有意义的规则，放到对应的 Skill 或 Rules 里
团队共享的架构规范和工作流

核心机制：向上遍历与全部拼接

Claude Code 启动时会做两件关键操作：向上遍历和全部拼接。

从你当前工作目录开始

向上遍历是指从你当前工作目录开始，逐级往上查找 CLAUDE.md 和 CLAUDE.local.md 文件。全部拼接则是把找到的所有文件内容全部拼接到上下文中——注意，是拼接而不是覆盖。

以实际案例来说，假设你在 131-SQL进化 这个目录下工作，Claude 启动时会从下往上依次查找：

当前目录的 CLAUDE.md
上一级 130-进化实验室 的 CLAUDE.md
再上一级个人仓库的 CLAUDE.md
最后是全局用户目录的 CLAUDE.md

一共加载 4 个文件，全部拼在一起送入上下文。

冲突处理：后缀覆盖原则

当多个层级的指令发生冲突时，遵循后缀覆盖原则。更深层级（更接近当前工作目录）的文件排在后面，由于 LLM 的特性——后输入的内容权重大于先输入的——所以离你工作目录越近的指令优先级越高。

同一层级内，CLAUDE.local.md 追加在 CLAUDE.md 后面加载，因此你的个人笔记在该层级中拥有最高优先级。

子目录的延迟加载

子目录里的CLAUDE.md

还有一个精妙的设计细节：子目录里的 CLAUDE.md 不会在启动时加载，只有当 Claude 实际读取那个子目录的文件时才会触发加载。这个设计非常聪明，有效节省了上下文空间。

三个层级：文件该放哪里

理解了加载机制后，来看文件应该放在哪里。CLAUDE.md 一共有三个层级，每个层级的作用范围和适用场景各不相同。

第一层：用户全局级

位置：~/.claude/CLAUDE.md

对你所有项目生效，适合放置个人偏好和工具配置，比如你偏好的代码风格、常用的开发工具设置等。

第二层：项目级

位置：项目根目录下的 CLAUDE.md 或 .claude/CLAUDE.md

这两个位置是等价的，选一个即可。通过 Git 与团队共享，适合放架构说明、工作流定义、命名规范等团队共识。

第三层：项目本地级

位置：CLAUDE.local.md

只对你自己、只对当前项目生效，应加入 .gitignore。适合放 API 地址、测试数据等不想提交到 Git 的个人配置。

两个高级功能

@import 导入机制

支持相对和绝对路径

在 CLAUDE.md 里写 @import 加文件路径，就能把其他文件的内容也导入进来。支持相对路径和绝对路径，最多支持 5 层嵌套递归。

但要注意：导入的文件也会在启动时加载，不能用来节省 Token，它只是一种组织文件的方式。

.claude/rules 规则系统

大型项目可以把指令拆成多个文件，放在 .claude/rules 目录下：

没有 Path 配置的规则：无条件加载
有 Path 配置的规则：只在操作匹配文件时才加载

比如你可以设置一个规则，只在编辑 TypeScript 文件时才加载 API 规范，非常灵活。

怎么写好 CLAUDE.md：具体可验证

写 CLAUDE.md 的核心原则是具体可验证，避免模糊的描述：

❌ 不要这样写	✅ 应该这样写
格式化代码	用 2 空格缩进
测试你的改动	提交前跑 `npm test`
保持文件有序	API 在 `src/api/handlers`

关键限制

每个文件控制在 200 行以内。超过这个长度，Claude 的遵从度会明显下降。

隐藏技巧：HTML 注释不消耗 Token

HTML注释会自动被过滤

HTML 注释（）会自动被过滤，不消耗 Token。你可以利用这个特性在 CLAUDE.md 中添加给人看的备注，而不影响 Claude 的上下文窗口。

常见问题与解决方案

CLAUDE.md 写了但不生效怎么办

运行 /memory 命令确认文件是否被加载
检查文件位置是否正确
检查指令是否足够具体
排查是否存在层级冲突

/compact 之后指令丢失

这是一个容易踩的坑：

根目录的 CLAUDE.md 会在 Compact 后存活，因为 Claude 会重新从磁盘读取
子目录的 CLAUDE.md 不会自动重新注入
对话中的临时指令 会被清除

所以重要的指令一定要写进 CLAUDE.md，不要只在对话中口头交代。

快速开始

最简单的方式：在项目根目录创建 CLAUDE.md，写入构建命令和基本规范即可。

或者更省事的方式——直接运行 /init 命令，Claude 会自动分析代码库并生成配置文件。如果想要交互式配置体验，可以设置环境变量 CLAUDE_CODE_NEW_INIT=1 后再运行 /init。

掌握了这些机制和技巧，你的 CLAUDE.md 就不再是一个随意堆砌的文本文件，而是一个精心设计的 AI 协作配置系统。