1. 项目概述：当你的AI编码伙伴学会“看家本领”

如果你是一位深度使用Cursor或类似AI编程工具的开发者，大概率经历过这样的场景：你满怀期待地输入一个复杂的指令，比如“重构这个函数，让它遵循我们项目的代码规范”，结果AI助手生成的代码虽然功能正确，却完全不符合你团队的命名约定、缩进风格或者导入顺序。你不得不花时间手动调整，那种感觉就像请了一位能力超强但不懂你家规矩的厨师，菜做出来了，但摆盘和调味还得自己来。

Youssefhossamm/cursor_rules_commands 这个项目，就是为了解决这个痛点而生的。它本质上是一套为Cursor编辑器量身定制的“家规”与“工作手册”。通过一系列精心编写的规则文件（ .cursorrules ）和预定义的命令模板，它能让你的AI编程助手深度理解并严格遵守你个人或团队特定的开发环境、技术栈偏好和代码风格。这不仅仅是关于代码格式化，更是将项目上下文、架构决策、最佳实践乃至避坑经验，“注入”到AI的思考过程中。

想象一下，当你告诉Cursor“添加一个用户登录的API端点”时，它不仅能生成功能代码，还能自动：

  • 使用你们团队约定的目录结构（比如 src/api/v1/auth/ ）。
  • 导入项目内部封装的工具库，而非随意使用第三方包。
  • 遵循特定的错误处理模式（比如统一使用自定义的 AppError 类）。
  • 甚至自动在代码注释中关联上相关的Jira任务ID（如果规则里这么定义了）。

这个项目适合所有希望将AI编程从“有趣的玩具”提升为“可靠的生产力伙伴”的开发者，无论是独立开发者想要保持个人项目的一致性，还是技术负责人希望在新团队中快速建立并推行统一的编码标准。

2. 核心设计思路：从临时指令到系统化上下文管理

2.1 为何 .cursorrules 是游戏规则改变者

在没有系统化规则之前，我们与Cursor的交互是碎片化且高成本的。每次开启新对话或新文件，我们都需要在提示词中重复描述项目背景、技术栈和规范，就像每次和新同事合作都要从头培训一样。 .cursorrules 文件的存在，将这种临时性的口头交代，变成了永久性的、可版本化的“项目宪法”。

它的核心设计思路基于一个简单的认知：AI助手需要持续、稳定、准确的上下文才能做出最佳决策。 .cursorrules 文件通常被放置在项目根目录或特定子目录下，Cursor在分析该目录下的文件时，会自动读取并应用这些规则。这意味着，一旦配置好，规则对项目内所有AI交互都生效，实现了“一次定义，处处生效”。

这个设计巧妙地将配置分为了几个层次：

  1. 环境与依赖 ：告诉AI项目运行在什么环境（Node.js 18+， Python 3.11），使用哪些核心框架（Next.js 14， Prisma）和关键依赖。这防止了AI建议使用不兼容的语法或废弃的API。
  2. 代码风格与架构约束 ：定义命名规范（camelCase函数， PascalCase类）、文件组织模式、禁止使用的模式（如全局变量）、推荐的设计模式等。这是保证代码库一致性的关键。
  3. 项目特定逻辑与惯例 ：这是最有价值的部分。例如，定义“所有数据库查询必须通过 @/lib/db 这个封装层进行，禁止直接使用Prisma Client”，或者“所有API响应必须包裹在 ApiResponse 这个标准格式中”。这些规则编码了团队在踩过无数坑后总结出的黄金经验。

2.2 命令模板：将复杂工作流封装为自然语言指令

如果说 .cursorrules 是静态的“宪法”，那么命令模板就是动态的“行政指令集”。Cursor允许用户自定义命令，这些命令可以通过 @ 符号快速调用。 cursor_rules_commands 项目提供了大量开箱即用的命令模板，将多步、复杂的开发任务简化为一句自然语言。

其设计思路在于 抽象和复用 。例如，一个“创建React组件”的任务，可能涉及：

  • 在正确的 components/ 子目录下创建文件。
  • 写入包含特定导入（如 import { cn } from '@/lib/utils' ）的组件样板。
  • 添加符合项目规范的PropTypes或TypeScript接口。
  • 在组件文件旁创建对应的故事书（Storybook）文件或单元测试文件骨架。

