CLAUDE.md 怎么写？项目记忆文件新手指南（附可抄模板）

⏱️ 预计阅读 17 分钟 ｜ 🎯 目标：让你看完就能动手写出一份能用的 CLAUDE.md——知道它是什么、该写什么、不该写什么，并且手里握着两份可以直接复制改用的模板。

你大概是这么搜进来的：装好了 Claude Code，听说要写一个叫 CLAUDE.md 的文件「Claude 才会更听话」，但打开网上的教程，满屏都是「记忆栈」「import 语法」「上下文窗口」，看完更晕了——到底第一行该写什么？这篇不堆术语，先用一个生活里的例子让你秒懂它是干嘛的，再直接把模板递到你手上。

30 秒答疑：先把结论拿走

如果你只想快速搞清楚 CLAUDE.md 是什么、要不要写，下面这张表就是答案：

最常见的新手误区：以为 CLAUDE.md 是「项目介绍页」，于是写满了背景故事和「保持高质量」之类的口号。完全用错了——它是一份操作说明，要写的是 Claude 干活时真正用得上的事实和边界，不是给人看的简介。

下面把这些一条条讲透。

一、CLAUDE.md 是什么：把它想成新员工的「入职手册」

想象你开了一家小店，每周都来一个新店员帮忙。问题是：这些店员全都失忆——每个人来上班的第一天，都完全不知道收银机怎么开、货架怎么摆、哪个抽屉的钱不能动、关门前要做哪几件事。

你有两个选择：

• 每来一个就口头交代一遍：累，而且你总会漏讲某条，新人总在同一个地方出错。
• 写一份《新人入职手册》贴在门后：新人一来先看手册，立刻知道怎么干、哪里是雷区。

CLAUDE.md 就是这份贴在门后的入职手册——只不过这个「失忆的新员工」叫 Claude Code。

💡 通俗讲

Claude Code 有一个新手最容易忽略的特点：它每开一个新会话都是一张白纸，完全不记得你上次跟它聊过什么、解释过什么。这不是它笨，是它本来就这么设计的。
所以「让 Claude 更听话」的关键，不是每次费劲把项目重新讲一遍，而是把这些话写进一份它每次开工都会先读的手册——这份手册就是 CLAUDE.md。

Claude Code 在每次会话开始时，会自动读取 CLAUDE.md，把里面的内容当成「我现在在干的这个项目的背景」。所以你在手册里写得越清楚，它干活时就越少猜、越少跑偏。

1.1 它解决的是「重复解释」这一个具体痛点

不写 CLAUDE.md 也能用 Claude Code，但你会陷入一个循环：

你：帮我加个登录功能
Claude：（不知道用什么框架、测试怎么跑、API 放哪）→ 瞎猜一个写法
你：不对，我们用 pnpm 不用 npm，组件放在 components/ 里
Claude：（改）
（第二天，新会话）
你：帮我加个注册功能
Claude：（又忘了）→ 又瞎猜
你：……又得再解释一遍 pnpm 和 components/

CLAUDE.md 把「我们用 pnpm」「组件放 components/」这种每次都要说的话写下来一次，以后 Claude 每次开工自己先读。它治的就是这个「重复解释」的病——不是让 Claude 变聪明，是让你不用当复读机。

🔥 翔宇判断

很多人纠结「我的项目这么小，值得专门写个 CLAUDE.md 吗」。我的判断标准很简单：不看项目大小，看任务会不会重复。哪怕是个练手小项目，只要你打算反复让 Claude 改它、读同一套目录、守同一批命令，就值得花十分钟写一份。真正不需要写的，只有「问完这一次就再也不碰」的临时问答。重复，才是 CLAUDE.md 回本的前提。

二、CLAUDE.md 该写什么、不该写什么：好坏写法对照

这是新手最容易翻车的地方——不是不会写，是写错了东西。把篇幅花在没用的内容上，真正该写的边界反而漏了。下面这张对照表，建议你边写边对。

