1. 项目概述：为AI编码伙伴定制规则

在深度使用Cursor这类AI驱动的代码编辑器一段时间后，我逐渐意识到一个核心问题：默认的AI助手虽然强大，但它的“性格”和“习惯”是通用的。它不知道我个人的编码偏好、项目架构的特定约束，或者团队内部的代码规范。这就导致了一个常见的摩擦点——我需要反复在对话中强调“请使用TypeScript而不是JavaScript”、“函数命名请用驼峰式”、“这个项目里我们不用 any 类型”。每次开始一个新的会话或文件，这些上下文都会丢失，沟通成本无形中增加。

这正是 cedricfressin/cursor.rules 这个项目试图解决的问题。简单来说，它是一个用于Cursor编辑器的规则集配置文件。你可以把它理解为给你的AI编程伙伴（Cursor内置的AI模型）定制的一份“员工手册”或“项目开发规范”。通过编写特定的 .cursorrules 文件，你可以系统地、一劳永逸地告诉AI：在这个项目（或这个目录）里，你应该如何思考、如何编码、以及要避免什么。

这不仅仅是关于代码风格（那可以用Prettier或ESLint解决），更是关于 开发意图、架构决策和上下文约束 的传递。例如，你可以规定：“本项目使用React Server Components，因此请优先考虑在服务端获取数据”、“所有API调用必须封装在 lib/api 目录下的特定钩子中”、“为新功能生成代码时，请同时生成相应的单元测试骨架”。通过这种方式，AI生成的代码从一开始就更贴合你的实际需求，减少了后续人工调整的工作量。

对于任何已经将Cursor作为日常开发助手的开发者——无论是独立开发者还是团队技术负责人——理解和应用 .cursorrules 都是提升效率、保证代码一致性的关键一步。它让AI从一个需要频繁指导的“实习生”，转变为一个深刻理解项目背景的“资深协作者”。

2. .cursorrules 文件的核心机制与语法解析

要有效使用规则，首先需要理解Cursor是如何读取和应用这些规则的。其机制直观且符合开发者习惯：基于文件系统的层级结构。

2.1 规则的加载与作用域

Cursor会从你当前打开的文件所在目录开始，向上逐级查找 .cursorrules 文件，直到找到为止。这意味着你可以为不同的项目、甚至同一个项目下的不同子模块设置不同的规则。

例如，假设你的项目结构如下：

/my-project/
├── .cursorrules          # 项目级通用规则
├── package.json
├── frontend/
│   ├── .cursorrules      # 前端特定规则（覆盖或补充项目级规则）
│   └── src/
│       └── App.tsx
└── backend/
    ├── .cursorrules      # 后端特定规则
    └── api/
        └── index.py

当你在 /my-project/frontend/src/App.tsx 中工作时，Cursor会首先查找该文件所在目录的 .cursorrules ，未找到则向上到 frontend/ 目录，找到并加载 frontend/.cursorrules 。同时，它 可能也会继承或参考 更上级的 /my-project/.cursorrules 中的部分全局设定（具体行为取决于规则定义）。这种设计提供了极大的灵活性，允许你定义全局基准，并在特定领域进行精细化调整。

注意 ：规则的合并与优先级是一个需要留意的细节。目前，Cursor的规则系统更倾向于“就近原则”，即子目录的规则通常会对同类型指令进行覆盖。对于复杂的项目，建议在根目录的规则中定义最基础的、跨领域的约束（如“禁止使用某些不安全函数”），在子目录中定义技术栈相关的具体规则（如“使用React Hooks格式”）。

2.2 规则文件的基本语法

.cursorrules 文件本质上是一个文本文件，其语法设计得非常人性化，类似于自然语言与结构化指令的结合。它主要包含两种类型的指令：

  1. 全局指令 ：通常位于文件顶部，用于设定AI交互的总体基调、角色和目标。它们不针对具体代码生成，而是塑造AI的“思维方式”。
  2. 具体规则 ：用于定义在特定场景下（如创建文件、编写函数、修复错误时）AI应遵循的具体行为。