手动完成这些步骤繁琐且易错。而一个预定义的 @component 命令，可以将上述所有步骤、根据规则文件中的约定，一次性准确无误地执行。这极大地提升了开发效率，并确保了所有生成的代码都符合预设规范。

2.3 项目结构解析：模块化与可组合性

浏览 cursor_rules_commands 的仓库，你会发现它的结构非常清晰，体现了模块化的设计思想：

cursor_rules_commands/
├── rules/                    # 核心规则目录
│   ├── frontend/            # 前端相关规则
│   │   ├── react.cursorrules
│   │   ├── nextjs.cursorrules
│   │   └── vue.cursorrules
│   ├── backend/             # 后端相关规则
│   │   ├── nodejs.cursorrules
│   │   └── python.cursorrules
│   └── general/             # 通用规则
│       ├── git.cursorrules
│       └── best-practices.cursorrules
├── commands/                # 命令模板目录
│   ├── create-component.md
│   ├── generate-api-route.md
│   └── refactor-code.md
└── templates/              # 代码模板片段（可选）
    └── component-template.tsx

这种结构允许开发者像搭积木一样组合规则。你可以为你的全栈项目同时引入 rules/frontend/nextjs.cursorrules 和 rules/backend/nodejs.cursorrules ，再叠加 rules/general/git.cursorrules 。这种可组合性使得它能够灵活适配从简单静态页面到复杂微服务架构的各种项目。

3. 规则文件深度解析与定制实践

3.1 .cursorrules 文件语法与核心指令

.cursorrules 文件使用一种类自然语言的指令格式，核心在于几个关键指令：

  • YOU ARE / YOU ARE A ： 设定AI的角色和专长领域。这是最重要的指令之一，它从根本上塑造了AI的“人格”和思考倾向。

    # 示例：将AI定位为资深React专家
YOU ARE A senior React frontend engineer with 10 years of experience, specializing in building performant, accessible, and maintainable component libraries using TypeScript and Tailwind CSS.

    注意 ：角色设定要具体且有侧重。“资深全栈工程师”不如“专注于性能优化和Clean Architecture的Node.js后端专家”来得有效。明确的角色能引导AI调用更相关的知识。

  • TECH STACK ： 明确声明项目技术栈。这能有效防止AI提出不切实际的建议。

    TECH STACK:
- Language: TypeScript (strict mode)
- Frontend Framework: Next.js 14 (App Router)
- UI Library: React 18
- Styling: Tailwind CSS v3.4
- Database ORM: Prisma
- API Protocol: tRPC

  • RULES ： 这是规则的主体，包含具体的“能做”与“不能做”。

    RULES:
- Always use functional components with TypeScript interfaces for props.
- Never use `any` type. Use `unknown` or proper generics if needed.
- All API calls must be made through the `@/lib/api` client, which handles authentication and error parsing.
- Utility functions must be placed in `@/lib/utils` and be fully unit tested.
- Use `async/await` for all asynchronous operations, avoid `.then()` chains.
- **IMPORTANT**: When creating database queries, always include a `deletedAt` IS NULL check for soft-delete models.

    规则应当从笼统到具体。先定义大原则（如“使用函数组件”），再定义具体约束（如“禁止使用any”），最后强调关键陷阱（如软删除检查）。

  • FILES ： 提供关键文件的路径或内容片段，让AI了解项目结构。

    FILES:
- `@/types/index.ts`: Contains global type definitions like `User`, `ApiResponse<T>`.
- `@/lib/db/index.ts`: The singleton Prisma client instance. Always import from here.

3.2 编写高效规则的实操心得

经过大量实践，我总结出几条编写高效 .cursorrules 的黄金法则：

  1. 正向引导优于负面禁止 ：与其说“不要写类组件”，不如说“请始终使用函数组件”。正向指令更清晰，AI也更容易遵循。
  2. 提供范例（Example-Driven） ：对于复杂的模式，光有文字描述不够。在规则中直接提供代码范例是最高效的方式。 
    RULES:
