Cursor Rules 怎么写？.cursorrules + CLAUDE.md 配置指南（附模板）

如果你已经在用 Cursor、Claude Code 或 GitHub Copilot 写代码，你一定遇到过这种情况：AI 生成的代码风格跟项目完全不搭，用了你根本不想用的库，甚至给出了跟项目架构背道而驰的方案。

这不是 AI 不够聪明，而是它根本不知道你的项目长什么样。

AI 编程规则文件 就是解决这个问题的关键。它是一个放在项目根目录的配置文件，告诉 AI 助手：“在这个项目里，我们是这样写代码的。“本文会覆盖所有主流格式，并给出可以直接复制使用的实战示例。

为什么需要 AI 编程规则？

不配置规则的 AI 编程助手，就像一个刚入职但没读过任何项目文档的新同事——能力很强，但写出来的代码总是需要大量修改。

配置规则文件后，你会获得以下收益：

• 代码风格统一 ：命名规范、格式化、import 顺序等全部对齐，不再需要反复纠正 AI
• 框架用法正确 ：告诉 AI 用 Zustand 而不是 Redux，用 React Query 而不是 useEffect 拉数据
• 架构约束生效 ：明确标注”禁止使用 class 组件”、“禁止在 route handler 里写业务逻辑”等红线
• 新人上手更快 ：团队新成员打开 AI 助手就能获得符合项目规范的代码建议
• Code Review 效率提升 ：AI 生成的代码已经遵循规范，评审时需要修改的地方更少

简单来说，规则文件是一份「人和 AI 都能读懂的编码规范」。

四大主流规则文件格式一览

目前每个主要的 AI 编程工具都支持项目级配置，但文件名和位置各不相同。

.cursorrules（Cursor IDE）

文件位置： 项目根目录下的 .cursorrules

Cursor 是目前国内开发者使用最多的 AI IDE，在 2025-2026 年迅速崛起。它会自动读取项目根目录的 .cursorrules 文件，将内容作为系统级上下文注入所有 AI 对话。

# 项目：电商管理后台


# 技术栈：React 18 + TypeScript 5 + Tailwind CSS




## 代码规范


- 只使用函数式组件和 Hooks


- 优先使用 named export，避免 default export


- 使用 cn() 工具函数做条件类名拼接

Cursor 还支持 .cursor/rules/ 目录，可以按文件路径匹配创建模块化规则。比如 backend.mdc 只对后端代码生效， components.mdc 只对组件代码生效。这个目录级规则功能在处理 monorepo 项目时特别有用。

CLAUDE.md（Claude Code CLI）

文件位置： 项目根目录下的 CLAUDE.md （也支持 ~/.claude/CLAUDE.md 全局规则）

Claude Code 是 Anthropic 官方推出的 CLI 编程 Agent，它在启动时自动读取 CLAUDE.md 。这个文件使用标准 Markdown 格式。

# 项目概述


Python 3.12 + FastAPI 后端 API 服务




## 开发命令


-
 `make dev`
 -- 启动开发服务器


-
 `make test`
 -- 运行 pytest 测试


-
 `make lint`
 -- 运行 ruff 检查




## 代码约定


-
 所有函数必须有类型注解


-
 使用 Pydantic 模型定义请求和响应


-
 默认使用 async 处理函数

CLAUDE.md 和其他规则文件有一个重要区别：Claude Code 是完全的 Agent 工作流——它会自己运行命令、编辑文件、管理整个任务。所以在 CLAUDE.md 中加入构建命令、项目结构说明和工作流程描述特别重要。

另一个特色是层级继承：子目录中也可以放 CLAUDE.md ，Claude Code 在处理该目录文件时会自动加载对应的规则。这在大型项目中非常实用。

.windsurfrules（Windsurf / Codeium）

文件位置： 项目根目录下的 .windsurfrules

Windsurf（原 Codeium IDE）读取这个文件来定制 AI 行为。格式和 .cursorrules 类似，支持纯文本或 Markdown。

# Windsurf 规则


- 语言：TypeScript（严格模式）


- 总是用 early return 减少嵌套


- 优先组合而非继承


- 所有公开函数必须写 JSDoc 注释

.github/copilot-instructions.md（GitHub Copilot）

文件位置： .github/copilot-instructions.md

