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

作者：企业微信团队 – gomezlai

一、问题：AI 写业务代码为什么总是”差一口气”？

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

一句话总结：AI 不是不会写代码，是不会”按工程规范”开发需求。

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

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

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

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

三、第一性原理：Skill 为什么这样设计？

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

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

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

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

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

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

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

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

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

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

5.1 三级金字塔：从总览到字段，按需展开

L1：项目总览——AI 入场的”大堂导览”

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

规模示例：Model模块统计（686 个 .h、456 个 .mm、Top 5 大文件）。整份文件控制在 5KB 以内，可以毫无负担地塞进每次定位上下文。

L2：模块级——文件粒度的”街道地图”

每份 <module>.md 顶部有一段机器可读的元数据：

<!-- module_id: mlist -->
<!-- root_dirs:
  - App/Mailbox/MList/
-->
<!-- desc: 邮件列表展示、同步、过滤、多选编辑 -->

接下来是按 Controller/ ViewModel/ View/ Helper/ Lab/ 分组的文件登记表，每个文件一行职责：

这相当于把”老司机脑子里的项目地图”显式打印出来：哪个文件是干嘛的、它和兄弟文件什么关系——一次读 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**。

关键设计：

效果：本项目的全部模块 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 鸿沟在哪？

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

每一步翻车都很真实：

Skill 用五个确定性规则逐层堵住每个翻车点。

6.2 ① 范围识别：用”硬关键词表”代替 LLM 直觉

PRD 是产品视角写的，常常 Web 后台和移动端混在一段里。让 LLM “凭语义判断”是个灾难——同一段描述里出现”配置后台”+”客户端展示”，LLM 经常因为段落主语是后台就把整段判为非移动端。

Skill 的解法是一张强信号关键词表，硬触发，不依赖 LLM 语义理解：

硬规则：

即使段落主旨在讲后端 / 配置 / 推送规则，只要任一关键词命中，那一段所描述的功能点就必须单独拆成移动端项。 范围判断不是”AI 觉得”，是”关键词命中”——客观、可机器复现、不允许降级。

这条规则非常朴素，但威力巨大：把”AI 范围错判”这种最典型的翻车，从概率事件压成 0。

6.3 ② 设计稿归宿：每张图必须归到三类之一

⛔ RL-12：候选清单里每张设计稿都必须归宿明确，不允许出现”未归类”。

关键铁律：如果某张图归不到任何需求点——

• 要么是筛选误纳（回去把它从候选清单里去掉）
• 要么是需求点遗漏（新增一项）

不允许用”参考图”当万能垃圾桶。这条规则把”漏需求”这种最隐蔽的事故彻底显式化。

6.4 ③ 拦截点清单：禁止”语义联想”

⛔ RL-21：任何”点击 X → 触发 Y” 类拦截，X 必须有具体引用依据，禁止凭语义联想扩大范围。

需求里最容易出错的是”交互拦截”。产品文档常常一句话带过，AI 最容易”自由发挥”。

Skill 强制要求输出一张可验证的清单：

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

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 个维度的设计哲学：

💡 关键洞察：这五个维度不是按”和需求最相关”排，是按”代码里实际可能出现的位置”排。

① 是平台层、② 是业务层、③ 是项目命名风格层、④⑤ 是跨模块通信层——任何一个 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 / open

⬇️ 第②层联想（项目命名风格）：
   邮件列表前缀 → XYZMList*
   提示组件类  → *TipsView / *Banner / *Notice
   跳转方法    → goto* / open* / push*

⬇️ 第③层（结合 mlist.md L2 wiki）：
   命中文件：XYZTipsView.h/.mm
   "邮件列表顶部提示条"——直接对应

⬇️ 候选搜索词集合（按命中概率从高到低）：
   1. XYZTipsView                  (强命中：组件类)
   2. showWarningTips:                (强命中：显示方法)
   3. XYZMListTipsType_         (中：枚举类型前缀)
   4. didTapTipsView:                 (中：点击响应)
   5. domainExpire / domainWarning   (中：业务关键词)
   6. gotoDomainManagement            (弱：跳转方法名猜测)