- Error handling pattern: Catch errors and wrap them in our standard AppError.
  EXAMPLE:
  try {
    await someAsyncOperation();
  } catch (error) {
    throw new AppError('Failed to perform operation', { cause: error, code: 'OPERATION_FAILED' });
  }
  3. 分层与优先级 ：将规则分为 MUST 、 SHOULD 、 AVOID 等级别。可以在规则开头声明：“以 MUST: 开头的规则必须严格遵守， SHOULD: 是强烈推荐， AVOID: 是尽量避免。” 这能帮助AI在复杂场景下做出权衡。
  4. 保持更新 ：项目技术栈和最佳实践会演进， .cursorrules 也应作为一个活文档进行版本管理。在团队中，对 .cursorrules 的修改应该像修改代码一样经过评审。

3.3 针对不同场景的规则配置策略

  • 个人小项目 ：规则可以相对宽松，侧重于自动化样板代码和避免常见错误。可以重点配置 TECH STACK 和几个关键的 RULES ，例如代码风格（用Prettier配置）、导入别名设置等。
  • 大型团队项目 ：规则必须严格且详尽。除了编码规范，还应包括：
    • 架构边界 ：明确哪些层可以访问数据库，哪些层只能处理业务逻辑。
    • 安全规范 ：禁止直接拼接SQL查询，强制使用参数化查询或ORM方法；对用户输入验证提出明确要求。
    • 依赖管理 ：规定哪些第三方库是允许使用的（白名单），或者哪些是禁止的（如不稳定的 v0.x 版本库）。
    • 测试要求 ：规定为新功能编写单元测试或集成测试，并指定测试文件的存放位置和命名格式。
  • 遗留项目迁移 ：规则可以扮演“防腐层”的角色。你可以制定这样的规则：“在修改 legacy/ 目录下的文件时，首要目标是修复缺陷且不破坏现有功能。但在 features/new/ 目录下创建的任何新代码，必须完全遵守新的架构规则。” 这允许渐进式重构。

4. 命令模板的创建与高级应用

4.1 解剖一个命令模板：以“创建Next.js API路由”为例

命令模板通常是一个Markdown文件，其结构包含触发指令、描述和具体的操作步骤。我们来看一个 commands/generate-api-route.md 的示例：

# @api-route
**Description**: Creates a new Next.js 14 App Router API route handler with proper error handling and validation.
**Usage**: `@api-route <route-name> [--method=GET|POST|PUT|DELETE]`

## Steps
1. **Determine Path**: The API route should be created under `src/app/api/v1/<route-name>/route.ts`.
2. **Import Dependencies**: Always import `NextResponse` from `next/server` and our custom `ApiError` and `validateRequest` from `@/lib/api-utils`.
3. **Implement Handler**: Generate a handler function for the specified HTTP method (defaults to POST).
4. **Add Validation**: Use `validateRequest` with a Zod schema (you will need to ask the user for the schema or create a basic one).
5. **Add Error Handling**: Wrap the core logic in a try-catch block and throw `ApiError` on failures.
6. **Return Standard Response**: Always return `NextResponse.json(data, { status: 200 })` on success.

## Example Output
When user types `@api-route users/create --method=POST`, generate a file `src/app/api/v1/users/create/route.ts` with content similar to:

```typescript
import { NextRequest, NextResponse } from 'next/server';
import { ApiError, validateRequest } from '@/lib/api-utils';
import { createUserSchema } from '@/schemas/user'; // Assume this schema exists

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const validatedData = validateRequest(createUserSchema, body);

    // Core business logic here (e.g., call a service function)
    // const newUser = await userService.create(validatedData);

    return NextResponse.json(
      { success: true, data: newUser }, // Use standard response format
      { status: 201 }
    );
  } catch (error) {
    if (error instanceof ApiError) {
      return NextResponse.json(
        { success: false, error: error.message },
        { status: error.statusCode }
      );
    }
    // Log unexpected errors
    console.error('Unexpected error in POST /api/v1/users/create:', error);
    return NextResponse.json(
      { success: false, error: 'Internal server error' },
      { status: 500 }
    );
  }
}
```

