1. 项目概述：一份为AI编程助手定制的“行为准则”

如果你和我一样，每天都在和Cursor、GitHub Copilot这类AI编程助手打交道，那你肯定也经历过这样的时刻：你满怀期待地输入一个需求，结果AI助手生成的代码风格和你项目里的完全对不上，或者它自作主张地用了你已经淘汰的旧API，甚至给你推荐了一些你团队里明令禁止的“反模式”。每次都要在聊天框里反复强调“用TypeScript”、“别用默认导出”、“遵循我们的项目结构”，不仅效率低下，还容易遗漏关键约束。

这就是 .cursorrules 文件诞生的背景。它本质上是一个放在你项目根目录下的纯文本配置文件，专门用来“调教”Cursor编辑器内置的AI助手。你可以把它理解为一份给AI的、极其详细的“岗位说明书”和“编码规范”。当AI在分析你的项目上下文时，它会读取这份文件，并严格按照你设定的规则来思考、建议和生成代码。这不再是简单的“上下文学习”，而是主动的“规则约束”，能确保AI输出的代码从第一行起就符合你的技术栈、架构偏好和团队规范。

我花了不少时间研究并实践了各种 .cursorrules 的写法，发现一个精心设计的规则集，能将AI助手的输出质量从“勉强可用”提升到“令人惊喜”的水平。它不仅能帮你保持代码风格的一致性，更能将一些行业最佳实践和架构思想“灌输”给AI，让它从一个单纯的代码补全工具，升级为一个理解你项目语境的“初级架构师”。接下来，我将结合我的实际使用经验，为你深入拆解如何构建和运用这份强大的“行为准则”。

2. .cursorrules 的核心价值与设计哲学

2.1 超越代码补全：从助手到协作者

很多人把AI编程助手当作一个更聪明的“Tab补全”，但 .cursorrules 的出现，改变了这种交互的维度。它的核心价值在于 建立共识 和 约束边界 。

首先，它建立了技术栈的共识。当你告诉AI“你是一个Next.js 15和TypeScript专家”，并详细说明了要使用App Router、默认服务端组件、Server Actions等原则时，AI在思考任何与路由、数据获取相关的问题时，都会自动在这个框架内寻找解决方案，而不是给出一个基于Pages Router或客户端渲染的过时答案。这极大地减少了沟通成本。

其次，它约束了代码风格的边界。是使用 interface 还是 type ？函数命名用驼峰还是帕斯卡？文件该如何组织？这些看似琐碎的细节，恰恰是团队协作中摩擦最多的地方。通过 .cursorrules 明确定义，AI生成的所有代码片段都会自动遵循这些约定，新人上手项目时，甚至可以通过AI生成的代码来学习团队的编码规范，起到了“活文档”的作用。

我的实操心得 ：不要试图在一个规则文件里覆盖所有技术。为每个项目或技术子领域创建独立的 .cursorrules 文件是更高效的做法。例如，一个全栈项目可以有一个顶层的 cursorrules 定义通用原则，同时在 /backend 和 /frontend 目录下放置更具体的规则文件。Cursor会优先使用离当前编辑文件最近的规则文件。

2.2 设计一份高效规则文件的黄金法则

从大量的实践和社区分享中，我总结出了设计 .cursorrules 文件的几个关键原则，遵循这些原则能让你的规则文件事半功倍。

1. 角色定义先行，明确专家领域 规则文件的开头必须清晰定义AI的角色。这不仅仅是礼貌，更是为后续所有规则设定上下文。例如， You are an expert in TypeScript, Next.js 15, React 19, and modern web development. 这句话就告诉AI，它应该以一个熟悉这些最新技术栈的专家视角来思考问题，避免使用过时或无关的知识。

2. 原则高于细节，聚焦核心范式 在罗列具体代码风格之前，应先阐述项目的核心架构原则。这些原则是决策的“为什么”。例如，“默认使用服务端组件”、“优先使用组合而非继承”、“错误应被显式处理而非隐藏”。当AI遇到规则未涵盖的边缘情况时，它会依据这些高阶原则进行推理，做出更符合你期望的选择。

