Cursor .cursorrules 提示词工程完全指南：2026规则配置教程

TL;DR

如果你的 Cursor AI 每次生成的代码都需要你手动修改，问题不在模型，而在你的规则文件。一个好的 .cursorrules 可以把你的"修改/接受"比例从 3:1 降到接近 1:1。我在 React、Python 和 Go 项目上迭代 Cursor 规则已有 8 个月，这份指南涵盖了我验证过的有效方法、常见陷阱，以及我实际使用的模板。

本教程是 Cursor 知识库 的一部分。如果你刚接触 Cursor，建议先阅读 Cursor FAQ 和完整安装配置指南。

.cursorrules 到底是什么

.cursorrules 是项目根目录下的一个 Markdown 文件。Cursor 在每次 AI 交互时都会读取它，并将其内容附加到模型的系统提示词前面。可以把它理解为一个持久化的指令层，位于你的查询和模型之间。

这个文件适用于所有 Cursor AI 模式：Inline（Ctrl+K）、Chat、Composer 和 Agent。Agent 模式是规则发挥最大作用的地方，因为模型有权创建文件、运行终端命令和执行多步操作。没有规则约束的情况下，Agent 模式很容易陷入过度工程化。

.cursorrules 文件可以包含项目规范、代码风格偏好、架构约束、技术栈详情以及针对 AI 的行为指令。模型会将其视为权威上下文：除非你明确在提示词中推翻某条规则，否则它会严格遵守。

为什么默认行为不够好

Cursor 自带的默认设置是合理的，但它们太通用了。模型不知道你团队的命名规范、你偏好的错误处理模式，也不知道你是否使用 TypeScript 严格模式。当它猜测时，猜错的频率足以拖慢你的进度。

以下是一个典型的 React 项目在没有好规则时会发生的情况：

• AI 从一个不存在的 barrel export 中导入 useState
• 它生成 40 行的组件，但你的团队约定是 80 行才拆分
• 它使用 any 而非正确的 TypeScript 类型，因为它不知道你的 zod schema 存在
• 它写内联样式，因为它不知道你用的是 Tailwind v4
• 它创建已经存在于 @/lib/ 中的新工具函数

每一项都会浪费你一轮修改。有了好的规则，大部分问题都不复存在。

真正有用的规则分类

在测试了几十种规则配置后，我发现规则分为四个影响层级。把精力集中在前面两类。

第一层：高影响规则（必须包含）

技术栈和版本：明确告诉 Cursor 你在用什么，包括版本号。我们使用 Next.js 15，App Router。所有新页面放在 app/ 目录。默认使用 React Server Components。仅在必要时添加 'use client'。

这一条规则消除了我 80% 的"架构错误"生成。没有它，Cursor 在 App Router 项目上大约有一半时间会生成 pages/ 目录的代码。

代码风格和格式：使用单引号。不使用分号。两空格缩进。优先使用箭头函数而非函数声明。默认使用 const，仅在需要重新赋值时使用 let。

模型一旦被告知就会严格遵守。如果你的团队使用 Prettier 或 Biome，也提一下，AI 会对齐其输出。

导入约定：从 @/components/ 导入共享 UI，从 @/lib/ 导入工具函数，从 @/hooks/ 导入自定义 hooks。绝不使用超过两层的相对导入。不要对组件使用 barrel export（index.ts）。

导入混乱是我过去在 AI 生成代码中最常修复的问题。这条规则直接解决了它。

错误处理模式：在异步函数中使用 try/catch。抛出类型化错误，绝不抛出字符串。在 API 路由中，返回 NextResponse.json({ error: message }, { status: code })。

第二层：中等影响规则（针对你的技术栈添加）

TypeScript 严格度：使用严格 TypeScript。不使用 any。优先使用 unknown 而非 any。在 @/types/ 中定义类型。在 API 边界使用 zod 进行运行时验证。

测试偏好：使用 Vitest。测试文件放在被测试文件旁边的 __tests__/ 目录中。测试文件命名为 *.test.ts。使用 describe/it 块。优先使用命中真实 API 的集成测试，而非全部 mock。

组件模式：使用函数式组件。Props 放在同目录下的 types.ts 文件中。使用组合而非 prop drilling。将可复用逻辑提取为 @/hooks/ 中的自定义 hooks。

文件命名：文件和目录使用 kebab-case。组件使用 PascalCase 文件名。工具函数文件使用 camelCase。

第三层：锦上添花规则（打磨用）

提交风格：遵循 conventional commits：feat:、fix:、chore:、refactor:、docs:。保持提交原子化：一次提交只做一件事。

文档：为公共 API 函数添加 JSDoc 注释。包含 @param 和 @returns 标签。不需要为显而易见的内部辅助函数写文档。

性能注意事项：避免不必要的重渲染。仅在实测必要时使用 useMemo 和 useCallback。优先使用 Server Components 获取数据。

第四层：应该避免的规则

有些规则会适得其反。以下是我学会删掉的：

