DevTk.AI
English
CursorClaude CodeAI 编程开发工具编程规则提效

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

手把手教你写 .cursorrules、CLAUDE.md、.windsurfrules——让 Cursor、Claude Code、Copilot 生成的代码完全符合你的项目规范。含 6 套开箱即用模板，一键复制。

DevTk.AI 2026-02-19

如果你已经在用 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% 相同但文件名不同的规则文件是一件痛苦的事。

我们的 AI 编程规则生成器 可以一次性解决这个问题：你只需要定义一次项目的技术栈、编码规范和约定，然后一键导出所有格式——.cursorrules、CLAUDE.md、.windsurfrules 和 .github/copilot-instructions.md。

如果你主要使用 Cursor 并且需要更细粒度的配置（比如目录级规则和 glob 模式匹配），可以使用 Cursor Rules 生成器，它针对 Cursor 的特有功能做了专门优化。

国内开发者的选择建议

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

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

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

总结

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

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