一、核心定义与作用

CLAUDE.md 是 Claude Code 在每次会话开始时自动读取的项目记忆文件，本质上是一份结构化、人类可读、机器可识别的项目语境说明书。它承载着项目目标、技术栈约束、风格规范、关键接口说明及历史决策依据等关键元信息。

你可以把它理解为给 AI 写的「入职手册」——就像新员工入职第一天，你会给他一份文档，介绍公司用什么技术、代码怎么写、测试怎么跑、有什么坑要注意。

二、CLAUDE.md vs. README.md 的区别

很多人会问：为什么不直接写在 README.md 里？

文件	读者	定位	加载方式
README.md	人类开发者	项目介绍、快速上手	需手动告诉 Claude 去读
CLAUDE.md	AI Agent	配置、规则、约定	每次会话自动加载至上下文

Anthropic 官方文档明确指出："README 是写给人看的，CLAUDE.md 是写给 agent 看的，两个读者群体不一样，密度也不一样。"

三、放置位置与加载机制

CLAUDE.md 支持多级放置，系统按优先级合并读取，加载顺序为：项目本地 > 项目根目录 > 子目录 > 全局用户级。

位置	作用域	加载方式
~/.claude/CLAUDE.md	全局，所有项目生效	始终加载，适合个人偏好（如注释风格、commit 格式）
项目根目录 CLAUDE.md	当前项目	始终加载，全程常驻上下文，压缩后重新读取
子目录 CLAUDE.md	进入该目录时叠加	按需加载，只有 Claude 读取该目录下文件时才加载，压缩后丢失

加载过程源码逻辑：Claude Code 会从当前工作目录一路向上爬到文件系统根目录，每爬一层就读取该层的 CLAUDE.md 和 .claude/CLAUDE.md，全部合并喂给模型。

四、写入内容判断标准

核心原则：对每一行问自己——"删掉这行，Claude 会犯错吗？"不会就删。

✅ 应该写入的内容（AI 猜不到的东西）

• 构建命令和测试命令
• 与默认不同的代码风格规则
• 团队的 Git 规范（分支命名、PR 格式）
• 项目特有的架构决策
• 开发环境的特殊要求（必需的环境变量）
• 容易踩坑的地方
• 业务术语解释（如"大瓦特=南网AI平台"）
• 项目特殊约束（如"不要修改 X 目录"、"数据库用 GaussDB 不用 Oracle"）

❌ 不该写入的内容

• AI 读代码就能知道的东西
• 通用的语言规范（AI 本来就会）
• 详细的 API 文档（放别的地方，CLAUDE.md 里放链接即可）
• "写干净的代码""注意性能"这种废话
• 流程性内容（部署流程、代码审查清单）——应放在 Skills 中

五、编写要点与避坑指南

1. 控制在 200 行以内

官方文档明确建议，CLAUDE.md 尽量控制在 200 行以内。原因在于：

• 每一行都占 token，不管当前任务会不会用到
• 规则越多，遵循率越低：实测 200 行以内遵循率约 92%，400 行以上明显下降
• 社区研究指出，AI 大概能合理遵循 150 到 200 条指令，超过后遵循质量均匀下降

2. 用正面指令代替否定指令

研究发现，87.5% 的 AI 规则违反都来自否定句激活了被禁止的概念（类似心理学中的"白熊效应"）。

❌ 否定指令（不推荐）	✅ 正面指令（推荐）
不要使用 class 组件	使用函数式组件和 Hooks
不要用 any 类型	所有变量必须有明确的 TypeScript 类型定义
不要在主分支直接提交	所有变更通过 feature 分支提交 PR

3. 指令要具体可验证

模糊的指令等于没有指令。

❌ 模糊写法	✅ 具体写法
正确格式化代码	使用 2 空格缩进
测试你的更改	提交前运行 npm test
保持文件有序	API handlers 放在 src/api/handlers/

4. 告诉"为什么"

光告诉规则不够，还要告诉规则的原因。例如：

"不要在测试里写入生产数据库，因为去年有次测试不小心把 users 表清空了，出过事故。"

这样 Claude 不光知道规则，还知道规则的边界，能在类似场景做出正确判断。

5. 持续更新，清理旧规则

• Claude 犯错两次以上，就加一条防御规则
• 老规则要及时删除——"错误的规则比没有规则更糟"
• 指定一个负责人，像审代码一样审 CLAUDE.md 的改动

6. 文件膨胀后的处理策略

当 CLAUDE.md 超过 200 行时，应当：

• 把团队级规范 -> 推到路径限定的 Rules 中（.claude/rules/）
• 把流程性内容 -> 推到 Skills 中（.claude/skills/）
• 让它们只在需要时才加载，节省 token

7. 用 @import 做渐进式披露

不要把所有东西塞进 CLAUDE.md，而是告诉 AI 去哪里找它需要的信息：

## 参考文档
### API 架构 — @docs/api-architecture.md
何时阅读：添加或修改 API 端点时

### 数据库设计 — @docs/database-design.md
何时阅读：创建或修改数据模型时

8. 让 AI 帮你维护

每次 Claude 犯错，不要只修正错误，还要顺手让它把纠正写进 CLAUDE.md。Claude 特别擅长给自己写规则，时间久了，你的 CLAUDE.md 就变成了一份完整的项目知识库，出错率会明显下降。

六、快速创建

在项目根目录运行以下命令，Claude 会自动分析代码库结构生成初始 CLAUDE.md：

claude /init

不过需要注意，自动生成的内容可能不够精确，AI 只能看到你的代码成果，不理解背后的过程，需要自己过一遍，该删的删、该补的补。