这个模板的精妙之处在于，它不仅仅是一个文件生成器，它 内嵌了项目的最佳实践 ：正确的路径结构、强制性的输入验证、统一的错误处理和响应格式。用户只需提供一个路由名称和方法，就能获得一个生产就位的API端点骨架。

4.2 设计可交互的动态命令

高级命令模板可以具备交互性。例如，一个 @refactor 命令，其步骤可能是：

  1. 分析用户当前选中的代码块。
  2. 向用户提问：“你的重构目标是什么？A) 提取函数 B) 重命名变量 C) 简化条件逻辑 D) 其他（请描述）”。
  3. 根据用户选择，执行不同的重构策略。

要实现这一点，可以在命令步骤中使用类似 {{用户输入}} 的占位符（具体语法取决于Cursor的更新，目前主要通过自然语言描述引导交互），并在描述中明确告诉用户命令执行过程中需要他们提供什么信息。这相当于为AI编写了一个清晰的“工作脚本”。

4.3 将命令与规则联动：实现上下文感知

最强大的用法是将命令模板与 .cursorrules 中定义的上下文结合。例如，你的规则文件里定义了项目使用 @/ 作为别名指向 src/ 目录。那么，在所有命令模板中，你都可以直接使用 @/components/Button 这样的路径，AI在生成代码时会自动将其解析为正确的相对或绝对路径。

更进一步，你可以在规则中定义一个“组件属性约定”：

RULES:
- All interactive components must accept `className?: string` and `disabled?: boolean` props.
- All data-fetching components must accept `isLoading?: boolean` and `error?: Error` props.

然后，在 @component 命令模板中，就可以直接引用这些约定，自动为生成的组件添加这些标准属性。这种联动使得整个系统成为一个有机整体，规则是知识库，命令是运用这些知识的自动化工作流。

5. 集成到工作流：从配置到团队共享

5.1 个人项目快速上手指南

  1. 克隆与探索 ：首先将 cursor_rules_commands 仓库克隆到本地，或直接浏览其 rules/ 和 commands/ 目录，找到与你技术栈最接近的规则文件。
  2. 选择性复制 ：不要全盘复制。将你需要的规则文件（如 nextjs.cursorrules ）复制到你项目的根目录。
  3. 本地化定制 ：打开复制过来的 .cursorrules 文件，进行“外科手术式”修改。更新 TECH STACK 为你项目的实际版本，在 RULES 部分添加或删除规则，使其完全贴合你的习惯。例如，如果你使用 pnpm ，就加上 - Use pnpm for package management, never npm or yarn . 的规则。
  4. 命令集成 ：将你觉得有用的命令模板内容，通过Cursor的“Custom Commands”功能添加到编辑器中。通常可以在Cursor设置中找到“Custom Commands”或“Snippets”区域，将模板的Markdown内容粘贴进去并保存。
  5. 测试与迭代 ：在项目中打开一个新文件，尝试输入 @ 调用你添加的命令，或者让Cursor执行一项任务，观察其输出是否符合新规则。根据效果微调规则。

5.2 团队协作标准化方案

在团队中推行这套系统，能极大提升代码一致性和新人上手速度。

  1. 创建团队规则仓库 ：可以 Fork 原项目，或在内部Git仓库中创建一个 team-cursor-rules 项目。将其作为团队的基础设施。
  2. 制定规则章程 ：在仓库README中明确规则文件的维护流程、命名规范（如 .cursorrules 必须放在项目根目录），以及如何为不同子项目（微服务、移动端）配置不同的规则。
  3. 版本化与发布 ：将规则和命令模板像代码库一样进行版本管理。当技术栈升级（如从React 17升级到18），相应更新规则文件，并通过Pull Request进行评审，然后发布新版本。
  4. 项目初始化脚本 ：将复制基础规则文件作为项目初始化脚本（如 setup.sh 或 init.js ）的一部分。新项目创建时，自动拉取最新版本的团队规则文件。
  5. 文档与培训 ：编写简明的内部文档，说明核心规则的目的（例如，“为什么我们强制所有API错误必须用 AppError 包装？”），并组织简短的分享会，让团队成员理解其价值，而不仅仅是遵守规定。

