CLAUDE.md / .cursor/rules——项目规则文件写法与实战

每次跟 AI 开新对话，第一件事就是把项目背景再交代一遍：用的是 TypeScript、不要写 any、数据库操作必须走 Repository 层、测试用 Vitest 不用 Jest……说了一遍又一遍，烦不烦？

这就是 规则文件要解决的问题。把这些约定一次性写进文件，AI 每次启动都能读到，你就再也不用重复交代了。

Claude Code 用的是 CLAUDE.md，Cursor 用的是 .cursor/rules（或者 .cursorrules），两个工具各有各的格式和生效方式，但背后逻辑是一样的：把项目的「人格」存下来。

---

这两个文件各是什么、放哪、怎么生效

CLAUDE.md

这是 Claude Code 的项目记忆文件。Claude Code 每次在某个目录里启动，会自动搜索并读取当前目录及其父目录下的 CLAUDE.md，把内容注入到系统提示里。

存放位置：

• 项目根目录：your-project/CLAUDE.md — 对整个项目生效，团队共享（建议纳入 git）
• 子目录：your-project/frontend/CLAUDE.md — 只对 frontend/ 下的操作生效，适合 monorepo
• 用户全局：~/.claude/CLAUDE.md（macOS/Linux）或 %USERPROFILE%\.claude\CLAUDE.md（Windows） — 对你所有项目生效

生效机制：Claude Code 启动时从当前目录往上逐层找 CLAUDE.md，找到的都会读，越靠近项目的越靠后注入（优先级越高）。你不需要做任何额外配置，放在那里它就读。

.cursor/rules

这是 Cursor 的规则文件。Cursor 在打开项目时自动加载 .cursor/rules/ 目录下的所有 .mdc 文件，或者项目根目录下的 .cursorrules 文件（旧格式，仍然支持）。

存放位置：

• 新格式：.cursor/rules/your-rule-name.mdc（推荐，可以拆成多个文件按功能分组）
• 旧格式：.cursorrules（项目根目录，一个文件写完）

生效机制：Cursor 打开项目后自动读取，每次 AI 对话时都会把规则内容带上。.mdc 格式支持设置"只在某类文件触发"（通过 glob 匹配），比如 *.vue 文件才触发 Vue 相关规则。

两者共同点：都是 Markdown 格式，AI 直接读文本内容，不需要特殊编译。改了文件，下次启动或新建对话就生效。

---

该写什么、不该写什么

该写进去的

1. 技术栈声明 语言版本、框架、测试框架、CSS 方案、状态管理——让 AI 一上来就知道生成的代码该对准哪个靶。

2. 代码风格约定 缩进、命名规范（camelCase vs snake_case）、注释语言（全中文 / 全英文 / 混合）、禁止使用的语法（比如"不用 var"、"不写 any"）。

3. 架构约定和禁区 "数据库操作只走 Repository 层"、"不要在组件里直接调 API"、"新增路由必须写对应单测"——这类约定 AI 不知道就容易打破，但你不想在每次对话里解释。

4. 常用指令和流程 "跑测试用 pnpm test"、"构建命令是 pnpm build:prod"、"提交前必须过 lint"——让 AI 知道你的项目用什么命令，省得它猜错。

5. 项目结构说明 简短描述目录布局，比如"业务逻辑在 src/domain/，纯工具函数在 src/utils/"。复杂项目特别有用。

6. 沟通偏好 "回复用中文"、"解释不超过 3 句话，直接给代码"、"每次改完给我一个 diff 摘要"。

不该写进去的

版本号（除非真的需要精确约束）："React 18.2.0"会随着升级失效，写"React 18+"或者根本不写版本号。

临时约定：某次 sprint 的特殊限制、当天有效的 hotfix 方向——这些写进去会让规则越来越脏。

太啰嗦的背景故事：前因后果、历史沿革写了 AI 也不会用，500 字以内的规则比 2000 字的更有效。

别人工具的规则：CLAUDE.md 不需要管 Cursor 的配置，反之亦然，别混在一起。

---

可抄实例

CLAUDE.md 实例

# 项目说明

这是一个 B 端 SaaS 后台，Node.js 后端 + React 前端，monorepo 结构。

## 技术栈

- 后端：Node.js + Hono + Prisma + PostgreSQL
- 前端：React + TypeScript + Vite + Tailwind CSS
- 测试：Vitest（单测）+ Playwright（E2E）
- 包管理：pnpm workspace

## 代码约定

- TypeScript 严格模式，**禁止** `any`，实在需要用 `unknown` + 类型守卫
- 命名：文件名 kebab-case，组件 PascalCase，函数/变量 camelCase
- 注释和 commit 信息统一用中文
- 数据库操作只走 `src/repositories/`，禁止在 service 层直接用 Prisma Client

## 目录结构

- `packages/api/` — 后端服务
- `packages/web/` — 前端应用
- `packages/shared/` — 前后端共享类型和工具

## 常用命令

- 启动开发：`pnpm dev`
- 跑全量测试：`pnpm test`
- 构建生产包：`pnpm build`
- 数据库迁移：`pnpm prisma migrate dev`

## 沟通方式

- 回复用中文
- 改代码时先说改了什么再给代码，别只丢一大段代码
- 涉及数据库 schema 变更时，提醒我一定要写迁移文件

.cursor/rules 实例（新格式 .cursor/rules/main.mdc）

