CLAUDE.md 是什么：让它一开口就懂你的项目
📍 Claude Code 干活
用着用着，你一定会撞到的痛点
Section titled “用着用着，你一定会撞到的痛点”你装好 Claude Code 用了一周。某天早上你又开一个新对话准备让它帮你改简历，你打：
「帮我改一下简历。」
它问：「好的，你的简历在哪里？」
你打：~/Documents/求职/简历最新.md
它继续问：「你想改成什么风格？之前有特别偏好吗？」
你打：「中文，语气克制，不要那种『我有幸』『我荣幸』的虚词，用动词起头讲事实。」
它又问：「目标行业 / 岗位是？」
……
你抬头看一眼屏幕，心里咕哝：「这一模一样的对话我上周已经讲过 3 遍了。」
这就是没有 CLAUDE.md 的状态。
CLAUDE.md 是什么：让它一开机就记得
Section titled “CLAUDE.md 是什么：让它一开机就记得”CLAUDE.md 是一个普通的 markdown 文档——你写一次，放在固定位置，Claude Code 每次启动自动加载，把你写的偏好、规则、上下文全都吃进去。
下次你打开一个新对话直接说：
「帮我改一下简历。」
它直接说：「好，改 ~/Documents/求职/简历最新.md 是吧？我用动词开头讲事实，不用「有幸」那种虚词，目标投咱们之前对齐的产品经理岗位。直接开改吗？」
省了 3 分钟、3 轮问答。
这就是 CLAUDE.md 唯一一个功能：把你跟 AI 的「磨合记忆」从对话里搬出来，变成一份持久文档。
它不是配置文件，不是数据库，就是一篇你写给 AI 看的「项目说明书 / 个人偏好书」。
一份 CLAUDE.md 长什么样
Section titled “一份 CLAUDE.md 长什么样”
下面是一份改简历专用的 CLAUDE.md 真实例子。直接抄走改：
# 简历相关项目说明
## 我是谁- 5 年产品经理,前 2 年做 SaaS,后 3 年做电商- 目前找:中大厂产品经理岗(优先字节、美团、拼多多)- 简历主版本路径:~/Documents/求职/简历最新.md
## 写作风格(给 Claude 的)- 中文为主,克制不夸张- 动词起头讲事实(❌「我有幸负责」 → ✅「主导」「驱动」「上线」)- 数据要具体(❌「显著提升」 → ✅「DAU 从 8k 到 23k」)- 避免空词:有幸、荣幸、致力于、不懈努力
## 项目背景- 上家公司 X 的项目:XX 商品中台,我是 PM 一号位- 上上家公司 Y 的项目:XX 增长黑客模块
## 别问我的事(直接动手即可)- 「简历」永远指 ~/Documents/求职/简历最新.md- 「JD」永远指 ~/Documents/求职/JD 收集/ 这个目录- 改完直接给我 diff,不要先问要不要改读完这份 CLAUDE.md,Claude 知道你是谁、你的项目背景、你的写作偏好、文件路径、哪些事可以不用问直接干。
注意三个关键部分：
- 我是谁 — 让它有「人物画像」
- 写作风格 / 工作偏好 — 让它每次输出都符合你审美
- 别问我的事 — 让它不用反复追问，直接动手
最后一部分是新手最容易忘的，但对效率提升最大。
⚠️ 这里省掉的是它追问你的问题。改文件、跑命令之前要不要你点确认，由权限模式和权限规则决定，写进 CLAUDE.md 改变不了，见让 Claude 跑命令。
它放在哪里：三层结构
Section titled “它放在哪里：三层结构”
CLAUDE.md 最常用的是三个位置，作用范围不一样：
🏠 1. 家目录 CLAUDE.md（全局）
Section titled “🏠 1. 家目录 CLAUDE.md（全局）”路径：~/.claude/CLAUDE.md
作用：所有项目都生效。
适合写：
- 你是谁（你的名字、职业、城市、偏好的语言）
- 通用品味（中文用不用 emoji、代码注释用中文还是英文）
- 全局红线（token 一律放在环境变量里，不写明文）
📁 2. 项目级 CLAUDE.md（项目根目录）
Section titled “📁 2. 项目级 CLAUDE.md（项目根目录）”路径：/你的项目目录/CLAUDE.md（也可以放在 /你的项目目录/.claude/CLAUDE.md）
作用：只在这个项目内生效。
适合写：
- 这个项目用什么技术栈（React 18 / Python 3.12 / PostgreSQL）
- 这个项目的代码规范（camelCase / 4 空格缩进）
- 这个项目的特殊规则（commit message 用英文 / PR 必须附测试）
📂 3. 子目录 CLAUDE.md（细粒度）
Section titled “📂 3. 子目录 CLAUDE.md（细粒度）”路径：/你的项目目录/某个子模块/CLAUDE.md
作用：Claude 读到这个子模块里的文件时才加载，只管这一块。
适合写：
- 这个模块的特殊规范（/api/ 下的接口必须返回 JSON）
- 这个模块的历史包袱（/legacy/ 是老代码，只修 bug、不重构）
另外两种，知道就行
Section titled “另外两种，知道就行”CLAUDE.local.md：放在项目根目录，写只属于你自己的项目偏好（比如你本地的测试地址）。记得把它加进.gitignore（git 的忽略清单），不提交进仓库。.claude/rules/目录：项目大了，可以把规则拆成几个小文件放在这里，还能设定某条规则只在处理某类文件时才加载。
公司统一管理的电脑上，可能还有一份管理员下发的组织级 CLAUDE.md。
什么时候加载、冲突了听谁的
Section titled “什么时候加载、冲突了听谁的”- 启动时就加载：家目录的
~/.claude/CLAUDE.md，加上从你启动 Claude Code 的目录一路往上、每一级目录里的 CLAUDE.md（和 CLAUDE.local.md）。在项目根目录启动，读到的就是全局这份加项目这份。 - 用到时才加载：项目下面各个子目录里的 CLAUDE.md，启动时不读，等 Claude 去读那个子目录里的文件时才载入。
- 是拼在一起，不是覆盖：几份文件的内容全部拼接进上下文，一起摆在 Claude 面前，没有「下级自动覆盖上级」这回事。
类比：
- 家目录 CLAUDE.md = 你的个人习惯（到哪都带着）
- 项目 CLAUDE.md = 公司规章（进了这家公司才拿到）
- 子目录 CLAUDE.md = 部门细则（走进这个部门才翻开）
冲突了怎么办？比如全局规定「代码注释用中文」，某项目 CLAUDE.md 规定「这个仓库的注释用英文」。官方说明里提到，冲突时项目级的指令通常会被优先采纳；但这靠的是 Claude 自己判断，不是强制覆盖，两条规则打架时它也可能随便挑一条。最稳的做法是不在不同层级写互相冲突的规则：全局只写到哪都适用的偏好，项目特有的规则写在项目里。
想确认哪几份已经加载，在会话里输入 /context，看 Memory files 那一栏。（官方说明：Claude 如何记住你的项目，面向开发者，偏技术。）
写好一份 CLAUDE.md 的 5 条原则
Section titled “写好一份 CLAUDE.md 的 5 条原则”
新手第一次写 CLAUDE.md，通常会犯一个错——写得太抽象。比如：
「请保持代码风格优雅。」
这一句话对 AI 等于没说——「优雅」是什么？2 空格还是 4 空格？变量名 camelCase 还是 snake_case？用 const 还是 let?
下面是 5 条原则，每一条都用「错例 vs 正例」演示。
1. 具体 > 抽象
Section titled “1. 具体 > 抽象”❌ 错例:「代码要 clean。」
✅ 正例:
- 缩进用 2 个空格
- 变量名用 camelCase
- 优先 const，需要重新赋值才用 let
- 函数不超过 30 行
2. 规则要短，必要时附一句原因
Section titled “2. 规则要短，必要时附一句原因”❌ 错例：「我喜欢简洁的 commit message，因为我看着舒服，如果太长会感觉项目历史很乱…」
✅ 正例：
- commit message 用英文（要给海外同事看）
- 第一行不超过 50 字符
- 用动词起头（Add / Fix / Update / Remove）
规则本身要短，不写长篇解释；但用一句话点明「为什么」很有用：它明白了你的用意，碰到规则没写到的情况也更容易做对。Anthropic 官方的提示词建议也是这样：说清楚背后的原因，比光下命令效果好。
3. 多用具体场景例子
Section titled “3. 多用具体场景例子”❌ 错例:「测试要写得完整。」
✅ 正例:
- 每个 endpoint 至少有 3 个测试：成功、失败、边界
- 例：
POST /api/login要测「正确密码」「错误密码」「空密码」 - 用 jest，放在
__tests__/目录下
4. 禁止的事，写成「该怎么做」
Section titled “4. 禁止的事，写成「该怎么做」”❌ 错例：「不要做不合理的修改。」
✅ 正例：
- commit message 只用字母和数字，不加表情
- token 一律放在环境变量里，不写明文
- 改动都走 PR（合并请求）合进 main，不直接推 main 分支
只写「不要 X」，它知道了不能做什么，却不知道该怎么做；把「该怎么做」写在前面、禁止的部分顺带一提，最不容易跑偏。Anthropic 官方的提示词建议（面向开发者，偏技术）也是「告诉 Claude 该做什么，而不是只说不该做什么」。
⚠️ CLAUDE.md 只是写给它看的说明，不是强制开关。真正必须拦住的操作（比如绝不能直接推 main），交给权限规则或 hooks（钩子：在固定时机自动运行的脚本）来拦，见让 Claude 跑命令和 Hooks 那篇。
5. 让它演进，不是一次写完美
Section titled “5. 让它演进，不是一次写完美”CLAUDE.md 不是一次性写完的。流程：
- 第一周 — 写一个最小版本(50 行就行)
- 每次踩坑 — 加一条新规则进去
- 每月回顾 — 删掉 outdated 的、合并重复的
把它当成你跟 AI 长期合作的「合同迭代版」，不是一份说明书。
进阶：auto memory，让 Claude 自己记笔记
Section titled “进阶：auto memory，让 Claude 自己记笔记”
从 2026 年 2 月（v2.1.59）起，Claude Code 有一个叫 auto memory（自动记忆）的能力，默认开启——它会自己记下值得记的东西，写进它自己的记忆目录，不会动你的 CLAUDE.md。
记忆存在 ~/.claude/projects/<项目>/memory/ 里：一份 MEMORY.md 当目录（索引），每条记忆再单独存成一个小文件。每次启动只自动读 MEMORY.md 的前 200 行（或前 25KB），具体的小文件等用到时再翻。同一个 git 仓库里的子目录共用这一份记忆，而且只存在你这台电脑上。
举一个真实例子：
你：「我跟你说，所有 commit message 都用英文写。」 Claude：「好，已记下。」 （界面上会出现一行 Saved 1 memory 之类的提示：它在自己的记忆里加了一条「用户偏好：commit message 用英文」）
下次你新开对话，它已经记得了——不用你再告诉一遍。
想让某条规则进 CLAUDE.md、而不是它的记忆，直接对它说「把这条加到 CLAUDE.md」就行。
怎么查看和管理
Section titled “怎么查看和管理”auto memory 默认就开着。如果你想看它具体记了什么，可以打：
/memory会打开记忆管理界面：列出你的各级 CLAUDE.md，能打开自动记忆的文件夹逐条查看、修改或删除，也能在这里把 auto memory 关掉。分工记清楚：CLAUDE.md 归你管，记忆目录归它自动记——两边互不打架。
警告：它有时会记错
Section titled “警告：它有时会记错”auto memory 不是 100% 准确。它可能：
- 把临时偏好当成长期规则(你今天说「这次用英文」，它以为你「永远要英文」)
- 过度泛化(你说「这一段代码不要注释」，它以为「整个项目都不要注释」)
所以每两周看一次 /memory，删掉记错的。这点 5 分钟的维护，能让它的记忆一直精准。
三个新手最容易踩的坑
Section titled “三个新手最容易踩的坑”❌ 坑 1:CLAUDE.md 写得跟流水账一样
Section titled “❌ 坑 1:CLAUDE.md 写得跟流水账一样”「我是产品经理，5 年经验，平时用 Notion 多，喜欢喝咖啡，不喜欢加班…」
没用。AI 不在乎你喝什么咖啡。只写「能影响它工作的规则」——文件路径、风格偏好、技术栈选择、避坑清单。其他个人信息全删。
❌ 坑 2：把 CLAUDE.md 写成「写给人看的设计文档」
Section titled “❌ 坑 2：把 CLAUDE.md 写成「写给人看的设计文档」”「## 架构设计 本系统采用 MVC 模式，前端用 React + TypeScript，后端用 Python FastAPI…」
没用。CLAUDE.md 不是给团队看的文档,是给 AI 看的操作手册。把这种「设计文档」放在 README.md 或者 docs/ 目录，不要塞进 CLAUDE.md。
❌ 坑 3:CLAUDE.md 越写越长(超过 500 行)
Section titled “❌ 坑 3:CLAUDE.md 越写越长(超过 500 行)”CLAUDE.md 每次启动都会被全文加载进 context——越长越烧钱、越占记忆。
新手第一年，CLAUDE.md 控制在 100-200 行以内。超过了：
- 把通用规则放家目录
~/.claude/CLAUDE.md(全局共享) - 把模块规则放到对应的子目录 CLAUDE.md
- 把过时的规则删掉，不要囤
精简的 CLAUDE.md > 臃肿的 CLAUDE.md。
最快的起步办法：/init
Section titled “最快的起步办法：/init”对着空白文件手写有点难？进到项目目录、打开 Claude Code，输入：
/init它会先看一遍你的项目（代码、构建和测试命令、目录结构），自动生成一份初始的 CLAUDE.md；项目里已经有 CLAUDE.md 的话，它会给出修改建议，不会直接覆盖。生成之后，再按上面 5 条原则删改：删掉它自己看代码就能知道的，补上只有你知道的偏好和坑。改完输入 /context，在 Memory files 那一栏确认它已经加载。
读完这篇你应该理解 CLAUDE.md 的位置、写法、维护节奏。如果你今天就要写一份：手上有项目的，进项目目录跑一次 /init，再按本文的原则删改；还没有具体项目的，先写家目录的全局 CLAUDE.md（50 行内），等遇到第一个具体项目再加项目级的。
接下来这两篇：
→ 上下文窗口怎么算的：会忘记前面说的吗 —— CLAUDE.md 写多了会占 context，这一篇讲清楚怎么不爆
→ 一次说错可以撤回：checkpoint 用法 —— Claude 改坏了怎么一键回滚