GitHub Copilot 通过这个 Markdown 文件来读取项目级指令，支持 VS Code、JetBrains 等所有集成编辑器。

## 代码风格


-
 使用 ESM import，禁止 CommonJS require()


-
 优先 const，其次 let，禁止 var


-
 使用模板字符串而非字符串拼接




## 测试


-
 使用 Vitest 做单元测试


-
 使用 Testing Library 做组件测试


-
 每个测试至少包含一个正常路径和一个异常路径

规则文件应该写什么？

不管你用哪种格式，一份高质量的规则文件应该包含以下几个板块：

1. 项目身份信息

开门见山地说明语言、框架和主要依赖。这是给 AI 建立上下文最快的方式。

# 技术栈：Next.js 14 + TypeScript + Prisma + PostgreSQL


# 包管理器：pnpm


# Node 版本：20 LTS

2. 代码风格与命名约定

命名规范（camelCase、snake_case、PascalCase）、文件命名模式、import 排序规则。重点写那些 ESLint/Prettier 管不到的约定。

3. 架构模式

组件结构、状态管理方案、数据获取模式、目录组织。告诉 AI 你是「怎么构建」的，而不只是「构建了什么」。

4. 测试要求

用哪个测试框架、覆盖率期望、断言风格、mock 方案。AI 在知道你的测试模式后，生成的测试代码质量会大幅提升。

5. 错误处理策略

用 Result 类型还是 try/catch？日志怎么打？参数验证用什么方案？

6. 禁止事项

明确列出反模式。“禁止使用 any 类型” 比 “请使用合适的类型” 有效得多。否定性规则能最有效地阻止 AI 犯常见错误。

实战示例：React + TypeScript 的 .cursorrules

这是一个可以直接复制到项目中使用的完整示例：

# 项目：SaaS 管理后台


# 技术栈：React 18, TypeScript 5.3, Vite, Tailwind CSS 3, Zustand, React Query




## 代码风格


- 只用函数式组件，禁止 class 组件


- 组件使用 named export：`export function ProductCard() {}`


- 文件命名：组件 PascalCase（ProductCard.tsx），工具函数 camelCase（formatPrice.ts）


- Props 用 interface 定义，联合类型和交叉类型用 type


- 优先使用 early return 减少嵌套层级




## 组件结构


- 一个文件一个组件


- Props interface 紧贴在组件定义上方


- Hooks 放在组件函数体最顶部


- 事件处理函数用 handle 前缀：handleSubmit, handleClick




## 状态管理


- Zustand 管全局状态（stores 放在 src/stores/）


- React Query 管服务端状态（hooks 放在 src/hooks/queries/）


- useState 只用于 UI 局部状态


- 禁止用 useEffect 做数据获取——一律用 React Query




## 样式


- 只用 Tailwind 工具类，禁止 CSS Modules


- 条件类名用 cn()（src/lib/utils）


- 响应式：移动端优先（sm:, md:, lg:）


- 深色模式：使用 dark: 变体




## 测试


- Vitest + React Testing Library


- 测试文件放在组件旁边：Component.test.tsx


- 测试行为而非实现细节


- 用 MSW 模拟 API 请求




## 禁止事项


- 禁止使用 any 类型——用 unknown 然后做类型收窄


- 禁止 barrel export（index.ts 重导出）


- 禁止引入 @mui 或其他 UI 库——我们用 shadcn/ui + Tailwind


- 禁止用 useEffect 计算派生状态——用 useMemo

实战示例：Python + FastAPI 的 CLAUDE.md

# 发票处理 API




## 技术栈


Python 3.12, FastAPI, SQLAlchemy 2.0 (async), PostgreSQL, Alembic, Pydantic v2




## 常用命令


-
 `uv run fastapi dev`
 -- 启动开发服务器（端口 8000）


-
 `uv run pytest`
 -- 运行测试


-
 `uv run ruff check .`
 -- 代码检查


-
 `uv run ruff format .`
 -- 代码格式化


-
 `alembic revision --autogenerate -m "描述"`
 -- 创建迁移


-
 `alembic upgrade head`
 -- 执行迁移




## 项目结构


-
 `app/api/`
 -- 路由处理（每个资源一个文件）


-
 `app/models/`
 -- SQLAlchemy 模型


-
 `app/schemas/`
 -- Pydantic 请求/响应模型


