😨先说痛点：为什么"会用大模型"还不够
把大模型接入日常开发后，多数团队很快会撞到同一堵墙——问题不是模型"写不出代码"，而是它"不懂我们的代码" ：
- 每次对话都要重新交代上下文：架构分层、命名前缀、用哪个网络基类、布局用 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 操作说明
- 谁在匹配：在 Agent 模式下，Cursor 根据 SKILL.md 顶部 YAML 的 description 自动匹配
- 提高命中率：说法尽量带上领域词；未触发时直接
@对应 SKILL.md - 子参考文件：
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
小结:
- 使用本方案后，Token降本率: 56.56%
- 生码准确率无法数字量化，从体感上来讲，分析+生成的效率更高了.
🚥落地经验与避坑（最值得带走的部分）
如果你打算在自己团队复制这套体系，下面这些是我们用返工换来的经验：
- 从"高频 + 痛"的场景切入，而不是追求大而全。 我们最先做的是"需求开发"和"创建组件"——它们占据了日常 80% 的重复劳动，收益立竿见影，也最容易让团队建立信任。
- Rules 要少而精，单文件单职责。 通用规则建议 ≤50 行、核心规则 ≤200 行。规则太长太杂，模型反而抓不住重点，注入成本也高。
- 冲突优先级必须显式写明。 多模块项目尤其如此，否则模型会在矛盾规则间随机选择。
- 给 Skill 划清边界（互斥/前置条件）比堆功能更重要。 模型选错流程的代价，往往比流程本身不完美更高。
- SSOT 优先治"易混淆"。 防幻觉的 ROI 集中在那些"产品/接口/代码三套命名对不齐"的概念上。
- 始终"人在回路"。 AI 产出必须过人工 Review 和真机测试；大需求坚持"先计划后写码"。
- 配置即代码，走 Git + MR 演进。 规则和能力随仓库版本化管理，团队
git pull即同步；改配置和改代码一样需要评审。 - 建立"自检"闭环。 每次改动 Rules/Skills 后跑一遍端到端自检，确保能力没有回退——AI 配置同样会"腐化"。
- 上线后复盘反哺配置。 把需求中暴露的"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。飞轮一旦转起来，会比你预期的更快。
