DeepDojo.AI发布 2026-11-12English

CLAUDE.md 怎么写，Claude 才会照做

Claude CodeAI 编程

仓库统一用 pnpm，你新开一个会话让 Claude Code 装依赖，它跑的却是 npm install。另一次，它把 Next.js 的类型引进了本该和框架无关的 domain/ 目录。代码能运行，可团队约定一条也没守住，你只好在新会话里再讲一遍。

问题出在这些约定根本不在代码里。代码能展示函数怎样调用，却记不下“改完 TypeScript 先跑 typecheck”“领域层不依赖框架”这样的团队决定。Claude 读不到，就只能按通用做法来。

CLAUDE.md 就是放这些约定的地方：新会话启动时自动加载，Claude 不用再猜。难的是写什么、怎么写。它每次都会进入上下文，写得太多会挤占注意力；写成“请编写高质量代码”，又没有一句能照着执行。

一份好用的 CLAUDE.md 靠三件事：

  • 只保留会反复用到、又很难从代码推断出来的约定；
  • 每条规则写清什么时候做、做什么、怎样检查；
  • 用 /init 生成草稿后，再补上代码表达不出的团队决定。

下面用一组 TypeScript 项目的规则，从筛选内容一直走到起步模板。

01 缺少约定时，Claude 会按通用做法来

把会反复用到的团队约定保存下来，可以减少新会话中的重复说明。缺少这些信息时，Claude 可能采用通用做法，得到的代码即使能运行，也可能不符合项目要求。例如：

  • 仓库使用 pnpm，Claude 却运行 npm install；
  • domain/ 不能依赖框架，Claude 却把 Next.js 类型引入领域层；
  • 团队禁止 any，生成的代码仍使用了宽松类型；
  • 修改认证模块后必须运行专项测试，Claude 只做了语法检查。

先保存那些会影响工作方式、又难从代码看出的长期约定。新会话加载 CLAUDE.md 后，Claude 就能少猜一些团队要求。

02 值得常驻的内容要满足两个条件

手边有一条项目说明时，先看它能否同时满足两个条件：

  1. 它会在许多会话中反复使用；
  2. Claude 很难仅靠读取代码准确推断它。

可以用三条信息试一试：

信息怎样处理
团队统一用 pnpm，禁止混用 npm保留。经常会用到，锁文件也说不清“禁止混用”这个团队决定
共有 42 个源文件，入口是 src/index.ts直接查目录即可
上次重构的三个待办在 TODO.md放在当前对话或任务清单，随任务更新

优先保留项目用途、技术边界、目录职责和依赖方向。再写清真实命令及使用顺序、项目特有编码规则、安全与协作约定，以及高频错误的检查方法。

Anthropic 在 Claude Code 最佳实践里给出的标准几乎一样：CLAUDE.md 会进入每一次会话，每一行都会占用 Claude 在每个任务上的一点注意力，所以它最适合只放 Claude 无法从代码自己推断出的内容。官方列了四类：确认工作的确切命令，代码里容易误导的地方，仓库里找不到的团队决定，以及你已经纠正过两次的问题。

小黑用筛子从可推断信息和临时状态中筛出值得写入 CLAUDE.md 的长期规则

03 把项目事实写成可执行的要求

下面这组规则把项目事实写成了可执行的要求：

# 项目概览

- 前端使用 Next.js App Router 和 TypeScript，数据库访问统一通过 Prisma。
- 认证由 `src/server/auth/` 提供，业务模块不自行解析登录 Cookie。

# 目录职责

- `src/app/`：页面和路由入口，不放数据库查询。
- `src/server/`：服务端业务编排。
- `src/domain/`：领域类型和纯业务规则，不依赖框架。

# 验证命令

- 修改 TypeScript 后先运行 `pnpm typecheck`。
- 修改 `src/server/auth/` 后运行 `pnpm vitest src/server/auth`。
- 只有跨模块改动才运行完整的 `pnpm test`。

上例中的目录限制和验证顺序来自团队决定。保留简短的项目概览、设计意图、接口限制和项目特有的检查要求。详细代码信息按需查阅，通用语法和宣传描述留在常驻指令之外。

规则多起来以后，放在哪个文件、什么时候加载，也会影响它能不能起作用，具体可以看团队规则和个人偏好该放进哪个 CLAUDE.md。

04 每条规则都要能检查

规则要让人知道何时行动、具体做什么，以及怎样检查。“请编写高质量代码”没有提供这些依据。可以比较下面几种写法：

模糊写法可执行写法
修改后做好测试修改 src/server/auth/ 后运行 pnpm vitest src/server/auth
不要破坏架构domain/ 不得导入 app/、adapters/ 或 Next.js 模块
注意敏感信息不读取或提交 .env*；示例凭证使用明显占位值
尽量少改文件只修改当前任务必需的文件；无关问题先报告，不顺带重构

比如“改数据库模型后，运行迁移检查并列出生成文件”，就能清晰看出触发条件、动作和结果。

以认证测试规则为例：修改 src/server/auth/ 是触发条件，运行 pnpm vitest src/server/auth 是动作，命令记录和测试结果是检查依据。示例中的路径与命令要换成项目实际要求。

Claude Code 的记忆文档对此说得很直接：Claude 把 CLAUDE.md 当作上下文，而不是强制执行的配置，所以写法决定了它遵循得有多可靠。官方建议把指令写到“具体到可以核实”，例如用“使用两个空格缩进”代替“正确格式化代码”，用“提交前运行 npm test”代替“测试你的修改”。

规则之间也要兼容。全局要求默认用 npm，项目却要求 pnpm，就把全局改成“使用项目锁文件对应的包管理器”。具体用哪个，交给项目说明。官方文档也提醒，两条指令互相矛盾时，Claude 可能任选其一。

05 用 /init 起草，再补团队决定

在项目根目录运行：

/init

/init 会分析代码库，生成一份包含构建命令、测试说明和已发现约定的起步草稿；已经有 CLAUDE.md 时，它会提出修改建议，不会直接覆盖。

拿到草稿后，先检查其中的依赖与目录信息，再补上代码难以表达的团队决定：目录为何分开、测试按什么顺序运行、哪些错误需要提前检查。消除模糊、重复、冲突和过期内容后，再验证加载与行为。

规则写进文件后，Claude 是否照做还要另外确认。加载没加载、触发条件满足没有、该跑的检查有没有跑，排查顺序见CLAUDE.md 规则不被遵守的排查步骤。

06 一份起步模板

# 项目概览与边界

- 填写项目用途、主要技术栈和技术边界。

# 目录职责

- 填写入口、服务、领域和测试目录的职责与限制。

# 开发与验证

- 填写安装、启动、相关测试和最低检查的实际命令及使用条件。

# 编码与协作

- 写清项目特有规则、依赖边界和高频错误。
- 修改前阅读模块与测试，只改当前任务必需内容。
- 完成后报告实际改动和已运行的验证。

用项目事实替换占位内容后，再查三项：

  1. 这条内容值得长期保留吗？
  2. 能照着执行，并且检查得出来吗？
  3. 放置位置与它的适用范围一致吗？

回到开头那个 pnpm 仓库：把“统一用 pnpm，禁止混用 npm”写进 CLAUDE.md，Claude 在下一次会话里就有了依据。这些要求写清楚了，每次新会话需要你重复解释的东西就会少很多。