2.1 该写 vs 不该写

2.2 一眼看懂的好坏写法对比

光看表还不够直观，来看几组真实改写——左边是新手常写的，右边是改好的：

发现规律了吗？好写法全都能用「做没做到」来判断，坏写法只是态度。

🔥 翔宇判断

写 CLAUDE.md 时我有一条铁律：每写一条规则，先问自己「这条能不能检查」。「保持整洁」检查不了，「不要在 src/ 外新建文件」一眼就能查。检查不了的，要么删掉，要么改写成能检查的动作。一份全是态度、没有动作的 CLAUDE.md，Claude 读了等于没读——它不知道「整洁」对你具体意味着什么。规则的价值不在多，在于每一条都能落到一个具体的文件、命令或结果上。

2.3 「不要做什么」要单独成段

新手写 CLAUDE.md 往往只写「希望 Claude 做什么」，却忘了写「哪些事必须停下来」。而后者恰恰是最能防事故的部分。建议专门留一段写禁区，比如：

## 红线（绝对不要）

- 不要删除任何用户数据或上传的文件
- 不要直接 push 到 main 分支，一律走 PR
- 不要修改 `.env`、`secrets/` 里的任何内容
- 不要把代码里的密钥、token 打进日志
- 改动数据库结构前必须先问我

这些边界越早写清，后面被「惊吓」的概率越低。至于其中涉及密钥、删除这类绝不能出事的动作，光靠 CLAUDE.md 提醒还不够——还要在设置里上硬锁，这点第五节会专门讲。

2.4 好规则 vs 烂规则：Claude 的实际表现差多少

前面讲的「好写法 / 坏写法」不是文风讲究，它会直接改变 Claude 干活的结果。把同一个任务，分别交给「有一份好 CLAUDE.md」和「没有 / 一份烂 CLAUDE.md」的 Claude，差距是肉眼可见的。我们拿一个具体场景对比一下。

场景：你让 Claude「给项目加一个用户反馈表单，提交后存进数据库」。

没有 CLAUDE.md（或写满口号的烂 CLAUDE.md）时，Claude 大概会这样：

• 它不知道你用 pnpm，于是默认敲了 npm install 去装新包——结果和你项目里的 pnpm-lock.yaml 打架，依赖装乱了。
• 它不知道组件该放哪，随手在 src/ 根目录新建了一个 FeedbackForm.tsx，和你「组件统一放 components/」的习惯完全不符，过两天你自己都找不到它在哪。
• 它不知道数据库改动要先问你，直接动手改了 migrations/ 里的迁移文件——这种操作一旦跑下去，回滚起来很费劲。
• 它写完不知道怎么验证，扔下一句「应该能用了」就结束，结果你一跑 pnpm test 才发现根本没过。
• 最难受的是下一个会话它全忘了：第二天你让它加个「联系我们」表单，上面这些坑它一个不落地再踩一遍，你又得把 pnpm、组件目录、迁移禁区从头解释一次。

把这几条加起来你会发现，真正吃掉你时间的不是 Claude「不会做」，而是它「每次都从零开始猜」。它不是不想用 pnpm，是没人告诉它这个项目用 pnpm；它不是故意把组件放错地方，是没人告诉它组件该放哪。每一次猜错，你都要花几分钟发现问题、解释原因、看着它重做——一个本该十分钟搞定的小功能，最后拖成半小时的来回拉扯。更糟的是这种消耗不会随时间减少：今天解释完，明天新会话又归零，你永远停在「教新人上手」的第一天。

有一份好 CLAUDE.md 时，同一个任务变成这样：

