← 返回全部文章
指南 · 2026年5月21日 · 8 分钟阅读

如何写好 CLAUDE.md（含真实前后对比）

我见过的大多数 CLAUDE.md 文件都没有真正发挥作用。它们更像文档：解释代码库结构，讨论工程价值观，列出“我们一般会尽量遵循”的偏好。Claude 读完之后，还是会按它认为统计上最常见的方式去做。

修复方法很小，但有点反直觉：写少一点，写硬一点，并且放在正确的位置。

这是我们给 AI Memory Reader 写 CLAUDE.md 时学到的（披露：这是我们做的工具）。它是一个 macOS 应用，恰好就是用来浏览别人项目里的 CLAUDE.md 文件的。所以我们确实看过很多。

先讲层级（比大多数人想的更重要）

Claude Code 会按特定顺序从多个文件加载指令。优先级高的文件会覆盖优先级低的文件：

  1. 托管策略 — /Library/Application Support/ClaudeCode/CLAUDE.md (macOS) 或 /etc/claude-code/CLAUDE.md (Linux)。由管理员设置，不能排除。
  2. 用户全局 — ~/.claude/CLAUDE.md。你的个人偏好，作用于所有项目。
  3. 项目根目录 — ./CLAUDE.md 或 ./.claude/CLAUDE.md。提交到 git，供团队共享。
  4. 项目本地 — ./CLAUDE.local.md。个人的项目级覆盖，自动加入 gitignore。
  5. 子目录 — 嵌套的 CLAUDE.md 只作用于对应子树。

如果只记一条：个人偏好放全局，团队共享规范放项目文件。把两者混在一起，是我们最常见到的错误。

如果一位新同事克隆仓库后也应该受到“提交前必须跑 prettier”这类规则约束，那它应该写进项目文件。如果他被“用粤语回复并使用美制单位”这种规则影响了，那它应该只存在于你的全局文件。仓库里的 CLAUDE.md 是团队契约，不是个人配置。

写规则最重要的一条原则

写 Claude 能自己验证是否遵守的指令。

  • ❌ “正确格式化代码”

  • ✅ “使用 2 空格缩进；禁止使用 tab”

  • ❌ “测试你的改动”

  • ✅ “每次 commit 前运行 npm run test:unit”

  • ❌ “数据库查询要小心”

  • ✅ “所有新的数据库查询必须走 src/db/safe.ts；禁止直接调用 knex.raw()”

Anthropic 文档里的经验法则是：如果违反某条规则会让 code reviewer 皱眉，它适合放进 CLAUDE.md。如果违反某条规则会让 CI 失败，它应该放进 CI，而不是 CLAUDE.md。CLAUDE.md 适合承载那些人类在意、但机器无法自动强制执行的约定。这也是它值得花心思写的原因：Anthropic 的 40 万次会话研究发现，决定 agent 成败的是问题定义和判断力，而不是写语法，而 CLAUDE.md 正是把这份判断力落到纸面的地方。

长度很重要——控制在 200 行以内

Anthropic 自己的建议是：把 CLAUDE.md 控制在约 200 行以内，规则段落不超过 15 条。更长的文件会在每条消息里消耗上下文窗口，而且反直觉的是——遵守率往往更低，不是更高。

如果你写了 30 条规则，说明你还没有完成“哪 12 条真正承重”的取舍。删减的过程，本质上就是找出真正重要规则的过程。

否定式规则和肯定式规则同样重要

这点最容易被团队跳过。Claude 默认会采用统计上最常见的模式——而那几乎从来不是你这个代码库的模式。

  • ❌ 缺失规则 → Claude 生成 React class 组件，因为网上仍有大量教程这么写。

  • ✅ “禁止 class 组件，只允许 functional components + hooks。”

  • ❌ 缺失规则 → Claude 写 try { ... } catch (e) {}，因为这种模式到处都是。

  • ✅ “禁止 catch 错误后吞掉；要么记录到 bugsnag，要么 rethrow。”

把禁忌项写明确。它们常常比“应该做什么”更关键。

真实前后对比：一个 TypeScript 后端仓库

下面这个 CLAUDE.md 来自真实生产代码库（已脱敏）。“before” 有 287 行，“after” 只有 47 行。

Before

# 欢迎来到我们的代码库

这是一个 Node.js 后端应用，使用 TypeScript 和 Express 构建。我们遵循现代 JavaScript 模式，努力写出干净、可维护的代码。我们团队首要价值是可读性和可测试性。

## 架构

代码库按分层架构组织。我们有 controllers、services 和 repositories。Controllers 处理 HTTP，services 包含业务逻辑，repositories 负责数据库访问。我们一般尽量保持关注点分离。

## 编码规范

