Cursor .cursorrules 配置指南：让AI遵守团队编码规范，告别低级错误

你一定遇到过这样的场景：

你满怀期待地让Cursor帮你完成一个新功能，它不负众望，逻辑清晰、代码健壮，几乎完美。但当你准备合并代码时，却发现它压根没遵守项目的“潜规则”——它没有使用团队封装的HTTP客户端，日志格式完全错误，新建的Service类也没有继承约定的BaseService。

结果，你花了比自己写还多的时间去“擦屁股”，AI带来的效率提升，瞬间成了一场空欢喜。

问题的本质是什么？AI就像一个天赋异禀但毫无经验的实习生，它懂全世界的通用知识，却不懂你项目的“隐性知识”和“编码规范”。

今天，我们就来解决这个问题。主角，就是Cursor的灵魂功能——.cursorrules。它就是我们为这位“AI实习生”准备的“入职培训手册”和“编码规范指南”。

第一部分：`.cursorrules` 是什么？为什么它是Cursor的灵魂？

简单来说，.cursorrules 是一个位于你项目根目录下的配置文件（.cursor/rules.yml），它允许你为AI代码生成器设定一系列“行为准则”和“思维钢印”。

它不是一个简单的Linter。Linter是在代码生成后进行检查，而.cursorrules是在AI生成代码的最后一刻，像一个资深架构师一样，对AI的“草稿”进行审查和修正，确保最终输出的代码完全符合你的预期。

一句话总结：.cursorrules 让Cursor从一个“什么都懂但不懂你”的通用模型，变成一个“只为你服务”的私人代码专家。

第二部分：从0到1：手把手配置你的第一条规则

让我们从一个最简单的需求开始，感受一下.cursorrules的威力。

需求： 确保项目中所有新建的Python文件，都自动包含标准的UTF-8编码声明。

Step 1: 创建配置文件
在你的项目根目录下，创建一个路径和文件：.cursor/rules.yml。

Step 2: 编写第一条规则
在rules.yml文件中，写入以下内容：

rules:
  - name: Python File Header
    description: Ensures all Python files have the correct header.
    selector:
      language: python
    rule:
      file_header:
        template: |
          # -*- coding: utf-8 -*-

Step 3: 见证奇迹
现在，尝试让Cursor创建一个新的Python文件或模块。你会发现，无论它生成什么内容，文件顶部永远都会包含那行熟悉的# -*- coding: utf-8 -*-。

这个简单的动作，已经为你省去了无数次手动添加和Code Review中提醒的精力。这就是规则的力量。

第三部分：三大实战场景，让AI成为你的“模范员工”

掌握了基础，我们来看三个更强大的实战场景。

场景一：统一代码风格——“我们团队就这么写！”

痛点： AI生成的代码，版权信息、作者署名五花八门。
规则： file_header
实战配置：

rules:
  - name: Add Copyright Header
    description: Enforces the company's copyright and license header on all source files.
    selector:
      language: [python, go, typescript, javascript]
    rule:
      file_header:
        template: |
          // Copyright (c) 2025, TechJin Co., Ltd. All rights reserved.
          //
          // Licensed under the Apache License, Version 2.0 (the "License");
          // you may not use this file except in compliance with the License.
          // You may obtain a copy of the License at
          //
          //     http://www.apache.org/licenses/LICENSE-2.0
          //
          // Unless required by applicable law or agreed to in writing, software
          // distributed under the License is distributed on an "AS IS" BASIS,
          // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
          // See the License for the specific language governing permissions and
          // limitations under the License.

效果： 现在，无论AI生成什么语言的代码，都会被刻上团队的“烙印”，专业且统一。

场景二：遵守架构规范——“别在我的地盘上犯规！”

这是.cursorrules最核心的价值所在，强制AI遵守你的架构设计。

痛点1： AI创建的Service类，没有继承自core.BaseService。
痛点2： AI在代码里直接使用了datetime.now()，而不是我们封装的TimeUtil.get_current_time()。

规则： general
实战配置：

rules:
  - name: Enforce BaseService Inheritance
    description: All services must inherit from core.BaseService.
    selector:
      path: "src/services/**/*.py"
    rule:
      general:
        - must_contain:
            - "from core import BaseService"
            - "class .*\(BaseService\):"

  - name: Prohibit Direct Datetime Usage
    description: Must use the encapsulated TimeUtil instead of datetime.now().
    selector:
      language: python
    rule:
      general:
        - must_not_contain:
            - "datetime.now()"
        - must_contain:
            - "from utils import TimeUtil"

效果： AI被戴上了“紧箍咒”。它在生成代码时，会被强制引导去使用团队的公共库和基础类，从源头上保证了架构的一致性。

场景三：规避常见错误——“这个坑，不许再踩了！”

痛点： 团队新手和AI一样，经常写出宽泛的except Exception:，或者使用有安全风险的subprocess调用。
规则： general
实战配置：

rules:
  - name: Avoid Vague Exceptions
    description: Prevents catching broad exceptions like Exception.
    selector:
      language: python
    rule:
      general:
        - must_not_contain:
            - "except Exception:"

  - name: Secure Subprocess Usage
    description: Enforces shell=False in subprocess calls to prevent injection.
    selector:

      language: python
    rule:
      general:
        - must_not_contain:
            - "subprocess.run(.*shell=True.*)"
            - "subprocess.call(.*shell=True.*)"

效果： 你将团队多年踩坑总结出的血泪教训，变成了AI的“肌肉记忆”。那些最容易被忽略、但却可能引发严重问题的低级错误，将很难再出现在你的代码库中。