3. 提供正反示例，界定清晰边界 只说“应该怎么做”是不够的，还必须明确指出“不应该怎么做”。在“Anti-Patterns”或“Avoid”章节列出常见的错误模式，能有效防止AI踩坑。例如，“Never use var ”、“Avoid deeply nested ternary operators”、“Do not write raw SQL queries in Django views”。

4. 保持简洁与可维护性 规则文件不是一本百科全书。它应该聚焦于那些最常被违反、或对项目一致性最关键的规定。过于冗长的规则文件，其本身就会成为维护的负担。我建议将规则控制在能快速阅读完的篇幅内（例如一屏到两屏），并随着项目技术栈的演进定期回顾和更新。

3. 主流技术栈的规则文件深度解析与定制

了解了设计哲学后，我们来看看如何为不同的技术栈构造实用的规则。我将基于一个优秀的开源集合 Anuar-boop/cursor-rules ，并结合我自己的增补和调整，为你展示几个典型场景下的规则文件该如何编写。

3.1 现代前端：Next.js 15 + TypeScript + Tailwind CSS

这是当前最流行的全栈React框架组合。其规则文件需要精准反映App Router范式、服务端优先理念以及工具链的最佳实践。

You are an expert in TypeScript, Next.js 15, React 19, and modern web development.

Key Principles:
- **App Router First**: Use the App Router (`/app`) for all new routes. The Pages Router (`/pages`) is for legacy code only.
- **Server Components by Default**: Components are Server Components unless they need interactivity, event handlers, or browser-only APIs. Then and only then, add `‘use client’`.
- **Data Colocation**: Fetch data in Server Components, as close to where it‘s used as possible. Use React.cache() for automatic request deduplication.
- **Server Actions for Mutations**: Handle form submissions and data mutations directly via Server Actions. Do not create separate API routes for simple CRUD operations.
- **Progressive Enhancement**: Implement proper loading states (`loading.tsx`), error boundaries (`error.tsx`), and not-found handling (`not-found.tsx`) for every route segment.

Code Style & Structure:
- **TypeScript Strict**: Enable `strict: true` in tsconfig. Use `satisfies` for precise type checking without widening. Prefer `interface` for object shapes to leverage declaration merging.
- **Named Exports**: Use named exports for components, utilities, and types. This improves tree-shaking and auto-import accuracy.
- **File Naming**: Use `.tsx` for components, `.ts` for utilities/types. Route files: `page.tsx`, `layout.tsx`, `loading.tsx`, etc.
- **Path Aliases**: Use `@/*` alias for the root (`src`) directory. Import as `import { Button } from “@/components/ui/button”`.

Data Fetching & State:
- **Fetch in Server Components**: Use the native `fetch` with Next.js caching or libraries like `TanStack Query` for complex client-state.
- **Revalidation Strategy**: Use time-based revalidation (`next.revalidate`) for static data, and on-demand revalidation (`revalidatePath`, `revalidateTag`) after mutations.
- **Client State Management**: For global UI state, use Zustand or Context. For server state, use Server Components + Server Actions or TanStack Query. Avoid Redux in new projects.

Performance & Tooling:
- **Image Optimization**: Always use `next/image`. Define `sizes` and `priority` appropriately.
- **Font Optimization**: Use `next/font` with variable fonts when possible.
- **Bundle Analysis**: Use `@next/bundle-analyzer` to identify large dependencies. Prefer dynamic imports (`React.lazy`/`next/dynamic`) for heavy client components.
- **Tailwind CSS**: Use utility classes directly. Extract repeated patterns into components with `@apply` only if used more than 3 times. Follow mobile-first breakpoints.

Testing & Quality:
- **Unit Tests**: Use Vitest + React Testing Library. Test user behavior, not implementation details.
- **E2E Tests**: Use Playwright. Focus on critical user journeys.
- **Static Analysis**: ESLint with `@next/eslint-plugin-next`, and Prettier for formatting. Commit hooks should enforce these.

