CLAUDE.md 怎么写：给 Claude Code 团队的实战指南

写好 CLAUDE.md 的要点只有几条：只放”每次会话都用得上、且只属于这个项目”的指令；保持简短；用具体例子代替形容词；其他一切都推到按路径限定的规则文件、Skills 或 hook 里去。这个文件会加载进每一次 Claude Code 会话，所以它的定位是”新工程师入职第一天必须知道的共享简报”，而不是团队历史上所有工作流程的操作手册。

这条边界恰好也是 Claude Certified Architect – Foundations 考试在领域 3（Claude Code Configuration & Workflows，占 20%）要考的东西。题目全是情景题：某团队的配置出了问题，你要选出”最不坏”的修法。这篇文章既讲机制，也讲判断。

CLAUDE.md 到底是干什么用的？

CLAUDE.md 是持久上下文。Claude Code 在会话开始时读取它，并把内容当作长期有效的指令：项目怎么组织、跑测试用哪个命令、团队遵循什么约定、哪些事 Claude 永远不该自作主张。

由此推出两条性质，本文后面的所有内容都建立在这两条之上：

• 它是常驻的。 每一行都会出现在每次会话的上下文里，不管当前任务用不用得上。没有”跳过这一节”的机制，章节标题也不控制加载。
• 它是引导，不是强制。 模型读了通常会照做，但也可以在当下判断某条规则不适用。对风格建议来说这是优点，对安全规则来说这是隐患。

CLAUDE.md 的三个层级分别放在哪？

Claude Code 会叠加三个文件。它们不是互相覆盖，而是合并生效。

层级	路径	随 git 共享？	用途
用户级	~/.claude/CLAUDE.md	否	个人偏好：输出详略、编辑器习惯
项目级	仓库根目录的 CLAUDE.md 或 .claude/CLAUDE.md	是	全员必须遵守的团队标准
目录级	子目录内的 CLAUDE.md	是	只在编辑该子树时生效的规则

最经典的错误是资深工程师把团队标准写进用户级文件。在他自己机器上一切正常，新人 clone 仓库后什么都拿不到——因为 clone 仓库不会复制别人的 home 目录。全团队都要遵守的东西，就该放在项目级。学习指南里的把团队标准放到团队能拿到的地方讲了 monorepo 场景下这个决策怎么做；如果你刚接触 Claude Code，可以先看 Foundations 篇的 CLAUDE.md 的三个层级：用户、项目、目录。

哪些内容该进 CLAUDE.md，哪些该做成规则、Skill 或 hook？

按使用频率和出错后果两个维度来分，是最快的判断方法。