一个最简单的规则文件可能长这样：

# 这是一个注释，以#开头
AI，你在这个项目中的角色是资深前端架构师。

规则：
- 所有新代码必须使用TypeScript编写。
- 使用函数式组件和React Hooks，避免类组件。
- 使用ESLint和Prettier的默认规则保持代码风格。
- 为复杂的业务逻辑函数编写JSDoc注释。

2.3 核心指令深度解读

让我们拆解几个最常用且强大的指令，理解其背后的设计逻辑和最佳实践。

@role 或 “AI，你的角色是…” 这个指令为AI设定一个身份。这不仅仅是好玩，它深刻地影响了AI生成内容的视角和深度。例如：

  • @role senior backend engineer specializing in scalable microservices （专注于可扩展微服务的高级后端工程师）
  • @role empathetic code reviewer focused on readability and maintainability （专注于可读性和可维护性的共情代码审查员）

设定一个具体的角色，AI会尝试模拟该角色的知识体系和决策过程。一个“系统架构师”可能会更关注模块边界和接口设计，而一个“初级开发者”可能会生成更多带有详细注释和简单逻辑的代码。你应该根据当前任务的核心需求来切换角色。

@goal 或 “这个项目的主要目标是…” 这定义了项目的“北极星指标”。AI会以此为目标来权衡各种技术决策。例如：

  • @goal Build a highly performant, real-time dashboard with minimal bundle size. （构建一个具有最小打包体积的高性能实时仪表盘。）
  • @goal Create a robust and fault-tolerant data processing pipeline. （创建一个健壮且容错的数据处理管道。）

当AI在思考是否引入一个重型库，或者选择哪种状态管理方案时，它会参考这个终极目标。如果目标是“快速原型验证”，它可能会推荐更激进、更便捷的方案；如果目标是“长期可维护的企业级应用”，它则会倾向于更保守、更标准的模式。

@constraints 或 “约束条件包括…” 这是规则文件中最实在的部分，直接定义了“什么不能做”和“必须怎么做”。清晰的约束能极大减少无效输出。约束应尽可能具体、可操作。

  • 技术栈约束 ：

    @constraints
- Language: TypeScript with strict mode enabled.
- UI Framework: React 18+, using Next.js App Router.
- Styling: Tailwind CSS exclusively. Do not use inline styles or other CSS-in-JS libraries.
- State Management: Zustand for global state, React Context for theme/local state only.
- HTTP Client: `axios` for external APIs, `fetch` for internal Next.js API routes.

    这几乎为前端项目定下了完整的技术选型基调，AI不会再去建议使用Redux或Styled-components。

  • 代码质量与安全约束 ：

    @constraints
- Never use `any` type in TypeScript. Prefer `unknown` or proper generics.
- All async operations must have error handling with try-catch or .catch().
- Avoid functions with more than 3 parameters. Use an options object instead.
- Security: Never hardcode API keys or secrets. Reference environment variables.
- Accessibility: All interactive elements must have proper ARIA labels and keyboard navigation.

    这类约束将代码规范和安全意识直接注入到AI的生成过程中。

  • 项目结构约束 ：

    @constraints
- New React components go into `src/components/ui/` for basic UI, `src/components/features/` for business logic.
- API route handlers belong in `app/api/`.
- Utility functions go into `src/lib/`.
- Test files must be colocated with the source file, named `*.test.tsx`.

    这强制保持了项目结构的整洁和一致性，对于团队协作尤为重要。

@examples “少说空话，给我看例子。”这是最有效的沟通方式之一。通过提供正面和反面的代码示例，你可以极其精确地定义你的期望。

@examples
- Good (正确的):
  // 使用具名导出，清晰的类型定义
  interface UserProfile {
    id: string;
    name: string;
  }
  export function formatUserName(user: UserProfile): string {
    return `User: ${user.name}`;
  }

- Bad (错误的):
  // 使用默认导出，类型松散
  export default function format(user) { // 缺少类型注解
    return 'User: ' + user.name; // 潜在的运行时错误
  }