Anti-Patterns to Avoid:
- **Prop Drilling**: Use Context or state management library instead of passing props through many layers.
- **`useEffect` for Data Fetching**: In Server Components, fetch directly. In Client Components, use TanStack Query or a similar library.
- **Inline Styles**: Use Tailwind classes or CSS Modules. Inline styles are for dynamic values only.
- **Large Client Components**: If a component exceeds 200 lines, consider splitting it into smaller, composable pieces.

注意事项 ：这条规则中，最容易被忽略但又最重要的是 “Server Components by Default” 。很多开发者（包括AI）会习惯性地为所有组件添加 ‘use client’ ，这会导致不必要的客户端捆绑包增大和渲染性能下降。规则中强调“除非必要”，能有效纠正这一倾向。

3.2 高性能后端：Go 标准库与 Web 开发

Go 生态崇尚简洁和显式，其规则文件应着重强调错误处理、并发模型和标准库的优先使用。

You are an expert in Go 1.22+, following idiomatic Go patterns and the philosophy of simplicity.

Key Principles:
- **Simplicity is Paramount**: Write clear, readable code over clever code. If a piece of code is hard to understand, it‘s hard to maintain.
- **Standard Library First**: Reach for the standard library (`net/http`, `encoding/json`, `context`) before considering third-party packages.
- **Explicit Error Handling**: Every function that can fail must return an `error`. Handle errors where they occur, don‘t ignore them. Use `_` for intentionally ignored returns sparingly.
- **Concurrency with Care**: Use goroutines and channels, but start simple. A well-written synchronous program is better than a buggy concurrent one.

Code Style & Conventions:
- **Formatting**: `gofmt` and `goimports` are non-negotiable. CI must enforce this.
- **Naming**: Use short names in short scopes (`i` for index, `r` for `*http.Request`). Use descriptive, camelCase names for exported identifiers.
- **Interfaces**: Define interfaces where they are used, not where they are implemented. Accept interfaces (`io.Reader`), return concrete structs.
- **Documentation**: Every exported package, function, type, and constant must have a doc comment. Run `godoc -http=:6060` to review.

Error Handling Patterns:
- **Error Wrapping**: Use `fmt.Errorf(“operation: %w”, err)` to add context. This enables `errors.Is` and `errors.As` for inspection upstream.
- **Sentinel Errors**: Define package-level error variables with `errors.New` for expected error conditions (e.g., `ErrNotFound`).
- **Log or Return**: Choose one. Don‘t log an error and then return it, as this creates duplicate log entries. In HTTP handlers, log the error and return an appropriate HTTP status.

Concurrency & Context:
- **Context Propagation**: Pass `context.Context` as the first parameter to any function that does I/O, blocking operations, or needs cancellation/timeout awareness.
- **Structured Concurrency**: Use `errgroup.WithContext` to manage a group of goroutines that should succeed or fail together.
- **Mutex vs Channels**: Use a `sync.Mutex` or `sync.RWMutex` to protect shared memory. Use channels to coordinate goroutines and communicate data.

Project Structure for Web Services:

/cmd /myapp main.go # Application entry point /internal /app # Business logic (use cases, services) /domain # Core domain models and interfaces /pkg # Internal shared packages (avoid if possible) /server # HTTP server setup, routing, middleware /pkg # Public, reusable library code (if any) /test # Integration and end-to-end tests go.mod go.sum

Testing:
- **Table-Driven Tests**: The standard pattern. Define a slice of test cases and loop over them.
- **Test Helpers**: Use `t.Helper()` in helper functions to keep error reporting accurate.
- **HTTP Testing**: Use `net/http/httptest` for testing handlers in isolation.
- **Golden Files**: For complex output (JSON, HTML), consider using golden files for regression testing.

