让 AI 真正读懂你的代码：一套可复用的 Cursor 辅助编码实践

😨先说痛点：为什么"会用大模型"还不够

把大模型接入日常开发后，多数团队很快会撞到同一堵墙------问题不是模型"写不出代码"，而是它"不懂我们的代码" ：

• 每次对话都要重新交代上下文：架构分层、命名前缀、用哪个网络基类、布局用 Masonry 还是 StackView......讲一遍，下一轮又忘了。
• 产品语言、接口、设计稿、代码符号四套话术对不齐 ：PM 说"过户车"，接口字段叫 transfer_flag，代码里是 OrderTransferModel，AI 只能靠猜，返工不断。
• 工作流没有沉淀：审查、提交、MR、崩溃分析，每个人一套 prompt，质量飘忽，无法复用，也无法演进。
• 模型容易"自信地编造" ：在它不了解的业务概念上，它会发明一个看起来合理、实则不存在的类名或字段。

一句话总结：通用模型缺的不是智力，而是"这个项目的常识" 。而常识恰恰是团队最宝贵、也最难口口相传的隐性资产。

🎯它能解决什么问题

目标1: 降低Token无效的消耗使用

目标2: 生码更精准，返工率更低.

• 我们在司机主仓库里把「项目约束 + 标准工作流」沉淀为 Cursor 可读的机器配置 ：Rules（被动规则） 与 Skills（主动能力） ，再配合 领域知识 SSOT 与 MCP（Figma / GitLab） ，让 Agent 在 代理模式下按团队约定自动编排任务。
• 我们没有去追求"一个超级 prompt 解决一切"，而是把能力拆成职责清晰的三层，分别解决"约束、流程、事实"三个不同维度的问题

┌──────────────────────────────────────────────────────────┐
│  Skills（主动能力）------ 解决"怎么做一件复杂的事"                 │
│  自然语言意图触发，编排多步工作流                              │
│  需求开发 / 建组件 / 审查 / 调试 / 提交 / 自检                │
├──────────────────────────────────────────────────────────┤
│  Rules（被动规则）------ 解决"该守哪些规矩"                       │
│  按 alwaysApply 或 文件路径(glob) 自动注入上下文              │
│  架构 / 编码规范 / UI / 模块专约 / Git / 审查格式             │
├──────────────────────────────────────────────────────────┤
│  领域 SSOT（单一事实源）------ 解决"业务到底是什么"                │
│  概念表 / 接口契约 / 链路 / 状态机 / 路由 / 埋点               │
│  防止模型"编造"业务概念                                      │
└──────────────────────────────────────────────────────────┘
            ↑ 之外，再用 MCP 打通 Figma / GitLab，连接设计与协作

这套结构背后有一个简单的判断：

层	它回答的问题	类比	谁主动
Rules	"在这个项目里，代码该长什么样？"	入职须知 / 团队规约	系统自动注入
Skills	"做需求 / 审查 / 修 bug 的标准动作是什么？"	标准作业流程（SOP）	自然语言触发
SSOT	"这个业务概念到底对应什么？"	业务词典 / 架构文档	规则引导查阅
MCP	"设计稿和 MR 在哪、长什么样？"	外部系统接口	工具按需调用

触发方式 ：在 Cursor Agent（代理）模式 对话中用自然语言描述意图，Agent 会根据 Skills 的 description 自动匹配对应能力。若未触发，可手动 @ 对应 SKILL.md 或写明「按 xxx 技能执行」。

⛳️功能简介

---

📐 能力体系介绍

体系简介

本指南把「项目怎么写、需求怎么走、常见问题怎么排查」固化进仓库的 .cursor/ 目录，与项目代码 Git 同步，开箱即用。

能力	说明
需求开发编排	描述业务需求 → 自动分析 → 产出开发计划 → 你确认后再改代码；可对接 Figma、接口契约与模块路径说明。
模板级代码生成	按项目基类与规范生成 View / Cell / VC、网络请求与 YYModel 等，减少重复抄写。
质量与调试	代码审查 checklist、崩溃日志分析、非崩溃类 Bug 排查与最小改动修复等工作流。
交付配套	需求澄清、仅方案不写码、接口契约梳理、设计还原检查、冒烟清单、规范化中文提交说明等 Skill。
领域对齐	抢单大厅、履单、RN/、* /API/ 等路径由不同 Rule 约束.

定位 ：这不是单独安装的 App，而是 Cursor IDE + 本仓库配置 下的团队级 AI 辅助编码能力包。