-
 `app/services/`
 -- 业务逻辑层


-
 `app/core/`
 -- 配置、安全、依赖注入




## 开发约定


-
 所有路由处理函数必须是 async


-
 每个函数签名和返回值都要有类型注解


-
 请求体和响应体全部用 Pydantic 模型


-
 路由和数据库之间必须有 Service 层——路由中不写业务逻辑


-
 使用 Depends() 做依赖注入


-
 数据库会话用 async with 上下文管理器




## 错误处理


-
 只在路由处理函数中抛出 HTTPException


-
 Service 层抛出自定义异常（定义在 app/core/exceptions.py）


-
 所有 4xx/5xx 响应统一使用 ErrorResponse schema




## 测试


-
 pytest + pytest-asyncio


-
 使用 tests/factories.py 中的工厂函数创建测试数据


-
 每个测试用独立的数据库事务（测试后回滚）


-
 测试命名：test_<动作>
_<条件>_
<预期结果>




## 禁止事项


-
 禁止使用同步数据库调用


-
 禁止在路由中写业务逻辑


-
 禁止使用 * 导入


-
 禁止提交 .env 文件——用 .env.example 作为模板

写好规则文件的实用技巧

具体，不要抽象

“写干净的代码” 没有任何信息量。“使用 early return 避免超过 3 层的嵌套” 才是 AI 能执行的指令。规则越具体，AI 遵循得越好。

附带代码示例

两行代码示例比一段文字描述传达的信息更多。直接展示你期望的模式：

// 正确 ✓


export function UserCard({ name, email }: UserCardProps) {}




// 错误 ✗


export default function ({ name, email }) {}

大胆写「禁止」

“禁止事项” 部分的效果出奇地好。AI 模型对明确的否定指令反应非常敏感——因为它直接排除了一大类错误答案。

保持更新

规则文件是活文档。当你引入新库或改变技术方案时，在同一个 PR 里更新规则文件。过期的规则比没有规则更糟糕。

从少到多，逐步迭代

先写 10-15 条解决最大痛点的规则。使用一段时间后，针对 AI 反复犯的错误再补充新规则。不要一开始就写一份几百行的规则文件——太长了 AI 反而会忽略重点。

纳入版本控制

规则文件必须提交到 Git 仓库，和代码放在一起。它是项目开发者体验的一部分，应该跟随项目一起演进。

一次编写，导出所有格式

如果你的团队同时有人用 Cursor、有人用 Claude Code、有人用 VS Code + Copilot，维护四份内容 90% 相同但文件名不同的规则文件是一件痛苦的事。

2026 年更稳妥的做法，是把 AGENTS.md 作为唯一的主规则文件，只有在某个客户端支持额外能力时，再补充工具专用文件。你可以先看我们的 AGENTS.md 完整指南 ，先搭好一份同时适用于 Claude Code、Cursor、Copilot 等工具的通用基线。

如果你的工作流还依赖工具调用或结构化输出，再配合 MCP 清单生成器 和 JSON Schema 构建器 一起使用，让助手同时拿到编码规范、工具清单和稳定的输出约束。

国内开发者的选择建议

Cursor 在国内开发者中的普及率非常高，这很大程度上得益于它对 Claude 和 GPT 模型的无缝集成，以及相对便宜的订阅价格。如果你刚开始接触 AI 编程规则，从 .cursorrules 入手是最实际的选择。

如果你在使用 Claude Code（Anthropic 的 CLI 工具）， CLAUDE.md 是更好的起点——它的 Agent 工作流意味着你可以在规则文件中加入更丰富的上下文，比如项目结构、构建命令和部署流程。

不管用哪个工具，核心原则是一样的： 把你脑子里的编码规范写下来，让 AI 也能读到。

总结

AI 编程规则文件是你在 AI 辅助开发工作流中回报率最高的投入之一。一份写得好的规则文件，能把一个通用的 AI 助手变成一个真正理解你项目架构、遵循你编码规范、生成高质量代码的「AI 队友」。

现在就开始：选择你最常用的 AI 编程工具，写下 10 条最重要的规则，提交到仓库。用一周时间观察 AI 的表现，然后根据它犯的错误逐步补充规则。你很快就会发现，没有规则文件的 AI 编程体验，是不可想象的。