为什么需要规则
AI 编码的根本挑战
AI 编程助手（GitHub Copilot、Cursor、Claude Code 等）在代码生成方面已相当强大，但它们面临一个根本性问题：它们不了解你的代码库约定。
每次新的对话，AI 都是"失忆"的。它不知道：
- 你的团队使用
snake_case还是camelCase - 你的项目遵循哪种架构模式
- 哪些第三方库是你的首选
- 你的错误处理约定是什么
结果：每次对话都在重复解释背景，AI 生成的代码风格不一致，代码审查中频繁出现"这不符合我们的约定"。
Prompt 的局限性
许多团队试图通过在每次对话开头粘贴一段 "系统 prompt" 来解决这个问题：
请遵循以下约定：
1. 使用 TypeScript，开启严格模式
2. 函数使用箭头函数
3. 错误使用 Result 类型
...（20 条规则）这种方式存在显著缺陷：
| 问题 | 影响 |
|---|---|
| 需要手动粘贴 | 容易遗忘，尤其是新团队成员 |
| 不随文件类型变化 | Python 文件也会注入 TypeScript 规则 |
| 不可版本控制 | 无法追踪规则的演变历史 |
| 不可审查 | 无法像代码一样进行 code review |
| Context 占用 | 大段 prompt 占用宝贵的上下文窗口 |
规则的工程化价值
.mdc 规则文件解决了上述所有问题：
1. 自动注入，零心智负担
规则一旦放置在 .cursor/rules/ 目录，Cursor 会在每次 AI 交互时自动将匹配当前文件的规则注入上下文。开发者不需要手动粘贴，不需要记住规则。
2. 精准的文件范围控制
通过 globs 字段，规则只在需要的时候生效：
---
globs: **/*.py, tests/**/*.py
---Python 规则只在编辑 .py 文件时注入；React 规则只在编辑 .tsx 文件时生效。上下文窗口得到精确利用。
3. 可版本控制的团队约定
规则文件是普通的文本文件，提交到 Git 仓库后：
- 可以用
git log追踪规则的演变 - 可以通过 PR 对规则变更进行 code review
- 新成员
git clone后自动获得完整的规则集
4. 规则即架构文档
好的规则文件本身就是一份可执行的架构文档。当团队在讨论"我们应该遵循哪些 Python 最佳实践"时，.cursor/rules/python.mdc 就是那个答案——它不仅记录了约定，还会在每次 AI 编码时强制执行它。
规则的适用边界
规则不是万能的。了解规则的边界同样重要：
规则擅长的领域：
- 代码风格和命名约定
- 架构模式选择（如 MVVM、仓储模式）
- 依赖库偏好
- 错误处理策略
- 注释和文档风格
规则不适合的领域：
- 复杂的业务逻辑（应该通过文档或注释说明）
- 大量的项目上下文（规则应精简，不应成为文档仓库）
- 频繁变化的规范（过于细粒度的规则会增加维护成本）
规则库的设计哲学
cursor-rules 遵循以下设计哲学：
少而精：每条规则聚焦于一个技术栈或关注点。规则之间不重叠，不冗余。
可组合：多条规则可以叠加使用。typescript.mdc + react.mdc 组合适用于 React TypeScript 项目，互不干扰。
可信赖：规则内容基于行业最佳实践，经过实践验证，不引入主观偏见。
可维护：规则文件有明确的 Frontmatter 结构，支持自动验证和目录生成。
核心原则：规则库应该像
.eslintrc一样被对待——它是团队的工程约束，而不是个人的 AI 使用技巧。