本指南包含团队共享的 Cursor AI 能力配置，git pull 即可获取所有能力。仓库根的 AGENTS.md 是面向 Cursor / Claude Code 等 Agent 工具的统一入口。

Rules（被动规则）--- 自动生效

文件	作用	生效条件
project-architecture.mdc	项目架构上下文	始终生效
domain-glossary.mdc	业务领域术语词典	业务源码上下文
driver-domain-ssot.mdc	司机域 SSOT 入口	业务源码上下文
ios-code.mdc	编码规范	*.{h,m,mm,c,swift}
ui-development.mdc	UI 开发模式	*.{h,m,mm,c,swift}
order-hall.mdc	OrderHall 大厅域约定	OrderHall/**/*
rn-bridge.mdc	RN 桥接规范	RN/**/*.{h,m,mm,swift}
network-request.mdc	API Request 规范	API/**/*.{h,m,mm,swift}
code-review.mdc	代码审查优先级	审查代码时
git-workflow.mdc	Git 工作流规范	Git 操作时

履单 Order/ 专项约定见 order-module.mdc （按需 @ 或上下文命中时参考）

Skills（主动能力）--- 意图触发

如果说 Rules 是"静态护栏"，Skills 就是"动态剧本"。每个 Skill 是一个目录，入口是 SKILL.md，头部的 description 写清"做什么（WHAT）+ 何时触发（WHEN，含关键词）"。在 Agent 模式下，开发者用自然语言描述意图，Cursor 根据 description 自动匹配并执行多步流程。

我们沉淀的能力清单

Skill	触发关键词	目录
需求开发编排	需求开发、功能开发、改版、新增功能	/feature-development
创建组件	创建 View、新建 Cell、创建页面、创建 VC、写网络请求	/create-component
代码审查（本地）	审查代码、review、代码质量	/objc-code-review
GitLab MR 审查	MR 审查、review MR、审查合并请求	/gitlab-mr-review
崩溃调试	崩溃、crash、分析日志	/debug-crash
Bug 排查修复	Bug 排查、修 bug、逻辑不对、界面不对	/debug-bug-fix
提交暂存区并推送	提交、commit、push、git 提交	/git-commit-push
能力体系自检	能力自检、validate、cursor 验证	/validate-cursor

Skills 操作说明

1. 谁在匹配：在 Agent 模式下，Cursor 根据 SKILL.md 顶部 YAML 的 description 自动匹配
2. 提高命中率 ：说法尽量带上领域词；未触发时直接 @ 对应 SKILL.md
3. 子参考文件 ：feature-development 下的子文件由编排自动引用，也可手动 @ 单独使用

三个值得借鉴的设计细节

1）复杂流程拆成"主编排 + 参考子文件"。 以需求开发为例，主 SKILL.md 负责编排，把易变细节拆成可单独调用的子文件：产品语言拆解、需求澄清、接口契约、设计验收、计划与代码 diff 一致性校验、冒烟清单、上线复盘。这样主流程稳定，细节可独立演进。

2）用"互斥"避免模型选错路。 崩溃分析和 Bug 排查是两个截然不同的方法论：前者从堆栈逆推，后者从现象正查。我们在两个 Skill 的描述里明确写了互斥规则 ------有崩溃堆栈走崩溃分析，纯逻辑/UI 异常走 Bug 排查。给模型划清边界，比指望它自己判断更可靠。

3）"先计划，后写码"作为默认契约。 需求类 Skill 默认先产出方案、等人确认再动代码。开发者只要在需求里补一句"先出计划，我确认后再改"，就能避免 AI 越权大改。

---

为什么没有 Prompts

早期版本v1.0在 .cursor/prompts/ 下维护了一批 .md 文件（feature-dev.md、create-vc.md、fix-bug.md 等），作为固定模板让用户 @ 引用。实践中发现几个问题：

• Prompts 是静态模板 ，用户需要手动 @ 正确的文件、按格式填空，选错或漏填就走偏。
• Skills 是动态工作流 ，Agent 根据 description 中的关键词自动匹配，内部可以分步读取参考文件、调 MCP、串联多个子流程，不需要用户关心调度细节。
• 维护成本翻倍：Prompt 和 Skill 描述的是同一件事，两套文件容易不一致。

所以现在的策略是：Prompts 全部迁移为 Skills ，原 prompts/ 目录已废弃删除。用户只需用自然语言描述意图，Agent 自动选 Skill 执行；实在没触发时 @ 对应 SKILL.md 即可。

🗺️ 决策树

需求开发决策树

缺陷排查决策树

---

📚 领域知识（SSOT）根治"AI 一本正经地胡说"

