CLAUDE.md 是什么：让它一开口就懂你的项目

📍 进阶 3/10 · 上一篇:← 让 Claude 跑命令:三种权限模式

用着用着,你一定会撞到的痛点

你装好 Claude Code 用了一周。某天早上你又开一个新对话准备让它帮你改简历,你打:

“帮我改一下简历。”

它问:“好的,你的简历在哪里?”

你打:~/Documents/求职/简历最新.md

它继续问:“你想改成什么风格?之前有特别偏好吗?”

你打:“中文,语气克制,不要那种”我有幸”、“我荣幸”的虚词,用动词起头讲事实。”

它又问:“目标行业 / 岗位是?”

……

你抬头看一眼屏幕,心里咕哝:“这一摸一样的对话我上周已经讲过 3 遍了。”

这就是没有 CLAUDE.md 的状态。

CLAUDE.md 是什么:让它一开机就记得

CLAUDE.md 是一个普通的 markdown 文档——你写一次,放在固定位置,Claude Code 每次启动自动加载,把你写的偏好、规则、上下文全都吃进去。

下次你打开一个新对话直接说:

“帮我改一下简历。”

它直接说:“好,改 ~/Documents/求职/简历最新.md 是吧?我用动词开头讲事实,不用”有幸”那种虚词,目标投咱们之前对齐的产品经理岗位。直接开改吗?”

省了 3 分钟、3 轮问答。

这就是 CLAUDE.md 唯一一个功能:把你跟 AI 的「磨合记忆」从对话里搬出来,变成一份持久文档。

它不是配置文件,不是数据库,就是一篇你写给 AI 看的「项目说明书 / 个人偏好书」。

一份 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 知道你是谁、你的项目背景、你的写作偏好、文件路径、哪些事可以不用问直接干。

注意三个关键 section:

1. 我是谁 — 让它有「人物画像」
2. 写作风格 / 工作偏好 — 让它每次输出都符合你审美
3. 别问我的事 — 让它不用反复确认,直接动手

最后一个 section 是新手最容易忘的,但对效率提升最大。

它放在哪里:三层结构

CLAUDE.md 有三个不同位置,作用范围不一样:

🏠 1. 家目录 CLAUDE.md(全局)

路径:~/.claude/CLAUDE.md

作用:所有项目都生效。

适合写:

• 你是谁(你的名字、职业、城市、偏好的语言)
• 通用品味(中文用 emoji 还是不用、代码注释用中文还是英文)
• 全局红线(永远不要把 token 写明文)

📁 2. 项目级 CLAUDE.md(项目根目录)

路径:/你的项目目录/CLAUDE.md

作用:只在这个项目内生效。

适合写:

• 这个项目用什么技术栈(React 18 / Python 3.12 / PostgreSQL)
• 这个项目的代码规范(camelCase / 4 空格缩进)
• 这个项目的特殊规则(commit message 用英文 / PR 必须附测试)

📂 3. 子目录 CLAUDE.md(细粒度)

路径:/你的项目目录/某个子模块/CLAUDE.md

作用:只在这个子模块内生效。

适合写:

• 这个模块的特殊规范(/api/ 下的 endpoint 必须返回 JSON)
• 这个模块的历史包袱(/legacy/ 不要改 / 是个老坑)

三层叠加规则

Claude Code 启动时,三层全部加载,子目录优先级最高。

类比:

• 家目录 CLAUDE.md = 国家法律(所有人都要守)
• 项目 CLAUDE.md = 公司规章(只这家公司守)
• 子目录 CLAUDE.md = 部门细则(只这个部门守)

下级可以覆盖上级。例如全局规定「代码注释用中文」,某项目 CLAUDE.md 规定「这个仓库的注释用英文」,在这个仓库就走英文。

写好一份 CLAUDE.md 的 5 条原则

新手第一次写 CLAUDE.md,通常会犯一个错——写得太抽象。比如:

“请保持代码风格优雅。”

这一句话对 AI 等于没说——“优雅”是什么?2 空格还是 4 空格?变量名 camelCase 还是 snake_case?用 const 还是 let?

下面是 5 条原则,每一条都用「错例 vs 正例」演示。

1. 具体 > 抽象

❌ 错例:“代码要 clean。”

✅ 正例:

• 缩进用 2 个空格
• 变量名用 camelCase
• 优先 const,需要重新赋值才用 let
• 函数不超过 30 行

2. 用规则,不用解释

