一句话定义
CLAUDE.md 是放在项目里的 markdown 说明书，Claude Code 会在每次 session 启动时自动读入，把它当成这个项目的长期规则。
人话版：你不用每次都重新交代“这个项目怎么干活”，把长期有效的规矩写进 CLAUDE.md，AI 一进来就先看这张说明书。
为什么重要 / 什么场景会听到
它重要，不是因为名字特殊，而是因为它直接进入 上下文，决定 Claude Code 第一天进入项目时会不会乱猜。
常见场景：
- 新成员刚进项目，不知道目录结构、命令、禁区；没有
CLAUDE.md时 AI 容易乱改结构，有了它就会先按项目规则做事。 - 同一个 bug 一周内犯两次；如果没把“不要这样做”写进
CLAUDE.md，AI 还会重复踩坑，写进去之后它更像有了错题本。 - 团队想把共识固定下来，而不是靠口头提醒；
CLAUDE.md比一次性 prompt 更稳，因为它会被反复自动加载。
技术机制
官方 claude-code-docs/memory.md 的描述：
“Claude Code automatically loads CLAUDE.md into context at the start of every session.”
重要但大家常忽略：CLAUDE.md 有三层，作用域不同。
| 层 | 路径 | 作用域 | 谁维护 |
|---|---|---|---|
| 项目级 | ~/my-project/CLAUDE.md | 只对这个项目生效 | 团队 |
| 个人项目级 | ~/my-project/CLAUDE.local.md | 只对你本机 + 这个项目 | 你自己（不进 git） |
| 全局级 | ~/.claude/CLAUDE.md | 所有项目都生效 | 你自己 |
三层都会被读，合并进上下文；规则冲突时，局部覆盖全局。
该写什么：
- 常用 bash 命令
- 代码风格约定
- 项目结构说明
- 测试怎么跑、部署怎么做
- 常见错误的预防
别写什么：
- 一次性临时要求
- 保密信息
- 超长技术细节堆砌
- 无关的历史变更日志
Boris 的两个高价值做法也说明了它的运作方式：
- Claude 做错了，就把这条错法补进
CLAUDE.md - PR 评论里可以直接让 Claude 把新规则加回
CLAUDE.md
这也是为什么它和 MD-based System 强相关：系统规则不是藏在脑子里，而是落在 md 里让 AI 反复读取。
最小可跑通例子
一个能直接抄的最小模板：
# [项目名]
## 项目简介
## 常用命令
## 代码约定
## 目录结构
## 不要做
## 犯过的错（持续增长）从 22 份真实样本归纳出来，第一版最常见也最够用的几段是：
- 项目简介
- 常用命令
- 代码约定 / 风格
- 目录结构
- 不要做清单
常见误解 / 陷阱
- 误解一：
CLAUDE.md是一次性文档。不是，它更像持续增长的错题本。 - 误解二：越长越专业。不是，堆到几千字技术细节后，加载负担和歧义都会上来，往往不如精简且结构清楚的版本。
- 误解三：只写“要做什么”就够了。不是，“不要做”清单通常更关键，因为它直接划禁区。
- 误解四：临时要求也应该写进去。不是，临时要求应该放在当前对话里，长期规则才适合进
CLAUDE.md。
与其他术语的关系
[[MD-based System]]：CLAUDE.md是最典型的 MD-based 实践之一。[[agent]]/[[skill]]/[[workflow]]/[[subagent]]：这些运行单元都依赖CLAUDE.md提供项目级边界和默认规则。[[MCP]]：CLAUDE.md负责写清“怎么做事”，MCP 负责“能连哪些外部工具”。[[上下文]]：CLAUDE.md会自动进入上下文，是影响 session 起点的核心输入。[[Harness]]：它属于 harness 的说明书层。[[22 份真实 CLAUDE.md 共同结构]]：这页是CLAUDE.md写法的实证补充。[[hook-slash-command]]：CLAUDE.md给长期规则，hook 和 slash command 管运行时触发。[[入门]]：第一次写自己的CLAUDE.md，可以从这条路径开始。
陈彬视角
“不要做”清单比”要做”清单重要 3 倍。
另一个独立观察：CLAUDE.md 写得好不好，基本等于你”工作方式的自我觉察度”有多高。
延伸阅读 / 官方链接
🎬 3 个场景（读者最可能用到的情境）
场景 1 · HR 装”员工盘点规则”
HR 每季度盘点员工档案。把”数据字段口径、敏感信息脱敏要求、导出格式、哪些字段禁止外发”写进 CLAUDE.md。下次开对话不用再交代”工号脱敏后四位”，AI 第一时间就按规矩走。
场景 2 · 散户装”交易纪律”
散户复盘账户。CLAUDE.md 写清”只看 A 股 + 港股、仓位上限、禁止推荐个股、必须给持仓风险提示”。这样 AI 不会聊着聊着滑到”要不要满仓 XXX”。
场景 3 · 文科老师装”备课风格偏好”
老师备课让 AI 起草教案。CLAUDE.md 写”学生是大一文科生、避免编程术语、每节课留 10 分钟讨论题、不要照搬教材目录”。风格一次说清，之后每次备课都稳。
⚖️ 和最像的邻居比
| 术语 | 本质区别 | 适用边界 |
|---|---|---|
| CLAUDE.md | 项目级常驻说明书 · 每次 session 自动加载 | 长期有效的规则、禁区、命令、风格 |
| agent | 有角色、有判断的 worker | 某类任务需要固定”谁上场” |
| skill | 按需加载的能力包 | ”这件事怎么干”的可复用流程 |
| prompt | 一次性指令 | 这一轮的具体要求，不复用 |
🚫 反例（不该这么用）
反例 1 · 写成 5000 字技术细节
把架构文档、API 参考、历史变更日志全塞进 CLAUDE.md，每次 session 一开场就吃掉大半上下文。正确做法：技术细节放独立 md，CLAUDE.md 只留”真正每次都要读的长期规则”。
反例 2 · 把敏感员工数据写进去
HR 把真实员工姓名、工号、薪资样例写进 CLAUDE.md 方便 AI”理解”。结果 git 一 push 就泄露。正确做法：敏感数据放 CLAUDE.local.md（不进 git），或只写口径不写真实值。
反例 3 · 每次对话都重新配
开一个新会话就复制粘贴一版规则，从不落进 CLAUDE.md。正确做法：凡是”下一次还会再讲一遍”的规则，就是 CLAUDE.md 的命中区。
❓ 常见误解
- 误解 1：“CLAUDE.md 越长越专业” → 实际：越长加载负担越大，3000 字后噪音开始盖过信号，“能删则删”比”多写一条”更有价值。
- 误解 2：“只写正面要求就够了” → 实际：“不要做”清单通常比”要做”更关键，它直接划禁区，防止 AI 踩同一个坑两次。
- 误解 3：“CLAUDE.md 是一次写完的文档” → 实际：它是持续增长的错题本，每次 AI 做错一件事，就把这条错法补进去。
🧬 历史坐标（最早谁提 · 本质 · 分型 · git）
最早谁提
2025 年 2 月 · Anthropic 发布 Claude Code research preview（2025 年 5 月 GA）时把 CLAUDE.md 作为 memory 机制的一部分官方固化下来。官方说明页：https://code.claude.com/docs/en/memory
本质（一句话 · 20 字内）
启动时自动入上下文的项目说明书。
分型 / 演化（2-4 行主线）
- 2023 · 各 AI 编辑器（Cursor
.cursorrules、AiderCONVENTIONS.md）开始流行”项目级规则文件” - 2025-02 · Claude Code 发布，
CLAUDE.md作为官方 memory 机制定型（项目级 + user-level +~/.claude/CLAUDE.md三层合并） - 2025 中 ·
#键快速追加记忆、CLAUDE.local.md私有分层 - 2026 · 社群 awesome-claude-code 沉淀上百份真实样本，
CLAUDE.md成为”AI 工程师默认交付物”
代表 git / 文档
- anthropics/claude-code · Anthropic · Claude Code 官方仓库
- hesreallyhim/awesome-claude-code · 社群 · 真实 CLAUDE.md 样本集合
- 官方 memory 文档 · Anthropic · CLAUDE.md 三层作用域权威说明