• 它一开工就读到「包管理只用 pnpm」，老老实实敲 pnpm add，依赖不打架。
• 它读到「组件统一放 src/components/」，表单组件直接落到正确位置，命名也随你的约定走。
• 它读到目录表里「migrations/ 改前必须问我」，于是改数据库结构前先停下来问你，而不是自作主张。
• 它读到「改完必须跑 pnpm test 全过才算完成」，于是自己把测试跑了一遍、发现没过又改到过，最后才交付。
• 而且因为这些规则写在文件里、不在某次对话里，第二天的「联系我们」表单任务，它照样自动遵守——你一次都不用重复解释。

同一个任务、同一个 Claude，结果却天差地别——差的不是模型能力，是它手里有没有一份「知道这个项目怎么运作」的手册。好 CLAUDE.md 下，你的角色从「全程盯着、随时纠错」变成「派完活、等它自己跑通来交付」，省下来的是注意力和返工，而不只是几句话。这种省心还会随项目变大而放大：项目越复杂、目录越多、约定越细，没手册时 Claude 要猜的东西就越多、踩的坑就越深；而一份维护得当的手册，恰恰在这种时候帮你挡掉最多的麻烦。

💡 通俗讲

把这两段对比读一遍你就明白了：CLAUDE.md 省的不是「打几个字」的小工夫，而是「同一个坑反复踩、同一句话反复说」的大消耗。烂规则下，Claude 每次都像第一天上班的失忆新人；好规则下，它像一个看过手册、知道公司怎么运作的熟手。差别不在 Claude 聪不聪明，在于你有没有把它该知道的事写在它每次都会读的地方。

🔥 翔宇判断

衡量一份 CLAUDE.md 好不好，我只看一个信号：写完之后，你给 Claude 派活时是不是明显少解释了。如果你发现自己不用再交代「我们用 pnpm」「别动那个目录」「改完记得测」，那这份手册就真的在干活；如果每次还得把这些话重说一遍，说明规则要么没写到、要么写得太泛、要么放错了位置。别用「写得长不长、全不全」来评价 CLAUDE.md，用「它让你的任务变短了多少」来评价——好手册的唯一标准，是让你越来越省心，而不是让文件越来越厚。

2.5 哪条规则最该写？回报最高的四种信号

网上多数模板会丢给你一张「该包含的十个板块」清单，让你一次填满。但新手真正缺的不是「板块够不够全」，而是「哪一条值得占用宝贵的篇幅」。这里有一个比「填满模板」靠谱得多的判断法——不要凭空想该写什么，等下面这四种信号出现时再补：

这四条不是我拍脑袋定的，是官方文档给出的「该往 CLAUDE.md 加什么」的判断标准。它们有一个共同点：都来自真实发生过的摩擦，而不是想象中的「最佳实践」。

🔥 翔宇判断

如果让我给新手排一个「回报从高到低」的优先级，我会这么排：第一梯队是命令和红线（怎么跑、怎么测、哪里绝对不能碰）——这两类几乎每次任务都用得上，漏一条就反复出事，回报最高；第二梯队是项目特有约定（用 pnpm 不用 npm、组件放哪），它省的是「反复纠正」；第三梯队才是目录地图和验收标准，项目变复杂后价值才显出来。至于项目背景故事、设计理念、技术选型理由这些——回报趋近于零，Claude 干活时几乎用不上，想写就留给 README 给人看。一句话：先写「不写就会反复出事 / 反复解释」的，再写锦上添花的。篇幅有限，把每一行都花在回报最高的地方。

三、可直接抄的 CLAUDE.md 模板（最小可用版）

理论讲够了，上模板。这一份是最小可用版——大约 20 行，适合你的第一个项目或练手仓库。把尖括号 <...> 里的占位符按你的项目替换掉就能用。

# <项目名>

> 一句话说明：这是一个 <做什么的> 项目，用 <技术栈，例如 Next.js + TypeScript>。

## 运行

- 安装依赖：`<pnpm install>`
- 本地启动：`<pnpm dev>`
- 跑测试：`<pnpm test>`
- 构建：`<pnpm build>`

## 项目约定

