CLAUDE.md（项目说明书）

一句话定义

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 份真实样本归纳出来，第一版最常见也最够用的几段是：

1. 项目简介
2. 常用命令
3. 代码约定 / 风格
4. 目录结构
5. 不要做清单

常见误解 / 陷阱

• 误解一：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 写得好不好，基本等于你”工作方式的自我觉察度”有多高。

延伸阅读 / 官方链接

• 22 份真实 CLAUDE.md 共同结构
• https://code.claude.com/docs/en/memory

---

🎬 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、Aider CONVENTIONS.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 三层作用域权威说明

---

一句话

CLAUDE.md 不止一份——它有三个位置（全局 / 项目 / 组件），加载时机各不相同，搞清楚”哪一份在哪一刻生效”，才能避免规则不生效或互相打架。

---

记忆层级地图

CCBP（Claude Code Best Practice）原文确认的三个层级：

• 全局级 · ~/.claude/CLAUDE.md

  • 对你这台电脑上所有项目生效
  • 适合：个人偏好、到处都用的命令习惯、你在所有项目里的禁区
  • 只有你自己能看到，不进 git

• 项目根级 · <项目目录>/CLAUDE.md

  • 对这个项目生效，进 git，团队共享
  • 适合：这个项目的编码规范、架构禁区、常用命令、不能碰的文件

• 组件级 · <项目目录>/<子目录>/CLAUDE.md（Monorepo 常见）

  • 对某个子模块（frontend / backend / api）生效
  • 不在启动时加载——只有 Claude 在那次 session 里读到那个子目录的文件时，才临时载入

另附一个隐形的”第 0 层”：

• 本机私有项目级 · <项目目录>/CLAUDE.local.md
  • 作用域 = 这个项目，但不进 git（靠 .gitignore 屏蔽）
  • 适合：你在本机的个人测试配置、密钥 path、不想让队友看到的私人偏好

---

加载时机与优先级

CCBP 原文对 monorepo 加载机制的描述：

“Claude Code uses two distinct mechanisms for loading CLAUDE.md files: Ancestor Loading (UP the directory tree) — walks upward from your current working directory toward the filesystem root and loads every CLAUDE.md it finds. These files are loaded immediately at startup. Descendant Loading (DOWN the directory tree) — CLAUDE.md files in subdirectories below your current working directory are NOT loaded at launch. They are only included when Claude reads files in those subdirectories. This is known as lazy loading.”

翻译成人话：

位置关系	加载时机	例子
当前目录及其所有祖先目录	启动时立即加载	从 frontend/ 启动 → frontend/CLAUDE.md 和根目录 CLAUDE.md 都立刻进上下文
当前目录的子目录（后代）	懒加载（用到才加载）	从根目录启动 → frontend/CLAUDE.md 要等 Claude 读了 frontend 下的文件才载入
当前目录的兄弟目录	永不自动加载	在 frontend/ 工作时，backend/CLAUDE.md 根本不会出现
~/.claude/CLAUDE.md	所有 session 启动时	全局生效，最先加载

优先级：局部覆盖全局——规则冲突时，范围越小的 CLAUDE.md 说了算。

---

import 语法（@path 机制）

CLAUDE.md 支持用 @ 符号引入外部文件，把长文档拆分管理。写法：

@./docs/coding-standards.md
@~/.claude/shared/team-rules.md

效果：Claude Code 读到 @路径 时，会把那个文件的内容展开插入，效果等同于直接写在 CLAUDE.md 里。

用处：

• 把大段技术细节（如 API 规范、测试指南）放进独立 md，CLAUDE.md 只留精华
• 多个项目共享同一份规则文件，改一处处处生效

本项目（AIBuilder）的全局 CLAUDE.md 就用了 @~/.claude/shared/systems-registry.md 来拉全局系统注册表——这是 import 机制的典型用法。

---

常见坑

坑 1：以为”写了就生效”

在子目录下新建了 CLAUDE.md，但从根目录启动，那份文件不会在启动时读入——它要等 Claude 在那次 session 里真正读到那个子目录的文件才会触发懒加载。解法：从那个子目录启动，或者把关键规则提到根目录的 CLAUDE.md 里。

坑 2：兄弟目录的规则互相不可见

在 frontend/CLAUDE.md 里写了”禁止直接改 API schema”，以为 backend/ 也能遵守。但 Claude 在 backend 子目录工作时，frontend 的规则根本没被加载。解法：把跨组件的共识规则放到根目录 CLAUDE.md。

坑 3：全局和项目级写了矛盾的规则

~/.claude/CLAUDE.md 写”默认用 TypeScript”，某项目的 CLAUDE.md 写”这个项目只用 Python”。结果是项目级覆盖全局，Python 生效——但如果你忘了自己在全局写过 TypeScript 规则，debug 时会绕很久。解法：全局只写”任何项目都成立”的东西，项目级写”这个项目独有”的要求。

坑 4：把 CLAUDE.local.md 忘记加进 .gitignore

本机私有的 key path、临时偏好写进了 CLAUDE.local.md，但没把它加进 .gitignore，一次 git push 就把私人配置推上去了。解法：建 CLAUDE.local.md 的第一件事就是确认 .gitignore 里有它。

---

和 Monorepo 的关系

CCBP 原文总结的 3 条核心洞察：

“1. Ancestors always load at startup — Claude walks UP the directory tree and loads all CLAUDE.md files it finds. 2. Descendants load lazily — Subdirectory CLAUDE.md files only load when you interact with files in those subdirectories. 3. Siblings never load — If you’re working in frontend/, you won’t get backend/CLAUDE.md or api/CLAUDE.md loaded into context.”

这个机制的好处：几百个子模块的 monorepo，启动时不会把所有规则一口气塞进上下文；Claude 只在真正碰到那个模块时才加载对应的指导，避免上下文被无关规则撑爆。

---

关联术语

• [[CLAUDE.md（项目说明书）]]：本页是它的记忆机制详解补充
• [[22 份真实 CLAUDE.md 共同结构]]：实证看真实团队怎么写

---

来源：/Users/chenbin/Documents/Personal Kingdom/知识库/素材_AI使用/项目样本/claude-code-best-practice/github-mirror/claude-code-best-practice/best-practice/claude-memory.md（CCBP 原文 · Boris Cherny + 官方文档 · 2025）