内容	机制	原因
每次会话都用的约定（命名、测试命令、commit 格式）	CLAUDE.md	始终相关，始终加载
某一类文件的约定，且这类文件散落在整个目录树里（*.test.ts）	.claude/rules/*.md + paths frontmatter	只在编辑匹配文件时加载
某一个目录的约定（src/backend/）	目录级 CLAUDE.md	按位置限定范围
每周用一次的多步流程（写发布说明、数据库迁移）	.claude/skills/ 里的 Skill	按需加载，让 CLAUDE.md 保持精简
一旦失效会损失金钱、数据或安全的规则	Hook、权限模式或 allowed-tools	确定性执行；指令做不到

Skills 这一行是团队最常踩坑的地方。有个团队把五套详细流程加进 CLAUDE.md，文件从 300 行涨到 1,200 行。每套流程最多一周用一次，可那 900 行每次会话都要跟着加载，模型对真正的编码规范的注意力反而下降了。把它们挪进 Skills 后文件回到 300 行，任务准确率上升。完整推理见 CLAUDE.md 是始终开启的，Skills 是按需的。别搞混了。

Hook 这一行重要的原因不一样。基于提示词的规则有一小部分但非零的概率会失效，因为模型会自行判断——“rm 之前务必确认”在用户说”把项目清理一下”时就会被绕过。如果一次失误都不能接受，别把措辞写得更响，把规则改成程序化的。参见模型会在 4-15% 的情况下无视你的指令，以及本站的姊妹篇 hooks 与 CLAUDE.md 指令的分工。

一份好的项目级 CLAUDE.md 长什么样？

具体胜过描述。有一组实测数据：“准确提取关键事实”得分 60%，加上”要精确、要全面”变成 63%，而给三个输入/输出示例直接到 91%。形容词有歧义天花板，例子没有。这个结论同样适用于 CLAUDE.md：与其描述 commit 格式，不如直接给出一条示例。数据见文字描述的歧义天花板在 63%，例子直达 91%。

一个紧凑的骨架：

# Acme API

## Stack
Node 22, TypeScript strict, Fastify, Prisma, Vitest.

## Commands
- Test:  `pnpm test` (must pass before any commit)
- Lint:  `pnpm lint --fix`
- Types: `pnpm typecheck`

## Conventions
- Commit format, example:
  `fix(parser): handle missing JSON field in parse_record()`
- Errors: throw `AppError` subclasses; never return `{ error }` objects.
- Never edit files under `prisma/migrations/` by hand.

## Shared standards
@docs/coding-standards.md
@docs/security-policy.md

注意最后一段。写一句”遵守 docs/coding-standards.md”只是一句话，Claude 不会去打开那个文件。@path 导入语法才会把内容当作内联文本拉进来，这样主文件可以保持精简，而标准本身继续放在团队原本维护它的地方。细节见提到一个文件不等于加载了它。

按路径限定的规则怎样让上下文保持干净？

凡是按文件类型而不是按位置生效的约定，都该放进 .claude/rules/，并带上 paths glob：

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---
Use Vitest. One `describe` per exported function.
Assert with `toEqual`, never `toBe`, on objects.

不写 paths 的规则文件会在每次编辑时都加载，和根目录 CLAUDE.md 一模一样。有个项目放了十二个未限定范围的规则文件，每次编辑大约花 4,500 个 token 在规则上，其中只有约 1,000 个真正相关。加上 glob 就解决了，一行内容都不用删。多个模式重叠时会一起加载，这正是你想要的：Button.test.tsx 同时拿到 React 规则和测试规则。

glob 规则和目录级 CLAUDE.md 之间怎么选，标准很简单：按类型散布的（测试、CSS module、YAML 配置）用 glob；按位置集中的（一个自成一体的后端目录）用目录文件。学习指南里的没有 Path Glob，86% 的规则上下文被浪费和文件类型还是文件位置——决定了用哪种机制覆盖了边界情况，包括为什么把测试约定复制到八个目录文件里是维护陷阱。

考试里反复出现的 CLAUDE.md 反模式有哪些？

下面这些是 CCA-F 情景题一再回到的模式。能认出来，题就答了大半。

1. 团队标准放在用户级。 症状：“我这儿好使，新人什么都没有。“修法：移到项目级。
2. 多语言仓库只用一个巨型根文件。 症状：编辑 Python 时收到 React 建议。修法：拆成按路径限定的规则；判断标准是文件类型的多样性，不是团队规模。
3. 用文字引用代替导入。 症状：“Claude 无视我们的规范。“修法：@docs/file.md。
4. 每个子目录文件互相导入。 症状：每次编辑加载 3,000 行。修法：只导入真正共享的标准。
5. 不常用的流程写在正文里。 症状：文件超过几百行，质量下降。修法：Skills。
6. 安全规则写成散文。 症状：破坏性命令仍有 4% 的概率照跑。修法：hook 或 allowed-tools。
7. 把不一致当成随机性。 症状：“Claude 有时候守规矩有时候不守。“修法：先跑 /memory 看看实际加载了什么，再考虑加重试。参见 /memory 告诉你什么被实际加载了——MEMORY.md 不能。
8. 发明不存在的功能。 没有 <include> 标签，CLAUDE.md 没有 imports: frontmatter，Skills 没有 always-active 开关，层级之间也没有优先级排序。依赖这些的选项都是干扰项。

上面大多数模式背后的考题都长这样：“某团队报告了 X 现象。哪项改动是最合适的第一步？“诱人的选项是加强语气、加重试、加更多文字。得分的答案通常是把内容挪到与其范围和后果相匹配的机制上。

下一步

如果领域 3 是你练习分数最弱的地方，按顺序过一遍领域 3 学习指南；配置层级、规则、Skills 这几篇是层层递进的。然后做一次免费的 60 题模拟考，它按官方领域权重抽题，你能看到 Claude Code 配置类情景题实际是怎么问的。125 美元报名费、120 分钟时长、720 量表分通过线之类的考试信息，报名前请到 Anthropic / Pearson VUE 官方页面核对。