- 包管理用 `<pnpm>`，不要用 npm / yarn
- 组件统一放在 `<src/components/>`
- API 处理函数放在 `<src/api/handlers/>`

## 红线（绝对不要）

- 不要修改 `.env` 和 `<dist/>`
- 不要直接 push 到 `main`，改动走 PR
- 删除文件或改数据库结构前先问我

## 验收

- 改完必须跑 `<pnpm test>`，全过才算完成
- 新功能要配对应测试

💡 通俗讲

别被「才 20 行够吗」吓到。第一版本来就该短。这 20 行已经覆盖了 Claude 最常猜错的四件事：怎么跑、放哪里、不能碰什么、怎么算干完了。等你用几天、发现它还在某处反复犯错，再针对那一处补一条——这比一开始就憋一份 200 行的完美手册靠谱得多。

3.1 怎么用这份模板

1. 在你项目的根目录新建一个文件，命名就叫 CLAUDE.md（注意全大写）。
2. 把上面的内容整段复制进去。
3. 把所有 <...> 占位符换成你项目的真实情况——大概改 5 到 10 处。
4. 保存。下次启动 Claude Code，它就会自动读这份手册。

就这么简单。不需要任何命令、不需要任何配置，一个普通 markdown 文件而已。

四、进阶版模板：项目长大了怎么写

当你的项目从练手变成「认真在做、还可能拉人协作」时，最小版就不够了。下面这份进阶版约 60 行，多了目录地图、协作约定、状态边界，仍然控制在好维护的范围内。

# <项目名>

> <一句话：这是什么项目，给谁用，核心价值是什么>
> 技术栈：<Next.js 15 + TypeScript + Tailwind + Postgres>

## 行为准则

- 改前先读：动任何文件前，先确认它属于哪个目录、归谁管
- 简化优先：能少写的分支就少写，不要为「以后可能用到」提前抽象
- 改完自验：每次改动结束跑测试 + 自查产出，再交付

## 目录地图

| 目录 | 职责 | 能不能改 |
|---|---|---|
| `src/app/` | 页面路由 | 可改 |
| `src/components/` | 复用组件 | 可改，优先复用已有的 |
| `src/lib/` | 工具函数、数据库连接 | 谨慎改，改前看清调用方 |
| `migrations/` | 数据库迁移 | 改前必须问我 |
| `.env` / `secrets/` | 密钥配置 | 绝对不要碰 |

## 运行与验证

- 装依赖：`pnpm install`
- 开发：`pnpm dev`（默认 3000 端口）
- 测试：`pnpm test`（提交前必跑）
- 类型检查：`pnpm typecheck`
- 构建：`pnpm build`

## 项目约定

- 包管理只用 `pnpm`
- 组件用函数式写法 + hooks，不用 class 组件
- 提交信息用中文，格式：`类型: 简述`
- 新增依赖前先问我，不要随意装包

## 红线（绝对不要）

- 不要直接 push 到 `main`，一律走 PR
- 不要修改 `.env`、`secrets/`、`migrations/` 已有文件
- 不要把密钥 / token 打进日志或提交进 git
- 不要把 `draft`（草稿）当 `published`（已发布）内容去改

## 交付标准

- `pnpm test` + `pnpm typecheck` 全过
- 新功能配测试
- 涉及发布、删除、付款的动作先停下来问我，不要自动执行

🔥 翔宇判断

进阶版里最值钱的一段，是那张「能不能改」的目录表。新手通常只告诉 Claude「东西在哪」，却忘了告诉它「哪里是禁区」。我的经验是：标清楚每个目录能不能动，比写十条抽象原则都管用——Claude 改错文件、动了不该动的迁移脚本，几乎全是因为没人告诉它那里碰不得。一张三列小表，就能挡掉一大半「它怎么把那个文件改了」的惊吓。

五、多级 CLAUDE.md 与权限边界：两个进阶但关键的点

写好一份根目录 CLAUDE.md 之后，有两件事值得早点知道，能帮你避开后面的麻烦。