⬇️ 最终 grep 命令（漏斗式收敛）：
   $ rg "XYZTipsView|showWarningTips" App/Mailbox/MList/ -l
   App/Mailbox/MList/View/XYZTipsView.mm     ← 命中！
   App/Mailbox/MList/Controller/XYZMListController.mm ← 调用方

✨ 整个过程不需要”读源码猜方法名”——只用 wiki + 命名约定就把关键词扩展出来了。从产品原文到 grep 命令，全程机器可执行。

反例：不联想会怎么翻车？

5 维交叉才是唯一稳定路径——单维都会要么 0 命中、要么海量误命中。

与红线 RL-21 的边界

⚠️ 6.5 联想关键词和6.4 拦截点禁止语义联想是两件事，不要混淆：

• 6.5 允许联想：在”找代码该改哪里”这件事上，必须用领域知识扩展候选搜索词，否则根本搜不到（这一步只是缩小搜索范围，不直接影响实现）
• 6.4 禁止联想：在”X 触发 Y 是哪条交互”这件事上，必须有具体引用依据，不能因为”看起来像”就加进拦截清单（这一步直接决定实现内容，关系到”AI 越界”红线）

一句话：联想用于搜索，引用用于决策。

6.6 ⑤ 翻译产物：五列表格 + subtasks.json

经过①②③ 三道关之后，需求侧的语义已经被收敛成结构化清单。它就是「拆解」阶段的产出：

人类可读的五列表格：

**机器可读的 subtasks.json**（结构化字段）：

[
  {"id":"M1","title":"邮件列表顶部小红条","type":"新增UI",
   "data_source":"CGI字段is_show_warning_icon_in_mailtab",
   "figma_node":"153:74513","depends_on":[]},
  {"id":"M2","title":"Tab 角标显示感叹号","type":"修改逻辑",
   "data_source":"已存字段","figma_node":"153:74600","depends_on":["M1"]}
]

这份 JSON 是 Skill 的关键中枢——它同时承担三个角色：

到这里，”产品语言 → 代码指令”的语义鸿沟就被彻底抹平了：

6.7 完整翻译链：知识库 + 拆解规则 = 闭环

把第五章的代码侧地图、和本章的需求侧翻译合在一起看，就能看清 Skill 是怎么把”AI 独立开发需求”这件事工程化的：

两条链一对接，AI 就拥有了”独立开发完整需求”所需的全部确定性输入：

• 需求侧：每个需求点是什么、范围在哪、关联设计稿哪个 nodeId、依据是什么
• 代码侧：项目里有哪些模块、每个模块有哪些文件、每个文件做什么、UI Token 怎么翻译

💡 **真正的提效不在”AI 写代码”，而在”AI 不再需要人来当翻译”**。

当语义翻译这件事被规则化、可执行化、有产物可校验后，开发者从”PRD 翻译机”的角色里解放出来，转而成为”AI 的产品经理”——只在硬关卡处做决策。这就是 94% 代码生成率背后的真正机制。

七、公理 Ⅱ：把”判断”留给 LLM，把”数据”交给脚本

LLM 最不擅长两件事：精确数值和幂等执行。Skill 把这两类工作全部下沉到脚本，LLM 只负责”读结果 + 下决策”。

7.1 多源物料收集：每种来源一个专用脚本

整个 Skill 支持六类输入，每类都有自己的”专用通道”，**严禁通用 web_fetch**：

为什么不能用 web_fetch？ 这正是 Skill 写死的 Critical 红线：

⛔ RL-02doc.weixin.qq.com 必须走 wecom-cli，web_fetch 鉴权后只拿到 HTML 外壳

⛔ RL-03 TAPD URL 必须走 tapd_mcp_http MCP，web_fetch 拿不到 markdown 描述

7.2 设计稿筛选：脚本直方图 vs LLM “手感”