5.3 与现有工具链的融合

.cursorrules 和命令模板不应与你现有的工具链冲突，而应增强它。

  • 与ESLint/Prettier共存 ：规则应侧重于ESLint/Prettier无法覆盖的 高层次约定和架构决策 。例如，ESLint可以检查代码风格，而 .cursorrules 可以规定“状态管理必须使用Zustand，禁止直接使用Context API for global state”。两者职责互补。
  • 与文档生成器结合 ：可以在规则中要求为复杂函数添加特定的JSDoc注释格式。这样，当AI生成代码时，也会自动生成符合你团队标准的文档注释，便于后续使用TypeDoc等工具生成API文档。
  • 作为新人 onboarding 指南 ：对于新加入的开发者，让他阅读项目的 .cursorrules 文件，是比任何文档都更快了解项目技术决策和编码规范的方式。这本身就是一份活的、可执行的开发指南。

6. 常见问题与效能优化技巧

6.1 规则失效或行为异常的排查

即使配置正确，有时AI的行为也可能偏离预期。以下是系统的排查思路：

  1. 检查文件位置与命名 ：确保 .cursorrules 文件位于当前打开文件所在目录或其任意父级目录中，且文件名 完全正确 （包括开头的点）。Cursor是大小写敏感的。
  2. 验证规则语法 ：检查是否有未闭合的引号、错误的缩进或拼写错误。一个简单的语法错误可能导致整个文件被忽略。可以尝试先注释掉所有规则，然后逐条启用，以定位问题规则。
  3. 上下文窗口过载 ：Cursor的上下文窗口有限。如果你的 .cursorrules 文件非常长（比如超过几千字），或者同时打开了多个包含大量规则的目录，AI可能无法加载全部规则。 优化策略是保持规则简洁 ，只保留最关键、最高频的约束。将不常用或项目特定的详细约定放在项目内部的 README-dev.md 中，并在规则里简单引用：“有关详细的组件设计规范，请参阅 README-dev.md#component-guide ”。
  4. 指令冲突 ：如果项目中有多个 .cursorrules 文件（例如根目录一个，子目录一个），Cursor通常会合并它们，但可能出现冲突。明确规则的优先级，通常子目录的规则可以更具体，但不应与根目录的核心原则冲突。
  5. AI模型“遗忘” ：在很长的对话中，AI可能会逐渐忽略早期的系统指令（包括规则）。如果发现对话后期AI开始“违规”，可以尝试 开启一个新对话 ，或者用一句简单的提示词重申核心规则，如：“请记住，我们正在使用Next.js 14 App Router，并且所有API调用都要通过 @/lib/api 客户端。”

6.2 提升AI遵循率的进阶技巧

  1. 使用强调语气 ：在关键规则前使用 **IMPORTANT:** 、 **CRITICAL:** 或 ## MUST FOLLOW 等强调标记，能提高AI的注意力。
  2. 结构化输入与输出 ：在规则中明确要求AI以特定格式思考或输出。例如： 
    RULES:
- Before writing code, think step-by-step about the architecture.
- When providing code, first write a brief explanation in a comment, then the code.
  3. 提供负面示例 ：对于容易出错的地方，除了正面规则，提供一个“反面教材”非常有效。 
    RULES:
- Do NOT directly mutate state. Always use the state setter function.
  BAD EXAMPLE:
  ```javascript
  const [list, setList] = useState([]);
  list.push(newItem); // WRONG!
    GOOD EXAMPLE: 
    setList(prev => [...prev, newItem]); // CORRECT
  4. 定期“刷新”上下文 ：在复杂的多轮对话中，可以适时地以总结的方式重新提及核心规则，例如：“基于我们的项目规则（TypeScript, App Router, 使用shadcn/ui组件），请继续...”

6.3 效能边界认知与互补策略

必须认识到， .cursorrules 不是银弹。它的效能边界在于：

  • 无法替代代码审查 ：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技术社区