AI代码生成率94%:我们用一个 Skill 跑通需求开发全流程
一、问题:AI 写业务代码为什么总是"差一口气"?
把"AI 辅助编码"放到企业级真实项目里,我们很快撞上一堵墙。下面这几个场景,每个移动端同学应该都不陌生:
didSelectRowAtIndexPath | |
一句话总结:AI 不是不会写代码,是不会"按工程规范"开发需求。
我们的解法不是换更大的模型,而是把"需求开发"这件事流程化、原子化、可校验化,然后把每一步都喂给 AI。
二、整体架构:把"需求开发"拆成 8 个语义化阶段
Skill 的核心是一条严格顺序的流水线。每个阶段输入清晰、产出明确、退出标准可机器校验。结合人日常的开发的流程,大概可以分成以下的流程:
子步骤命名约定:Skill 内部统一采用「阶段·动作」式命名,例如
设计稿·脚本筛选、实现·UI·切图、拆解·TAPD收料——这让 AI 在自报家门时永远清楚自己在哪一格上。
| 脚本化直方图筛选 | |||
subtasks.json 接力台账 | 多源收料 + 归宿校验 | ||
| 五步定位法 | |||
| 自底向上 | |||
bazel build | |||
TECH_SPEC.md | 跨会话知识传承的载体 | ||
三、第一性原理:Skill 为什么这样设计?
整条流水线背后只回答一个问题:怎样让一个没参与过原始实现的AI,在新会话里像"参与过的老同事"一样把活干完?
围绕这个目标,Skill 的设计原则可以收敛成四条公理:
下面把这四个公理逐个拆开看。
四、公理 Ⅰ:每一步都在"缩小范围"——五步定位法
大模型不是搜索引擎,把整个项目 find . 丢给它毫无意义。Skill 把"在 9000+ 文件里找到改动点"这件事拆成 5 个收敛步骤,每步 Token 消耗严格控制。
rg 直接跑 | ||
真正的窍门:前 2 步只看目录和文件名,第 3 步才让脚本 grep,到第 4 步才真正读代码。一路漏斗下来,模型从来不会被整个代码库淹死。
但这里还有一个前置问题没解决——五步定位法的第 1、第 2 步都依赖一个东西:项目本身得有一张"AI 看得懂"的地图。否则"项目概述 ~2K"从哪儿来?"目录树 + 解读"凭什么这么准?
下一节我们就讲:这张地图是怎么造出来、怎么维护、并且如何永不过时的。
五、代码知识库:让 AI 拥有项目的"地图"
定位精准的前提,是 AI 手里要有一份结构化、最新、可索引的项目知识。Skill 在这一层下了重注——我们构建了一套三级金字塔知识库,并配套了一个漂移自动检测机制,确保地图永远跟得上代码。
5.1 三级金字塔:从总览到字段,按需展开
| L1 总览 | project_wiki/overview.md | ||
| L2 模块 | project_wiki/ | .h/.mm 文件 + 功能说明 | |
| L3 语义桥 | figma_token_mapping.mdui_components_wiki.md |
L1:项目总览——AI 入场的"大堂导览"
overview.md 只做一件事:用一张表告诉 AI "这个项目有哪些模块、各自负责什么"。例如:
MList/ | mlist.md | |
RMail/ | rmail.md | |
CMail/ | cmail.md | |
Model/ | model.md | |
规模示例:Model模块统计(686 个 .h、456 个 .mm、Top 5 大文件)。整份文件控制在 5KB 以内,可以毫无负担地塞进每次定位上下文。
L2:模块级——文件粒度的"街道地图"
每份 顶部有一段机器可读的元数据:
接下来是按 Controller/ ViewModel/ View/ Helper/ Lab/ 分组的文件登记表,每个文件一行职责:
XYZMListController.h/.mm | 邮件列表主控制器 |
XYZMListViewModel.h/.mm | 邮件列表 ViewModel |
XYZTipsView.h/.mm | |
这相当于把"老司机脑子里的项目地图"显式打印出来:哪个文件是干嘛的、它和兄弟文件什么关系——一次读 70 行就能在脑子里建立整个模块的拓扑。
L3:领域语义桥——抹平"设计 / 协议"和"代码"的鸿沟
这一层是最容易被低估、却最能体现工程价值的部分。
举个例子:设计稿上写着 Mobile/callout,AI 该怎么写代码?目测字号?硬编码 [UIFont systemFontOfSize:15]?——都不对。Skill 把这种翻译规则全部沉淀到 figma_token_mapping.md:
// ❌ 错误:目测字号 + 硬编码颜色
self.titleLabel.font = [UIFont systemFontOfSize:15];
self.titleLabel.textColor = [UIColor colorWithRed:0.1 green:0.1 blue:0.1 alpha:1.0];
// ✅ 正确:按映射规则翻译 Figma Token
self.titleLabel = [UILabel xyz_styledLabel:@"callout"]; // Mobile/callout
self.titleLabel.textColor = XYZColor(base_gray_100); // Base/base_gray_100
self.titleLabel.text = R_NSSTRING(XYZ::XXX::TITLE_KEY); // i18n
整张映射表覆盖了:
文字样式 Mobile/title_1 ~ caption_2↔xyz_styledLabel:颜色 Base/base_gray_100↔XYZColor(base_gray_100)(自动响应 Dark Mode)按钮组件 button_blue_large↔[UIButton xyz_styledButton:...]阴影 / 渐变 / 字体兜底 等约 20+ 类规范
⛔ RL-29:UI 改动必须比对 figma_token_mapping.md,禁止硬编码字号/颜色——这是从无数"设计稿走样"事故中淬出来的红线。
5.2 自维护:让知识库永不过时
构建知识库不难,难的是让它不随代码漂移。该项目半年内净增 200+ 文件、改动 1000+ 处,靠人工维护早就崩了。
Skill 的解法是一个核心脚本:**check_project_wiki_stale.py**。
关键设计:
SHA 基线缓存.review_cache.json) | |
| 三色分诊清单 | |
| pre-commit hook 阻断 | |
| 元数据驱动 overview | desc,overview.md 索引自动跟随 |
效果:本项目的全部模块 wiki 在过去 6 个月里没有出现过"地图和代码脱节"的情况——因为每次有人改了代码、想 commit 上去,hook 都会提醒他顺手把 wiki 同步了。
5.3 知识库 + 定位法:1 + 1 > 2
回到第四章的五步定位法,把它和知识库结合,就能看清整个精准定位的完整闭环:
第 1 步:从 L1 总览里 1 秒选出"MList"模块(不用 grep) 第 2 步:从 L2 模块 wiki 里 5 秒锁定 XYZTipsView.h/.mm(不用读源码)第 3 步:进入文件后 rg精准搜索(脚本而非 LLM)第 4 步:只读相关片段(~10K token) 第 5 步:写代码前先查 L3 映射表(杜绝硬编码)
总 token 消耗从"全项目灌入"的 ~10M+ 降到 ~30K——300× 的压缩比。这就是知识库带来的本质提效。
✨ 一个有意思的副作用:这套知识库对人类新人同样有用。我们组新同学入职后,不再需要"找老人聊一上午"才知道项目结构——直接读
overview.md加几份模块 wiki,半天就能上手改 bug。"AI 友好" 和 "新人友好" 在这里完全统一了。
但这只解决了问题的一半。
知识库让 AI 拥有了"代码侧的地图"——可它还要看懂"需求侧的描述"。产品同学说的"加个红点"和工程师写的 setMailboxBadgeValue:,中间隔着一道语义鸿沟:自然语言模糊、口语化、以业务视角描述;代码精确、形式化、以技术视角组织。
要让 AI 独立跑完,必须把这道鸿沟也补平。这就是下一节要讲的。
六、需求语义翻译:把"产品语言"变成"代码指令"
直觉上 AI 在提效,过程却强依赖于人——很大一部分"人工成本"花在了这道翻译上:开发者读完 PRD/Figma/CGI 后在脑子里完成"产品语言 → 代码语言"的转换,再把翻译结果喂给 AI。这一步如果不做,AI 经常会越界、漏改、改错位。
Skill 在「拆解」阶段把这道翻译规则化、可执行化,做到 AI 也能独立完成。
6.1 鸿沟在哪?
下图是一条典型的"产品 → 代码"翻译链。每一层都可能翻车:
每一步翻车都很真实:
grep "小红条" → 0 命中;只 grep "tips" → 800+ 处淹没 | ||
Skill 用五个确定性规则逐层堵住每个翻车点。
6.2 ① 范围识别:用"硬关键词表"代替 LLM 直觉
PRD 是产品视角写的,常常 Web 后台和移动端混在一段里。让 LLM "凭语义判断"是个灾难——同一段描述里出现"配置后台"+"客户端展示",LLM 经常因为段落主语是后台就把整段判为非移动端。
Skill 的解法是一张强信号关键词表,硬触发,不依赖 LLM 语义理解:
| 平台 / 端 | 手机上手机端、移动端、iOS、Android、安卓、苹果、客户端、App |
| 原生控件 / 交互 | Toast弹窗、浮层、小红条、红点、Tab 角标、角标、下拉刷新、侧滑、长按 |
| iOS 系统组件 | 状态栏导航栏、Home Indicator、底部安全区、刘海 |
| 移动端页面术语 | 输入法键盘展开、全屏弹窗、actionsheet |
硬规则:
即使段落主旨在讲后端 / 配置 / 推送规则,只要任一关键词命中,那一段所描述的功能点就必须单独拆成移动端项。 范围判断不是"AI 觉得",是"关键词命中"——客观、可机器复现、不允许降级。
这条规则非常朴素,但威力巨大:把"AI 范围错判"这种最典型的翻车,从概率事件压成 0。
6.3 ② 设计稿归宿:每张图必须归到三类之一
⛔ RL-12:候选清单里每张设计稿都必须归宿明确,不允许出现"未归类"。
关键铁律:如果某张图归不到任何需求点——
要么是筛选误纳(回去把它从候选清单里去掉) 要么是需求点遗漏(新增一项)
不允许用"参考图"当万能垃圾桶。这条规则把"漏需求"这种最隐蔽的事故彻底显式化。
6.4 ③ 拦截点清单:禁止"语义联想"
⛔ RL-21:任何"点击 X → 触发 Y" 类拦截,X 必须有具体引用依据,禁止凭语义联想扩大范围。
需求里最容易出错的是"交互拦截"。产品文档常常一句话带过,AI 最容易"自由发挥"。
Skill 强制要求输出一张可验证的清单:
figma_overview_p3.png | ||||
https://..." |
「依据来源」只接受三种:
设计稿标注:PNG 上的连接线 / 箭头从 X 指向 Y(必须有 nodeId) 文档原文:TAPD / 企微文档的直接引用原句 用户消息:用户原话引用
禁止用业务语义作依据:
❌ "Z 看起来也属于这类功能" → 删除 ❌ "为了一致性应该也拦一下" → 删除 ❌ "属于同类功能行为" → 删除
填不出具体引用的行直接删掉,不实施。这是一条非常硬的红线,把"AI 自作主张越界"这个公认顽疾彻底锁住。
6.5 ④ 领域联想:把"产品语言"扩展成"代码搜索词"
到这一步,我们已经把需求拆出了"M1 邮件列表顶部小红条"这样精确的需求项。但它在代码里叫什么?
产品同学说"小红条",工程师在代码里可能找到的是:
XYZMListTipsView // "Tips" 才是这个组件的工程命名
XYZMListTipsType_xxx // 枚举值
showWarningTips: // 显示方法
is_show_warning_icon_in_mailtab // CGI 字段
XYZLOG_WARN(@"show tips") // 日志关键字
"小红条"和 Tips / Warning / Icon 之间,隔着一道领域知识鸿沟——它不是 AI 不够聪明,而是产品语言和代码命名本来就属于两套词汇体系。
如果直接 grep "小红条",结果一定是 0。如果只 grep "tips",又会被几百处历史用法淹没。Skill 的解法是:用 5 个搜索维度做交叉扩展,把一个需求项展开成一组高命中率的候选搜索词。
5 维搜索矩阵
5 个维度的设计哲学:
| ① iOS 事件方法 | didSelectRowAtIndexPath:handleTapGesture: / touchUpInside: | |
| ② 功能语义 | tips / banner / warning / notice / alert | |
| ③ OC 命名习惯 | show*handle* / on* / goto* / setup* | |
| ④ 协议 / 代理 | tableViewDelegate / didSelectXxx: | |
| ⑤ 通知 / 回调 | XxxNotificationXxxCallback / XxxHandler / RACSignal |
💡 关键洞察:这五个维度不是按"和需求最相关"排,是按"代码里实际可能出现的位置"排。
① 是平台层、② 是业务层、③ 是项目命名风格层、④⑤ 是跨模块通信层——任何一个 UI 行为,必然落在这 5 层之一。把它当成一张"代码命名空间的全景图",而不是凭运气联想关键词。
联想的依据:知识库 + Glossary
5 维矩阵不是凭空联想,背后有两份领域知识作为依据:
L2 模块 wiki(第五章)告诉 AI:"邮件列表模块下已经有 XYZTipsView.h/.mm,描述是'邮件列表顶部提示条'"——这一条直接把"小红条"翻译成了Tips项目 Glossary(命名约定的总结)告诉 AI:"本项目用 show*表示显示、goto*表示跳转、XYZ是邮件插件类前缀"——这能从动词层面匹配代码命名
没有这两份知识,AI 联想出来的关键词是"瞎猜";有了这两份知识,联想出来的关键词命中率 > 80%。
实战:从一句产品话到一组 grep 命令
用一个真实例子完整走一遍:
📝 产品原文:
"邮件列表顶部出现红色小条,提示用户域名即将过期,
点击跳转域名管理页"
⬇️ 第①层联想(功能语义):
红色小条 → tips / banner / warning / alert
即将过期 → expire / expiry / due / warning
跳转管理 → goto / route / push /…