❌ 错例:“我喜欢简洁的 commit message,因为我看着舒服,如果太长会感觉项目历史很乱…”

✅ 正例:

• commit message 用英文
• 第一行不超过 50 字符
• 用动词起头(Add / Fix / Update / Remove)

3. 多用具体场景例子

❌ 错例:“测试要写得完整。”

✅ 正例:

• 每个 endpoint 至少有 3 个测试:成功、失败、边界
• 例:POST /api/login 要测「正确密码」「错误密码」「空密码」
• 用 jest,放在 __tests__/ 目录下

4. 包含「负面例子」(永远不要)

❌ 错例:“不要做不合理的修改。”

✅ 正例:

• ❌ 不要在 commit message 加表情(纯字母数字)
• ❌ 不要把 token 写明文(用 env 变量)
• ❌ 不要在 main 分支直接推(必须走 PR)

负面规则比正面规则更有效——它防的是 AI 的「自由发挥」。

5. 让它演进,不是一次写完美

CLAUDE.md 不是一次性写完的。流程:

1. 第一周 — 写一个最小版本(50 行就行)
2. 每次踩坑 — 加一条新规则进去
3. 每月回顾 — 删掉 outdated 的、合并重复的

把它当成你跟 AI 长期合作的「合同迭代版」,不是一份说明书。

进阶:让 Claude 自己更新 CLAUDE.md

最近 Claude Code 引入了一个叫 auto memory 的能力——它能自己记下来值得记的东西,自动写进 CLAUDE.md。

举一个真实例子:

你:“我跟你说,所有 commit message 都用英文写。” Claude:“好,已记下。” (它在 CLAUDE.md 里悄悄加了一条:“用户偏好:commit message 用英文”)

下次你新开对话,它已经记得了——不用你再告诉一遍。

怎么开启

Claude Code 默认开了 auto memory。如果你想看它具体记了什么,可以打:

/memory

会列出来 Claude 当前记住的所有「自动学到的偏好」,你可以手工删除不该记的。

警告:它有时会记错

auto memory 不是 100% 准确。它可能:

• 把临时偏好当成长期规则(你今天说「这次用英文」,它以为你「永远要英文」)
• 过度泛化(你说「这一段代码不要注释」,它以为「整个项目都不要注释」)

所以每两周看一次 /memory,删掉记错的。这点 5 分钟的维护,能让 CLAUDE.md 一直精准。

三个新手最容易踩的坑

❌ 坑 1:CLAUDE.md 写得跟流水账一样

“我是产品经理,5 年经验,平时用 Notion 多,喜欢喝咖啡,不喜欢加班…”

没用。AI 不在乎你喝什么咖啡。只写「能影响它工作的规则」——文件路径、风格偏好、技术栈选择、避坑清单。其他个人信息全删。

❌ 坑 2:把 CLAUDE.md 写成「写给人看的设计文档」

”## 架构设计 本系统采用 MVC 模式,前端用 React + TypeScript,后端用 Python FastAPI…”

没用。CLAUDE.md 不是给团队看的文档,是给 AI 看的操作手册。把这种「设计文档」放在 README.md 或者 docs/ 目录,不要塞进 CLAUDE.md。

❌ 坑 3:CLAUDE.md 越写越长(超过 500 行)

CLAUDE.md 每次启动都会被全文加载进 context——越长越烧钱、越占记忆。

新手第一年,CLAUDE.md 控制在 100-200 行以内。超过了:

• 把通用规则放家目录 ~/.claude/CLAUDE.md(全局共享)
• 把模块规则放到对应的子目录 CLAUDE.md
• 把过时的规则删掉,不要囤

精简的 CLAUDE.md > 臃肿的 CLAUDE.md。

下一步

读完这篇你应该理解 CLAUDE.md 的位置、写法、维护节奏。如果你今天就要写一份,先写家目录的全局 CLAUDE.md(50 行内),然后等遇到第一个具体项目再加项目级的。

接下来这两篇正在赶工:

→ 上下文窗口怎么算的:会忘记前面说的吗 —— CLAUDE.md 写多了会占 context,这一篇讲清楚怎么不爆

→ 一次说错可以撤回:checkpoint 用法 —— Claude 改坏了怎么一键回滚

想第一时间收到,可以收藏 niuxue.org 主页。

---

你那份 CLAUDE.md 第一版写完,可以发我们邮箱 [email protected],我们会精选好的样本做社区参考。