AI代码生成率94%:我们用一个 Skill 跑通需求开发全流程


一、问题:AI 写业务代码为什么总是"差一口气"?

把"AI 辅助编码"放到企业级真实项目里,我们很快撞上一堵墙。下面这几个场景,每个移动端同学应该都不陌生:

真实痛点
现象
上下文塞不下
9000+ 源文件、跨 5~6 层调用,单轮对话喂不进去
物料分散
PRD 在 TAPD、设计稿在 Figma、协议在企微文档、UI 改动还要看 Figma Token
命名不一致
用户说"邮件点击入口",代码里其实叫 didSelectRowAtIndexPath
模糊指令
用户一句"按 PRD 改一下",AI 直接跳过拆解开始改代码,越界、漏改、改错位
验证不闭环
AI 报"完成",结果编译都没过;改完一处没顾上同步另一处
跨会话失忆
上一次的设计决策、改了哪些文件、为什么这么改,下一次会话全忘

一句话总结:AI 不是不会写代码,是不会"按工程规范"开发需求。

我们的解法不是换更大的模型,而是把"需求开发"这件事流程化、原子化、可校验化,然后把每一步都喂给 AI。


二、整体架构:把"需求开发"拆成 8 个语义化阶段

Skill 的核心是一条严格顺序的流水线。每个阶段输入清晰、产出明确、退出标准可机器校验。结合人日常的开发的流程,大概可以分成以下的流程:

子步骤命名约定:Skill 内部统一采用「阶段·动作」式命名,例如 设计稿·脚本筛选、实现·UI·切图、拆解·TAPD收料——这让 AI 在自报家门时永远清楚自己在哪一格上。

阶段
输入
关键产出
灵魂动作
① 设计稿
Figma 链接
移动端候选稿清单 + PNG 概览
脚本化直方图筛选
,绝不允许 LLM "手感"分桶
② 拆解
PRD + 设计稿 + CGI + TAPD
五列需求清单 + subtasks.json 接力台账
多源收料 + 归宿校验
(每张设计稿必须归到三类之一)
③ 定位
需求点
文件 + 行号 + 调用链
五步定位法
(见下文)
④ 实现
调用链 + 上下文
代码改动
自底向上
:数据 → 解析 → 枚举 → 业务 → UI → 日志
⑤ 验证
源码改动
编译报告(退出码 0)
bazel build
 + 最多 3 轮自修复
⑥ 模拟器验证
编译通过的产物
装机后的截图 + 日志
"人机秒级确认 + 阶段内重试 ≤ 2 轮"
⑦ 沉淀
git diff + 时间线
TECH_SPEC.md
 单一事实源
跨会话知识传承的载体
⑧ 提交
全部产物
git commit + 分支
三段式 commit + AI 署名 + 代码生成率

三、第一性原理:Skill 为什么这样设计?

整条流水线背后只回答一个问题:怎样让一个没参与过原始实现的AI,在新会话里像"参与过的老同事"一样把活干完?

围绕这个目标,Skill 的设计原则可以收敛成四条公理:

下面把这四个公理逐个拆开看。


四、公理 Ⅰ:每一步都在"缩小范围"——五步定位法

大模型不是搜索引擎,把整个项目 find . 丢给它毫无意义。Skill 把"在 9000+ 文件里找到改动点"这件事拆成 5 个收敛步骤,每步 Token 消耗严格控制。

步骤
给 LLM 的输入量
输出
1. 意图消歧
项目概述 ~2K + 用户原话
「这个目标可能对应 4 种技术解读」
2. 模块定位
目录树 + 解读结果
2-3 个候选文件路径
3. 关键词搜索
(不进 LLM)rg 直接跑
函数声明 + 位置
4. 调用链追踪
单个文件相关片段 ~10K
完整调用链
5. 验证确认
函数实现 ~5K
最终改动点 + 理由

真正的窍门:前 2 步只看目录和文件名,第 3 步才让脚本 grep,到第 4 步才真正读代码。一路漏斗下来,模型从来不会被整个代码库淹死。