Anti-Patterns:
- **Panic in Production Code**: Libraries should never panic. Applications should only panic for unrecoverable errors on startup.
- **Empty Interface (`interface{}`/`any`)**: Use sparingly. Prefer generics or defined interfaces for type safety.
- **Global Variables**: They make testing difficult and introduce hidden dependencies. Use dependency injection.
- **Ignoring Errors**: `_ = conn.Close()` is a bug waiting to happen. Handle the error or explicitly document why it‘s safe to ignore.

实操心得 ：在Go项目中， 错误处理 是AI最容易出错的地方。明确要求“显式错误处理”并给出具体模式（包装、哨兵错误）后，AI生成的代码会稳健得多。另外，强调 internal 目录的使用 能有效防止AI将本应是内部实现的包错误地暴露为公共API。

3.3 数据科学与机器学习：Python 工作流

数据科学项目对可复现性和实验跟踪要求极高，规则文件应引导AI建立一套规范的工作流。

You are an expert in Python data science and machine learning, using pandas, NumPy, scikit-learn, and Jupyter effectively.

Key Principles:
- **Reproducibility First**: Every analysis and model must be fully reproducible. This means pinned dependencies, seeded random states, and clear data provenance.
- **Exploratory Data Analysis (EDA) is Mandatory**: Never jump straight to modeling. Understand your data‘s distributions, missingness, and relationships first.
- **Validation is Non-Negotiable**: Always hold out a test set before any modeling begins. Use cross-validation for robust performance estimation.
- **Simplicity Before Complexity**: Start with a simple baseline model (e.g., linear regression, decision tree). Only add complexity if it provides a validated improvement.

Data Manipulation with pandas:
- **Method Chaining**: Use method chaining for readability: `df.query(‘col > 0’).assign(new_col=lambda d: d.col * 2).groupby(‘cat’).mean()`.
- **Avoid Iteration**: Never use `iterrows()` or `apply` for simple column operations. Use vectorized NumPy/pandas operations.
- **Categoricals**: Convert low-cardinality string columns to `category` dtype for memory and performance gains.
- **Indexing**: Use `.loc[]` and `.iloc[]` for explicit label/integer-based indexing. Avoid chained indexing (`df[‘a’][‘b’]`).

Modeling with scikit-learn:
- **Pipeline Everything**: Use `sklearn.pipeline.Pipeline` to chain preprocessing (imputation, scaling, encoding) and the estimator. This prevents data leakage.
- **Hyperparameter Tuning**: Use `GridSearchCV` or `RandomizedSearchCV` within a pipeline. Tune on the validation set, not the test set.
- **Feature Engineering**: Create new features in a reproducible way, ideally within a pipeline using `FunctionTransformer` or custom transformers.
- **Evaluation Metrics**: Choose metrics appropriate for the business problem (e.g., F1 for class imbalance, MAE for regression). Don‘t default to accuracy.

Project Structure & Tooling:

/project /data /raw # Immutable原始数据 /processed # 清洗后的数据 /notebooks # 探索性分析 /src /features # 特征工程代码 /models # 模型定义与训练脚本 /visualization # 绘图工具函数 /models # 保存的模型文件 (.pkl, .joblib) /reports # 生成的图表、报告 requirements.txt # 或 poetry.lock/pipenv environment.yml # Conda环境

Experiment Tracking:
- **Log Everything**: For serious projects, use MLflow, Weights & Biases, or even a simple CSV logger to track parameters, metrics, and artifacts (plots, models).
- **Version Data**: Use DVC (Data Version Control) or at least note the exact data source and hash.
- **Document Assumptions**: In a README or code comments, document any assumptions made during data cleaning and feature engineering.

Visualization & Communication:
- **Static Plots**: Use `matplotlib` or `seaborn` for publication-quality static plots. Set a consistent style.
- **Interactive Exploration**: Use `plotly` or `altair` for interactive plots in notebooks.
- **Clarity over Artistry**: The goal of a plot is to communicate an insight. Ensure axes are labeled, legends are clear, and the chart title explains the “so what”.

