大家好，我是程序员小策。
先跟你讲三个故事——
故事一：你点了一份红烧肉，菜谱上写着"五花肉 500g，酱油适量，冰糖少许，小火慢炖"。你照着做了，出来的肉又柴又腥。为什么？因为菜谱没告诉你：五花肉要先焯水去腥，炒糖色时火候不能大，炖的时候水要一次加够不能中途添水。这些"没说但必须知道"的东西，就是老厨师脑子里的隐性知识。
故事二：你拿着 2019 年的导航地图去开车，地图显示前面是条小路，你开了过去——发现路早就修成了双向八车道，而你要去的商场已经拆了三年。这就是文档过期的后果：代码已经进化到了 3.0，文档还停留在 1.0 时代。
故事三：你新买了个乐高千年隼，盒子里倒出来 7500 个零件，但只有一张 A4 纸大小的示意图。你拼到第 300 步发现底板装反了，前面 6 个小时的努力全部报废。你想找个人帮忙，但他光看这张示意图，完全不知道该从哪下手。
这三件事，干过软件开发的你一定不陌生——它们讲的其实是同一件事：知识传递出了问题。
不是没有文档，而是文档没有把"真正重要的东西"讲出来。更致命的是，在 AI 辅助编程的时代，你把这样的文档喂给 AI，它能给你写代码，但写出来的代码漏掉了分布式锁、忘了幂等校验、不知道状态该怎么流转。因为 AI 和那个看菜谱学做菜的你一样——它只知道"有什么"，不知道"为什么"和"坑在哪"。
来，灵魂拷问：
- 新人接手项目，多久能独立做完一个需求？
- 文档和代码不一致，什么时候暴露？大概率是线上事故那天。
- AI 帮你写代码，它理解业务里的隐藏约束吗？还是说它会写出"逻辑上正确、业务上致命"的代码？
- 老员工离职，他脑子里的"这些接口调用必须注意 X"也跟着走掉了，你怎么办？
你看，这些问题表面是"写不写文档"，本质是知识怎么组织、怎么传递、怎么让机器也能消费。
今天聊的就是这个解法：面向 AI Coding 的 Skill 业务知识体系。它不是"把文档写得更好看一点"，而是把知识重新组织成一种人读得懂、AI 也消费得了的模块化单元。
什么是 Skill 业务知识体系
先定个性。
Skill 就是：把一件事里所有的"是什么"、“怎么做”、“为什么这样做”、“坑在哪”，打包成一个可被 AI 直接消费的模块化知识单元。
用一个最通俗的例子帮你建立直觉——
生活类比：菜谱里的"显性知识"和"隐性知识"
传统文档 = 菜市场的价格标签
五花肉 25.8元/斤，前腿肉 18.8元/斤你知道了名字和价格，但你不知道这块肉适合红烧还是爆炒，不知道买回去要不要焯水。
API 文档 = 菜谱 App 上的食材清单
红烧肉：五花肉 500g，酱油 3勺，冰糖 20g，料酒 2勺你知道用料了，但照着做大概率翻车——因为火候没写、焯水没提、收汁的判断标准没给。
Skill = 老厨师手把手教的"经验菜谱"
## 选肉 五花肉要带皮、三分肥七分瘦。太瘦柴，太肥腻。 别买纯瘦肉——那是做回锅肉用的，红烧必翻车。 ## 焯水（这步不能省！） 冷水下锅，加姜片料酒。水开后煮 2 分钟捞出。 为什么不能省：不焯水，肉里的血沫和腥味全留到菜里，神仙都救不回来。 ## 炒糖色（最容易翻车的一步） 冰糖下冷油，小火！一定是小火！大火 10 秒就变苦。 什么时候下肉：冰糖全化成琥珀色液体，冒小泡的时候。 翻车后果：炒过了 → 发苦 → 整锅扔掉重来。 ## 炖煮 加热水，不是冷水。冷水一激，肉就紧了，再怎么炖也炖不烂。 水量一次加够，中间不补水。实在水少了，只能加热水。 盖上锅盖，最小火，焖 1 小时。看出来了吗？Skill 的核心差别：
| 传统文档 | Skill | |
|---|---|---|
| 告诉你用料 | 知道名字和类型 | 知道选什么、为什么选、选错了会怎样 |
| 告诉你步骤 | 知道要焯水 | 知道为什么不能省焯水、省了的后果 |
| 告诉你参数 | 知道炖 1 小时 | 知道小火多大、水怎么加、中间不能干啥 |
| 告诉你陷阱 | 没有 | 炒糖色翻车→整锅扔掉，这就是 gotchas |
| 能传授给 AI 吗 | 不能，AI 只会照猫画虎 | 能，AI 知道了约束就知道什么不能做 |
好了，直觉建立起来了。现在我们正式下定义——
Skill 不是：
- 不是传统意义上的技术文档（传统文档是"说明书"，Skill 是"师傅的话"）
- 不是简单的 API 文档（API 文档是"菜单"，Skill 是"厨房操作手册"）
- 不是架构图的文字版（架构图是"地图"，Skill 是"导航"）
- 不是代码注释的堆砌（注释是"路牌"，Skill 是"交通规则"）
Skill 是：
- 可被 AI 直接理解的结构化知识单元
- 包含业务约束、设计动机、操作顺序、常见陷阱的完整知识包
- 代码和文档放在一起，改了代码顺手改 Skill，永远同步
- 解决"这个业务到底怎么运转"的决策指南
举个真实代码的例子，一眼看出区别——
传统文档这样写：
面试会话有 6 个状态：DRAFT、RESUME_UPLOADING、READY、IN_PROGRESS、FINISHED、ABANDONED。Skill 这样写：
# 面试生命周期 ## 会话状态 - `DRAFT`：刚创建，尚未上传或提取简历。这时候啥也没有，不能面试。 - `RESUME_UPLOADING`：正在上传简历并提取题目。为什么要设这个中间态？因为上传可能比较慢，并发进来如果判断 DRAFT 就直接开始面试，简历还没上传完，题目出不来。 - `READY`：题目、方向、简历地址全部准备好，可以进场了。 - `IN_PROGRESS`：已经开始取题或答题了。 - `FINISHED`：面试结束，一切落盘归档。 - `ABANDONED`：废了，别再管它了。 ## 状态怎么流转（为什么这样流转） - `createSession`：创建会话，起点是 `DRAFT`。 - `extractInterviewQuestions`：先标成 `RESUME_UPLOADING`，防止并发进来看到 DRAFT 就开搞。成功了标 `READY`，失败就回退到 `DRAFT`——别卡在中间态。 - `getCurrentQuestion`、`getNextQuestion`、`answerInterviewQuestion`：都会先校验两件事：① 这个会话是不是你的；② 会话还能不能继续。首次进入时把 `READY` 升到 `IN_PROGRESS`。 - `finishSession` / `endConversation`：统一走 finalize 收口——不管什么原因结束面试，都走同一个入口，保证记录落盘、状态完结。 ## 什么时候可以恢复（canResume） - 只有 `READY` 和 `IN_PROGRESS` 可以恢复——因为面试需要的准备已经做完了或正在进行中。 - `DRAFT` 不能恢复——题目材料还不完整，恢复了也没题可答。 - `FINISHED` 和 `ABANDONED` 不能恢复——结束了就是结束了，就像电影散场不能再进场。看出区别了吗？传统文档只告诉你"6 个状态"。Skill 告诉你：
- 每个状态什么时候进入、什么时候退出
- 为什么要设
RESUME_UPLOADING这个中间态（防护并发的，不是拍脑袋加的） - 哪些状态能恢复、哪些不能，以及为什么（不理解这个"为什么"，重构的时候就容易把
canResume搞坏）
为什么需要 Skill
传统文档的三道硬伤
硬伤一：文档和代码不同步，而且永远不同步
写文档那一刻它是准的。三个月后代码改了 27 次，文档一个字没动。这不怪谁——写文档的人和改代码的人往往不是同一个人，而改完代码顺手更新文档这件事，从来不会出现在 PR 描述里。
生活类比：就像你家小区门口的路 5 年前改成了单行道，但骑手用的导航还是旧版本。每次外卖小哥都要在小区门口掉头——不是因为不聪明，是因为他拿到的地图没更新。
硬伤二：隐性知识传不下去
代码里藏着大量"大家都知道"的约束：答题必须幂等、这个锁必须加 120 秒超时、排序字段必须从 1 开始不能从 0 开始。你问老同事为什么，他说"上次出过事故"——这句话就是隐性知识。文档里不会写，新人不知道，AI 更不可能知道。
生活类比：就像奶奶做的饺子——“盐放多少？”“看着放。“奶奶看着放了一辈子盐，你不会。这不叫"没文档”，叫"知识锁在了人的经验里”。你要做的不是追着奶奶问每个细节，而是让奶奶把"怎么判断咸淡合适"写下来——尝尝馅，应该是微微偏咸，因为煮的时候会流失一部分盐味。
硬伤三：AI 拿到传统文档，等于没拿
你让 AI 改代码，AI 读了传统文档，文档说"用户下单后扣库存"。AI 照着写了，代码逻辑上完全正确——下单→扣库存。但它不知道真实代码里藏了：预扣库存（不是直接扣）、分布式锁（防超卖）、异步补偿（扣失败要回滚）。上线就是事故。
生活类比：就像你让一个从来没开过车的智能助手帮你规划从 A 到 B 的路线，你只给了它一张纸写着"走高速"。它不知道你要避开某个匝道因为那里修路、不知道某个收费站周末只开两条通道——这些信息不在纸上，在每天通勤的老司机脑子里。
Skill 凭什么解决这三个问题
解法一：代码和文档住在一起
Skill 不在 Wiki 上，就在代码仓库里，放在skills/目录下。改代码时顺手改 Skill，PR Review 一起审。如果改了核心逻辑但 Skill 没动，reviewer 可以直接问：“Skill 更新了吗？”
生活类比：就像你把洗衣标签直接缝在衣服上，而不是把洗衣指南贴在家里的公告栏。每次穿这件衣服的时候标签都在，每次改代码的时候 Skill 也都在眼前。
解法二：把隐性知识结构化
奶奶的"看着放盐"变成"尝尝馅，微微偏咸即可"。老同事的"上次出过事故"变成gotchas.md里的一条记录：用questionNumber做数据库主键会出什么事故、为什么、怎么避免。
生活类比：航空业的"检查清单"就是最经典的知识结构化。飞行员不需要记住 327 条起飞检查项——他有清单。清单不是不信任飞行员，而是解放了他的大脑，让他专注于那些清单覆盖不了的突发情况。
解法三：AI 消费得了这种结构
当 Skill 写清楚了"状态怎么流转"、“什么不能做”、“为什么这样设计”，AI 就不再是照猫画虎了。它知道requestId必须稳定因为它是幂等边界，知道questionNumber不能当主键因为它在追问题场景下会重复——AI 写的代码自然就对了。
生活类比：就像你给一个翻译员的不只是单词表，还有这个行业的术语惯例、文化禁忌、客户风格偏好。有了这些，他翻译出来的东西才不是机翻味。
如何设计 Skill
Skill 的核心结构
一个完整的 Skill 就是一个独立的知识模块，目录长这样：
skills/ ├── xunzhi-interview-domain/# 面试业务域│ ├── SKILL.md# 入口文件：什么时候用、怎么看、有哪些必守约束│ ├── agents/ │ │ └── openai.yaml# AI Agent 配置│ ├── references/# 知识库│ │ ├── object-dictionary.md# 对象字典：有哪些对象、每个字段什么意思│ │ ├── lifecycle.md# 生命周期：从生到死的完整链路│ │ ├── state-machine.md# 状态机：每个状态能往哪走、不能往哪走│ │ ├── invariants.md# 业务约束：铁律，绝对不能违反│ │ ├── gotchas.md# 常见陷阱：踩过的坑，每人只需要踩一次│ │ └── api-map.md# API 映射：哪个接口管什么事儿│ └── scripts/# 自动化脚本│ └── extract_workflow_contracts.py一眼看去就像一个大项目的"微缩版说明书"。接下来逐个讲每个文件的设计逻辑，每个都带生活类比。
SKILL.md —— 就像机场的指路牌
“你要去哪？往哪个方向走？这里面有什么坑要注意？”
--- name: xunzhi-interview-domain description: AI-Meeting 面试业务知识 Skill。当需求命中 /api/xunzhi/v1/interview/**、workflow/*.yml 或面试运行态恢复逻辑时使用。 --- # xunzhi-interview-domain 只要需求落到面试主链路，就用这个 Skill。 ## 使用顺序（先看什么后看什么） - 先看 `references/object-dictionary.md` 和 `references/invariants.md`——搞清楚有哪些对象、哪些铁律不能犯。 - 再看 `references/lifecycle.md`——你现在处在业务的哪个阶段。 - 再看 `references/answer-pipeline.md`——答题的幂等、加锁、评分、推进到底怎么做。 ## 关键入口 - `admin/.../InterviewSessionController.java` ——对外开放的面试接口 - `admin/.../InterviewSessionFacade.java` ——面试会话的主流程 - `admin/.../InterviewAnswerPipeline.java` ——答题流水线 ## 必守约束（踩过坑才知道的） - 面试会话状态和题目流转状态是两套状态，别混着写——混了就全乱了。 - `questionNumber` 既可能是主问题，也可能是追问题，不能用它当数据库主键。 - `requestId` 是答题的幂等边界，前端不能每次重试都换个新的。生活类比：SKILL.md 就是机场落地后的第一块指路牌——你不是要把机场全逛一遍，你是要知道"行李转盘在哪、打车去哪排队、走到出口要多久"。好的 SKILL.md 就是让你 30 秒知道该往哪走。
object-dictionary.md —— 就像药品说明书里的成分表
“这东西包含什么？每个成分起什么作用？对什么过敏的人不能用？”
# 对象字典 ## InterviewSession（面试会话） - `sessionId`：会话唯一标识，MongoDB 主键。一个面试就是一个 session，别重复创建。 - `status`：当前状态，取值范围见 lifecycle.md。别自己拍脑袋设状态值。 - `questionNumber`：当前题目序号，从 1 开始。 - 注意！这是视觉序号，不是数据库主键。追问题会复用主问题的 number。 - `requestId`：答题幂等标识，由前端生成，后端负责校验。 - 一个 requestId 只能成功提交一次答案——重试也不能换！ ## InterviewQuestion（面试题目） - `questionId`：题目的唯一 ID，这才是正经主键。 - `questionType`：MAIN（主问题）还是 FOLLOW_UP（追问题）。 - `content`：题面，就是给候选人看的东西。 - `referenceAnswer`：参考答案，给面试官看的，不出现在候选人界面上。生活类比：你去药店买药，药品说明书一定有一个"成分"段落。它会告诉你"每片含对乙酰氨基酚 500mg"，更重要的是它会告诉你"对本品过敏者禁用，严重肝肾功能不全者禁用"。object-dictionary 也是同理——它不仅告诉你有什么字段，更重要的是告诉你每个字段的边界和限制。
state-machine.md —— 就像交通信号灯
“什么情况能走？什么情况不能走？硬走了会出什么事？”
生活类比：十字路口的红绿灯就是一个状态机。红灯→绿灯→黄灯→红灯，这个顺序是铁定的，不存在"红灯直接跳到绿灯"或者"绿灯突然变红灯"——黄灯必须在中间过渡。面试会话的状态也一样：不存在从 DRAFT 直接跳到 IN_PROGRESS（题目还没准备好呢），也不存在从 FINISHED 再跳回去（结束了就是结束了）。状态机的作用就是告诉你：哪些跳转会出事，连想都不要想。
invariants.md —— 就像交通法规里的"绝对禁令"
“有些规则在什么情况下都不能违反，违反了就有严重的后果。”
# 业务约束（铁律，不可违反） 1. **答题必须幂等**：同一个 `requestId` 只能成功提交一次答案。 → 你按了 5 次电梯按钮，电梯只会来一次，而不是 5 台电梯一起来。 2. **状态只能向前推进**：`DRAFT` → `READY` → `IN_PROGRESS` → `FINISHED`。 → 你不能把吃完饭的碗变回没吃过的。FINISHED 就是 FINISHED。 3. **恢复必须校验状态**：只有 `READY` 和 `IN_PROGRESS` 可以恢复。 → 电影结束后再检票是进不去的。散场了就是散场了。 4. **题号必须连续**：不能跳题，不能重复答题。 → 考试不能从第 1 题直接跳到第 5 题，跳过的那几题必须答过。生活类比：道路交通法规里有一些"绝对禁令"——比如高速上不能逆行、不能闯红灯、酒驾零容忍。这些不是"建议"，是"绝对禁止"，违反的代价是生命。系统的 invariants 也一样——每一个约束背后都发生过一次事故：不是超卖了、就是重复扣费了、就是数据不一致了。写在这里，就是为了不要让同一个人踩同一个坑两次。
gotchas.md —— 就像地铁站台上的"小心缝隙"
“前面有个坑，有人掉下去过，你看着点。”
# 常见陷阱 ## 陷阱一：questionNumber 不是主键 `questionNumber` 既可能是主问题序号，也可能是追问题序号。追问题的 number 和主问题相同——因为它算同一个"题位"。如果你拿它当数据库主键，追问题一进来就把主问题的记录给覆盖了。用 `questionId` 做主键。 → 就像门牌号——同一个单元号可能有 21 楼 A 座和 21 楼 B 座，不能只靠"21楼"来区分。 ## 陷阱二：requestId 不稳定 前端同学嫌麻烦，每次重试都生成一个新 `requestId`。后果：幂等校验完全失效，用户狂点提交按钮，后端收到 8 个请求以为是 8 次不同提交，数据库里多了 8 条重复记录。后端必须校验同一个题目的 `requestId` 不能变，变了就要报错。 → 就像你按下单按钮后卡住了，你刷新页面又按了一次——你希望的是"别给我下两单"，而不是"系统判断不出来这两次是重复的"。 ## 陷阱三：两套状态混着写 面试会话有自己的状态（DRAFT/READY/IN_PROGRESS/FINISHED/ABANDONED），每个题目也有自己的流转状态（UNANSWERED/ANSWERING/ANSWERED）。这两个是完全独立的维度。不要在一个判断逻辑里混用两套状态——该用会话状态的地方用了题目状态，或者反过来，逻辑就全炸了。 → 就像公司和员工——公司倒闭了（会话 ABANDONED），不代表员工就离职了（题目可能还在 ANSWERING 状态）。两个维度的状态要分开管。生活类比：地铁站台上一定有"小心缝隙"的标识。这个标识不会出现在地铁公司的新员工培训手册里，它只会出现在站台边缘——因为它是"已经有人踩过这个坑了，提醒后人别踩"的东西。gotchas.md 就是这样：不需要长篇大论，只需要告诉你"这里有个坑，你小心点"。
实战案例：AI-Meeting 项目的 Skill 体系
项目背景
AI-Meeting 是一个基于大语言模型的智能面试平台。包含面试会话、简历解析、实时语音转写等多个业务域，模块化单体架构，代码量约 5 万行。
人多了、业务域多了之后，最大的问题不是"代码怎么写"，而是不同的人在不同的时间改同一个业务，怎么保证没有人破坏隐藏的约束？这就是设计 Skill 体系的出发点。
整体布局
skills/ ├── xunzhi-repo-map/ # 总导航：告诉你需求落在哪个域 ├── xunzhi-interview-domain/ # 面试域：会话、答题、评分、追问 ├── xunzhi-agent-domain/ # 智能体域：AI 代理的配置和调度 ├── xunzhi-media-domain/ # 媒体域：语音转写、表情分析 ├── xunzhi-ai-runtime/ # AI 运行时：调用大模型的底层 ├── xunzhi-auth-user/ # 认证用户：登录、鉴权 ├── xunzhi-change-playbook/ # 变更手册：改什么要注意什么 └── xunzhi-debug-playbook/ # 调试手册：出问题从哪查起生活类比：就像一个大商场的地图——一楼大厅有总体索引（repo-map），告诉你"餐饮在 3 楼，服装在 2 楼"。你要吃烤鱼，不需要在一楼逛 20 分钟，直接上 3 楼找对应的店（对应 domain skill）。
两个核心思想
一、分层路由：一层一层找，不迷路
xunzhi-repo-map（总路由） ├── xunzhi-interview-domain（面试相关全在这） ├── xunzhi-agent-domain（Agent 配置） └── xunzhi-media-domain（语音、视频）需求来了 → 先看 repo-map → 判断属于哪个域 → 切到对应 Skill → 按 Skill 指引一步步来。
生活类比：打 120 急救电话。总台接听后判断"车撞的 → 转创伤中心，脑出血 → 转神外"。不会让一个出车祸的病人直接送到妇产科。分层路由干的就这事：通知落到正确的处理域，不要找错人。
二、知识分层：每个 Skill 内部也是分层的
一个 Skill 的知识组织： ↑ 越往上越像"指路牌" SKILL.md — 入口、使用顺序、必守约束 │ api-map.md — 接口映射，哪个 URL 进哪个 Controller │ object-dictionary.md — 有哪些对象，每个字段怎么回事 lifecycle.md — 从生到死的完整时间线 state-machine.md — 每个状态的门禁规则 invariants.md — 绝对不可违反的铁律 gotchas.md — 前人踩过的坑 ↓ 越往下越像"踩坑笔记"生活类比：一本好的旅行指南一定是分层的——第一页是"3 天精华路线"（SKILL.md），接着是"景点列表"（object-dictionary），然后是"每天行程安排"（lifecycle），最后几页是"防坑指南：哪些店专坑游客"（gotchas.md）。你不会要求读者把防坑指南放在第一页，也不会把路线总览藏在附录里。
实战：答题幂等到底怎么设计
需求：用户提交答案，怎么保证按 10 次提交只算 1 次？
Skill 指引的使用顺序：
- 打开
xunzhi-interview-domain/references/answer-pipeline.md - 了解
requestId在幂等中的作用 - 理解分布式锁的粒度和超时为什么这样设
- 知道 AI 调用失败时的补偿策略
核心代码（精简版，展示关键逻辑）：
publicAnswerResultanswerInterviewQuestion(StringsessionId,IntegerquestionNumber,StringrequestId,Stringanswer){// 第一步：加锁——同一道题同时只能有一个人在答StringlockKey="interview:answer:"+sessionId+":"+questionNumber;booleanlocked=redisLock.tryLock(lockKey,120,TimeUnit.SECONDS);if(!locked){// 锁没拿到——看看是不是已经有结果了（幂等返回）AnswerResultcached=answerCache.get(requestId);if(cached!=null){returncached;// 有缓存结果，说明之前已经答过了，直接返回}thrownewConcurrentAnswerException();// 没结果但被锁了，说明并发冲突}try{// 第二步：状态校验——会话还在面试中吗？InterviewSessionsession=sessionRepository.findById(sessionId);if(session.getStatus()!=Status.IN_PROGRESS){thrownewInvalidSessionStatusException();}// 第三步：题号校验——答的是当前该答的题吗？if(!questionNumber.equals(session.getCurrentQuestionNumber())){thrownewInvalidQuestionNumberException();}// 第四步：真正的 AI 评分AnswerResultresult=aiInvoker.evaluate(sessionId,questionNumber,answer);// 第五步：缓存结果，这样重复的 requestId 就能幂等返回了answerCache.put(requestId,result,24,TimeUnit.HOURS);returnresult;}finally{redisLock.unlock(lockKey);}}配套的 Skill 说明（answer-pipeline.md 里的内容）：
## 答题幂等设计 ### requestId 是什么 - 前端在每次开始答题时生成一个 ID，这整次提交里不能换。 - 后端用 requestId 做幂等判断——见过就不认第二次。 - 结果缓存 24 小时——用户不小心关了页面再打开，还能看到。 ### 分布式锁设计 - 锁的粒度：sessionId + questionNumber。（为什么不是全局锁？因为不同题可以并行答。） - 锁超时：120 秒。（为什么这么长？AI 评分可能挺慢的，设短了锁提前释放，第二个请求进来以为没结果又评了一次。） - 锁失败先查缓存：说明可能已经处理过，直接返回缓存结果——别傻等着。 ### 失败了怎么办 - AI 调用失败：清除锁和缓存，让用户重试。 - 定时任务兜底：检查所有"一直在评分中"的老记录，主动补一把。生活类比：就像你去银行柜台办业务——你取个号（requestId），叫到你了就去窗口。另一个窗口同时叫了另一个号，两个人不会冲突（不同题的锁）。系统知道你办完业务了，你不可能再用同一张票根办一次（幂等）。如果柜台系统崩了，还有个补打回单的机器（定时任务兜底）。
如何在项目中落地 Skill
五步走，像盖房子一样。
第一步：选地——识别核心业务域
别一上来就想着画整个小区的户型图。先挑一栋最复杂的楼——业务逻辑最绕、状态流转最多、新人最容易踩坑的那个域。从一个做起，做透了再铺开。
选域标准：哪块代码看的人最多、改的最频繁、每次上线最心慌？就它了。
第二步：打地基——设计知识结构
一个业务域至少要有这几样东西：
- SKILL.md—— 导航牌，告诉你什么时候用、怎么看
- object-dictionary.md—— 有哪些核心对象、每个字段的坑位
- lifecycle.md—— 一个业务从生到死的完整链路
- invariants.md—— 绝对不能违反的铁律
- gotchas.md—— 前人掉过的坑，后来的人不必再掉
第三步：住进去——和代码放在一起
Skill 不放在 Wiki，不放在飞书文档，就放在代码仓库的skills/目录下。改了代码？顺手把 Skill 相关段落也改掉。PR Review 的时候 reviewer 自然就会问：“这个逻辑改了，Skill 改了吗？”
第四步：维护——住进来了就要打扫
Skill 不是一锤子买卖：
- 每踩一个坑，就在 gotchas.md 里记一笔
- 每重构一次，把相关 Skill 里的旧描述清掉
- 新人入职 3 个月后让他 review 一次 Skill：哪写的不对？哪漏了？
第五步：给 AI 用——知识体系最终的价值出口
当 Skill 体系成型之后，在 AI 编码工具的提示词里引用对应的 Skill。AI 读完后心智模型就和老员工对齐了——它知道什么不能做、为什么不能做。出来的代码不需要老员工逐行 review 找业务 bug。
常见误区
误区一：“Skill 不就是把文档换个格式吗？”
换个格式叫"刷墙"。把文档刷成 Skill 格式但不加"为什么"、“坑在哪”——刷完了还是传统文档。Skill 的核心是结构化知识，格式只是载体。
就像把菜谱从 Word 改成 Markdown——内容还是"肉 500g，酱油适量"，该不会做还是不会做。
误区二：“设计完就不用管了”
Skill 不更新 = 迟早变成另一份过期的传统文档。知识体系是活的，它是团队认知的沉淀，而认知是不断进化的。
就像你家的 Wi-Fi 密码——2018 年设的"12345678"，到现在还在用，早不安全了。
误区三：“Skill 是给 AI 看的，人不用管”
Skill 最受益的群体在新人头三个月。他们读代码不知道哪些是业务约束、哪些只是实现细节，Skill 帮他们建立了这个"过滤器"。AI 和新人消费的是同一套知识——写得好的 Skill，人和 AI 都受益。
误区四：“等我有空的时候再做 Skill”
那它永远不会发生。正确做法：下一个需求做完之后，顺手花 15 分钟把相关 Skill 写掉。一次 15 分钟，一个 sprint 就是 2 个 Skill，一个季度一个域就搭起来了。
总结
Skill 业务知识体系本质上是干了一件事：
把锁在人脑子里的经验，变成结构化、可传播、可被 AI 消费的知识单元。
- 菜你不查菜谱也能做吗？能，做 100 遍就记住了。但你想要的不是每个新人都做 100 遍——你想要的是能复制的能力。Skill 就是这份可复制的菜谱。
- 代码改了文档没改？把菜谱放进代码仓库，让 chef 做完菜随手改菜谱。
- AI 写的代码逻辑上对吗？总对。业务上对吗？那就是命了。Skill 的存在就是让"命"变成"必然"。
掌握 Skill 不只是学一种文档格式，而是学会一种把隐性知识变成团队基础设施的方法论。有一天你不能亲自 review 每一行代码了，但你的 Skill 体系还在替你做 code review——这才是它真正值钱的地方。
如果这篇文章对你有帮助，不妨收藏起来。下次接手一个老项目、或者要搭一个新项目的知识体系时，翻出来对照着做——比从零摸索要快得多。
