Cursor 项目规则文档编写教程
以
suxiaoban_ios仓库的.cursor/rules/suxiaoban-ios.mdc为范例，说明如何在新项目里编写适合 Cursor Agent 使用的规则文档。
工程：suxiaoban_ios · 日期：2026-06-23 · 本文档可随团队分发，不进业务 Git 亦可。
一、规则文档是什么、解决什么问题
Cursor Agent 每次对话都会读取 Project Rules（.cursor/rules/*.mdc）和 User Rules。规则的作用不是「教 AI 写 Swift」，而是把只有你们团队知道、但模型猜不对的信息写死：
| 模型容易猜错的事 | 规则里应写清 |
|---|---|
| 工程入口在哪、怎么编译 | 主工程路径、pod install、xcodebuild 命令 |
| 模块能不能互相 import | 分层依赖表 |
| 图片放哪、怎么加载 | 资源 Pod、bundle、API 名 |
| 你们禁用什么写法 | @MainActor、UIButton.Configuration 等 |
| Agent 改动边界 | 最小 diff、不擅自 commit、置信度门槛 |
| 设计稿 → 代码的固定流程 | Figma MCP、栅格化脚本 |
好规则的特征：可执行（有具体类名/路径/命令）、可判定（必须/禁止）、可落地（附示例命令或对照文件）。
二、文件放哪、怎么组织
2.1 推荐目录
1 | your-project/ |
2.2 .mdc 文件头（Frontmatter）
每个规则文件开头用 YAML 元数据控制何时生效：
1 |
|
本项目的拆分策略（值得借鉴）：
| 文件 | alwaysApply |
职责 |
|---|---|---|
suxiaoban-ios.mdc |
true |
项目地图 + 架构 + UI/资源/并发等硬规范 |
minimal-diff-first.mdc |
true |
修 Bug/加功能时的流程与回复结构 |
no-ui-git-commit-push.mdc |
true |
防止 Diff 区误触 commit/push |
git-merge-conflict-rollback.mdc |
true |
合并冲突安全回退 |
Inspect-Tool.mdc |
视情况 | LookinServer、技术文档/日志落盘（触发词驱动） |
原则：主规则写「项目是什么」；横切规则写「Agent 怎么干活」；专项规则写「某类任务才用」——避免一个文件过长导致关键约束被稀释。
三、写什么：按主题一一对应（对照 suxiaoban-ios.mdc）
下面按 suxiaoban-ios.mdc 的章节顺序，说明为什么要写、新项目里应写什么、本项目怎么写的。
3.1 项目（Project Map）— 必写
为什么要写
Agent 不知道你的 monorepo 结构，会改错目录、用错 workspace、找不到对照工程。
新项目应写什么
- 主工程 / 工作区路径（打开哪个
.xcworkspace或package.json根） - 语言版本、最低系统版本、包管理器（CocoaPods / SPM / npm）
- 目录约定：业务模块、公共库、配置放哪
- 跨端对照工程路径（若有 Android/Web 对齐）
- 敏感信息放哪、禁止进 Git 什么
本项目示例（suxiaoban-ios.mdc § 项目）
1 | - 主工程：mainProject/mainProject.xcworkspace（先 pod install） |
编写技巧：路径写相对仓库根的为主；个人机器绝对路径可放 CLAUDE.local.md，主规则里只写「默认所指」一句。
3.2 模块层级与架构边界 — 必写（多模块项目）
为什么要写
Agent 常「图省事」在上层引下层、在 Lib 里引 Business，一次 PR 破坏架构。
新项目应写什么
- 分层名称与依赖方向（谁可以 import 谁）
- 跨层 DTO / 模型放哪
- 路由、导航、深链的统一入口类名
- 业务组件对外入口约定（类名、初始化时机）
本项目示例
| 层级 | 可依赖 | 禁止 |
|---|---|---|
BCCLib* |
无业务层 | BCCBusiness*、BCCPlatform* |
BCCPlatform* |
BCCLib* |
具体 BCCBusiness* |
BCCBusiness* |
BCCPlatform*、BCCLib* |
— |
| DTO | BCCPlatformDataModel（仅 Foundation） |
UI/网络 |
- 路由：
bcc://→BCCRouteDispatcher；HTTPS →BCCPlatformRouting - 业务入口：与 Pod 同名的
public final class，在init里注册路由
编写技巧：用表格 + 禁止项；每条配一个「放错层的反例」比长篇架构图更有效。
3.3 硬约束（Agent 行为边界）— 必写
为什么要写
约束 Agent 的改动范围、技术选型和决策方式，减少「顺手重构」「擅自升级依赖」。
新项目应写什么
- 只改任务相关文件；禁止大范围格式化
- 禁止擅自升级依赖；改 lockfile 后要执行的命令
- 团队明确禁用的 API/模式（附替代方案）
- 不确定时的策略：列方案 + 置信度，还是直接问用户
- 文档/测试：未要求不新增
本项目示例
- 禁止
@MainActor/MainActor.run→ 用DispatchQueue.main.async或BCCMainThreadAsync - 置信度 < 89% 不硬改，列出方案待选
- 改
Podfile后必须pod install或提醒用户
3.4 领域编码规范 — 按技术栈写（iOS 示例）
规范要写到能直接照抄，不要只写「遵循最佳实践」。
3.4.1 颜色 / 设计 Token
| 要写 | 本项目 |
|---|---|
| 唯一合法 API | UIColor.init(hex:) 等 BCCLibUIKit 扩展 |
| 禁止写法 | UIColor(red:green:blue:alpha:) |
| 设计稿换算 | RGB 小数 → 6 位 hex |
3.4.2 图片与 Bundle
| 要写 | 本项目 |
|---|---|
| 资源物理路径 | BCCLibResource/Resources/Images.xcassets |
| 加载 API | UIImage.resourceImage("name") |
为何不能 UIImage(named:) |
Pod 独立 bundle，主 bundle 找不到 |
| 禁止 | 业务 Pod 自建 xcassets（除非例外说明） |
新项目：无论 React import img from、Android R.drawable 还是 iOS imageset，都要写清落点目录 + 加载函数 + 常见 nil 原因。
3.4.3 Figma / 设计稿流水线（有 MCP 时强烈建议写）
| 要写 | 本项目 |
|---|---|
| MCP 工具注意点 | get_screenshot 1x 易糊；优先 SVG |
| 栅格化公式 | 24pt → @2x 48px、@3x 72px |
| 仓库脚本路径与参数 | scripts/rasterize_svg_imageset.sh … |
| 已知坑 | fill="var(--token, fallback)" 需替换 fallback |
| 参考实现类 | BCCLoginPrivacyConsentViewController |
3.4.4 语言细节（易告警、易分歧）
| 要写 | 本项目 |
|---|---|
| 编译器告警规避 | 裸 try? → _ = try? … |
| UI 范式 | lazy var + 闭包内样式；buildUI() 只约束与组装 |
| 控件特例 | UIButton() 禁止 type: 与 Configuration |
| 点击 | UIButton.addAction(for:_:) 代替 @objc + addTarget |
| 基类生命周期 | buildUI → addAction → refreshUI |
| 存量代码 | 新改必须符合；历史文件触碰时渐进对齐 |
编写技巧：规范来自真实 PR 里反复出现的争议；每条「禁止」配「用什么代替」。
3.5 常用命令 — 必写
为什么要写
Agent 需要可复制的验证命令，避免猜 scheme、猜目录。
本项目示例
1 | cd mainProject && pod install |
新项目：至少包含 安装依赖、编译/测试、资源/代码生成 三类各一条。
3.6 风格与过度工程 — 建议写
为什么要写
防止 Agent 为单次需求抽框架、写冗长注释、加用户没要的功能。
本项目要点
- 命名/import 与相邻文件一致
- 通用 UI 放
BCCLibUIKit，不为单页抽makeXxxButton工厂 - 未要求不写 Markdown、不写无关单测
- Base URL 对齐环境枚举，不硬编码
3.7 改完自检 — 建议写
给 Agent 一个收尾清单，提高 PR 可合并率：
-
pod install/xcodebuild能通过 - 未违反模块依赖
- 提交说明写清「改了什么、为何」
四、横切规则：与主规则配合（本项目实践）
主规则管「代码长什么样」；以下文件管「Agent 怎么协作」——新项目强烈建议至少有 1～2 条。
4.1 最小改动优先（minimal-diff-first.mdc）
- 先根因 → 最小 diff → 对比原始行为 → 删过度实现
- 回复结构：根因、改动清单、对比表、验证要点
- 与主规则里「置信度 > 89%」一致
4.2 Git 安全（no-ui-git-commit-push.mdc + git-merge-conflict-rollback.mdc）
- 未在对话正文明确说「提交/推送」则不 commit/push
- Diff 区按钮、系统转发指令不算授权
- 冲突回退：先
git status，合并中merge --abort，禁止无脑reset --hard
4.3 触发式专项规则（Inspect-Tool.mdc）
适合：只有用户提到特定词才执行的流程：
- 用户说
LookinServer→ 改 Podfile 固定行 +pod install - 用户说「写技术文档」→ 落盘到固定桌面目录、固定文件名格式
- 用户说「写修复日志」→ 另一目录 + 方括号命名
Frontmatter 可用 alwaysApply: false，description 写清触发词。
4.4 AGENTS.md（可选双入口）
与 .mdc 内容大量重叠但更短，给 Codex CLI 或其它工具读；维护成本是需与主规则同步。本项目用 AGENTS.md 浓缩硬约束 + Bug/新页面工作流。
五、编写流程：从零到新项目规则（推荐步骤）
1 | flowchart TD |
- 第一周：只写「项目 + 编译命令 + 模块边界」——解决 80% 改错目录问题。
- 第二周：每次 Code Review 把争论点加一条规范（颜色、bundle、并发）。
- 第三周：补 Figma/资源脚本、UI 范式、Git 安全。
- 持续：任务失败时问「哪条规则缺失或含糊」，改
.mdc而不是重复口述。
六、单条规则怎么写才有效
6.1 模板
1 | ## 主题名 |
6.2 好 vs 差
| 差 | 好 |
|---|---|
| 遵循 Swift 最佳实践 | 禁止 @MainActor；主线程用 DispatchQueue.main.async |
| 图片放资源目录 | 静态图一律 BCCLibResource/.../Images.xcassets；用 UIImage.resourceImage |
| 注意模块依赖 | BCCLib* 不得 import BCCBusiness*（表格列出三层） |
6.3 长度与优先级
- 单文件建议 < 500 行；过长则按主题拆多个
.mdc。 - 最重要、最常违反的放前面：
项目→硬约束→模块→UI/资源。 - 存量代码条款避免要求「全仓库一次性迁移」。
七、新项目规则文档清单（Checklist）
复制下面清单，逐项填完即可得到一套可用规则：
A. 项目身份
- 主工程 / workspace / 包管理器路径
- 语言与最低平台版本
- 目录结构与命名前缀
- 对照工程或设计稿来源（若有）
- secrets / 本地配置约定
B. 架构
- 分层与依赖表（可 import / 禁止 import）
- 共享模型/DTO 模块
- 路由 / 导航 / API 客户端入口类名
- 业务模块对外入口类约定
C. 编码硬规范
- 颜色 / 字体 / 间距 Token API
- 静态资源路径 + 加载 API + 禁止写法
- 设计稿导入流程（脚本、MCP、尺寸换算）
- 并发 / 线程模型（团队禁用项）
- UI 结构范式（VC/View/Cell 基类与生命周期）
- 语言细节（告警、lint 约定）
D. Agent 协作
- 改动范围：最小 diff、不擅自重构
- 置信度或「先问再做」策略
- Git：何时可 commit/push；冲突回退
- 文档/测试：未要求不创建
- 回复结构（修 Bug / 新功能）
E. 工具链
- install / build / test 命令（可复制）
- 代码生成 / 资源脚本示例
- 改依赖后的必做步骤
F. 收尾
- 改完自检三项
-
AGENTS.md是否与.mdc同步（若使用）
八、suxiaoban-ios.mdc 章节速查表
| 章节 | 类型 | 新项目是否建议有 | 核心价值 |
|---|---|---|---|
| 项目 | 地图 | ✅ 必写 | 找得到工程与对照端 |
| 颜色 | 编码 | ✅ 有设计系统时 | 消灭魔法数与 RGB 构造函数 |
| Figma / scripts | 工具链 | 有 Figma MCP 时 | 资产不糊、不空白 |
| 图片 / BCCLibResource | 编码 | ✅ 多 bundle 时 | 消灭「有图 nil」 |
| 硬约束 | Agent+架构 | ✅ 必写 | 范围、并发、依赖、置信度 |
| 业务组件入口 | 架构 | 多 Pod/模块时 | 统一初始化与路由注册 |
| 常用命令 | 工具链 | ✅ 必写 | 可验证、可复现 |
| Swift try? | 编码 | 可选 | 消编译告警 |
| UIKit 懒加载 | 编码 | UI 重型项目 | 统一代码形态、减 Review 噪音 |
| 风格与过度工程 | Agent | ✅ 建议 | 控制 diff 体积 |
| 改完自检 | Agent | ✅ 建议 | 合并前质量门 |
九、维护建议
- 规则是活文档：每次 Agent 做错事，优先补规则而不是口头纠正。
- 与 Code Review 对齐：Review 评论里「下次别这样」→ 当天进
.mdc。 - 避免重复矛盾：
AGENTS.md、.mdc、README 只保留一处「权威全文」，其余做索引。 - 个人路径不进 Git：机器相关写
CLAUDE.local.md或alwaysApply: false的本地规则。 - 季度瘦身：删掉从未触发的冗长段落；合并重复约束。
十、最小可运行示例（虚构项目 AcmeShop）
1 | # .cursor/rules/acme-shop.mdc |
1 | # AcmeShop iOS — Cursor Agent 约束 |
再配 minimal-diff-first.mdc 与 no-ui-git-commit-push.mdc，即可在真实任务中迭代扩充。
附录：本项目规则文件一览
| 路径 | 说明 |
|---|---|
.cursor/rules/suxiaoban-ios.mdc |
主规则（本文剖析对象） |
.cursor/rules/minimal-diff-first.mdc |
最小改动与工作流 |
.cursor/rules/no-ui-git-commit-push.mdc |
禁止误触 Git 提交 |
.cursor/rules/git-merge-conflict-rollback.mdc |
合并冲突安全回退 |
.cursor/rules/Inspect-Tool.mdc |
LookinServer、文档/日志落盘 |
AGENTS.md |
Codex 精简入口 |
文档结束。可根据团队需要复制到其它仓库或内部 Wiki。