Anti-Patterns:
- **Data Leakage**: Never use information from the test set (or future data) during training or feature engineering.
- **Overfitting on Validation**: Repeatedly tuning hyperparameters on the same validation set leads to overfitting. Use nested cross-validation for final evaluation.
- **Ignoring Class Imbalance**: Applying a standard classifier to imbalanced data without strategies (resampling, class weights, different metrics) will fail.
- **“Black Box” Models**: For high-stakes decisions, prefer interpretable models (linear models, trees) or use SHAP/LIME to explain complex models.

4. 高级技巧：编写与调试你的专属规则

掌握了为特定技术栈编写规则后，我们来看看如何让规则文件本身更强大、更易于维护。

4.1 利用分层与继承组织复杂规则

对于大型单体仓库或涉及多种技术的项目，单一的 .cursorrules 文件会变得臃肿。我推荐使用 分层规则 策略。

1. 根目录通用规则 ( /.cursorrules ): 定义全项目通用的原则，如代码质量、安全规范、Git提交约定、通用工具链（ESLint, Prettier）配置。

   You are a senior engineer focused on clean, maintainable, and secure code.
   
   Universal Principles:
   - Write code that is easy to delete, not just easy to extend.
   - Functions should do one thing and do it well.
   - Prefer readability over cleverness.
   - All new code must have associated tests.
   - Never commit secrets or credentials.
   
   Security Baseline:
   - Validate and sanitize all user inputs.
   - Use parameterized queries/prepared statements for database access.
   - Dependencies must be regularly updated and scanned for vulnerabilities.
   - Use environment variables for configuration, never hardcode.
   

2. 技术域特定规则 (如 /frontend/.cursorrules , /backend/.cursorrules ): 继承通用原则，并添加前端或后端特定的细节。你可以在域规则开头引用根规则的理念。

   # /frontend/.cursorrules
   You are an expert in modern frontend development. In addition to the project‘s universal principles of clean and secure code, adhere to the following frontend-specific rules:
   - Use TypeScript with strict mode enabled.
   - Prefer functional components and hooks.
   - ...
   

3. 框架特定规则 (如 /frontend/apps/admin/.cursorrules ): 对于使用特定框架的子项目，可以放置更精确的规则。Cursor会从当前目录向上查找，使用找到的第一个 .cursorrules 文件，因此子目录的规则会覆盖父目录的。

4.2 调试与验证：确保规则生效

编写了规则文件，如何知道它是否被正确应用？以下是几个验证方法：

1. 直接提问测试 ：在Cursor的聊天框中，直接询问与规则相关的问题。例如，在Next.js项目根目录下，你可以问：“我应该如何在这个项目中获取数据？” 一个配置正确的AI应该会回答基于服务端组件和 fetch 的方案，而不是建议你使用 getServerSideProps （Pages Router）或 useEffect 。

2. 代码生成测试 ：给AI一个具体的任务。例如，“请为我生成一个用户登录表单组件，包含邮箱和密码字段，并处理提交。” 观察生成的代码：

   • 是否使用了正确的文件命名和导出方式？
   • 是否遵循了状态管理原则（例如，对于Next.js，它可能建议使用Server Action）？
   • 样式是否符合Tailwind的约定？

3. 检查“思考过程” ：在Cursor的设置中，可以开启“显示AI推理步骤”的选项（如果支持）。这能让你看到AI在生成建议时是否参考了你的规则文件。

4. 规则冲突排查 ：如果AI的行为不符合预期，检查是否存在规则冲突。例如，通用规则说“函数要短小”，但前端规则说“组件内聚”，当生成一个复杂的表单组件时，AI可能会困惑。这时需要调整规则优先级或细化规则描述。

4.3 常见问题与规则失效场景

即使规则文件写得再好，也会遇到AI“不听话”的情况。以下是一些常见问题及解决思路：

问题1：AI完全忽略了规则文件。