通过对比，AI能迅速理解“好代码”在你项目中的具体标准是什么。你可以为不同的模式（如数据获取、错误处理、组件设计）提供多个示例。

3. 高级规则策略与场景化配置

掌握了基础语法后，我们可以探索更高级的用法，以应对复杂的开发场景。

3.1 多规则文件与上下文继承

在大型单体仓库（Monorepo）或全栈项目中，不同部分的规则差异可能很大。如前所述，你可以利用目录层级的 .cursorrules 文件进行管理。关键在于设计清晰的职责划分：

  • 根目录规则 ( /.cursorrules ) ：定义全仓库通用的元规则。

    # 通用规则：适用于所有子项目
@role senior software engineer
@goal Write clean, maintainable, and well-tested code.
@constraints
- Write meaningful commit messages.
- Prefer descriptive variable names over abbreviations.
- Add comments for non-obvious business logic.

  • 前端子项目规则 ( /frontend/.cursorrules ) ：继承通用目标，但覆盖具体技术栈。

    # 继承根目录目标，但角色和约束特定于前端
@role senior frontend engineer specializing in React and performance
@constraints
- Use TypeScript with strict mode.
- Framework: Next.js 14 with App Router.
- Styling: Tailwind CSS. Avoid `styled-components`.
- Fetching: Use React Server Components and `fetch` by default. For client-side, use TanStack Query.
- New components: Use the `src/components/` structure as per project convention.

  • 后端子项目规则 ( /backend/.cursorrules ) ：完全不同的技术语境。

    # 独立的后端规则
@role backend engineer focused on security and database efficiency
@constraints
- Language: Python 3.11+, using FastAPI.
- Use SQLAlchemy 2.0 ORM with async support.
- All endpoints must have Pydantic request/response models.
- Include comprehensive error handling and logging.
- Write unit tests with `pytest` for all business logic.

这种结构使得AI在 /frontend 目录下聊天或生成代码时，会自动切换到前端工程师的思维模式，而不会提出关于Python或SQLAlchemy的建议。

3.2 动态规则与条件指令

有时，规则需要根据一些条件动态启用。虽然 .cursorrules 原生不支持复杂的逻辑判断，但我们可以通过注释和清晰的描述来实现“软条件”。

@constraints
- When working in `src/components/forms/`:
    - All form components must use React Hook Form for state management.
    - Integrate with Zod for schema validation.
    - Ensure all fields have proper `aria-*` attributes.
- When creating files in `scripts/`:
    - Use Node.js with ES modules (`import/export`).
    - Include a shebang (`#!/usr/bin/env node`) for executable scripts.
- When the task involves "refactor" or "optimize":
    - Prioritize readability over clever one-liners.
    - Before changing, analyze if there are existing unit tests that might break.

通过“When...”这样的描述，你在给AI提供上下文线索。虽然AI可能不会像程序一样精确解析这些条件，但在你明确提及“在 scripts/ 目录下创建一个部署脚本”时，结合文件路径的上下文，AI会倾向于应用与之相关的规则。

3.3 与现有开发工具链集成

.cursorrules 不应与你现有的工具链冲突，而应成为它们的“智能触发器”和“补充说明”。

  • ESLint/Prettier ：规则文件不需要重复定义具体的代码风格（如缩进、引号）。只需告诉AI遵循这些工具即可。

    @constraints
- Code style must comply with the project's ESLint configuration and Prettier setup.
- Run `npm run lint:fix` in your mind before finalizing code.

    这样，AI生成的代码在格式上就会与团队标准保持一致。

  • TypeScript配置 ：强调 tsconfig.json 中的关键设置，尤其是那些AI容易忽略的严格检查。

    @constraints
- Adhere to `strict: true` in tsconfig.json. No implicit `any`.
- Use `satisfies` operator for type assertions where appropriate.

  • 测试框架 ：规定测试模式和位置。

    @constraints
- For new features, include a corresponding test file using Vitest and React Testing Library.
- Follow the Given-When-Then structure for test descriptions.
- Aim for high user-behavior coverage rather than just line coverage.