- 我们使用 TypeScript strict 模式
- 我们一般倾向于函数式写法
- 我们尽量为新功能写测试
- 代码应该正确格式化
- 除非必要不要使用 `any`
- 使用描述性的变量名
- 注释应该解释为什么，而不是是什么
- ... (继续 240 行)

After

# 工程规则

## 技术栈
- TypeScript strict 模式。禁止 `any`——用 `unknown` 后再窄化。
- Express 4.x，Knex 操作数据库，Vitest 跑测试。

## 架构 (IMPORTANT)
- Controllers 放在 `src/controllers/`。保持薄层——只剥离 HTTP，调用 service。
- Services 放在 `src/services/`。所有业务逻辑都在这里。
- Repos 放在 `src/repos/`。这里是唯一允许 import `knex` 的地方。
- Controller 里 import knex 是 bug。

## 测试 (YOU MUST)
- 新 service 方法必须配 Vitest 单测。
- Commit 前运行 `npm run test:unit`。
- 集成测试使用真实 Postgres：`docker compose up test-db`。禁止 mock 数据库。

## 禁止的写法
- 已提交代码里禁止 `console.log`——用 `src/lib/logger.ts`。
- 禁止 `try { ... } catch (e) {}`——要么记日志，要么 rethrow。
- 业务逻辑里禁止 `Date.now()`——注入 `src/lib/time.ts` 的 `Clock`（我们要测试时间敏感代码）。
- `src/config.ts` 之外禁止 `process.env.X`。

## 拿不准时
- 新 endpoint？参考 `src/controllers/health.ts` 的标准形态。
- 新 repo 方法？参考 `src/repos/users.ts`。

注意删掉了什么：哲学、 “我们一般尽量”、欢迎语、架构解释。留下来的都是可执行的规则。每条规则都能通过“PR review 会不会被指出来”这个测试。

哪些东西不该放进 CLAUDE.md

有三类内容我们会直接删掉：

1. 代码里已经看得到的事。 “我们用 Express”——Claude 能看 package.json。“入口在 src/index.ts”——Claude 能看文件树。CLAUDE.md 应该写那些读代码读不出来的东西：不变量、约定、近期决策、隐蔽陷阱的位置。

2. CI 已经执行的事。 “Commit 前跑 prettier”——如果你已经有 pre-commit hook 或 CI check，Claude 不需要这条规则。CLAUDE.md 不要重复机器可执行的规则，把空间留给只有人类 review 才能抓到的事。

3. 实现历史。 “我们 3 月从 Redux 迁到了 Zustand”——这是 commit message，不是规则。除非迁移留下了雷（“不要把 Redux 加回来；旧的 src/store/legacy/ 目录视为只读”），否则删掉。

使用 /memory 命令

Claude Code 自带 /memory。它会显示当前会话加载了哪些 CLAUDE.md，按顺序列出，并标明各自作用域。如果某条规则没有被遵守，先跑 /memory。很多时候答案是：“你以为会加载的文件根本没有加载”（目录错了、文件名错了，或者不该被 gitignore 的文件被忽略了）。

如果你要审计多个项目的 CLAUDE.md，AI Memory Reader 可以给你一个跨 home 目录的统一视图——当你记不清哪个项目用了哪些规则时很实用。披露：这是我们做的工具，免费，GPL-3.0。

关于长度和语气

短不等于生硬。对比：

Commit 前跑 npm test.

VS

YOU MUST 每次 commit 前运行 npm run test:unit。如果套件失败，修测试，而不是跳过——禁止使用 --no-verify。

第二条更长，但每个字都在做事：强调标记提升优先级，具体命令消除歧义，提前指出失败模式，并关上逃逸口。

Anthropic 文档证实了我们在实践中观察到的现象：IMPORTANT 和 YOU MUST 标记会可测量地提高遵守率。要慎用——如果所有事情都重要，就没有事情重要——但对于过去真正咬过你的 3–5 条规则，应该用。

收尾清单

提交 CLAUDE.md 之前，过一遍：

  • 总行数不超过 200。
  • 个人偏好在 ~/.claude/CLAUDE.md，不在项目文件里。
  • 每条规则都是直接命令（没有“我们一般尽量”）。
  • 每条规则都可验证（没有“要小心”）。
  • 至少 30% 的规则是否定式（禁止 X，不要 Y）。
  • 没有任何条目跟 CI/lint 配置重复。
  • IMPORTANT 和 YOU MUST 标记只用在 3–5 条最关键的规则上。
  • 跑过 /memory，确认文件按你预期的顺序加载。

如果你的 CLAUDE.md 能全部通过——它已经比我们见过的中位数代码库写得更好了。

编辑说明：本文属于 bestagent.dev——由一线工程师独立运作的 AI 编程工具评测站，不为厂商打广告。我们做 AI Memory Reader，文中提了两次。文中其他工具没有付费露出。

这篇对你有帮助吗?

相关阅读

文章独立产出 · 编辑政策

继续阅读 →