大家好我是程序员小策。先跟你讲三个故事——故事一你点了一份红烧肉菜谱上写着五花肉 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/目录下。改代码时顺手改 SkillPR Review 一起审。如果改了核心逻辑但 Skill 没动reviewer 可以直接问“Skill 更新了吗”生活类比就像你把洗衣标签直接缝在衣服上而不是把洗衣指南贴在家里的公告栏。每次穿这件衣服的时候标签都在每次改代码的时候 Skill 也都在眼前。解法二把隐性知识结构化奶奶的看着放盐变成尝尝馅微微偏咸即可。老同事的上次出过事故变成gotchas.md里的一条记录用questionNumber做数据库主键会出什么事故、为什么、怎么避免。生活类比航空业的检查清单就是最经典的知识结构化。飞行员不需要记住 327 条起飞检查项——他有清单。清单不是不信任飞行员而是解放了他的大脑让他专注于那些清单覆盖不了的突发情况。解法三AI 消费得了这种结构当 Skill 写清楚了状态怎么流转、“什么不能做”、“为什么这样设计”AI 就不再是照猫画虎了。它知道requestId必须稳定因为它是幂等边界知道questionNumber不能当主键因为它在追问题场景下会重复——AI 写的代码自然就对了。生活类比就像你给一个翻译员的不只是单词表还有这个行业的术语惯例、文化禁忌、客户风格偏好。有了这些他翻译出来的东西才不是机翻味。如何设计 SkillSkill 的核心结构一个完整的 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这才是正经主键。 - questionTypeMAIN主问题还是 FOLLOW_UP追问题。 - content题面就是给候选人看的东西。 - referenceAnswer参考答案给面试官看的不出现在候选人界面上。生活类比你去药店买药药品说明书一定有一个成分段落。它会告诉你每片含对乙酰氨基酚 500mg更重要的是它会告诉你对本品过敏者禁用严重肝肾功能不全者禁用。object-dictionary 也是同理——它不仅告诉你有什么字段更重要的是告诉你每个字段的边界和限制。state-machine.md —— 就像交通信号灯“什么情况能走什么情况不能走硬走了会出什么事”创建会话上传简历提题成功提题失败回退别卡在中间态开始答题完成面试中途作废还没开始就作废DRAFTRESUME_UPLOADINGREADYIN_PROGRESSFINISHEDABANDONED生活类比十字路口的红绿灯就是一个状态机。红灯→绿灯→黄灯→红灯这个顺序是铁定的不存在红灯直接跳到绿灯或者绿灯突然变红灯——黄灯必须在中间过渡。面试会话的状态也一样不存在从 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-domainAgent 配置 └── 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){// 第一步加锁——同一道题同时只能有一个人在答StringlockKeyinterview:answer:sessionId:questionNumber;booleanlockedredisLock.tryLock(lockKey,120,TimeUnit.SECONDS);if(!locked){// 锁没拿到——看看是不是已经有结果了幂等返回AnswerResultcachedanswerCache.get(requestId);if(cached!null){returncached;// 有缓存结果说明之前已经答过了直接返回}thrownewConcurrentAnswerException();// 没结果但被锁了说明并发冲突}try{// 第二步状态校验——会话还在面试中吗InterviewSessionsessionsessionRepository.findById(sessionId);if(session.getStatus()!Status.IN_PROGRESS){thrownewInvalidSessionStatusException();}// 第三步题号校验——答的是当前该答的题吗if(!questionNumber.equals(session.getCurrentQuestionNumber())){thrownewInvalidQuestionNumberException();}// 第四步真正的 AI 评分AnswerResultresultaiInvoker.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——这才是它真正值钱的地方。如果这篇文章对你有帮助不妨收藏起来。下次接手一个老项目、或者要搭一个新项目的知识体系时翻出来对照着做——比从零摸索要快得多。
给 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 这样写# 面试生命周期 ## 会话状态 - 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/目录下。改代码时顺手改 SkillPR Review 一起审。如果改了核心逻辑但 Skill 没动reviewer 可以直接问“Skill 更新了吗”生活类比就像你把洗衣标签直接缝在衣服上而不是把洗衣指南贴在家里的公告栏。每次穿这件衣服的时候标签都在每次改代码的时候 Skill 也都在眼前。解法二把隐性知识结构化奶奶的看着放盐变成尝尝馅微微偏咸即可。老同事的上次出过事故变成gotchas.md里的一条记录用questionNumber做数据库主键会出什么事故、为什么、怎么避免。生活类比航空业的检查清单就是最经典的知识结构化。飞行员不需要记住 327 条起飞检查项——他有清单。清单不是不信任飞行员而是解放了他的大脑让他专注于那些清单覆盖不了的突发情况。解法三AI 消费得了这种结构当 Skill 写清楚了状态怎么流转、“什么不能做”、“为什么这样设计”AI 就不再是照猫画虎了。它知道requestId必须稳定因为它是幂等边界知道questionNumber不能当主键因为它在追问题场景下会重复——AI 写的代码自然就对了。生活类比就像你给一个翻译员的不只是单词表还有这个行业的术语惯例、文化禁忌、客户风格偏好。有了这些他翻译出来的东西才不是机翻味。如何设计 SkillSkill 的核心结构一个完整的 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这才是正经主键。 - questionTypeMAIN主问题还是 FOLLOW_UP追问题。 - content题面就是给候选人看的东西。 - referenceAnswer参考答案给面试官看的不出现在候选人界面上。生活类比你去药店买药药品说明书一定有一个成分段落。它会告诉你每片含对乙酰氨基酚 500mg更重要的是它会告诉你对本品过敏者禁用严重肝肾功能不全者禁用。object-dictionary 也是同理——它不仅告诉你有什么字段更重要的是告诉你每个字段的边界和限制。state-machine.md —— 就像交通信号灯“什么情况能走什么情况不能走硬走了会出什么事”创建会话上传简历提题成功提题失败回退别卡在中间态开始答题完成面试中途作废还没开始就作废DRAFTRESUME_UPLOADINGREADYIN_PROGRESSFINISHEDABANDONED生活类比十字路口的红绿灯就是一个状态机。红灯→绿灯→黄灯→红灯这个顺序是铁定的不存在红灯直接跳到绿灯或者绿灯突然变红灯——黄灯必须在中间过渡。面试会话的状态也一样不存在从 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-domainAgent 配置 └── 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){// 第一步加锁——同一道题同时只能有一个人在答StringlockKeyinterview:answer:sessionId:questionNumber;booleanlockedredisLock.tryLock(lockKey,120,TimeUnit.SECONDS);if(!locked){// 锁没拿到——看看是不是已经有结果了幂等返回AnswerResultcachedanswerCache.get(requestId);if(cached!null){returncached;// 有缓存结果说明之前已经答过了直接返回}thrownewConcurrentAnswerException();// 没结果但被锁了说明并发冲突}try{// 第二步状态校验——会话还在面试中吗InterviewSessionsessionsessionRepository.findById(sessionId);if(session.getStatus()!Status.IN_PROGRESS){thrownewInvalidSessionStatusException();}// 第三步题号校验——答的是当前该答的题吗if(!questionNumber.equals(session.getCurrentQuestionNumber())){thrownewInvalidQuestionNumberException();}// 第四步真正的 AI 评分AnswerResultresultaiInvoker.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——这才是它真正值钱的地方。如果这篇文章对你有帮助不妨收藏起来。下次接手一个老项目、或者要搭一个新项目的知识体系时翻出来对照着做——比从零摸索要快得多。