• 过于具体的架构规则："始终使用依赖注入的仓库模式"会让 Cursor 在生成简单 Landing Page 组件时困惑。将架构规则限制在相关目录范围内。
• 相互矛盾的指令："优先函数式风格"和"对有状态服务使用类"同时出现在文件中，会导致模型在两种方法之间不可预测地切换。
• 模型已经知道的事情：你不需要写"使用现代 JavaScript 语法"或"写干净的代码"。这些是噪音。
• 长篇大论：在约 500 token 的密集指令之后，模型开始略读。使用要点和短声明句。

模板：我实际使用的 .cursorrules 文件

以下是我在新项目中直接使用的模板。它涵盖了我最常用的 Next.js + TypeScript Web 开发场景。请根据你的框架调整技术栈相关部分。

# Cursor Rules

## Stack
- Next.js 15 (App Router)
- TypeScript 5.x, strict mode
- Tailwind CSS v4
- Prisma for database
- Zod for validation
- Vitest for testing

## Code Style
- Single quotes, no semicolons, 2-space indent
- const by default, let only for reassignment
- Arrow functions preferred
- No any; use unknown if type is genuinely uncertain

## Architecture
- app/ for routes, components/ for shared UI, lib/ for utilities
- React Server Components by default
- Add 'use client' only when using hooks or event handlers
- Data fetching in server components; use server actions for mutations

## Imports
- @/components/*, @/lib/*, @/hooks/*, @/types/*
- No relative imports beyond ../../
- Do not use barrel exports for components

## Components
- One component per file
- Props interface in the same file
- Composable over prop drilling; extract to custom hooks in @/hooks/
- kebab-case filenames, PascalCase component names

## Error Handling
- try/catch for all async operations
- Throw typed Error subclasses
- API routes: return NextResponse.json({ error: string }, { status: number })
- Log errors to console.error, do not expose stack traces to the client

## Testing
- Vitest, __tests__/ directory next to the tested file
- *.test.ts naming
- Integration tests preferred over unit tests
- Test real behavior, not implementation details

## Git
- Conventional commits: feat:, fix:, chore:, refactor:, docs:, test:
- Atomic commits: one change per commit
- Good commit messages explain why, not what

这个文件大约 1200 个字符。这恰到好处地适合模型的注意力窗口，不会挤掉其他上下文。如果你的文件超过 2500 字符，先删第三层规则。

规则如何与 Cursor 各模式交互

不同的 Cursor 模式对规则的遵循程度不同。

Inline（Ctrl+K）：规则会生效但影响最小。Inline 模式的上下文窗口更短，通常优先考虑周围代码而非规则文件。如果你发现 Inline 编辑忽略你的风格规则，改用 Chat 模式。

Chat（Ctrl+L）：规则被一致遵循。Chat 拥有完整的上下文窗口，模型会在每次回应前仔细读取规则文件。这是规则对代码质量影响最明显的模式。

Composer（Ctrl+I）：规则同时应用于计划和生成的代码。如果你的规则说"优先使用 server components"，Composer 会围绕此构建计划。生成的 diff 会遵循你的风格规则。这是规则最节省时间的模式，因为一个 Composer 会话可能生成几十个文件，你不想在每个文件中都手动格式化。

Agent 模式：规则在此至关重要。Agent 模式可以创建文件、运行 shell 命令、安装包和执行多步修改。没有规则时，它可能随意安装你不需要的库，在错误目录创建文件，随心所欲地格式化代码。有了好的规则，Agent 模式就变成了一个可靠的初级开发者，而不是一个失控的家伙。

我注意到一个怪癖：Agent 模式在非常长的会话中（超过 50 轮）有时会忽略规则。我怀疑是上下文窗口压力把规则挤出了。发生这种情况时，重启会话而不是跟模型争论。

高级：使用 @-mentions 定义条件规则

Cursor 支持在 .cursorrules 中使用 @file 和 @directory 引用。你可以将规则限定在代码库的特定部分：

@file src/app/api/**/*.ts:
- Validate all request bodies with zod before processing
- Return consistent error shapes: { error: string, details?: unknown }
- Include request IDs for debugging

@file src/components/**/*.tsx:
- Use Tailwind classes only; no inline styles
- Export named, not default
- Include Storybook stories in *.stories.tsx sibling files

@file 指令告诉 Cursor，这些规则只在 AI 处理匹配该 glob 模式的文件时激活。这样在你编辑按钮组件时，API 验证规则就不会污染上下文。

@directory 变体的工作方式相同，但适用于该目录树中的所有内容。

我很少使用条件规则，因为它们增加了复杂性。从一个平面的规则文件开始。仅在你有真正不适用于其他地方的领域特定约定时，才添加 @file 作用域。

测试你的规则：决定性的迭代过程

你不可能第一次就写出完美的规则。以下是我的迭代流程：

1. 写初始规则文件。保持简短：800-1500 字符。
2. 运行测试提示词。让 Cursor Composer 为你的项目添加一个功能。观察它生成了什么。
3. 记录你对生成代码的每一次修改。统计你接受前应用的修复次数。
4. 对每一次修复，问自己：有没有规则可以防止这个？如果有，添加规则。如果修复是"AI 添加了我没要求的功能"，不要加规则：那是提示词问题，不是规则问题。
5. 重复步骤 2-4 三次。到第三轮时，你的规则文件应该趋于稳定。

