← All reviews
· May 21, 2026 · min read

如何写好 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 是给人在意但机器无法自动执行的事。

长度很重要——控制在 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 会不会被 flag” 这个测试。

哪些东西不该进 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 不要重复机器可执行的规则。留它给只有人能抓的事。

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

用 /memory 命令

Claude Code 自带 /memory——它显示当前会话加载了哪些 CLAUDE.md，按顺序，带各自的作用域。如果某条规则没被遵守，先跑 /memory。结果常常是”你以为会加载的文件根本没加载”（目录错了、命名错了、不该被 gitignore 的被 gitignore 了）。

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

关于长度 vs 语气

短不等于生硬。对比：

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，文中提了两次。文中其他工具没有付费露出。

相关阅读

Reviews independently produced · Editorial policy

Read more reviews →