Figma 一个 fileKey 下面常有几十上百个画板：海报、PC 端、平板、移动端、变体、注释稿……让 LLM 凭”看起来像移动端”挑出移动端是灾难。

Skill 的做法是：

⛔ RL-17：严禁 LLM 手工分桶——必须先跑 scan_figma_frames.py 出直方图（数据来自 tools/iphone_sizes.json 这份 iPhone 尺寸白名单），LLM 只能在已分桶基础上补判UNCERTAIN 项，不能凭印象决定。

这条红线把”AI 看图选稿”的随机性从根上扫掉了。

7.3 “落盘判定成功” — RL-32 的工程美感

git commit 长消息会被 terminal 当后台任务、stdout 会被截断、管道命令会变成异步……这些都是脚本和 LLM 之间常见的”信号丢失”陷阱。

Skill 引入了一个朴素但极漂亮的设计：sentinel 文件 = 成功的唯一判据。

同样的思路也用在 git commit（RL-31：以 git log -1 hash 更新为唯一判据）。任何”长跑命令”都不靠 stdout 报告成功，全靠落盘文件——这是从无数翻车里淬出来的工程经验。

八、公理 Ⅲ：红线机制——把”翻车”前置成”硬关卡”

LLM 在工程上最大的风险，是它”什么都敢说，什么都敢做”。Skill 用一套红线系统给它戴上紧箍。

8.1 红线架构：YAML 单一真源 + 分层加载

红线分两级：

• 🔴 Critical（6 条）：全流程必守，启动即加载，违反会直接造成线上事故或严重返工
• 🟡 Standard（30+ 条）：按阶段加载，违反会污染工程规范

8.2 触发即停 + 模板化报告

任何红线被触发，AI 必须停下并按固定模板汇报：

⛔ 触发红线 RL-XX：<标题>
当前情形：<具体说明>
建议处理：<回退到哪个步骤 / 需要用户确认什么>

这把”AI 偷偷做了它不该做的事”变成”AI 主动告诉你它撞上红线了”——可观测性远比聪明更重要。

8.3 几条”血泪换来”的 Critical 红线

红线只是把”翻车点”拉到了硬关卡，但还有一个更根本的问题：AI 怎么证明自己写的代码真的”做对了”？

编译过 ≠ 跑得对，跑得起 ≠ 长得对。下一节我们讲 Skill 怎么把”代码质量验证”也工程化、自动化。

九、运行时验证：让 AI 自己跑通

AI 最大的诚信问题是”自报完成”——说”已经做完了”，结果编译都没过；说”功能正常”，截图打开一看 UI 错位。

Skill 把”验证”拆成两道闸门：编译验证（代码层）+ 模拟器验证（运行时 + 视觉），两道都通过才允许进入沉淀阶段。

9.1 闸门一：编译验证——退出码 0 是唯一判据

代码改完后，AI 不允许说”实现完成”——必须先跑通 bazel build。

A/B 分类的设计精髓：

⛔ RL-15 + 自修复硬上限 3 轮：超过 3 轮仍编译不过 → 强制停下报告用户，不允许继续。这条规则把”AI 越改越乱”的死循环锁死。

报告里直接带上下文代码行——让 AI 不用回头读源码就能修。这是脚本设计的一个小巧思：

App/Mailbox/mailcore/mailbox_protocol.cpp:1822:25:
  error: use of undeclared identifier 'undefined_xxx'
 1822 | void __test_error__() { undefined_xxx(); }
      |                         ^^^^^^^^^^^^^

9.2 闸门二：模拟器验证——真跑一遍 + 截图核对

编译通过 ≠ 功能正确。Skill 用一套自动化 UI 验证流程让 AI 自己装机、自己点击、自己截图、自己核对预期。

第①步：路径推导——从 git diff 反推一条 UI 路径

AI 不是”想点哪点哪”，而是按 git diff 改动 + TECH_SPEC §3「相关代码位置」+ 设计稿终态图，反推出一条具体的 UI 验证路径：

verify_plan.md 的标准骨架：

# 模拟器验证计划：<feature-name>