5.1 多级 CLAUDE.md：大项目按目录分层写

如果你的项目很大、有很多子目录，把所有规则塞进一份根 CLAUDE.md 会越来越长、越来越乱。更好的做法是分层：

• 根目录的 CLAUDE.md：写全局通用规则（整个项目都适用的命令、约定、红线）。
• 子目录里的 CLAUDE.md：写只在这个子目录适用的局部规则。

它的加载逻辑很聪明：根目录和你启动位置之上的 CLAUDE.md 在开工时全部加载；而子目录里的 CLAUDE.md 不会一开始就加载，只在 Claude 真正去读那个目录的文件时才加载。这样既不浪费篇幅，又能让 Claude 进到不同区域时看到「就近的规则」。

💡 通俗讲

还是用入职手册打比方。根目录的 CLAUDE.md 是「全公司通用守则」，每个新人都要读；子目录的 CLAUDE.md 是「贴在某个具体车间门口的须知」，只有走进那个车间的人才需要看。
比如一个内容站项目，根目录写全局规则，内容/ 子目录里单独放一份 CLAUDE.md 写「文章 frontmatter 怎么填、草稿和已发布怎么区分」，工具/ 子目录再放一份写「工具怎么跑、日志在哪」。Claude 去改文章时看到内容规则，去修工具时看到工具规则，互不干扰。

如果你想更精细地按文件类型挂规则（比如「只有改 .ts 文件时才生效的规则」），Claude Code 还提供了 .claude/rules/ 目录，可以给规则文件标上适用路径——这属于更进一步的玩法，新手先掌握「根目录 + 子目录」两级就够用了。

5.2 权限边界：CLAUDE.md 是「提醒」，settings.json 才是「硬锁」

这是一个新手必须分清、否则会吃大亏的区别。

你在 CLAUDE.md 里写「不要碰 .env」，Claude 会尽量遵守——但请记住，CLAUDE.md 里的内容本质是行为引导，是说给 Claude 听的建议，不是一道拦在它面前的铁闸。绝大多数时候它会听，但在复杂任务里，不能保证 100% 不被忽略。

为什么是建议而不是铁闸？官方文档把原理说得很直白：CLAUDE.md 的内容是在系统提示之后、作为一条用户消息送给 Claude 的，而不是写死在系统提示里的强制配置。换句话说，它和你在对话框里打的字是同一个层级——Claude 会认真读、会努力照做，但它终究是「读进来的上下文」，不是「拦在手前的开关」。明白这一点，你就不会再幻想「只要写进 CLAUDE.md 就一定不会被碰」。

真正「不管 Claude 怎么想都拦得住」的硬限制，要写在 Claude Code 的设置文件 settings.json 里，用 permissions 的三个清单声明：