但这里还有一个前置问题没解决——五步定位法的第 1、第 2 步都依赖一个东西:项目本身得有一张"AI 看得懂"的地图。否则"项目概述 ~2K"从哪儿来?"目录树 + 解读"凭什么这么准?

下一节我们就讲:这张地图是怎么造出来、怎么维护、并且如何永不过时的。


五、代码知识库:让 AI 拥有项目的"地图"

定位精准的前提,是 AI 手里要有一份结构化、最新、可索引的项目知识。Skill 在这一层下了重注——我们构建了一套三级金字塔知识库,并配套了一个漂移自动检测机制,确保地图永远跟得上代码。

5.1 三级金字塔:从总览到字段,按需展开

级别
文件
粒度
加载时机
L1 总览project_wiki/overview.md
模块名 + 一句话职责
「定位」阶段默认 preload(< 5KB)
L2 模块project_wiki/
每个 .h/.mm 文件 + 功能说明
命中模块后按需加载
L3 语义桥figma_token_mapping.md
 / ui_components_wiki.md
Figma Token → 工程 API 的精确映射
「实现·UI」阶段强制参考
L1:项目总览——AI 入场的"大堂导览"

overview.md 只做一件事:用一张表告诉 AI "这个项目有哪些模块、各自负责什么"。例如:

模块
职责
详细文档
MList/
邮件列表展示、同步、过滤、多选编辑
mlist.md
RMail/
邮件正文渲染、附件预览、AI 总结/翻译
rmail.md
CMail/
邮件撰写、富文本编辑、附件上传、AI 润色
cmail.md
Model/
领域模型 + DB 持久化 + 业务管理器
model.md
...(共 N 个一级模块)


规模示例: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)
记录每个文件上次审阅时的 SHA。再次变化时自动 flag "待复核"
三色分诊清单
新增 / 删除 / 大改三类信号分开列,30 秒就能扫完
pre-commit hook 阻断
退出码 1 = 有 stale 信号 → 阻止提交,强制开发者顺手维护
元数据驱动 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 鸿沟在哪?

下图是一条典型的"产品 → 代码"翻译链。每一层都可能翻车:

每一步翻车都很真实:

翻车点
真实场景
代价
① 范围错判
PRD 段落整体在讲"后台配置",中间一句"手机上看到的效果"被当口语忽略
漏实现移动端 UI
② 归宿不明
设计稿 9 张移动端候选稿,AI 只挑 2 张做需求点,其余笼统当"参考图"
漏 7 个独立页面
③ 联想扩大
用户说"点 A 拦截",AI 联想"按一致性 B 也应该拦",自作主张越界
改了不该改的逻辑
④ 关键词找不到
直接 grep "小红条" → 0 命中;只 grep "tips" → 800+ 处淹没
定位失败或误命中
⑤ 找错文件
"邮件红点"翻译错位置,改了 RMail 而不是 MList
功能完全走错地方

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 强制要求输出一张可验证的清单:

#
触发元素 X
触发事件
响应 Y
依据来源
1
邮件列表"全选" 按钮
点击
Toast 提示"超过 100 封不可全选"
figma_overview_p3.png
 上从全选按钮指向 toast 的绿色箭头
2
顶部小红条
点击
跳转管理页
TAPD 原文:"小红条点击跳转 https://..."

「依据来源」只接受三种:

  1. 设计稿标注:PNG 上的连接线 / 箭头从 X 指向 Y(必须有 nodeId)
  2. 文档原文:TAPD / 企微文档的直接引用原句
  3. 用户消息:用户原话引用

禁止用业务语义作依据:

❌ "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 事件方法
平台标准 API
didSelectRowAtIndexPath:
 / handleTapGesture: / touchUpInside:
② 功能语义
产品意图的英文同义词
"小红条" → tips / banner / warning / notice / alert
③ OC 命名习惯
项目里的命名前缀
show*
 / handle* / on* / goto* / setup*
④ 协议 / 代理
谁通知谁
tableViewDelegate
 /  / didSelectXxx:
⑤ 通知 / 回调
跨模块通信
XxxNotification
 / XxxCallback / 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 /…
— 以上为试看内容(约 40%),开通会员后阅读全文 —