Appearance
CLAUDE.md 与 Rules 编写指南
最后更新：2026-08-11
CLAUDE.md 是所有 AI 编程工具（Claude Code、Cursor、CodeBuddy、Codex CLI）的**"项目记忆文件"**。它告诉 AI：这个项目是怎么组织的、有什么规矩、用什么命令——不需要每次都重新解释。
如果把 AI 比作新加入团队的工程师，CLAUDE.md 就是他的入职培训手册。
一、CLAUDE.md 解决了什么问题
| 没有 CLAUDE.md | 有 CLAUDE.md |
|---|---|
AI 不知道用 npm run dev 还是 yarn start，需要你每次说 | AI 自动用对的命令 |
| AI 可能建议用 Vue 方案，但项目是 React | AI 知道技术栈 |
| 每次新对话都要解释"我们不用 src 目录，用 lib" | 一次写入，永久生效 |
| AI 写的代码风格不统一 | AI 遵循团队规范 |
核心公式：
CLAUDE.md 的价值 = 减少解释次数 × 每次对话的 Token 消耗 × 团队人数
二、CLAUDE.md 的等级体系
优先级口诀：企业覆盖团队，团队覆盖项目，项目覆盖个人，个人覆盖 IDE 默认。
不同工具的对应文件
| 工具 | 记忆文件 | 规则目录 |
|---|---|---|
| Claude Code | CLAUDE.md | .claude/rules/ |
| CodeBuddy | CODEBUDDY.md | .codebuddy/rules/ |
| Cursor | .cursorrules | .cursor/rules/ |
| Windsurf | .windsurfrules | .windsurf/rules/ |
| GitHub Copilot | .github/copilot-instructions.md | — |
虽然文件名不同，但内容和写法完全通用。本文以 CLAUDE.md 为例，所有技巧对上述文件同样适用。
三、CLAUDE.md 的结构模板
一份好的 CLAUDE.md 应该包含以下五个部分：
markdown
# [项目名称]
## 1. 架构与技术栈（AI 需要知道的"大图"）
- 语言: TypeScript 5.x
- 前端: React 18 + Next.js 14
- 后端: Node.js 20 + Express
- 数据库: PostgreSQL 16 + Prisma
- 测试: Vitest + Playwright
## 2. 常用命令（AI 执行操作的基础）
- `npm install` # 安装依赖
- `npm run dev` # 启动开发服务器 (端口 3000)
- `npm test` # 运行所有测试
- `npm run test -- -t "auth"` # 按名称筛选
- `npm run lint` # ESLint 检查
- `npm run build` # 生产构建
- `npx prisma generate` # 更新 Prisma 客户端
## 3. 架构约定（AI 容易搞错的地方）
- 路由在 src/app/api/ 下，不是 src/routes/
- 错误格式: { code: string, message: string, data?: any }
- 数据库迁移用 Prisma Migrate，不要手动改 SQL
- 所有 API 返回用 Response 包装类，不要直接返回裸对象
## 4. 编码规范（AI 写代码时遵守）
- 组件: 函数式 + Hooks，不要用 Class 组件
- 命名: 变量 camelCase，组件 PascalCase，常量 UPPER_SNAKE
- 导入顺序: React → 第三方库 → 本地模块
- 每个文件只 export 一个主要实体
## 5. 约束与禁忌（这个项目绝对不能做的事）
- 不要直接操作 DOM（用 React 状态管理）
- 不要在浏览器端存储密钥（用服务器环境变量）
- 不要引入新的外部依赖，除非先在 CLAUDE.md 中批准各部分详解
| 部分 | AI 最需要什么 | 反面例子 |
|---|---|---|
| 架构与技术栈 | 明确的技术选型，避免 AI 想当然 | ❌ "我们用 Node.js" → ✅ "Node.js 20 + Express 4.19，TypeScript strict 模式" |
| 常用命令 | 精确到参数的完整命令 | ❌ "用 npm 跑测试" → ✅ "npm test -- --coverage --reporter=verbose" |
| 架构约定 | 非标准的目录结构、非默认的命名习惯 | ❌ "路由在特定目录" → ✅ "路由在 src/app/api/[resource]/ 下" |
| 编码规范 | AI 容易违背的点（因为它学的是"主流写法"） | ❌ "写干净代码" → ✅ "返回值用 { ok, data, error } 三元组" |
| 约束与禁忌 | 客观上绝对正确的约束 | ❌ "性能很重要" → ✅ "不在循环内创建 Prisma client 实例" |
四、十条编写铁律
铁律 1：写 AI 容易搞错的事，不要写常识
markdown
# ❌ 浪费 Token
"使用 const 而不是 var"
"函数命名要清晰"
# ✅ 有价值
"配置文件不是 config.json，是 config.yaml"
"我们的日志库不是 console.log，是 pino"
"路由必须手动在 index.ts 中注册，不会自动发现"铁律 2：命令要精确到参数
markdown
# ❌ 模糊
`npm test` 运行测试
# ✅ 精确
`npm test -- --run --reporter=verbose --testPathPattern='src/__tests__/'`铁律 3：技术栈版本号要写死
markdown
# ❌
使用 React 和 TypeScript
# ✅
React 18.3 + TypeScript 5.5 + Next.js 14.2AI 会假设"最新版本"，但你的项目可能还在用旧版。版本号错了，AI 可能建议不兼容的 API。
铁律 4：目录结构要写明"例外"而非"常规"
markdown
# ❌ 列常规目录（AI 也能猜到）
src/
components/
utils/
pages/
# ✅ 列出 AI 猜不到的
- 共享类型定义在 shared/types/ 下，不在 src/types/
- 数据库 schema 文件: prisma/schema.prisma（不是 src/db/schema.ts）
- API 中间件在 middleware/ 目录，不在 src/middleware/铁律 5：约束要客观，不要主观
markdown
# ❌ 主观（AI 不知道怎么判断）
"函数要短"
"命名要有意义"
# ✅ 可量化
"单个函数不超过 30 行，超过则拆分为子函数"
"布尔变量用 is/has/should 前缀"铁律 6：区分"团队规范"和"项目事实"
markdown
## 团队规范（style guide，AI 遵守）
- 使用 ESLint + Prettier
- 导入顺序: React → 库 → 本地
## 项目事实（告诉 AI 这是什么，不要改）
- 后端是用 Go 写的，不会改架构
- 数据库是 PostgreSQL，不考虑换 MySQL
- 部署在 Vercel，构建命令是 `vercel build`铁律 7：写清楚"这个项目不做什么"
明确告诉 AI 的边界，比告诉它"要做什么"更节省 Token：
markdown
# 本项目不做的事
- 不使用 Docker（本地开发用 pnpm + Node 本地运行）
- 不使用 Serverless 函数（全是长驻进程）
- 不用 CSS-in-JS（统一用 CSS Modules）铁律 8：对低延时/量化系统，把延迟预算写进去
markdown
# 延迟预算
- 端到端延迟目标: < 5ms (P99)
- 关键路径: 行情解析 → 策略决策 → 订单生成
- 允许的最大 gc pause: < 100µs
- 不允许在热路径上分配堆内存这样 AI 在建议方案时会自动过滤不符合延迟要求的选项。
铁律 9：用"不要..."比"要..."更有效
AI 在"要不要做某事"上的判断不如"绝对不能做某事"准确：
markdown
# ❌ 弱约束
"优先使用 fetch 而不是 axios"
# ✅ 强约束
"不要引入 axios，所有 HTTP 请求必须用 fetch"铁律 10：定期由 AI 帮你更新
bash
# 项目改动后，让 AI 帮你更新 CLAUDE.md
claude "根据最近的代码变更，帮我更新 CLAUDE.md"
# 或者给 AI 一个更新清单
claude "检查 CLAUDE.md，确保所有命令和新包的版本号是最新的"五、不同项目类型的 CLAUDE.md 示例
5.1 标准 Web 项目
markdown
# My SaaS App
## 技术栈
- 前端: React 18.3 + TypeScript 5.5 + Vite 5
- 后端: Node.js 20 + Fastify 4 + Prisma 5
- 数据库: PostgreSQL 16
- 测试: Vitest + Playwright
## 命令
npm install && npm run dev
npm test && npm run lint
## 约定
- API 路由: src/api/[resource]/
- 所有 API 返回 { ok, data?, error? }
- 状态管理用 Zustand，不用 Redux
- 不要手动写 SQL5.2 C/C++ 低延时项目
markdown
# Performance Profile Knowledge Base
## 架构
- 这是一个中文技术文档仓库
- 五层知识金字塔: L1 工具 → L5 二进制
- PlantUML 图 + 表格 + 一句话总结
## 命令
make # 构建 cpu_demo
make run # 构建并运行
make release # -O2 构建
make clean
## 约定
- 文档语言: 中文
- PlantUML 图要适配手机宽度
- 所有链接用相对路径
- 不引入新依赖5.3 monorepo 项目
markdown
# Monorepo
## 目录
packages/
shared/ # 共享类型和工具库
web/ # 前端 (Next.js)
server/ # 后端 (Express)
worker/ # 后台 worker (BullMQ)
## 关键命令
pnpm install # 安装全部依赖
pnpm --filter web dev # 只启动前端
pnpm --filter server test # 只测后端
## 约定
- 跨包引用用 @org/package-name
- 共享类型在 packages/shared/src/types/
- 修改 shared 后要跑 pnpm build六、常见问题
| 问题 | 答案 |
|---|---|
| CLAUDE.md 越长越好吗？ | 不是。50-200 行最佳。超过 500 行建议拆分到 .claude/rules/。 |
| CLAUDE.md 要放进 Git 吗？ | 必须放进 Git，这是团队共享的基础设施。 |
| 多个 CLAUDE.md 冲突怎么办？ | 优先级：企业策略 > 项目共享规则 > 项目根 CLAUDE.md > 个人全局 |
| 改了 CLAUDE.md 要重启吗？ | 不需要。下次 /compact 或新会话自动生效。 |
| Skill 和 CLAUDE.md 的区别？ | CLAUDE.md 常驻（每次对话都知道），Skill 按需加载（用到才读）。高频信息放 CLAUDE.md，低频长流程放 Skill。 |
| .cursorrules 能当 CLAUDE.md 用吗？ | 能，结构完全一致。如果同时用 Claude Code 和 Cursor，保持两个文件同步即可。 |
七、进阶：拆分到 Rules 目录
当 CLAUDE.md 超过 300 行时，用 Rules 目录拆分维护：
项目根/
├── CLAUDE.md # 核心规范（50-200 行）
└── .codebuddy/rules/
├── coding-style.md # 编码规范
├── test-conventions.md # 测试约定
├── git-workflow.md # Git 工作流
└── architecture.md # 架构设计CLAUDE.md 只保留最核心的内容 + 各 Rules 的索引：
markdown
# 编码规范 → .codebuddy/rules/coding-style.md
# 测试约定 → .codebuddy/rules/test-conventions.md
# Git 工作流 → .codebuddy/rules/git-workflow.md八、和本仓库其他文档的关系
| 文档 | 内容 | 与本文的关系 |
|---|---|---|
| AI 编程工具总纲 | 工具选型矩阵 | CLAUDE.md 是所有工具共通的基础设施 |
| Agent vs Skill 解析 | CLAUDE.md vs Skill vs Agent 的定位差异 | 本文是那篇的延伸——专攻 CLAUDE.md 写法 |
| Prompt 工程指南 | 单次对话的提示词技巧 | CLAUDE.md 是"持久化 prompt"，一写一读，两种互补 |
| Claude Code CLI 教程 §五 | /init 命令和 CLAUDE.md 创建流程 | 本文是"怎么写"，那里是"怎么操作" |
一句话总结
CLAUDE.md 是你写给 AI 的"入职培训手册"：告诉它项目技术栈（避免瞎猜）、常用命令（避免跑错）、架构约定（避免放错文件）、编码禁忌（避免踩坑）——写得好的 CLAUDE.md 不是越长越好，而是 AI 最容易搞错的事情用最精确的语言说清楚。