.cursorrules 与项目级指令

.cursorrules 与项目级指令

本节摘要:.cursorrules 是 Cursor 的项目规范文件,放在项目根目录,内容会在每次 AI 对话时自动注入模型上下文。它相当于你写给 AI 的「员工手册」:技术栈是什么、代码风格怎么写、哪些事情绝对不能做。本节讲清 .cursorrules 的工作机制、全局 Rules 与项目 Rules 的优先级、文件内容的最佳结构,以及 Windsurf 和 Cline 的等价实现。

一、.cursorrules 的工作机制

原理极简:Cursor 启动对话时,自动读取项目根目录的 .cursorrules 文件,把内容作为「系统指令」注入到模型的第一条消息中。AI 在生成任何回复之前,先「读到」你的规范。

这意味着:

• 你不需要每次对话都重复「我们用 TypeScript + Tailwind」
• 团队所有人共享同一份规范(文件在 Git 里)
• 换一个 AI 模型,规范依然生效(它不依赖特定模型)

文件位置:项目根目录,文件名 .cursorrules(注意前面的点)。

💡 技巧:Cursor 新版还支持 .cursor/rules/ 目录,可以放多个规则文件(如 frontend.md、backend.md、testing.md),按模块组织。但核心机制一样——都会被注入上下文。

二、全局 Rules vs 项目 Rules

Cursor 有两层规范:

优先级:项目 Rules 优先于全局 Rules。如果两者冲突(全局说「用 tabs」,项目说「用 spaces」),AI 会遵守项目级。

⚠️ 注意:全局 Rules 不要写太多——它会影响你所有项目。只放真正跨项目通用的偏好(如语言、回复格式)。技术栈相关的都放项目级。

三、.cursorrules 的最佳结构

一个高质量的 .cursorrules 应该包含以下板块(按需选用):

# 项目规范

## 技术栈
- 后端:FastAPI 0.115 + Python 3.12 + SQLAlchemy 2.0(async)
- 前端:Next.js 14(App Router)+ TypeScript 5 + Tailwind CSS
- 数据库:PostgreSQL 16
- 测试:pytest(后端)+ vitest(前端)

## 代码风格
- Python:遵循 PEP 8,使用 type hints,函数优先于类
- TypeScript:strict 模式,不用 any,接口用 interface 不用 type
- 变量命名:Python 用 snake_case,TS 用 camelCase
- 组件命名:PascalCase,文件名与组件名一致

## 目录结构
- 后端:src/api/(路由) + src/services/(逻辑) + src/models/(数据模型)
- 前端:src/app/(页面) + src/components/(组件) + src/lib/(工具)

## 错误处理
- 后端:统一用 AppError 基类,路由层用 exception_handler 捕获
- 前端:API 错误用自定义 useApiError hook 处理

## 禁止事项
- 不要使用 lodash(用原生方法)
- 不要使用 class 组件
- 不要直接操作 DOM(用 React ref)
- 不要在组件中直接写 SQL
​

写法原则

1. 用祈使句:「使用 XXX」「不要用 YYY」——比「我们建议使用 XXX」更有效
2. 具体可执行:「不用 any」比「写好类型」有效 10 倍
3. 给理由(可选):「不用 lodash(项目已有原生工具函数,避免增加包体积)」
4. 控制长度:500~1500 字。超过 2000 字就该精简了

四、Windsurf 和 Cline 的等价实现

Windsurf:.windsurfrules

机制完全相同——项目根目录放 .windsurfrules 文件,内容格式自由(纯文本/Markdown 都行)。写法跟 .cursorrules 一模一样。

Cline:Custom Instructions

在 Cline 扩展设置中,有一个「Custom Instructions」文本框。把规范写进去,效果等价。

区别:Cline 的指令不在项目目录中(在 VS Code 设置里),不方便 Git 共享。变通方案:把规范写在项目的 docs/ai-instructions.md 中,然后在 Cline 设置中写「请遵循 docs/ai-instructions.md 中的规范」。

Claude Code:CLAUDE.md

Claude Code 使用项目根目录的 CLAUDE.md 文件。格式自由,支持 Markdown。

五、常见误区

误区 1:写得太长(3000+ 字)

• 问题:上下文窗口被规范占太多,实际任务空间不够
• 正解:精简到 1500 字以内;把「示例代码」移到单独文件用 @file 引用

误区 2:写得太模糊

• 问题:「写高质量代码」「遵循最佳实践」——AI 不知道具体指什么
• 正解:「所有 API 返回 {code, data, message} 格式」「错误用 AppError 抛出」

误区 3:互相矛盾

• 问题:一处写「用 Tailwind」,另一处写「样式写在 CSS Modules 中」
• 正解:写完后通读一遍,检查有没有冲突

误区 4:期望 AI 100% 遵守

• 问题:偶尔 AI 还是会「忘记」某条规范
• 正解:规范提高遵守率到 90%+,但不是 100%。关键修改仍需审查。

本节要点回顾

1. 机制:项目根目录的 .cursorrules 内容自动注入每次对话的上下文
2. 两层规范:全局(跨项目偏好)+ 项目(技术栈/风格/结构),项目优先
3. 最佳结构:技术栈 → 代码风格 → 目录结构 → 错误处理 → 禁止事项
4. 写法原则:祈使句、具体可执行、控制 1500 字内
5. 跨工具:.windsurfrules / Cline Custom Instructions / CLAUDE.md 机制相同
6. 不是万能的:提高遵守率到 90%+,但关键修改仍需人工审查

规范文件解决了「AI 知道规矩」的问题。但 AI 还需要「看到材料」——它得了解你项目的具体代码实现。这就是 RAG 和代码库感知要解决的。下一节讲。