---
description: 主项目规则
globs: ["**/*.ts", "**/*.tsx"]
---

# 项目规则

## 技术栈

React + TypeScript + Vite + Tailwind CSS。测试用 Vitest。

## 代码风格

- 严格 TypeScript，不写 `any`
- 组件用函数式，不写 class component
- 状态管理用 Zustand，禁止在组件里用 `useState` 管理跨组件共享状态
- CSS 只用 Tailwind，不写内联 style，不新增 .css 文件

## 文件约定

- 一个组件一个文件，文件名和组件名一致
- 所有 API 请求封装在 `src/api/` 下对应的 module 里，不在组件里直接 fetch
- 类型定义集中在 `src/types/`

## 响应格式

- 中文回复
- 修改多个文件时列出改动文件清单再给代码

---

和 AGENTS.md 的分工

如果你还不熟悉 AGENTS.md，先看 4.1 AGENTS.md 跨工具配置标准。简单说：

文件	适用工具	定位
AGENTS.md	所有支持它的 AI 工具	跨工具通用规范，放项目级共识，比如架构原则、接口约定
CLAUDE.md	仅 Claude Code	Claude Code 专属配置，命令别名、Claude 特有的工作流
.cursor/rules	仅 Cursor	Cursor 专属配置，glob 触发、Cursor 特有的提示习惯

实际项目的做法：把不依赖工具的约定（技术栈、架构、禁区）放 AGENTS.md，工具专属的配置（命令、响应格式偏好）放各自的文件。这样换工具时，核心约定不用重写，只改工具专属的部分。

---

规则分层：全局 vs 项目

全局规则和项目规则同时生效，项目规则优先级更高。这让你可以把通用偏好（比如"总是用中文回复"、"提交前跑 lint"）放全局，项目特有的约定放项目级。

全局规则文件位置：

• Claude Code：~/.claude/CLAUDE.md
• Cursor：暂无原生全局规则，可以通过 Cursor 的 Settings → Rules for AI 配置

全局规则的内容建议只放与具体项目无关的个人偏好：

# 全局偏好（~/.claude/CLAUDE.md）

- 回复用中文
- 代码注释用中文
- 解释要简洁，先给结论再说原因
- 生成测试时一定要覆盖边界条件和异常路径

不要在全局规则里写技术栈或路径约定，那些是项目级的事。

---

故障排查表

症状	可能原因	解法
规则写了但 AI 没有按规则行事	文件路径不对，AI 没读到	Claude Code：/status 确认读取的 CLAUDE.md 路径；Cursor：重新打开项目或新建对话
AI 生成的代码风格乱，明明规则里写了	规则描述太模糊（"代码要好"），AI 理解偏差	改成可验证的具体约束，比如"禁止使用 var"、"函数名用动词开头"
全局规则和项目规则冲突，AI 行为不稳定	两份规则对同一件事有矛盾指令	项目规则里明确覆写全局规则，比如"本项目注释用英文（覆盖全局中文设置）"
规则文件越来越大，AI 开始忽略部分规则	单个规则文件太长，超过有效注意范围	Cursor 用 .cursor/rules/ 拆成多个 .mdc 文件；CLAUDE.md 精简到 500 字以内核心约束
规则写了技术栈，但 AI 还是生成旧写法	规则是旧版本，项目升级后没同步更新	把"更新 CLAUDE.md"加进 PR checklist，每次升级依赖时顺手更新

---

常见问题

Q：CLAUDE.md 会占用上下文 token 吗？

会。Claude Code 会把 CLAUDE.md 内容注入到每次对话的系统提示里。规则文件越大，每次对话消耗的 token 越多。这就是为什么建议控制在 500 字以内——只放真正高频有用的约定。关于上下文管理的更多细节见 4.3 上下文工程：管 token 防漂移。

Q：.cursorrules（旧格式）和 .cursor/rules/（新格式）哪个更好？

新格式（.cursor/rules/*.mdc）支持 glob 触发，可以针对不同文件类型加载不同规则，更灵活。旧格式更简单，适合小项目一个文件搞定。两种格式可以共存，Cursor 都支持读取，但建议新项目用新格式。

Q：规则文件要加进 git 吗？

CLAUDE.md 和 .cursor/rules/ 都强烈建议加入 git。团队里每个人的 AI 工具能读到一样的约定，就不会出现"你这边 AI 生成的代码风格跟我完全不一样"的情况。个人偏好（比如"回复用中文"）放全局规则，不要提交到项目仓库。

Q：可以在规则文件里引用其他文件吗？

Claude Code 的 CLAUDE.md 支持 @file-path 语法引用其他文件内容，比如 @docs/api-conventions.md。Cursor 的规则文件目前不直接支持引用外部文件。如果约定文档太多，可以在规则里写路径说明，让 AI 自己去读对应文件。

Q：我已经有 AGENTS.md 了，还需要 CLAUDE.md 吗？

取决于你的工作流。如果你只用 Claude Code，AGENTS.md 也够用（Claude Code 能读到它）。但如果有 Claude Code 专属的命令、工作流配置，或者你想精细控制 Claude Code 的行为，CLAUDE.md 更合适——它是 Claude Code 第一级优先读取的文件。参考 上下文是一切：引用规则的底层逻辑 理解为什么规则文件的位置和格式影响 AI 的行为。

---

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。