CLAUDE.md 怎么写？我整理了 10 个模板

用 Claude Code 的人，很多都有这种体验：同样的话，每开一个新会话就要重讲一遍。测试怎么跑、用哪个框架、哪些文件不能碰，AI 每次都像第一天上班。

解决办法就是 CLAUDE.md。这篇文章不讲空话，直接给你 10 个能复制的模板，以及把它写好的 5 条原则。

一、CLAUDE.md 是什么

它是放在项目里的一份 Markdown 文件，相当于写给 AI 的"入职说明书"。Claude Code 每次启动会话，都会先读取它，所以你只需写一次，之后每个会话都生效。

常见的放置位置有三处：

项目根目录 的 CLAUDE.md：团队共享，建议提交到 Git。
个人全局 的 ~/.claude/CLAUDE.md：你的个人习惯，对所有项目生效。
子目录 里的 CLAUDE.md：处理该目录下的文件时会补充读取，适合 monorepo。

需要说明的是：CLAUDE.md 是作为上下文交给 AI 的，不是强制执行的程序。写得越清楚、越具体，AI 遵守得越好，但不能当成百分之百的硬规则。这一点后面讲安全时还会再提。

二、写好它的 5 条原则

1. 具体，不要抽象。 "代码要整洁"没有任何信息量，"缩进 2 个空格，函数不超过 50 行"才是 AI 能照做的话。

2. 写命令，不要写描述。 与其写"项目有单元测试"，不如写 pnpm vitest run。

3. 只写"看代码看不出来"的。 目录结构、依赖版本，AI 自己能读出来。真正值钱的是：金额必须用整数分、订单状态只能向前流转，这类踩过坑才知道的规则。

4. 给理由，别只给禁令。 "不要用 ORM"不如"不要用 ORM：批量查询要手写 SQL，性能要求高"。有了理由，AI 遇到边界情况才会判断。

5. 保持精简。 内容越多，每一条被重视的程度越低。一个实用的自测方法：删掉这一行，AI 会不会犯错？不会，就删。

三、10 个模板

模板分三组：基础、协作、进阶。不用全抄，挑出和你项目相关的，拼成一份 50 到 100 行的文件就够了。

模板 1：项目概述 + 常用命令

markdown 复制代码

# 项目
电商后台 API，Node 20 + Express + PostgreSQL

# 常用命令
- 开发：npm run dev
- 测试：npm test
- 单个测试：npm test -- path/to/file
- 构建：npm run build

最重要的是命令。AI 最常卡在"怎么运行"，这几行能省下大量试错。

模板 2：代码规范

markdown 复制代码

# 代码规范
- 缩进 2 个空格，字符串用单引号
- 函数不超过 50 行，嵌套不超过 3 层
- 禁止 any；确需使用，必须写注释说明原因
- 错误必须显式处理，不要吞掉异常

只写能被检查的规则，格式类的细节交给 Prettier、ESLint 这类工具，不必占用 CLAUDE.md。

模板 3：测试要求

markdown 复制代码

# 测试
- 新功能和 bug 修复都要带测试
- 先跑被改动的单个文件，通过后再跑全量
- 测试不通过，不要修改测试来迁就代码，先说明原因
- 不要 mock 数据库，集成测试用测试库

第三条很关键。没有它，AI 遇到失败的测试，有时会倾向于直接改测试让它通过。

模板 4：目录结构（写职责，不只是列表）

markdown 复制代码

# 目录
- src/routes/    路由，只做参数校验
- src/services/  业务逻辑，所有规则写在这里
- src/db/        SQL 与迁移，不要在别处写 SQL
- tests/         与 src 目录结构保持一致

重点是"这里只做什么"。AI 知道每个目录的职责，就不会把代码随手放错位置。

模板 5：Git 与提交规范

markdown 复制代码

# Git
- 分支：feat/xxx、fix/xxx
- 提交信息：type: 描述（feat、fix、docs、refactor）
- 一次提交只做一件事
- 我没要求时，不要 commit，更不要 push

最后一条能避免 AI 擅自提交。如果你希望它自动提交，就把这条改成相反的要求。