以下是我一个项目的真实案例。第一轮：AI 生成了 12 个文件。我做了 8 处修复：3 处导入风格修复，2 处类型注解修复，1 处架构修复（pages/ 而非 app/），1 处命名修复，以及 1 处缺少错误处理。我添加了导入、类型、架构和错误的规则。第二轮：4 处修复。添加了命名和子目录约定的规则。第三轮：1 处修复（AI 直接使用了 fetch 而非我们的 API 客户端，我之前忘了在规则中记录）。三轮之后，规则文件稳定下来了。

常见错误

厨房水槽问题。新用户常常从博客文章复制一个 5000 字符的规则文件，丢进去，然后困惑为什么 Cursor 忽略了一半。模型的注意力预算有限。保持规则文件在 2500 字符以内。如果你有更多规范，放在 CONTRIBUTING.md 中，并从 .cursorrules 中引用。

规则重复 ESLint/Prettier。Cursor 的 AI 在输出代码前不会运行你的 linter。"无未使用变量"或"props 字母排序"这类规则，交由 lint-staged 强制执行比由 AI 执行更好。让 linter 处理语法层面的规则；使用 .cursorrules 处理 linter 无法检查的语义层面指导（架构、命名、模式）。

规则文件内部的风格不一致。如果你的规则说"kebab-case 命名文件"，但你把文件命名为 .cursorrules（带点前缀），模型会注意到这种不一致。系统提示词中的细节很重要。

技术栈变化时没有更新规则。我把一个项目从 Next.js 14 迁移到 15，但忘记更新规则文件。整整一周，Cursor 在我的 app/ 目录项目中不断生成 pages/ 目录的代码。每次更改框架、主版本或架构模式时，都要更新规则文件。

.cursorrules vs Cursor Settings

Cursor 有一个设置面板，包含 AI 偏好设置（模型选择、上下文长度、特定语言的规则）。不要将它们与 .cursorrules 混淆。

Cursor Settings 是用户级别的：它们适用于你在 Cursor 中打开的所有项目。用于设置你的模型偏好（claude-sonnet-4 vs gpt-5）和全局代码风格默认值。

.cursorrules 是项目级别的：它们仅适用于包含该文件的项目。用于设置项目特定规范：技术栈、架构、团队约定、目录结构。

两者都会被 AI 读取，但 .cursorrules 在冲突时优先级更高，因为它更具体。

设置面板还有一个按语言的"Rules for AI"部分。这是中间层：全局应用但按文件扩展名限定范围。我很少使用它们，因为在两个地方维护规则会让调试变得混乱。我倾向把所有内容放在 .cursorrules 中，只在设置面板中做模型选择。

.cursorrules 与 CLAUDE.md 的关系

如果你同时使用 Claude Code 和 Cursor，可能既有 .cursorrules 又有 CLAUDE.md 文件。它们用途相同（系统指令），但服务于不同工具。Claude Code 读取 CLAUDE.md；Cursor 读取 .cursorrules。

如果你需要维护两者，保持架构规则（技术栈、目录结构）同步，但工具特定指令要分开。例如，CLAUDE.md 可能包含 使用 Claude Code 的 /init 来引导新文件，而 .cursorrules 写的是 使用 Cursor Composer 进行多文件重构。

一个实用的方法：维护一个权威规则文件（我使用 CLAUDE.md，因为我用 Claude Code 更多），并在 .cursorrules 顶部添加注释：详细约定见 CLAUDE.md。本文件包含 Cursor 特有的覆盖项。

什么时候规则不是答案

如果你发现自己在为 AI 根本不应该做的事情添加规则，你可能遇到了工作流程问题，而非规则问题。

问题不在规则的迹象：

• AI 生成了你没要求的完整功能：你的提示词太模糊
• AI 使用已废弃的 API：你的规则列出了技术栈但没写版本号
• AI 写出了正确但测试失败的代码：你的测试描述不够清晰
• AI 持续忽略你的规则：你的规则文件可能超出了上下文预算

从好的提示词开始，然后添加规则来收紧护栏。规则是细化层，不是清晰指令的替代品。

最终规则组合（快速上手）

如果你想复制粘贴一个极简、经过实战检验的规则文件，以下是：

# Cursor Rules
- Stack: [你的框架 + 版本]
- Use [你的风格规范] (single quotes, 2-space, no semicolons)
- const > let, arrow functions preferred
- Imports: [你的别名模式]
- No any; use unknown when uncertain
- try/catch for async; typed errors only
- Tests: [你的测试框架], __tests__/ directory, *.test.* naming
- Conventional commits: feat:, fix:, chore:, refactor:, docs:, test:
- Do not over-engineer. Write the simplest solution first.

将方括号替换为你的实际值。最后一行关于简单的规则，是我从未后悔添加的一条。

相关教程：

• Cursor Hub：AI 代码编辑器完整知识库
• Cursor AI 编码工作流：Plan、Delegate、Review 完整指南
• Cursor FAQ：15 个常见问题解答（2026）
• Cursor 2.0 完整指南：Composer 2 安装、定价与性能