给 AI 写一份老厨师的菜谱：从传统文档到 Skill 知识体系

大家好，我是程序员小策。

先跟你讲三个故事------

故事一： 你点了一份红烧肉，菜谱上写着"五花肉 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 这样写：

markdown 复制代码

# 面试生命周期

## 会话状态

- `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 就是一个独立的知识模块，目录长这样：

yaml 复制代码

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 ------ 就像机场的指路牌

"你要去哪？往哪个方向走？这里面有什么坑要注意？"

markdown 复制代码

---
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 ------ 就像药品说明书里的成分表

"这东西包含什么？每个成分起什么作用？对什么过敏的人不能用？"

markdown 复制代码

# 对象字典

## 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
RESUME_UPLOADING
READY
IN_PROGRESS
FINISHED
ABANDONED

生活类比：十字路口的红绿灯就是一个状态机。红灯→绿灯→黄灯→红灯，这个顺序是铁定的，不存在"红灯直接跳到绿灯"或者"绿灯突然变红灯"------黄灯必须在中间过渡。面试会话的状态也一样：不存在从 DRAFT 直接跳到 IN_PROGRESS（题目还没准备好呢），也不存在从 FINISHED 再跳回去（结束了就是结束了）。状态机的作用就是告诉你：哪些跳转会出事，连想都不要想。

invariants.md ------ 就像交通法规里的"绝对禁令"

"有些规则在什么情况下都不能违反，违反了就有严重的后果。"

markdown 复制代码

# 业务约束（铁律，不可违反）

1. **答题必须幂等**：同一个 `requestId` 只能成功提交一次答案。
   → 你按了 5 次电梯按钮，电梯只会来一次，而不是 5 台电梯一起来。

2. **状态只能向前推进**：`DRAFT` → `READY` → `IN_PROGRESS` → `FINISHED`。
   → 你不能把吃完饭的碗变回没吃过的。FINISHED 就是 FINISHED。

3. **恢复必须校验状态**：只有 `READY` 和 `IN_PROGRESS` 可以恢复。
   → 电影结束后再检票是进不去的。散场了就是散场了。

4. **题号必须连续**：不能跳题，不能重复答题。
   → 考试不能从第 1 题直接跳到第 5 题，跳过的那几题必须答过。

生活类比：道路交通法规里有一些"绝对禁令"------比如高速上不能逆行、不能闯红灯、酒驾零容忍。这些不是"建议"，是"绝对禁止"，违反的代价是生命。系统的 invariants 也一样------每一个约束背后都发生过一次事故：不是超卖了、就是重复扣费了、就是数据不一致了。写在这里，就是为了不要让同一个人踩同一个坑两次。

gotchas.md ------ 就像地铁站台上的"小心缝隙"

"前面有个坑，有人掉下去过，你看着点。"

markdown 复制代码

# 常见陷阱

## 陷阱一：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 调用失败时的补偿策略

核心代码（精简版，展示关键逻辑）：

java 复制代码

public AnswerResult answerInterviewQuestion(
    String sessionId,
    Integer questionNumber,
    String requestId,
    String answer
) {
    // 第一步：加锁------同一道题同时只能有一个人在答
    String lockKey = "interview:answer:" + sessionId + ":" + questionNumber;
    boolean locked = redisLock.tryLock(lockKey, 120, TimeUnit.SECONDS);
    if (!locked) {
        // 锁没拿到------看看是不是已经有结果了（幂等返回）
        AnswerResult cached = answerCache.get(requestId);
        if (cached != null) {
            return cached; // 有缓存结果，说明之前已经答过了，直接返回
        }
        throw new ConcurrentAnswerException(); // 没结果但被锁了，说明并发冲突
    }

    try {
        // 第二步：状态校验------会话还在面试中吗？
        InterviewSession session = sessionRepository.findById(sessionId);
        if (session.getStatus() != Status.IN_PROGRESS) {
            throw new InvalidSessionStatusException();
        }

        // 第三步：题号校验------答的是当前该答的题吗？
        if (!questionNumber.equals(session.getCurrentQuestionNumber())) {
            throw new InvalidQuestionNumberException();
        }

        // 第四步：真正的 AI 评分
        AnswerResult result = aiInvoker.evaluate(sessionId, questionNumber, answer);

        // 第五步：缓存结果，这样重复的 requestId 就能幂等返回了
        answerCache.put(requestId, result, 24, TimeUnit.HOURS);

        return result;
    } finally {
        redisLock.unlock(lockKey);
    }
}

配套的 Skill 说明（answer-pipeline.md 里的内容）：

markdown 复制代码

## 答题幂等设计

### 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------这才是它真正值钱的地方。

如果这篇文章对你有帮助，不妨收藏起来。下次接手一个老项目、或者要搭一个新项目的知识体系时，翻出来对照着做------比从零摸索要快得多。