模型幻觉在业务代码里最典型的表现，就是编造一个不存在的字段名或业务概念。光靠 Rules 约束代码风格解决不了这个问题------它缺的是"事实"，不是"规矩"。

我们的对策是建立一份司机域单一事实源（Single Source of Truth） ，放在与 AI 配置并列的 docs/driver-domain/ 下：

文件	内容
concepts.yaml	业务概念 id、定义、别名
contracts.md	接口契约样例与文档入口
flows.md	关键链路端到端说明
error-codes.md	错误码 / 业务状态码
routes.md	路由路径常量
state-machines/order-status.md	订单状态机
feature-flags.md	特性开关 / 灰度
telemetry.md	埋点事件 id
design-tokens.md	设计令牌

再用一条"领域入口规则"在进入业务源码上下文时自动引导模型优先查阅这些文件 。效果是：当 PM 说"过户车"，模型不再凭感觉造类名，而是先去 concepts.yaml 找到这个概念对应的真实符号和别名。

经验：SSOT 的价值不在"全"，而在"权威且唯一"。 哪怕只先维护"易混淆概念"和"接口字段映射"两块，防幻觉的收益就已经非常明显。

---

🧰MCP：把设计与协作系统接进对话

Rules + Skills + SSOT 解决了"代码内"的问题，但真实研发还要跨系统。我们通过 MCP（Model Context Protocol）打通了两个高频外部源：

• Figma MCP：需求带设计稿时，由 Agent 直接拉取设计上下文，配合"设计验收"子流程补齐空态 / 错误态 / 加载态 / 暗黑模式等边界；
• GitLab MCP：MR 审查时拉取真实 diff、按 checklist 审查、并在确认后把意见回写到 GitLab。

这一层把"AI 编码"从孤立的代码补全，升级成贯穿设计 → 编码 → 审查 → 协作的研发助手。

---

🚀 快速开始

需求开发（最常用）

在 Cursor 对话中描述你的需求，Agent 会自动匹配 /feature-development 技能：

/feature-development  (此行可选)
我需要改版待办列表页面，
UI 参考 https://figma.com/design/xxxx/subnode/xxx
逻辑变更：1. 新增紧急标签筛选 2. 列表支持排序
涉及模块：OrderHall/Classes/TodoList/
先出开发计划，我确认后再改代码。

需求开发子参考文件

场景	参考文件
PRD/需求 → 业务实体识别	@prd-decompose.md
需求澄清与验收边界	@requirement-intake.md
接口 JSON / 契约表	@api-contract.md
Figma 还原与状态检查	@figma-acceptance.md
只出方案、不写代码	需求中写明「只出方案 / plan-only」
改动后冒烟自测	@smoke-checklist.md
plan ↔ diff 一致性校验	@plan-verify.md
上线后复盘	@retro.md

快速创建组件

对话中说"创建 独立View组件"、"创建工具SDK"等，自动匹配 /create-component：

/create-component (此行可选)
帮我新建一个大厅列表用的 悬浮动画组件：类名你来定
展示订单数量、状态，点击整行回调 delegate。
放在 OrderHall/Classes/Hall/Components/Views/ 这一带。

代码审查与调试

场景	技能	触发方式
代码审查（本地）	/objc-code-review	"审查代码"、"review"
GitLab MR 审查	/gitlab-mr-review	"MR 审查"，附 MR 链接
分析崩溃日志	/debug-crash	"崩溃分析"、"crash"
Bug 排查与修复	/debug-bug-fix	"Bug 排查"、"修 bug"

Git 操作

场景	技能	触发方式
生成 commit + push	/git-commit-push	"提交推送"、"commit"
审查 Merge Request	/gitlab-mr-review	"MR 审查"，附gitlab链接

AI辅助编码能力体系自检

说"能力自检"、"validate"即可触发，对需要变更的Rules / Skills 进行端到端验证。

---

🚚实战演示

需求开发编排

描述需求

生成开发计划

执行计划并查看变更代码

token消耗量

代码审查

需求Bug修复

git代码提交

他人Gitlab代码审查&报告

输入gitlab链接并执行

Gitlab PR页面评论点

❓ 常见问题

Q: Rules 没有生效？

A: 确认文件在 .cursor/rules/ 下且扩展名为 .mdc；YAML 头无语法错误。改完后新开对话或重启 Cursor。

Q: globs 类 Rule 有时感觉没带进对话？

A: 请将相关 .h/.m @ 进对话，或先在编辑器中打开目标文件再提问。

Q: Skill 没有被自动触发？