模板 6：工作流程约定

markdown 复制代码

# 工作方式
- 改动超过 3 个文件时，先说计划，我确认后再动手
- 改完自己跑测试，并把结果告诉我
- 需求不明确就提问，不要自己猜
- 完成后用 2 到 3 句话总结改了什么

这是性价比最高的一段：它把"先想后做"变成了默认行为。

模板 7：安全红线

markdown 复制代码

# 安全
- 不读取、不修改 .env 和任何密钥文件
- 不执行 rm -rf、git push --force、DROP TABLE
- 不把密钥、token 写进代码或日志
- 涉及生产环境的操作，一律先问我

这里有一个必须注意的点。 写在 CLAUDE.md 里的规则属于"说明"，AI 通常会遵守，但并不是硬拦截。真正不能出事的东西，要叠加三层：文字规则、权限设置里的 deny 规则（直接禁止读取某些文件或执行某些命令）、以及 Hooks（在工具执行前后强制检查）。CLAUDE.md 是说明，权限和 Hook 才是门锁。

模板 8：踩坑清单

markdown 复制代码

# 本项目的坑
- 金额一律用整数"分"，禁止浮点数
- 时间统一存 UTC，展示层再转换
- 改数据库结构必须新建迁移文件，不要改旧的
- 订单状态只能向前流转，规则见 src/services/order.ts

这一段的长期价值最高。它记录的是代码里看不出来、却出过事故的知识。每踩一次坑，就加一行。 注意最后一条的写法：指向具体文件，让 AI 去读，而不是靠它猜。

模板 9：个人偏好（放全局文件）

markdown 复制代码

# 个人偏好（写在 ~/.claude/CLAUDE.md）
- 用中文回复，技术名词保留英文
- 解释要简短，先说结论
- 不要在代码里加多余的注释
- 不确定时给出选项和推荐，不要直接改

个人习惯放在全局文件，不要写进团队共享的项目文件，否则会影响同事。

模板 10：拆分与引用

bash 复制代码

# 详细文档（按需读取）
- 架构说明：@docs/architecture.md
- API 约定：@docs/api-style.md
- 数据库规范：@docs/database.md

用 @文件路径 引用其他文档，主文件保持精简。

一个经验判断：主文件超过 150 行，或者一半内容只和某个目录有关，就该拆了。你还可以用 CLAUDE.local.md 放个人私有设置并加入 .gitignore，用 .claude/rules/ 目录按主题拆分规则。具体的加载细节和语法，以官方文档为准。

四、完整示例：前端项目

把模板 1、2、3 合起来，就是一份实用的前端项目文件，大约 20 行：

markdown 复制代码

# 项目
管理后台前端，React 18 + TypeScript + Vite

# 命令
- 开发：pnpm dev
- 类型检查：pnpm tsc --noEmit
- 测试：pnpm vitest run
- 提交前：pnpm lint && pnpm test

# 规范
- 组件用函数式 + hooks，禁用 class 组件
- 接口类型放 src/types，禁止 any
- 样式用 CSS Modules，不写行内样式

# 测试
- 新组件必须配 .test.tsx
- 先跑单个文件，再跑全量

五、怎么开始，怎么维护

起步： 在项目里运行 /init，让 Claude 先生成一份草稿，再把它删到只剩真正有用的内容。草稿通常偏长，不要原样保留。

维护： CLAUDE.md 不是写一次就完事。一个简单的循环是：AI 犯错 → 找原因（没写？写得含糊？太长被忽略？）→ 补一行具体的话 → 新开会话验证。如果改了没改善，就换种写法，而不是一味加粗、全大写。

每月做一次体检：过时的命令和路径删掉，从没起过作用的规则删掉，互相矛盾的规则合并。

写在最后

一份好的 CLAUDE.md 不是越长越好，而是每一行都有用。先从模板 1、3、6 开始，花 10 分钟写出第一版，然后在日常使用中，每遇到一次 AI 犯错，就补上一条。几周之后，你会得到一份真正贴合你项目的"说明书"。