主题
Cursor Rules
Cursor Rules 是给 Cursor / Cline / Windsurf 这类 IDE Agent 用的项目规范，作用和 CLAUDE.md 一样：告诉模型你的项目该怎么写。
现代写法：.cursor/rules/
新版 Cursor 用目录形式，一条规则一个 .mdc 文件：
your-project/
├── .cursor/
│ └── rules/
│ ├── general.mdc
│ ├── frontend.mdc
│ └── database.mdc
└── src/文件格式
markdown
---
description: 前端组件编写规范
globs:
- "web/src/**/*.tsx"
- "web/src/**/*.ts"
alwaysApply: false
---
# 前端规范
- 组件一律函数式 + hooks，禁止 class 组件
- 状态优先用局部 `useState`，跨组件才上 store
- 所有用户可见文案走 i18n：`t('English key')`，禁止硬编码中文
- Tailwind 类名超过 8 个就抽成 `cn()` 变量
- 表单校验用 zod schema，不要手写 if 链frontmatter 三个字段
| 字段 | 作用 |
|---|---|
description | 规则用途，模型据此判断要不要加载 |
globs | 匹配到这些文件时自动注入该规则 |
alwaysApply | true = 每次都加载；false = 按 glob / description 按需加载 |
用 globs 分片是省钱的关键
把规则按目录切开，只有改到对应文件时才注入。 一个 500 行的全局规则每次请求都要付钱；切成 5 个 100 行的按需规则，实际每次只加载其中一份。
旧写法：.cursorrules
项目根目录一个纯文本文件，全局生效、无条件加载：
你是一个资深 Go 工程师。
- 所有金额用 decimal，禁止 float
- 错误必须用 %w 包装
- 不要自动 git commit仍然可用，但没有 glob 分片能力。新项目直接用 .cursor/rules/。
写什么才有用
和 CLAUDE.md 一个道理：规则必须可判定。
markdown
# ✅ 有效
- API 返回统一用 `{ code, message, data }` 结构
- 数据库查询必须走 repository 层，controller 里不准出现 `db.`
- 新增接口必须同时在 `docs/openapi.yaml` 里补 schema
- 时间字段一律存 UTC，展示层再转时区
# ❌ 无效
- 代码要清晰易读
- 注意安全性
- 遵循 SOLID 原则常用规则模板
通用（general.mdc，alwaysApply: true）
markdown
---
description: 项目通用约定
alwaysApply: true
---
# 通用
## 命令
- 装依赖：`pnpm i`
- 开发：`pnpm dev`
- 测试：`pnpm test`
- 类型检查：`pnpm typecheck`
## 铁律
- 改完代码必须能通过 `pnpm typecheck && pnpm test`
- 不要新增依赖，需要时先问我
- 不要自动提交 git
- 回答用中文，代码注释用英文后端（backend.mdc，按 glob）
markdown
---
description: 后端 API 规范
globs:
- "server/**/*.ts"
alwaysApply: false
---
- 路由只做参数校验，业务逻辑写在 `service/`
- 所有外部调用加超时和重试
- 日志用结构化字段，禁止字符串拼接
- 事务边界在 service 层，repository 不开事务Cline / Windsurf 的对应机制
| 工具 | 规则文件 |
|---|---|
| Cursor | .cursor/rules/*.mdc 或 .cursorrules |
| Cline | .clinerules 或 .clinerules/*.md |
| Windsurf | .windsurfrules |
| Claude Code | CLAUDE.md |
| Codex | AGENTS.md |
一份内容，多处引用
把真正的规范写在 AGENTS.md 里，其它文件只写一行引用：
# .cursorrules
参见 AGENTS.md避免五份文件互相漂移。
和成本的关系
规则文件属于每次请求都会带上的上下文。在快米兔 API 上：
- 规则内容稳定不变 → 会命中 Prompt Cache，按十分之一价格计费
- 频繁改规则 → 每改一次缓存重建，反而更贵
所以：规则一次写好，别天天调。