4. 实战：从零构建一个全栈项目的规则集

让我们通过一个虚构的“任务管理全栈应用”项目，来演示如何一步步构建一个完整、实用的 .cursorrules 配置。假设项目使用Next.js (App Router) + TypeScript + Tailwind CSS + Prisma + PostgreSQL。

4.1 项目根目录规则：奠定基础

首先在项目根目录创建 .cursorrules ，定义跨前后端的通用原则。

# .cursorrules at project root
AI，你在这个项目中的角色是全栈开发专家，精通TypeScript、现代React和数据库设计。你的核心任务是帮助构建一个高效、可靠且易于维护的任务管理应用。

@goal
交付一个功能完整、性能优异、代码清晰且测试覆盖良好的生产级应用。优先考虑用户体验和代码的长期可维护性。

@constraints
- **代码质量**：
    - 始终启用TypeScript严格模式。禁止使用`any`类型。优先使用`unknown`并缩小类型范围。
    - 函数和方法最多接受三个参数。超过三个时，必须使用一个选项对象。
    - 为所有导出的函数、组件和复杂逻辑添加清晰的JSDoc/TSDoc注释。
    - 遵循“单一职责原则”。一个函数/组件只做一件事。

- **安全与最佳实践**：
    - 绝对禁止在代码中硬编码敏感信息（API密钥、数据库URL）。必须从环境变量(`process.env`)中读取。
    - 所有用户输入在用于数据库查询或显示前都必须经过验证或转义。
    - 异步操作必须有错误处理（try-catch或.catch()）。

- **项目一致性**：
    - 严格遵守项目现有的目录结构和命名约定。
    - 在修改任何现有文件前，先理解其上下文和依赖关系。
    - 提交代码前，在思维中运行`npm run lint`和`npm run type-check`。

