Tutorial 4: Rules 与配置

Abstract	Cursor Rules 配置与最佳实践
Authors	Walter Fan
Status	WIP
Updated	2026-02-07

什么是 Cursor Rules 

Cursor Rules 是一种让 AI 遵循特定规范的机制。通过配置 Rules，你可以：

定义代码风格和规范
指定技术栈和框架
设置项目特定的约定
提供领域知识和上下文

为什么需要 Rules 

没有 Rules 时：

AI 可能使用你不喜欢的代码风格
AI 可能不了解你的项目结构
AI 可能使用过时的 API
每次都需要重复说明要求

有了 Rules：

AI 自动遵循你的规范
代码风格一致
减少重复沟通
提高生成质量

Rules 的类型 

Cursor 支持多种类型的 Rules：

Rules 类型

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   ┌─────────────────┐   ┌─────────────────┐                    │
│   │   Global Rules  │   │  Project Rules  │                    │
│   │   全局规则       │   │   项目规则       │                    │
│   ├─────────────────┤   ├─────────────────┤                    │
│   │ ~/.cursor/rules │   │ .cursor/rules   │                    │
│   │ 所有项目生效     │   │ 仅当前项目生效   │                    │
│   └─────────────────┘   └─────────────────┘                    │
│                                                                 │
│   ┌─────────────────┐   ┌─────────────────┐                    │
│   │  .cursorrules   │   │ Cursor Settings │                    │
│   │   项目根目录     │   │   设置中配置     │                    │
│   ├─────────────────┤   ├─────────────────┤                    │
│   │ 简单配置        │   │ 图形界面配置     │                    │
│   │ 向后兼容        │   │ 用户级别        │                    │
│   └─────────────────┘   └─────────────────┘                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

1. .cursorrules 文件 

最简单的方式，在项目根目录创建 .cursorrules 文件：

# .cursorrules

You are an expert Python developer.

## Code Style
- Use Python 3.11+ features
- Follow PEP 8 style guide
- Use type hints for all functions
- Write docstrings in Google style

## Project Structure
- Use src/ layout
- Tests go in tests/ directory
- Use pytest for testing

## Dependencies
- Use Poetry for dependency management
- Prefer standard library over third-party

2. .cursor/rules 目录 

更灵活的方式，可以按文件类型或模块配置不同规则：

.cursor/
└── rules/
    ├── global.md        # 全局规则
    ├── python.md        # Python 特定规则
    ├── typescript.md    # TypeScript 特定规则
    └── testing.md       # 测试相关规则

global.md:

# Global Rules

## General Principles
- Write clean, readable code
- Prefer simplicity over cleverness
- Always handle errors appropriately

## Documentation
- Add comments for complex logic
- Keep README up to date

python.md:

---
description: Rules for Python files
globs: ["**/*.py"]
---

# Python Rules

## Style
- Use Black for formatting
- Use isort for imports
- Maximum line length: 88 characters

## Type Hints
- All functions must have type hints
- Use `from __future__ import annotations`

## Error Handling
- Use specific exception types
- Always log exceptions

3. Cursor Settings 

在 Settings → Rules 中配置用户级别的规则：

打开 Settings（Cmd+,）
搜索 “Rules”
在文本框中输入规则

这些规则会应用到所有项目。

Rules 语法详解 

基本结构 

Rules 使用 Markdown 格式，支持 YAML front matter：

---
description: 规则描述
globs: ["**/*.py", "**/*.pyi"]
alwaysApply: false
---

# 规则标题

## 分类 1
- 规则内容

## 分类 2
- 规则内容

Front Matter 选项 

选项	类型	说明
description	string	规则的简短描述
globs	string[]	文件匹配模式
alwaysApply	boolean	是否总是应用（默认 false）

Globs 模式示例 

# 所有 Python 文件
globs: ["**/*.py"]

# 特定目录
globs: ["src/**/*.py"]

# 多种文件类型
globs: ["**/*.ts", "**/*.tsx"]

# 排除测试文件
globs: ["**/*.py", "!**/test_*.py"]

实用 Rules 示例 

Python 项目 Rules 

---
description: Python project rules
globs: ["**/*.py"]
---

# Python Development Rules

## Environment
- Python 3.11+
- Use Poetry for dependency management
- Use pyproject.toml for configuration

## Code Style
- Follow PEP 8
- Use Black formatter (line length 88)
- Use isort for import sorting
- Use Ruff for linting

## Type Hints
- All functions must have type hints
- Use `from __future__ import annotations`
- Use `typing` module for complex types

## Documentation
- Use Google-style docstrings
- Include type info in docstrings
- Add examples for complex functions

## Error Handling
- Use specific exception types
- Create custom exceptions when needed
- Always log exceptions with context

## Testing
- Use pytest
- Test file naming: test_*.py
- Aim for 80%+ coverage
- Use fixtures for common setup

## Example Function

```python
from __future__ import annotations

def calculate_total(
    items: list[dict[str, float]],
    tax_rate: float = 0.1,
) -> float:
    """Calculate total price with tax.

    Args:
        items: List of items with 'price' key.
        tax_rate: Tax rate as decimal. Defaults to 0.1.

    Returns:
        Total price including tax.

    Raises:
        ValueError: If items list is empty.

    Example:
        >>> items = [{'price': 10.0}, {'price': 20.0}]
        >>> calculate_total(items)
        33.0
    """
    if not items:
        raise ValueError("Items list cannot be empty")

    subtotal = sum(item['price'] for item in items)
    return subtotal * (1 + tax_rate)
```