• 排查 ：首先确认文件名为 .cursorrules （注意开头的点），并且位于项目根目录或当前工作目录的上级路径。检查文件编码是否为UTF-8。
• 解决 ：在Cursor中，尝试手动指定规则文件路径（如果功能支持），或重启Cursor编辑器。

问题2：AI部分遵循规则，但在某些细节上出错。

• 排查 ：规则描述可能不够具体或存在歧义。例如，“使用函数式组件”是明确的，但“保持代码简洁”是主观的。
• 解决 ：将模糊的原则转化为具体的、可执行的指令。把“代码简洁”改为“单个函数长度不超过30行”、“组件文件长度不超过200行”。

问题3：规则文件过长，AI似乎无法理解全部内容。

• 排查 ：目前AI的上下文窗口虽大，但过于冗长的指令可能导致关键信息被稀释。
• 解决 ：精简规则。删除陈述性的、非强制性的描述。使用更紧凑的列表和关键词。采用分层策略，将最核心、最通用的规则放在最前面。

问题4：针对某个非常具体的第三方库，规则如何定义？

• 解决 ：创建针对该库的规则片段，并放在离使用该库的代码最近的位置。例如，对于 react-hook-form ，你可以在表单相关的组件目录下放置一个简短的规则：

  When working with forms, use `react-hook-form` with `zod` for validation.
  - Use `useForm` hook with `resolver: zodResolver(schema)`.
  - Destructure `register, handleSubmit, formState: { errors }`.
  - Display errors next to the corresponding input field.
  - Use `onSubmit` with `handleSubmit(yourFunction)`.
  

5. 将规则文件融入团队工作流

个人使用 .cursorrules 能极大提升效率，但对于团队而言，它的价值在于 统一编码风格和降低认知负荷 。要让规则文件在团队中发挥作用，需要将其正式纳入开发流程。

1. 版本化与共享 将 .cursorrules 文件提交到代码仓库中。这使它成为项目资产的一部分，任何克隆项目的人都能立即获得相同的AI辅助体验。可以考虑在项目模板或脚手架中内置基础规则文件。

2. 作为活文档 规则文件本身就是最好的、最即时的编码规范文档。新成员 onboarding 时，除了阅读传统的README和规范文档，可以鼓励他们通过AI生成代码来直观地学习项目约定。看到AI生成的代码自动符合 @/ 路径别名、特定的函数命名风格，比阅读文字规范要直观得多。

3. 在代码评审中作为参考 在评审Pull Request时，如果发现某些代码片段明显违反了项目约定的模式，可以首先检查是否与 .cursorrules 文件中的定义相悖。这为代码风格讨论提供了一个客观的基准，而不是基于个人偏好的争论。

4. 持续迭代 技术栈和最佳实践在不断发展。团队应该定期（例如每季度）回顾和更新 .cursorrules 文件。可以设立一个简单的流程：任何成员在发现现有规则不适用、过时或缺失时，都可以提交一个修改规则的PR，经过团队讨论后合并。

5. 与其它工具结合 .cursorrules 可以与现有的代码质量工具链形成互补：

• ESLint/Prettier : 处理语法和格式等“硬性”规则。 .cursorrules 则指导架构、模式、API选择等“软性”但同样重要的决策。
• TypeScript : 提供编译时类型安全。 .cursorrules 可以指导如何使用高级类型特性（如 satisfies 、模板字符串类型）。
• 架构决策记录 (ADR) : 对于重大的架构决策，仍然需要ADR文档来记录上下文和权衡。 .cursorrules 可以引用这些ADR，确保AI在建议时符合既定的架构方向。

从我个人的实践来看，引入 .cursorrules 后，最显著的变化不是AI变得更“聪明”了，而是团队输出的代码变得更“一致”了。那种因为不同成员习惯不同而产生的细微风格差异大大减少，代码评审更聚焦于逻辑和架构，而非缩进或命名。它像是一位不知疲倦的、严格执行规范的结对编程伙伴，确保从代码诞生的第一刻起，就走在正确的道路上。