CLAUDE.md 怎么写？让 Claude Code 懂你项目的 7 节模板
CLAUDE.md 怎么写决定了 Claude Code 在你项目里有多懂事，本文按官方推荐的 200 行内、信号密度优先原则给一份 7 节模板和 5 个常见错例
30 秒了解：CLAUDE.md 是什么、为什么重要
CLAUDE.md 怎么写这件事，官方一句话能讲清——把它当作「给新同事第一天上岗时的简报」来写。 短、密度高、只放真正能减少 Claude Code 犯错的信息。
Claude Code 每次启动会自动读取项目根目录的 CLAUDE.md，作为 system prompt 的一部分喂进去。换句话说：你不写，每次会话都得重复解释「我们这个项目用 pnpm 不用 npm」「commit message 走 Conventional Commits」「src/legacy/ 别动」；写了，一次写好以后省下成百上千次解释。
这篇按官方的写法+实际项目经验，给你一份能直接复制的模板和 5 个常见坑。如果你完全不知道 Claude Code 是什么，先看 Claude Code 是什么 再回来。
准备工作：搞清楚 3 件事
1. CLAUDE.md 放哪里？
官方支持 3 个位置，从全局到局部：
| 位置 | 作用域 | 放什么 |
|---|---|---|
~/.claude/CLAUDE.md | 你这台机器所有项目 | 个人偏好（不要 emoji、回答用中文） |
项目根/CLAUDE.md | 这个项目 | 项目约定（最重要的一份） |
子目录/CLAUDE.md | 进入该子目录时 | 模块专属规则 |
最关键的是项目根那一份，绝大多数团队只需要这一份就够。
2. 要不要 commit 到 git？
项目根的 CLAUDE.md：要 commit。 它是团队共享的「Claude Code 配置」，跟 .editorconfig、tsconfig.json 一个性质——所有人在这个项目里启动 Claude Code 都应该读到同一份约定。
~/.claude/CLAUDE.md 是个人偏好，不要 commit。
3. 长度多少合适？
官方推荐：200 行以内。
为什么这么短？因为 CLAUDE.md 每次会话都被注入到 prompt，行数越多、占的 token 越多、给真实任务的预算越少。写超过 200 行通常意味着你把不必要的东西塞进去了。
最简单的开始：跑 /init
不知道写啥？让 Claude Code 自己起草：
cd 你的项目
claude在 CLI 里输入：
/init它会探索整个 codebase，识别构建命令、测试方式、目录结构、命名约定，输出一份草稿 CLAUDE.md。
你需要做的：
- 通读一遍它写的草稿
- 删掉它猜错的、加上它不知道的——比如团队内部的潜规则、protected directory、commit message 格式、code review 偏好
- 保存、commit 到 git
不要直接用它生成的草稿——AI 写的草稿往往太详细（违反「信号密度」原则）或者太通用（没有项目特异性）。
7 节模板：能直接复制改的版本
下面这份模板覆盖了 90% 项目用得上的内容。复制改成你自己项目的样子：
# 项目简报
[一句话定位 + 3 句话讲清架构]
例：这是一个用 Astro + MDX 的静态站点，部署在 Cloudflare Pages。
内容文件在 src/content/articles/\{cluster\}/\{slug\}.mdx，frontmatter schema 在
src/content.config.ts。所有页面 SSG 生成，没有运行时。
## 关键命令
- 开发：pnpm dev
- 构建：pnpm build
- 类型检查：pnpm check
- 文章质检：pnpm check-articles
- 不要用 npm 或 yarn，全项目走 pnpm
## 代码约定
- TypeScript 严格模式
- 组件用 .astro 写在 src/components/
- 不要用 React，纯 Astro
- 样式走 Tailwind，不写 CSS Module
- 文件命名：组件 PascalCase，工具函数 kebab-case
## 内容约定（mdx 文章）
- frontmatter 字段以 src/content.config.ts 为准
- mdx 里中文中的 { } < > 必须转义或用全角
- PromptCopy 组件内只能纯文本 + 缩进
- 每篇至少 3 个站内链接，格式 [文字](/cluster/slug/)
## 不要碰的目录
- src/content/articles/ 下已存在的 mdx 不要乱改
- public/ 下的静态资源除非任务相关
- node_modules / .astro / dist 是构建产物
## Commit 约定
- 走 Conventional Commits：feat / fix / docs / refactor / chore
- 中文 OK，比如 「feat: 新增 ai-coding cluster 7 篇文章」
- 一个 commit 一个独立主题，跨主题拆开
## 跑测试 / 验收
任何代码改动后跑 pnpm check 和 pnpm build 验证。
新增文章后跑 pnpm check-articles \{cluster\} 确保 0 warnings。
全部绿了才提示「可以 commit 了」。把上面这段当骨架，按你项目实际改。短就是好——能删的尽量删。
7 节分别该写什么
第 1 节：项目简报（必有）
一句话讲项目是干什么的，再 2-3 句讲架构。Claude Code 从这一节判断「这是个什么类型项目，我该用什么思路」。
好例子：
这是一个内部 admin dashboard，Vue 3 + Pinia + ElementPlus。后端 API 在 services/api.ts 集中，所有页面在 views/ 里按业务模块分目录。
坏例子：
这是我们公司很重要的一个项目，承载着关键业务…（这种”夸赞”对 AI 没用，删）
第 2 节：关键命令（必有）
把构建、测试、运行、检查的命令列出来。这是 Claude Code 用得最频繁的信息。
关键技巧：写上「不要用什么」。
- 跑测试：pytest tests/ -v
- 不要用 unittest，全项目走 pytest负向约束往往比正向描述更有效——AI 知道「该跑什么」很容易，但「不该跑什么」必须显式说。
第 3 节：代码约定（必有）
命名、缩进、风格、类型策略。只写跟「业界默认」不一样的部分，跟默认一致的不用写。
好例子：
不用 any，必须用 unknown + 类型守卫。 Promise 链不超过 3 层，超过就拆成 async/await。
坏例子：
用 4 个空格缩进。（已经有 .editorconfig，不用重复）
第 4 节：架构关键决策
3-5 条核心架构决策，影响 Claude Code 怎么写代码。
- 状态管理用 Zustand，不用 Redux 或 Context
- 表单走 react-hook-form + zod 校验
- 时间统一用 dayjs，禁用 moment
- 日志走 pino，console.log 只在 dev 用第 5 节：禁区（强烈建议有）
protected directory、不要碰的文件、危险操作。
- src/legacy/ 下的代码是历史遗留，需要改之前先问我
- migrations/ 已应用的 SQL 文件不要改，新增就好
- 不要直接执行 git push --force
- 数据库相关操作必须先 dry-run这一节救过无数次「AI 一上来就改 prod 配置」的事故。
第 6 节：Commit / PR 规范
- Commit message 用 Conventional Commits（feat/fix/docs/refactor/chore/test）
- 一个 commit 一个独立主题
- PR title 跟 commit message 同格式
- 大改动先开 draft PR 让我 review 思路再写完第 7 节：验收标准
Claude Code 怎么知道「干完了」？写清楚。
任何改动后：
1. 跑 pnpm test，绿了再下一步
2. 跑 pnpm lint，无 error
3. 跑 pnpm build，无 warning
4. 输出一句话总结改了什么，等我 review5 个最常见的写法错误
错误 1：写成「项目历史」
# 项目历史
2023 年 X 月由 Y 团队启动，最初用 React，2024 年迁移到 Vue...问题：Claude Code 不需要历史，需要现状。删。
错误 2：抄了 README.md
把 README 直接复制进 CLAUDE.md。
问题：READMe 是给人看的（有市场宣传、致谢、changelog），CLAUDE.md 是给 AI 看的（只要操作性事实）。两者重叠 10%-20%（命令、架构），其他都要剔除。
错误 3：写「希望」而不是「现实」
- 所有代码必须有单元测试覆盖
- 函数不超过 30 行问题：如果项目里 70% 代码没测试、平均函数 80 行，写这个等于让 AI 跟你撒谎。写真实约定，不写理想约定。
错误 4：太详细
把整个 API 文档塞进 CLAUDE.md。
问题：Claude Code 自己会读代码。CLAUDE.md 只放「读代码读不出的元信息」——团队约定、风格偏好、禁区、流程。
错误 5：没维护
3 个月前写的 CLAUDE.md 还在让 AI 用 yarn，但项目早改成 pnpm 了。
解决：每个季度 review 一次，把过时的删掉。或者跑：
请帮我审一下当前的 CLAUDE.md：
- 列出所有可能已经过时的条目（命令、目录、约定）
- 对每一条说明你怎么判断它过时（看到的实际代码 vs CLAUDE.md 描述）
- 不要直接改文件，输出一份「建议修改清单」给我
参考实际代码：package.json / tsconfig.json / 主要源码目录的现状。
让 Claude Code 自己挑出 CLAUDE.md 跟代码现实的偏差，省心。
高级用法：让 Claude Code 边干边学
最强玩法：让它自我改进 CLAUDE.md。
跑完一个任务，发现 AI 犯了个本来可以避免的错（比如忘了项目用 pnpm 不用 npm），跟它说：
你刚才犯了一个错：用了 npm install 而不是 pnpm install。
请：
- 检查当前的 CLAUDE.md，看为什么这个约定没被你接收到
- 加一条精准的规则进 CLAUDE.md，让类似的错下次不会重复
- 给我看 diff，等我批准
规则要简短、明确、可执行——不要写「请记住要用 pnpm」这种废话，要写「所有包管理命令必须用 pnpm，禁用 npm 和 yarn」这种铁律。
跑几十次后，CLAUDE.md 会演变成一份「这个项目所有踩过的坑的清单」。这就是 Anthropic 官方说的「compounding engineering」——每次错都变成下次的护栏。
/memory 命令快速编辑
会话里临时想加一条 CLAUDE.md 规则？不用切窗口，直接：
/memory会打开 CLAUDE.md 编辑界面，加完保存退出，立刻生效。
下一步
- 上手 7 步走 → Claude Code 怎么用
- 命令速查表 → Claude Code 命令速查表
- 进阶 10 技巧 → Claude Code 进阶 10 技巧
- 装出问题 → Claude Code 安装教程
- 想了解 Claude 模型本身 → Claude 全功能教程
- 全景对比 → AI 写代码完全指南
常见问题
Q：CLAUDE.md 跟 .cursorrules 是一个东西吗？
A：作用类似（都是给 AI 看的项目约定），但格式和读取机制不同。Cursor 读 .cursorrules，Claude Code 读 CLAUDE.md。如果你两个工具都用，可以维护两份，或者写一份共用的（比如 AI-RULES.md）然后两边都 symlink 过去。
Q：CLAUDE.md 写中文还是英文？ A：都可以。中文项目用中文最自然，AI 完全理解。英文国际化项目用英文，方便外籍同事 review。重点是简短清晰，语言反而其次。
Q：能不能放敏感信息（API key、密码）？ A：绝对不能。CLAUDE.md 是 commit 到 git 的团队文件，任何能 clone 仓库的人都能看到。敏感信息走环境变量或 secrets manager。
Q：子目录的 CLAUDE.md 什么时候用？
A：项目特别大（monorepo、多个独立模块）时用。比如 frontend/CLAUDE.md 写 React 约定，backend/CLAUDE.md 写 FastAPI 约定。Claude Code 进入子目录时会读对应的那份。小项目不需要。
Q：能否在 CLAUDE.md 引用其他文件？
A：可以。用 @path/to/file 在 CLAUDE.md 里写，Claude Code 会按需加载。比如：「样式规范见 @docs/STYLE.md」。但不要塞太多 @ 引用——每个引用都增加 token，违背「信号密度」原则。