一个最小例子（放在项目的 .claude/settings.json 里）：

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./secrets/**)"],
    "ask": ["Bash(git push:*)"],
    "allow": ["Bash(pnpm test:*)", "Bash(pnpm dev:*)"]
  }
}

🔥 翔宇判断

这条分工我建议每个新手刻在脑子里：习惯性的小约束写进 CLAUDE.md，绝不能出事的动作上 settings.json 硬锁。比如「优先复用已有组件」这种，写进 CLAUDE.md 当引导就够；但「不准读 .env」「push 前必须问」这种一旦出事就是事故的，一定要进 permissions 的 deny / ask。两层配合——CLAUDE.md 管「希望它怎么做」，settings.json 管「绝对不许它做」——才是放心把活交出去的前提。指望一份 CLAUDE.md 兜住所有安全，是新手最危险的幻觉。

5.3 还想更硬一层：用「钩子」在动作发生前拦下

settings.json 的 permissions 已经能挡住绝大多数事故。如果你的项目对某个动作有「无论如何都必须先跑一道检查 / 必须在某一刻执行」的硬要求，Claude Code 还有一层更底层的机制——钩子（hook）。它的本质是：在 Claude 真正执行某个工具调用之前，先触发一段你指定的脚本，由脚本决定放不放行。因为它跑的是你写的命令、不依赖 Claude 的判断，所以不管 Claude 怎么想都拦得住。官方对「想要绝对拦截某个动作」的建议，正是用这一层、而不是指望 CLAUDE.md。

💡 通俗讲

把三层安全想成一栋楼的三道门：CLAUDE.md 是贴在门上的「友情提示」（请勿入内），settings.json 的 permissions 是门上的「电子锁」（刷卡才开），钩子则是门口的「保安」（每次都按规矩检查、不合规当场拦下）。新手先用好前两道就够安全了；钩子是等你有了「这个动作必须每次强制检查」的明确需求时，再去学的进阶层。这里点出它，是让你心里有底——真要上死规矩，工具是有的，不必把全部希望押在一份手册上。

六、手把手写出第一版：6 步，20 分钟

不知道从哪下笔？跟着这 6 步走一遍，你就有了第一版能用的 CLAUDE.md。不要追求完美，先跑通闭环。

6.1 第 1 步：一句话写清「这是什么项目」

在项目根目录新建 CLAUDE.md，第一行写清楚这个项目做什么、用什么技术栈。让 Claude 一进来就知道自己站在哪。

# 我的个人博客

> 一个用 Next.js + Markdown 写的个人博客，部署在 Vercel。

6.2 第 2 步：写运行和验证命令

写出能直接复制粘贴运行的真实命令。这是 Claude 用得最频繁的信息——它干完活想自查，第一件事就是找「怎么测」。

## 运行
- 启动：`pnpm dev`
- 测试：`pnpm test`
- 构建：`pnpm build`

6.3 第 3 步：写禁止动作（红线）

用「不要…」句式，把绝不能碰的东西列出来。宁可多列，不可漏掉关键禁区。

## 红线
- 不要改 `.env`
- 不要直接发布，`pnpm deploy` 前先问我
- 不要删除 `posts/` 里的已发布文章

6.4 第 4 步：写项目特有约定

写这个项目和别处不一样的地方。只写约定，不写常识——「这是 TS 项目」是常识不用写，「我们用 pnpm 不用 npm」是约定，要写。

## 约定
- 包管理用 pnpm
- 新文章放在 `posts/`，文件名用英文短横线
- 草稿在 frontmatter 标 `draft: true`，不要当已发布处理

6.5 第 5 步：让 Claude 做个小任务验证

别急着干大活。让 Claude Code 做一件低风险小事——改个标题、加段注释、写个小测试——盯着它看有没有按你写的规则走。规则只有被任务验证过，才算真的有用。

6.6 第 6 步：按它的误解反向补规则

Claude 哪里理解错了、跑错了命令、动了不该动的目录，就把对应那一条补得更具体。每一次犯错，都是一次「该补哪条规则」的免费提示。

💡 通俗讲

第 5、6 步合起来，就是写 CLAUDE.md 最高效的方法——从真实任务反推，而不是坐着空想模板。挑一件你经常交给 Claude 的活，看它每次都要你重复解释什么、总在哪里出错，那些内容就是你 CLAUDE.md 第一版最该写的东西。空想出来的规则常常用不上，从踩坑反推出来的规则条条管用。

七、200 行写不下怎么办：拆，别硬塞

随着项目长大，你会发现 CLAUDE.md 越写越长。记住官方那条建议：单份控制在 200 行以内。超了不是删内容，是搬家——把内容挪到更合适的地方：

💡 通俗讲

有个常见误会要澄清：有人听说可以用 @别的文件.md 这种「导入」语法把内容拆到别的文件，以为这样就能省篇幅。其实不能——被导入的文件在开工时照样会被整个加载进来，篇幅一点没省，只是看起来整齐了。真正能「按需加载、不占全局篇幅」的，是上表里的子目录 CLAUDE.md 和 .claude/rules/ 路径规则。想省上下文，靠的是这两个，不是 @import。

🔥 翔宇判断

我维护过一些层级很深的项目，最稳的结构永远是根目录薄、子目录补：根 CLAUDE.md 只放真正全局的几十行（行为准则、红线、最核心命令），具体到某个区域的细节全部下沉到那个区域自己的 CLAUDE.md。这样根文件永远清爽、永远好读，Claude 一开工抓到的都是最关键的规则；进到具体目录再加载局部规则，既不浪费、又不遗漏。「一个超长文件装下所有」是新手最容易走的弯路，越早学会拆，后面越省心。

7.1 两个能省心的小技巧（很多教程没讲）

把第一版跑顺之后，下面两个细节知道了能少踩坑，新手不必死记，留个印象即可：

• 给人看的备注，用 HTML 注释包起来，不占 Claude 的篇幅。 CLAUDE.md 里整段的 <!-- 这样的注释 --> 在送进 Claude 之前会被自动剥掉——也就是说你写给团队同事看的维护说明（「这条是 3 月那次事故后加的，别删」），既能留在文件里给人读，又不会消耗 Claude 的上下文。这是个被严重低估的小技巧：想给人留话又不想喂给模型，就用块级 HTML 注释。（注意：写在代码块里的注释会原样保留，不会被剥。）
• 聊太久触发「压缩」后，根 CLAUDE.md 会自动回来，子目录的不会。 长会话里 Claude Code 会把历史对话压缩（compact）以腾出空间。压缩之后，项目根目录的 CLAUDE.md 会被重新读进来，所以你的全局红线不会丢；但子目录里的 CLAUDE.md 不会自动重注入，要等 Claude 下次再去读那个目录的文件时才重新加载。所以最关键、必须时刻生效的规则，放在根 CLAUDE.md 最稳——这也是前面「根目录薄、子目录补」之外，又一个「核心规则要放根」的理由。

八、新手最容易踩的 5 个误区

误区 1：把 CLAUDE.md 写成「项目介绍页」

最典型的错。写满了项目背景、设计理念、「我们追求极致体验」——读起来很美，但 Claude 干活时一条都用不上。它要的是操作说明，不是简介。 凡是不能落到「改哪个文件、跑哪个命令、什么结果算对」的内容，都该删。

误区 2：全是口号，没有动作

「保持高质量」「注意安全」「遵循最佳实践」——这些话 Claude 没法执行，因为它不知道你说的「高质量」具体指什么。每条规则写完都问一句：这条能不能检查？ 不能就改写成能检查的。

误区 3：规则互相打架

一处写「所有改动走 PR」，另一处又写「小修改可以直接 commit」——Claude 读到矛盾的规则会随便挑一条执行，结果你以为它没听话，其实是你的手册自相矛盾。定期回头读一遍，把打架的、过期的规则清掉。

误区 4：写完就再也不改

项目在变，命令在变，目录职责在变，CLAUDE.md 也得跟着变。把它当成一份会呼吸的活文件：每次 Claude 误解了什么，就补一条；每条规则过期了，就删掉。一份半年没动过的 CLAUDE.md，大概率已经在误导 Claude 了。

误区 5：指望 CLAUDE.md 兜住所有安全

前面讲过但值得再强调：CLAUDE.md 里的「不要碰 .env」是提醒，不是铁闸。涉及密钥、删除、发布、付款这类绝不能出事的动作，一定要同时在 settings.json 的 permissions 里上硬锁。把安全全部押在一份「行为引导」上，是最危险的侥幸。

九、CLAUDE.md 自检清单

写完第一版，对照下面这几条过一遍，全打勾就可以放心用了：

• [ ] 文件名是 CLAUDE.md（全大写），放在项目根目录？
• [ ] 第一行用一句话说清了「这是什么项目」？
• [ ] 写了能直接复制运行的命令（运行 / 测试 / 构建）？
• [ ] 有一段单独的「红线 / 绝对不要」？
• [ ] 每条规则都能被检查（不是「保持整洁」这种口号）？
• [ ] 只写了项目特有约定，没塞「这是 TS 项目」这类常识？
• [ ] 全文在 200 行以内，你自己能 30 秒读出重点？
• [ ] 密钥 / 删除 / 发布类动作，除了 CLAUDE.md 提醒，还在 settings.json 上了硬锁？
• [ ] 让 Claude 做了一个小任务，确认它真的按规则走了？

任何一条没打勾，回去看对应章节补上。

十、写好 CLAUDE.md 之后，接下来学什么

CLAUDE.md 是 Claude Code 的地基。地基打牢了，下面这几块自然就该学了——按你遇到的需求挑着看：

• 不知道 Claude Code 整体是什么、能干嘛 → 看 Claude Code 是什么？新手一篇看懂，先建立对这个工具的整体认知。
• 想知道怎么系统地学、按什么顺序 → 看 Claude Code 完整学习指南，里面有从入门到精通的完整路径地图。
• CLAUDE.md 写好了，但不会给 Claude 派任务 → 看 Claude Code 提示词怎么写，学会把模糊需求变成 Claude 能执行的工程任务。CLAUDE.md 管「项目背景」，提示词管「这次干什么」，两者配合才顺。
• 还没装、不知道用哪个入口（App / 命令行 / IDE） → 看 Claude Code 三入口怎么选。
• 更想先搞懂「AI 编程到底怎么回事」 → 从 vibe coding 是什么 或 AI 编程入门 这两篇泛入口读起。

每一步都对应「写完 CLAUDE.md 后自然会有的下一个问题」，不用一次学完，按需推进就好。

一句话收官

CLAUDE.md 就是给 Claude Code 写的项目入职手册——它每次开工都失忆，你把「该怎么干、哪里是雷区、怎么算干完」写进这份手册，它就不用你一遍遍重讲。

新手最佳起点：抄本文第三节那份 20 行最小模板 → 改成你项目的真实情况 → 让 Claude 做个小任务验证 → 按它犯的错补规则。 跑完这一圈，你就真正理解 CLAUDE.md 该怎么写了——它不是一次写完的完美文档，是一份越用越准的活文件。

记住那条贯穿全文的判断：写能检查的动作，不写漂亮的口号；习惯约束进 CLAUDE.md，安全硬锁进 settings.json。 守住这两条，你的第一版就不会跑偏。

相关阅读

• Claude Code 是什么？新手一篇看懂 —— 先搞懂工具本身，再回头写 CLAUDE.md 会更顺。
• Claude Code 完整学习指南：学习路径与知识地图 —— 整个 Claude Code 系列的中枢，告诉你按什么顺序学。
• Claude Code 提示词怎么写？模糊需求转工程任务 —— CLAUDE.md 管项目背景，提示词管单次任务，配套使用。
• Claude Code 三入口怎么选？App、CLI、IDE 区别 —— 还没装的先看这篇选入口。
• vibe coding 是什么？氛围编程完全指南 —— 想从更宏观的「AI 编程是什么」读起的入口。
• AI 编程入门：零基础怎么学 —— 零基础的学习路径总览。

• OpenAI Codex AGENTS.md 指南 —— 同类工具的对应专题，对照看更完整。

• Agent 知识库自动写作实战
• 知识库云端化教程
  外部参考：

• Claude Code 官方文档 · 记忆与 CLAUDE.md —— CLAUDE.md 加载规则、四种位置、@import、Auto Memory 的权威说明。
• Claude Code 官方文档 · 设置与权限 —— settings.json 的 permissions.deny / ask / allow 硬锁配置。
• Anthropic Claude Code 官方文档总入口 —— Claude Code 全部官方文档。

📚 更多 Agent 编程方法论：Agent 编程方法论：不教工具教方法，让 AI 按你的规矩干活