## 操作步骤
1. launch App                                  → 01_launched.png
2. tap 邮件 Tab                                 → 02_mail_tab.png
3. tap 第一封邮件                               → 03_detail.png
4. 观察顶部 Tips 文字是否含 "xxx"               → 04_tips.png
5. tap nav_back_arrow                          → 05_back.png

## 预期
- 步骤 4 截图中 Tips 文字 == "<期望文案>"
- runtime.log 中 `XYZLOG_WARN(@"mailbox xxx")` 命中 ≥ 1

UI 路径预扫描：6 步反向溯源（附录 A 的精华）

如果改动涉及”按钮 enable 条件 / 拦截弹窗 / 新增点击响应”，AI 必须先做一次预扫描，把”代码层方法名”反推到”UI 层可点击控件”，避免点错或点了没反应：

📌 桥梁法——当依赖变量跨文件赋值时，按 3 类桥梁定位源头：通知（postNotificationName:）/ KVO（RACObserve(）/ Delegate（<DelegateProtocol> =）。这是把”AI 找不到控件来源”这种顽疾规则化的关键。

第③④步：执行 + A/B/C 三类诊断

每步固定 5 个动作，实时汇报，不静默连跑：

🎬 步骤 N/M：<动作>
- 命令：idb ui tap --udid $UDID 200 420
- 截图：03_detail.png
- 观察：导航栏标题 "邮件详情"，Tips 区域可见

预期点核对失败时，按 A/B/C 分类分流：

🎯 设计精髓：A/B/C 分类把”该不该重试”这个糊涂账变成清晰决策。AI 不允许在 A/B 类问题上反复硬试，最多 2 轮 C 类重试不过 → 升级为实质性问题报告用户。

第⑤步：视觉对齐核对——RL-30 的硬关卡

⛔ RL-30：触发了 RL-29（UI 改动）但 ui_alignment_spec.md 不存在 / 未对齐项 ≥1 → 视觉对齐直接判 FAIL，不允许跳过。

光”截图能看到”还不够，UI 改动还要逐项核对数值：

## 视觉对齐核对（依据 ui_alignment_spec.md，RL-30）

- [x] XYZTopicEmptyFooter container.height = 280 ✅（截图实测 280）
- [x] icon 居中且 size 96×96 ✅
- [x] title 字号 16 / Medium ✅
- [⚠] desc lineHeight 偏小 1pt（已知偏差，spec 已记录）
- [x] cta 主蓝色 ✅

## 视觉对齐结论
- 关键差异 0 / 接受偏差 1 / **未对齐 0**
- 未对齐 ≥1 → 状态自动降级为 ❌ FAIL

这把”设计稿走样”这个 UI 工程顽疾彻底显式化——不再依赖测试同学手肉眼比对，而是 AI 自己拿着数值清单逐项核对。

9.3 那些”血泪换来”的运行时小坑

模拟器验证过程踩过不少坑，Skill 把它们沉淀成 simulator_toolbox.md 里的死角清单——这些是 AI 必须知道的”不能做什么”：

这些坑没有一条是”模型不够聪明”导致的——全是工程层面的真实陷阱。沉淀成手册之后，每个新会话的 AI 都能直接绕开。

9.4 验证闭环：从代码改动到”敢说做完了”

把两道闸门串起来看，AI 从”改完代码”到”敢说做完了”经历了 5 道把关：

每一道关都有机器可校验的产物：build_report.txt 退出码、<NN>_xxx.png 截图、runtime.log 日志命中、result.md 状态字段。全部由文件证明，不靠 AI 自报。

💡 本质思想：把”质量保障”这件事从”靠测试同学发现 bug”变成”AI 自己写代码自己验证自己交差”。

这才是 AI 能从”辅助”升级为”主导”的关键——当 AI 拿出来的不仅是代码，还有截图、日志、视觉对齐报告时，开发者只需要做最后一道 review，而不是手动跑一遍验证。

十、公理 Ⅳ：跨会话知识传承——TECH_SPEC.md 是灵魂

如果说前三公理解决的是”一次会话内的提效”，那这条公理解决的是真正让 AI 像团队成员一样工作——会做、能记、可接力。

10.1 三件套：分别承担不同尺度的”记忆”

10.2 TECH_SPEC.md 的章节结构（精华）

§0  AI 自检清单        ← 给下次会话的 AI 当"入场扫描"
§1  功能边界          ← 哪些做、哪些不做（防越界）
§3  模块地图          ← 文件 + 关键方法 + 调用链
§5  不变式            ← 不能动的命名、文件清单、拦截边界
§7  演进事件          ← 按时间线排列的 BUG-N / ITER-N / REV-N
§8  产物清单          ← 每次 commit 改了什么
§9  版本号            ← v1.0 → v1.1 → ... → v2.0 (baseline 合并)

新会话的 AI 只要按 §0 → §1 → §3 → §5 → §7 顺序读完，就能”无缝接力”。

10.3 四类入口：根据现场状况自动分流

这套接力机制配合 4 种入口，把”需求开发”覆盖到了完整生命周期：

同一个 TAPD 需求的整个生命周期——从首次实现到 N 轮迭代、M 个 bug 修复、偶尔的推倒重来——全部由这一份 TECH_SPEC.md 串联起来。

10.4 硬关卡 HK：信任但不放任

每个工作流里都嵌着若干人机硬关卡（Hard Checkpoint），强制要求用户确认：

这套”硬关卡”是 Skill 工程的精髓之一——自动化和可控性的平衡点：AI 跑得飞快，但任何一个不可逆动作都先让人点头。

十一、提效效果：到底快了多少？

数据来源于本项目近半年实际跑下来的体感（非严格 benchmark），仅供参考。

最大的隐性收益：新人 / AI 都能直接接手已有需求的迭代，不再依赖”问原作者”。这是 TECH_SPEC.md 带来的复利效应。

十二、关键启示：如果你也想做这种 Skill

我们踩过的坑收敛成 5 条原则，普适性强，建议复用到你自己的项目：

十三、附录：Skill 目录速览

整套 Skill 由 6 大组件构成，按”AI 进入流水线”的视角分层组织：

skills/mailplugin-feature-dev/
│
├── ① 对外入口（LLM 启动时加载）
│   ├── SKILL.md                          # 流程总图 + 4 类入口分流 + 强约束
│   ├── README.md                         # 给人看的使用指南
│   └── CHANGELOG.md                      # 版本变更日志
│
├── ② 安装与配置
│   └── setup/
│       ├── install.sh                    # 一键安装（含 MCP 注册、依赖检测）
│       ├── uninstall.sh                  # 一键卸载
│       └── mcp.tapd.json                 # TAPD MCP Server 配置
│
├── ③ 自动化脚本（"判断交给 LLM，数据交给脚本"）
│   └── tools/
│       │  —— 收料（公理 Ⅱ：绕过上下文截断）——
│       ├── fetch_tapd_story.py           # TAPD 一站式收料：单据+附件+评论
│       ├── fetch_tapd_images.py          # TAPD 图片批量下载
│       ├── fetch_figma_mcp.py            # Figma MCP 数据落盘
│       ├── scan_figma_frames.py          # 设计稿直方图筛选（RL-17）
│       │
│       │  —— 文档生成与维护 ——
│       ├── locate_feature_doc.py         # 定位 TECH_SPEC.md 路径
│       ├── render_tech_spec.py           # TECH_SPEC.md 首次渲染
│       ├── append_evolution_log.py       # §7/§8/§9 增量维护 + sentinel
│       ├── append_bug_fix.py             # bug 修复记录追加
│       ├── breakdown_subtasks.py         # 子任务台账（跨会话接力）
│       ├── gen_red_lines_docs.py         # 红线 yaml → 派生 md
│       │
│       │  —— 编译与验证（公理 Ⅰ：落盘判定）——
│       ├── build_verify.sh               # bazel 编译 + 报告
│       ├── check_implement_done.sh       # 实现完成度自检
│       ├── check_intermediate_artifacts.py # 阶段产物完整性检查
│       ├── check_project_wiki_stale.py   # 知识库时效性扫描
│       ├── check_ui_token_usage.sh       # UI Token 合规检查
│       │
│       │  —— 模拟器与提交 ——
│       ├── install_to_simulator.sh       # 安装包到模拟器
│       ├── iphone_sizes.json             # 设备尺寸数据库
│       ├── finalize_commit.sh            # 提交收尾
│       ├── render_commit_msg.py          # commit message 模板渲染
│       ├── timeline_to_commit_lines.py   # 时间线 → commit 行
│       └── md_to_pdf.py                  # 文档导出
│
├── ④ 知识库与映射（"代码侧地图 + 语义桥"）
│   └── references/
│       ├── project_wiki/                 # 分模块知识库（按业务域 + 基础设施分册）
│       │   ├── overview.md               # 总览索引（< 5KB，作为 L1 入口）
│       │   └── *.md                      # 各模块 L2 详情（按需加载）
│       │
│       ├── figma_token_mapping.md        # L3 语义桥：Figma → 工程代码
│       ├── figma_device_sizes.md         # 设计稿设备尺寸映射
│       └── ui_components_wiki.md         # 统一 UI 组件文档
│
├── ⑤ 流程细则（按需加载，不污染上下文）
│   └── references/
│       │  —— 8 个阶段完整执行细则 ——
│       ├── stage_locate.md               # 阶段 1：意图消歧 + 定位
│       ├── stage_design.md               # 阶段 2：设计文档收料
│       ├── stage_breakdown.md            # 阶段 3：需求拆解 + 子任务台账
│       ├── stage_implement.md            # 阶段 4：编码实现
│       ├── stage_verify.md               # 阶段 5：编译验证
│       ├── stage_simulator_verify.md     # 阶段 6：模拟器验证
│       ├── stage_commit.md               # 阶段 7：提交收尾
│       ├── stage_archive.md              # 阶段 8：归档与沉淀
│       │
│       │  —— 4 类入口子流程 ——
│       ├── bug_fix_workflow.md           # 入口 ②：bug 修复
│       ├── incremental_workflow.md       # 入口 ③：增量迭代
│       ├── redo_workflow.md              # 入口 ④：推倒重来
│       │
│       │  —— 工具箱 ——
│       ├── simulator_toolbox.md          # 模拟器调试工具箱
│       └── tech_spec_template.md         # TECH_SPEC.md 模板
│
└── ⑥ 红线机制（公理 Ⅲ：硬关卡）
    └── references/
        ├── red_lines.yaml                # 红线单一真源（DSL）
        ├── red_lines_critical.md         # 全局强制加载（启动即生效）
        └── red_lines_by_stage/           # 分阶段按需加载
            ├── global.md                 # 跨阶段通用红线
            ├── locate.md                 # 阶段 1 红线
            ├── design.md                 # 阶段 2 红线
            ├── breakdown.md              # 阶段 3 红线
            ├── implement.md              # 阶段 4 红线（最厚一份）
            ├── verify.md                 # 阶段 5 红线
            ├── simulator_verify.md       # 阶段 6 红线
            ├── commit.md                 # 阶段 7 红线
            └── archive.md                # 阶段 8 红线

一个直观感受：**references/ 比 tools/ 体量更大**——这是”AI 提效在工程而不在模型”最朴素的证据，绝大部分能力都来自被显式编写的规则、知识、模板，而不是”指望模型聪明”。

写在最后

我们一开始想做的是”让 AI 帮我写代码”；做完才意识到——真正有价值的，是让”需求开发”这件事本身被显式建模、可观测、可接力。

Skill 只是把这些工程规范”具象成了 LLM 能消化的格式”。而沉淀下来的 TECH_SPEC.md 和 project_wiki，即使有一天换掉 AI，对人也是同样有用的资产。

AI 提效的天花板，既在模型，也在工程。