TypeScript/React 项目 Rules 

---
description: TypeScript React project rules
globs: ["**/*.ts", "**/*.tsx"]
---

# TypeScript React Rules

## Environment
- TypeScript 5.x
- React 18.x
- Next.js 14.x (App Router)

## Code Style
- Use ESLint + Prettier
- Use functional components
- Use hooks, no class components

## Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with 'use' prefix (useAuth.ts)
- Utils: camelCase (formatDate.ts)
- Types: PascalCase with suffix (UserType, UserProps)

## Component Structure
```tsx
// 1. Imports
import { useState } from 'react';

// 2. Types
interface Props {
  title: string;
  onSubmit: (data: FormData) => void;
}

// 3. Component
export function MyComponent({ title, onSubmit }: Props) {
  // 3.1 Hooks
  const [state, setState] = useState('');

  // 3.2 Handlers
  const handleClick = () => {};

  // 3.3 Render
  return <div>{title}</div>;
}
```

## State Management
- Local state: useState
- Complex state: useReducer
- Global state: Zustand or Context
- Server state: TanStack Query

## Styling
- Use Tailwind CSS
- Use cn() for conditional classes
- Prefer utility classes over custom CSS

API 开发 Rules 

---
description: REST API development rules
globs: ["**/api/**/*.py", "**/routes/**/*.py"]
---

# API Development Rules

## Design Principles
- RESTful design
- Use proper HTTP methods
- Use proper status codes
- Version APIs (v1, v2)

## Response Format
```json
{
  "success": true,
  "data": {},
  "message": "Success",
  "timestamp": "2024-01-01T00:00:00Z"
}
```

## Error Response
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": []
  },
  "timestamp": "2024-01-01T00:00:00Z"
}
```

## Status Codes
- 200: Success
- 201: Created
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error

## Validation
- Validate all input
- Use Pydantic models
- Return detailed error messages

## Security
- Use JWT for authentication
- Rate limiting on all endpoints
- Input sanitization
- CORS configuration

Rules 最佳实践 

1. 保持简洁 

不要写太长的 Rules，AI 可能无法完全遵循：

# 好的做法
- Use Python 3.11+
- Follow PEP 8
- Use type hints

# 不好的做法（太详细）
- Use Python 3.11 or higher versions...
- Follow PEP 8 style guide which includes...
- Use type hints according to PEP 484...

2. 提供示例 

示例比规则描述更有效：

## Error Handling

Good:
```python
try:
    result = process(data)
except ValidationError as e:
    logger.error(f"Validation failed: {e}")
    raise
```

Bad:
```python
try:
    result = process(data)
except:
    pass
```

3. 分层组织 

使用多个 Rules 文件，按职责分离：

.cursor/rules/
├── global.md       # 通用规则
├── python.md       # Python 规则
├── frontend.md     # 前端规则
├── api.md          # API 规则
└── testing.md      # 测试规则

4. 版本控制 

将 Rules 文件纳入版本控制，团队共享：

git add .cursorrules
git add .cursor/rules/
git commit -m "Add Cursor rules for project"

5. 定期更新 

随着项目演进，更新 Rules：

技术栈升级
新的代码规范
团队约定变化

调试 Rules 

检查 Rules 是否生效 

打开 Chat
输入：@rules 显示当前生效的规则
或者在对话中观察 AI 是否遵循规则

常见问题 

Rules 没有生效

检查文件位置是否正确
检查 globs 模式是否匹配
重启 Cursor

Rules 冲突

项目规则优先于全局规则
更具体的 globs 优先
后定义的规则优先

Rules 太长

精简规则内容
只保留最重要的规则
使用示例代替详细描述

实战：为项目配置 Rules 

步骤 1：分析项目 

首先了解项目的技术栈和规范：

使用什么语言和框架？
有什么代码规范？
项目结构是怎样的？

步骤 2：创建基础 Rules 

创建 .cursorrules 文件：

# Project: My Awesome App

## Tech Stack
- Python 3.11 + FastAPI
- PostgreSQL + SQLAlchemy
- React + TypeScript

## Code Style
- Backend: PEP 8 + Black
- Frontend: ESLint + Prettier

## Project Structure
- backend/: Python API
- frontend/: React app
- docs/: Documentation

步骤 3：添加特定规则 

为不同模块创建专门的规则：

mkdir -p .cursor/rules
touch .cursor/rules/backend.md
touch .cursor/rules/frontend.md

步骤 4：测试和迭代 

使用 AI 生成代码
检查是否符合规则
根据结果调整规则

小结 

本教程介绍了 Cursor Rules 的配置方法：

Rules 类型: .cursorrules、.cursor/rules、Settings
语法: Markdown + YAML front matter
最佳实践: 简洁、示例、分层、版本控制

关键要点：

Rules 让 AI 遵循你的规范
好的 Rules 需要示例
定期更新 Rules

下一步 

在下一个教程中，我们将学习提示词（Prompting）技巧，让 AI 更好地理解你的意图。

练习 

为你的项目创建一个 .cursorrules 文件
创建至少 3 个不同的规则文件
测试规则是否生效
与团队分享你的规则配置