@examples
- Good (正确的错误处理):
  async function fetchTask(id: string) {
    try {
      const response = await fetch(`/api/tasks/${id}`);
      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`);
      }
      const data: Task = await response.json();
      return data;
    } catch (error) {
      console.error('Failed to fetch task:', error);
      // 返回一个安全的默认值或重新抛出，取决于业务逻辑
      return null;
    }
  }

- Bad (错误的错误处理):
  // 缺少错误处理，可能导致未捕获的Promise拒绝
  const data = await fetch(`/api/tasks/${id}`).then(r => r.json());

4.2 前端规则：细化React与UI规范

在 /app 或 /src 目录下（取决于你的Next.js结构）创建前端专属规则。

# /app/.cursorrules (或 /src/.cursorrules)
AI，你现在专注于前端开发，特别是使用Next.js 14的App Router和React Server Components。

@constraints
- **技术栈**：
    - 使用Next.js 14+的App Router架构。页面放在`app/`目录下，使用`page.tsx`。
    - 使用React Server Components (RSC)作为默认选择。仅在需要`useState`, `useEffect`, `useContext`等客户端特性时使用“use client”指令。
    - 样式使用Tailwind CSS。禁止使用其他CSS-in-JS库或内联style。使用`@apply`提取常用样式。

- **数据获取**：
    - 在Server Components中，直接使用`async/await`和`fetch`。利用Next.js的自动缓存和重复数据删除。
    - 在Client Components中需要数据时，使用TanStack Query (React Query)。不要直接使用`useEffect`进行数据获取。
    - 所有API调用函数应统一放在`lib/api/`目录下。

- **组件设计**：
    - 通用UI组件（按钮、输入框、对话框）放在`components/ui/`下。使用`export function Button() {...}`具名导出。
    - 业务功能组件放在`components/features/`下。
    - 组件Props必须用TypeScript接口或类型严格定义。
    - 优先使用函数式组件和React Hooks。

- **状态管理**：
    - 局部状态用`useState`/`useReducer`。
    - 跨组件共享的UI状态（如主题、侧边栏开关）使用React Context。
    - 需要持久化或复杂的服务端状态使用Zustand。

@examples
- Good (一个Server Component):
  // app/tasks/page.tsx
  import TaskList from '@/components/features/TaskList';
  import { fetchAllTasks } from '@/lib/api/task';

  export default async function TasksPage() {
    // 在服务端直接获取数据
    const tasks = await fetchAllTasks();

    return (
      <div className="container mx-auto p-4">
        <h1 className="text-2xl font-bold mb-4">All Tasks</h1>
        <TaskList initialTasks={tasks} />
      </div>
    );
  }

- Good (一个Client Component with Query):
  // components/features/TaskList.tsx
  'use client';
  import { useQuery } from '@tanstack/react-query';
  import { fetchAllTasks } from '@/lib/api/task';
  import TaskItem from './TaskItem';

  export function TaskList({ initialTasks }: { initialTasks: Task[] }) {
    const { data: tasks } = useQuery({
      queryKey: ['tasks'],
      queryFn: fetchAllTasks,
      initialData: initialTasks, // 使用Server Component传递的初始数据
    });
    return (<div>{tasks?.map(task => <TaskItem key={task.id} task={task} />)}</div>);
  }

4.3 后端API规则：定义数据层与接口规范

在 /app/api 或专门的 /pages/api 目录下创建API规则。

# /app/api/.cursorrules
AI，你现在负责后端API开发，使用Next.js Route Handlers和Prisma ORM。

@constraints
- **API设计**：
    - 遵循RESTful原则。使用恰当的HTTP方法（GET, POST, PUT, PATCH, DELETE）。
    - 所有路由处理器必须放在`app/api/[resource]/route.ts`文件中。
    - 请求和响应体必须使用Zod进行验证，并使用`NextResponse`返回标准化的JSON。

- **数据库与Prisma**：
    - 通过`import { prisma } from '@/lib/prisma'`访问数据库。
    - 所有数据库操作必须包含错误处理。
    - 优先使用Prisma的查询优化（如`select`只取所需字段，使用`include`处理关系）。
    - 对于写操作，考虑使用Prisma事务确保数据一致性。

- **认证与授权**：
    - 所有受保护的路由必须首先验证用户会话（例如，使用NextAuth.js）。
    - 在修改或删除资源前，检查当前用户是否有权限操作该资源。

@examples
- Good (一个带验证和错误处理的API路由):
  // app/api/tasks/route.ts
  import { NextRequest, NextResponse } from 'next/server';
  import { createTaskSchema } from '@/lib/validations/task';
  import { prisma } from '@/lib/prisma';
  import { getCurrentUser } from '@/lib/auth';

  export async function POST(request: NextRequest) {
    try {
      const user = await getCurrentUser();
      if (!user) {
        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
      }

      const body = await request.json();
      const validatedData = createTaskSchema.parse(body); // Zod验证

      const newTask = await prisma.task.create({
        data: {
          ...validatedData,
          userId: user.id, // 关联用户
        },
        select: { id: true, title: true, status: true }, // 只返回需要的字段
      });

      return NextResponse.json(newTask, { status: 201 });
    } catch (error) {
      console.error('Failed to create task:', error);
      if (error instanceof ZodError) {
        return NextResponse.json({ error: 'Invalid input' }, { status: 400 });
      }
      return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
    }
  }

通过这样分层、场景化的规则配置，无论你是在编写一个React组件、设计一个数据库模型，还是创建一个API端点，Cursor AI都能在正确的上下文中，以符合项目最高标准的方式为你提供协助。

5. 调试、优化与规则管理心得

即使精心编写了规则，在实际使用中也可能遇到AI“不听话”或规则冲突的情况。以下是一些从实战中总结的调试技巧和规则维护心得。

5.1 规则不生效的常见原因与排查

  1. 文件位置错误 ：确保 .cursorrules 文件位于正确目录。记住，Cursor是从当前活动文件所在目录 向上 查找。如果你在 src/components/Button.tsx 里工作，但规则在项目根目录，它应该能被找到。如果不行，尝试在更近的目录（如 src/ ）放置一个规则文件。
  2. 语法错误或格式问题 ：规则文件虽然灵活，但格式混乱可能导致解析失败。确保使用正确的缩进（通常是空格），避免奇怪的符号。注释用 # 开头。指令关键词（如 @constraints ）最好单独一行。
  3. 规则冲突或过于模糊 ：如果你在根目录和子目录都有规则，且指令有冲突（例如，根目录说“用Redux”，子目录说“用Zustand”），AI的行为可能不可预测。解决方案是明确职责，让子目录规则更具体，或使用“When in frontend directory, use Zustand”这样的条件描述。模糊的指令如“写高质量的代码”不如“函数圈复杂度不得超过10”有效。
  4. AI的“遗忘”或上下文窗口限制 ： .cursorrules 的内容会作为系统提示词的一部分发送给AI模型，但受限于上下文长度。如果规则文件非常长（比如超过几千字），靠后的部分可能会被模型忽略或遗忘。 优化策略是保持规则简洁、核心 。将最常用、最重要的规则放在文件最前面。可以考虑将庞大的示例集移到一个单独的 EXAMPLE.md 文件中，并在规则里简要引用：“关于组件模式，参考 EXAMPLE.md 中的‘表单组件示例’”。
  5. 需要刷新或重新加载 ：有时修改了 .cursorrules 文件后，Cursor编辑器可能需要一点时间来识别更改。尝试保存文件后，关闭再重新打开当前文件，或者重启Cursor。

5.2 规则优化策略：从有效到高效

  • 从通用到具体 ：开始可以只写几条最关键的规则（如技术栈、禁用 any ）。在后续使用中，每当发现AI重复犯同一个错误（例如，总是忘记错误处理），就把对应的约束加到规则文件中。让规则文件随着项目一起成长。
  • 量化你的要求 ：比起“性能要好”，不如说“避免在渲染函数中进行昂贵的计算，使用 useMemo 和 useCallback 进行优化”。比起“代码要简洁”，不如说“单个函数行数尽量控制在50行以内”。
  • 提供正面范例 ： @examples 部分极其强大。花时间精心构造几个“黄金标准”代码块，这比写十句抽象的描述都管用。确保示例是可直接运行的、符合项目现状的代码片段。
  • 定期审查和重构 ：每个季度或重大项目阶段后，回顾一下你的 .cursorrules 。是否有不再适用的规则？是否有新的最佳实践需要加入？规则文件也应该像代码一样被维护。

5.3 团队协作中的规则管理

在团队中推广使用 .cursorrules 可以极大统一代码风格和降低评审成本。

  1. 版本控制 ：将 .cursorrules 文件纳入Git仓库。这样所有团队成员都能共享同一套AI协作规范。
  2. 制定规范 ：在团队内部讨论并确定规则的核心内容。可以将其视为一种“活”的编码规范文档。
  3. 分层管理 ：允许不同的子项目或特性分支有自己的规则文件，以适应不同的技术需求。但建议维护一个“公司级”或“项目级”的根规则模板。
  4. 作为新人入职指南 ：对于新加入的开发者，让他们先阅读项目的 .cursorrules 文件，可以快速了解项目的技术偏好、架构决策和代码风格，甚至可以直接让AI按照这些规则来辅导他们上手开发。

最终， cedricfressin/cursor.rules 这个项目所倡导的理念，是将开发者从重复性的、低层次的指令中解放出来。它让我们与AI的对话可以聚焦于真正的业务逻辑和架构设计，而不是一遍又一遍地纠正基本的格式问题。通过精心设计和维护你的规则集，你不仅是在配置一个工具，更是在为你和你的团队塑造一个高度专业化、理解项目语境的智能协作环境。这可能是当前阶段，提升AI辅助编程体验和产出质量的最具杠杆效应的实践之一。

# 代码规范
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

流式补全与 diff 视图同步的工程实现：DeepSeek-V4 代码助手落地踩坑

avatar DeepSeek技术社区
cover

Gemini 结构化输出 JSON mode 生产实践：DeepSeek 护栏与安全对齐的工程解法

avatar DeepSeek技术社区
cover

RAG 混合检索实战：向量+关键词何时能1+1>2，何时反成灾难？

avatar DeepSeek技术社区