A: 确认处于 Agent 模式 ；仍不触发时直接 @ 对应 SKILL.md。

Q: Agent 没等确认就直接改代码？

A: 需求里写清**「先给开发计划，我确认后再修改代码」 ；或说「只出方案 / plan-only」**。

Q: 接口 JSON 很大，怎样少返工？

A: 先 @api-contract.md 出字段与 YYModel 注意点，再走需求开发。

Q: @analyze-crash.md 和 @fix-bug.md 怎么选？

A: 以崩溃日志为主 说「崩溃分析」。不崩溃或逻辑/UI/数据不符说「Bug 排查」。

---

🆚Token消耗对比PK

需 求: "下线 todoBizAB==0 的代码"

使用模型: Claude Opus 4.6

操作步骤: 先生成Plan，再执行Plan (基于能力基建的不会生成xxxx_plan.md文档)

基于辅助编码基建能力

提示词: "需求开发: 下线 todoBizAB==0 的代码"

总消耗: $2.75

无辅助编码基建能力

提示词: "需求开发: 下线 todoBizAB==0 的代码"

总消耗: $6.33

小结:

1. 使用本方案后，Token降本率: 56.56%
2. 生码准确率无法数字量化，从体感上来讲，分析+生成的效率更高了.

🚥落地经验与避坑（最值得带走的部分）

如果你打算在自己团队复制这套体系，下面这些是我们用返工换来的经验：

1. 从"高频 + 痛"的场景切入，而不是追求大而全。 我们最先做的是"需求开发"和"创建组件"------它们占据了日常 80% 的重复劳动，收益立竿见影，也最容易让团队建立信任。
2. Rules 要少而精，单文件单职责。 通用规则建议 ≤50 行、核心规则 ≤200 行。规则太长太杂，模型反而抓不住重点，注入成本也高。
3. 冲突优先级必须显式写明。 多模块项目尤其如此，否则模型会在矛盾规则间随机选择。
4. 给 Skill 划清边界（互斥/前置条件）比堆功能更重要。 模型选错流程的代价，往往比流程本身不完美更高。
5. SSOT 优先治"易混淆"。 防幻觉的 ROI 集中在那些"产品/接口/代码三套命名对不齐"的概念上。
6. 始终"人在回路"。 AI 产出必须过人工 Review 和真机测试；大需求坚持"先计划后写码"。
7. 配置即代码，走 Git + MR 演进。 规则和能力随仓库版本化管理，团队 git pull 即同步；改配置和改代码一样需要评审。
8. 建立"自检"闭环。 每次改动 Rules/Skills 后跑一遍端到端自检，确保能力没有回退------AI 配置同样会"腐化"。
9. 上线后复盘反哺配置。 把需求中暴露的"AI 不懂的点"沉淀回 Rules/SSOT，形成正向飞轮。

🏅未来展望 (端到端需求交付自动化)

给一份需求 -> 方案设计 -> 代码开发 -> 编译运行 -> 测试用例 -> 代码提交 -> 报告清单

环节	当前能力覆盖度	AI 能做到	AI 做不到
方案设计	90%	自动拆解、影响面扫描、生成计划	替代产品经理判断业务优先级
代码开发	80%	按规范生成符合项目风格的代码	写出需要深度业务理解的复杂状态机
编译运行	0%	执行 xcodebuild 并修复常见编译错误	处理 Pod 依赖冲突、签名问题、环境差异
测试用例	0%	生成 Model/工具类单元测试	替代手工 UI 测试、集成测试
代码提交	85%	生成规范 commit message、plan 校验	替代 Code Review 中的业务逻辑审查
报告清单	50%	汇总所有环节产出为结构化报告	判断"是否可以上线"的最终决策

总结：AI 能覆盖重复性、结构化的工作（约 70-80%），核心判断仍需人在环。目标不是"完全替代"，而是"人只需要做决策确认，其余 AI 代劳"。

🏖️写在最后

大模型不会自动理解你的项目，但你可以主动把项目"讲"给它听------只不过这次"讲"的方式，是写成结构化、版本化、机器可读的配置。

我们的实践证明：真正的杠杆不在于换更强的模型，而在于把团队的隐性知识资产化、工程化。 Rules 立规矩、Skills 定流程、SSOT 给事实、MCP 接系统------四者合一，AI 才从"通用工具"变成"懂你项目的同事"。

如果这篇文章对你有启发，不妨从你团队最高频、最痛的那一个场景开始，写下第一条 Rule 和第一个 Skill。飞轮一旦转起来，会比你预期的更快。