用SKILL编排给存量代码做微创手术：从散装AI到流程化改造

帮我把这个接口改一下加上字段校验——三个月前我收到这条需求时打开和AI的聊天窗口把代码粘进去等它吐出方案再切回编辑器手动改。一次两次还好可当这个需求牵涉到三个微服务、两张表、五处调用链的时候我发现事情完全失控了AI给我改了A服务忘了B服务的入参校验我手动补上BC服务的日志格式又对不上了。整个上午就在粘贴代码——生成方案——手动粘贴回去之间反复横跳像极了用碎布头拼被子最后拼出一件四处漏风的棉袄。这就是典型的散装AI用法——你有一把好用的手术刀但每次用都要现场磨刀、现场找切口、现场回忆上一次是怎么缝的。后来我接触了SKILL这套东西才意识到问题的本质不在AI笨不笨而在于我根本没有把改存量代码这件事的完整方法论沉淀给AI。SKILL本质上是把一个特定任务的执行流程、约束条件、输出规范打包成一个AI能直接调用的技能包配合编排层把多个技能串成流水线相当于给AI配了一整套标准化的手术器械和操作手册。今天这篇就完整拆一下我是怎么用SKILL编排对一坨跑了五年、牵一发动全身的存量代码完成微创手术的。1. 散装AI的痛为什么零散对话式改代码越改越乱先别急着聊SKILL怎么写我们得先把痛点掰开揉碎。你在对话框里让AI改代码和让AI按一套固定流程改代码看起来都是AI帮你改实际差距非常大。1.1 每一次对话都是从零开始的失忆患者散装AI最大的问题是它不记得你项目的脾气。我那个电商后台的结算模块订单金额字段用的是BigDecimal可AI第一次看到时习惯性给我生成Double——它不知道这个团队的历史约定、不知道这个字段下游有多少对账逻辑在依赖、更不知道数据库里这个字段已经被索引了。你每一次提问它都像一个刚入职的实习生你每次都要重新交代一遍我们这里金额不能用浮点接口响应码统一走ResponseCode枚举这些背景知识。单个文件还好牵涉到跨模块的时候AI在聊天窗口里给你生成的方案经常是局部正确、全局崩溃。它看不到调用方看不到数据流看不到历史包袱。你告诉它改这个方法的返回类型它改了但没告诉你调用方的反序列化会炸——因为聊天窗口里根本没有上下文你得手动把调用方代码也贴进去它才有机会发现。一来二去一次本应十分钟的修改变成两小时的人肉上下文搬运工。1.2 没有过程和约束的AI输出根本无法审计散装AI的第二个致命伤是输出不可复现。上周让AI帮我重构一个工具类它给出了方案我点头说好它改了。这周同样的重构需求稍微变了点边界条件我再问一遍它给出一套完全不同的改法。你没看错同一个项目、同一个模块、近似需求AI两次给的方案南辕北辙因为你没有把约束固化成规则也没有把流程固化成步骤。对于存量代码来说这几乎是要命的。存量代码最怕的就是不确定性——你不知道某次改动会不会碰坏一个三年前埋的兼容逻辑。如果AI每次的方案都是随缘的你根本没法在code review时快速判断这个改动是否安全。散装AI的聊天记录没办法复用上次踩过的坑、定过的约束、排除过的方案全部随着窗口关闭蒸发掉了。1.3 真正需要的是一套可编排的固定方法论后来我想明白了一件事我们需要的不是一个更聪明的AI而是一套把AI聪明用在刀刃上的流程。存量代码改造这件事其实是有标准步骤的先摸清现状、再定位影响面、然后设计改动方案、接着小步执行、最后验证回归。这个流程完全可以标准化标准化之后就能做成SKILL——让AI每次接手存量代码改造时都严格按这套标准来。SKILL的本质是把资深工程师接到任务后大脑里跑的那套隐性流程显性化变成AI可加载、可执行、可复用的技能包。再配合编排层把这些技能按顺序组织起来——相当于你不再跟AI聊天式地东一榔头西一棒子而是给它一条流水线技能A负责扫描现状并输出报告技能B基于报告定位影响面技能C产出精确改动方案技能D执行修改。每一步都有输入输出规范每一步都留痕可审计。这才是对存量代码做微创手术的正确姿势有术前检查、有入路规划、有精细化操作、有术后复查而不是拿AI当砍刀直接劈。2. SKILL到底是什么一套可以被AI团队复用的方法论压缩包我理解的SKILL一句话概括就是把一个特定领域任务的执行方法论打包成AI可以直接加载执行的结构化文件。它不是一个普通的prompt——虽然外表看起来有点像但深度完全不同。2.1 SKILL的文件结构把隐性经验显性化我现在项目里维护的SKILL基本都长这样skills/ ├── legacy_code_surgeon/ │ ├── SKILL.md │ ├── scripts/ │ │ ├── scan_dependencies.py │ │ └── trace_data_flow.py │ └── references/ │ ├── impact_analysis_template.md │ └── change_plan_template.mdSKILL.md是这个技能包的主控文件里面会写清楚这个SKILL是干什么的、在什么场景下启用、执行步骤分几步、每一步的输入输出是什么、有哪些必须遵守的约束和红线。scripts目录放可执行的辅助脚本references放模板文件——比如影响面分析报告的模板、改动方案的模板。比如我写的SKILL.md开头一般长这样# Skill: Legacy Code Surgeon ## Description 对存量代码进行安全、可控、可审计的局部改造微创手术。 适用于老项目新需求、模块重构、技术债清理、风险修复。 不适用绿地项目从零开发、需要大规模架构重写。 ## 执行步骤 1. 术前检查读取项目结构输出模块地图与依赖概览 2. 影响面分析基于目标变更点定位所有调用方、数据流、依赖链 3. 手术方案设计产出最小改动方案标注每个改动的风险等级 4. 分步执行每步只改一个点改完立即验证 5. 术后复查对比改动前后行为差异输出回归结论你看这不只是一句帮我改代码的指令而是一个完整的任务分解框架。AI加载这个SKILL之后它会像带了一个内置SOP一样去执行任务——不会上来就改代码而是先做检查、再分析、再出方案、再动手。2.2 为什么说用了SKILL的AI和没用的AI是两个物种没加载SKILL的AI你问它帮我改一下订单查询接口增加时间范围筛选它会直接给你甩一段新代码。看起来很快但你看完得自己判断这个改动影响哪些调用方分页参数有没有冲突性能有没有隐患所有风险评估都是你自己来做。加载了SKILL的AI同一句话进来它会先跑术前检查——扫描项目结构给你一张模块地图然后做影响面分析——把订单查询接口的所有调用方列出来标注哪些地方会受参数变更影响接着产出手术方案——它会在推荐改接口签名之前先问一句这个接口目前有7个调用方改签名需要同步改7处是否接受或者我们加一个可选参数默认null不影响老调用——你看这就是微创和开胸手术的区别。我实测下来没SKILL的AI方案代码review时间基本是30分钟起步有SKILL的AI方案因为它在方案阶段就把调用链捋清楚了、风险标注出来了review时间能压到10分钟以内。不是AI变聪明了是它被训练成了按你的方法论干活的合格助手。SKILL把不可控的大模型自由发挥变成了可控的流程化执行。2.3 SKILL和普通prompt、以及workflow编排的边界很多人会混淆这三件事。我自己的理解是普通prompt是一句话指令——告诉AI做什么至于怎么做AI自由发挥。SKILL是一套任务流程的操作手册——告诉AI做这件事的完整方法论、步骤、约束、模板它是面向一类任务的。workflow编排是多个SKILL或步骤的流水线串联——它解决的是多个任务怎么衔接、数据怎么流转、产物怎么交接的问题。举我实战的例子我给存量代码改造建了三个SKILL——code_scanner负责扫描和出地图impact_analyzer负责影响面分析mini_surgeon负责执行修改。然后我写了一个编排配置把这三个SKILL串起来code_scanner的输出报告作为impact_analyzer的输入impact_analyzer产出的影响面清单作为mini_surgeon制定最小改动方案的依据。这就是编排——它解决的是三个技能之间怎么配合的问题。打个比方prompt像是你告诉厨师做一道鱼香肉丝SKILL像是给厨师一本川菜标准化操作手册——鱼香肉丝篇里面写了配比、火候、步骤workflow编排则是后厨的动线设计——传菜窗口在哪、配菜间和炒灶怎么衔接、出菜顺序怎么排。没有SKILLAI每次做菜都靠感觉没有编排你有了SKILL也得手工把上一道的菜端给下一道的厨师。3. 存量代码微创手术四阶段我用SKILL编排的完整落地实录接下来进入正题。我挑一个真实做过的改造来完整走一遍一个运行了五年的订单中心需要给它加一个订单备注字段。听起来很小对不对但牵涉到orders表和order_history表、订单创建的三个入口、查询列表的两个接口、导出功能、以及短信通知模板——一个字段牵出七处改动典型的小需求大影响面。我把整个过程跑成了四阶段流水线。3.1 第一阶段术前检查——让AI先画一张模块地图这个阶段的目标只有一个让AI先别动手改代码先把项目扫一遍产出一张带依赖关系的模块地图。我把code_scanner这个SKILL激活它的任务定义是扫描指定模块的项目结构识别实体类、仓储层、服务层、接口层、调用方输出模块依赖图和关键链路清单。约束不得修改任何代码。这里有个关键设计就是这个SKILL除了主文件还挂了一个辅助脚本scan_dependencies.py——它会用正则和语法分析库去扫代码里的import关系、方法调用关系、注解标记把这些信息结构化地喂给AI。纯靠AI自己读代码也能做但几千个文件的代码库让AI硬读效率极低而且容易漏。用脚本先做粗粒度扫描、AI在脚本结果基础上做语义分析两者配合快得多。扫描完成后code_scanner产出的报告包含模块结构订单中心的目录树、分层架构图文字版关键链路订单创建链路controller → service → repository → database涉及哪些类和方法依赖矩阵哪些类引用了OrderEntity哪些服务调用了OrderService.createOrder()这份报告是后续所有工作的基础。没有这张地图之前AI改代码是盲改有了地图之后AI知道自己在哪、要动哪里、哪里不能碰。存量代码最怕的盲人摸象在这一步就解决了一大半。3.2 第二阶段影响面分析——七处改动点是怎么被挖出来的拿到模块地图之后进入第二个SKILLimpact_analyzer。这个SKILL的任务定义是基于模块地图与目标变更点深度分析所有受影响的调用方、数据流、历史兼容逻辑输出影响面清单按风险等级高/中/低标注。这一次加订单备注字段的需求传入之后impact_analyzer把目标拆成两个变更点OrderEntity增加字段OrderCreateRequest增加字段。然后在模块地图上做数据流追踪定位到的受影响范围比我想象的还要全高影响订单创建入口三处APP端、管理后台、开放接口需要同步修改入参转换逻辑。中影响order_history表的快照记录逻辑——历史记录会把订单内容序列化成JSON存一份如果字段加进实体但没加进序列化配置历史记录会丢这个字段。低影响但必须处理导出功能里用了反射列字段新增字段会自动出现在导出列里可能改变导出格式——需要显式排除或配置。这些细节靠人肉去翻代码一下午不一定能翻全。AI带着impact_analyzer的SKILL去做半小时内给出完整清单而且每一处都附了代码定位和原因说明。这就是把资深工程师的经验沉淀成SKILL的效果——它知道查存量代码改造要看哪些地方。我特别想强调这个阶段里SKILL内置的一个红线规则**遇到任何涉及历史兼容的逻辑比如枚举值加项、字段类型变更、序列化格式调整一律先标记为高影响并迁移到风险决策单里由人工确认后才进入下一阶段。**这条规则写在了SKILL.md的约束区。没有这条规则AI很容易在影响面分析时凭感觉把历史兼容逻辑当成普通代码放过去那后面就等着线上事故吧。3.3 第三阶段手术方案设计——最小改动量的微创入路影响面清单确认之后mini_surgeon这个SKILL开始产出改动方案。这个SKILL的核心约束是微创的两个原则最小改动能不动接口签名就不动接口签名能不加新方法就不加新方法一切以降低回归风险为优先。显式兼容任何新增字段必须考虑老数据、老调用方的兼容性。它最终产出的方案是这样的OrderEntity增加remark字段使用Column(name remark)映射到数据库orders.remark列可空。OrderCreateRequest增加remark字段统一使用Size(max 200)校验。订单创建三处入口只改DTO → Entity的转换方法不动接口签名——老调用方不传remark它自然为null完美兼容。order_history的序列化配置显式把remark字段加入序列化字段列表确保历史记录不丢字段。导出功能在反射字段过滤配置里把remark字段排除在导出列之外避免改变现有导出模板。方案里没让AI直接改代码而是先给方案标注每处的改动文件路径、方法名、改动类型新增/修改、风险等级以及对应的测试建议。这个方案我来做review所有改动点都在影响面清单覆盖范围内没有意外动作10分钟确认通过。存量代码改造最忌讳的就是AI顺手优化——改着改着顺手把变量名重构了、顺手把if逻辑简化了看起来是好事但每一处顺手都在增加回归风险。所以我在mini_surgeon的SKILL里写明了一条硬约束**严格按方案执行禁止做方案外的任何顺手优化即使觉得很合理也只能记录到额外发现备注中留给人工决定。**这条被我称为微创手术的纪律是整套方法论里最值钱的一句话。3.4 第四阶段分步执行与术后复查——每动一刀就验一次方案确认后执行阶段我的做法是不让AI一次性把七处全部改完而是让它分步执行每步只改一个点然后用项目现有的测试集或让AI生成的最小验证用例跑一遍验证绿了才继续下一步。这一步的编排我很早就写死在流程里了改OrderEntity加字段跑实体映射相关测试。改OrderCreateRequest加字段与校验跑参数校验测试。改三处入口的DTO转换跑订单创建全链路测试。改order_history序列化配置跑历史记录写入测试。改导出过滤配置跑导出行字段验证。每一步改完AI都会输出本步改动文件、行为变化说明、验证结果。整个过程中任何一步测试红了流程暂停AI要把失败原因和分析报告输出由我决定是回滚这一步还是修正继续。全部执行完之后还有一道术后复查关卡——这个也是我后来手动加进去的编排节点。AI需要做一次全局diff复查对比改动前后的完整代码差异逐项核对与影响面清单的吻合度确认没有影子改动混进去。这一步非常有效因为我真的抓到过一次AI在改转换方法时顺手删了一个看似无用的if——那个if其实是处理老版本空指针的防御逻辑。幸好有术后复查把差异拎出来问了我一句这里有一个非方案内的删除是否确认我才没让一个隐藏的坑上线。4. 编排层实战从单个SKILL到流水线的三种组合模式有了SKILL不等于完事还得解决怎么把这些SKILL串起来的问题。我实际用下来编排模式大致有三种按复杂度和场景需求选。4.1 顺序流水线前一个输出就是后一个输入最简单也最常用的模式就是前面展示的code_scanner→impact_analyzer→mini_surgeon。这种模式下编排层的主要工作有两个定义每个SKILL的启停条件和交接物格式在交接处加人工确认点。我用的编排配置交接物的格式是统一的Markdown报告每个报告头部都有报告类型、生成时间、目标范围、结论这几个字段方便下一个SKILL快速解析。人工确认点加在影响面清单确认和手术方案确认这两个关键位置——因为这两处的判断直接决定后面的执行风险我坚持不把这两步做成全自动。顺序流水线的核心价值是过程可追溯。每个环节都留下了结构化产物地图、影响面清单、手术方案、分步执行记录、复查报告。这套东西不只是给AI看的也是给人看的——版本上线前我把这套流水线产物贴到团队的变更评审文档里代码reviewer不需要从零理解全局顺着流水线看下来就能快速建立判断。4.2 分支决策编排同一个任务不同的SKILL分支有些任务不是线性的需要根据中间结果走不同分支。我在做另一个故障排查类需求时用过这个模式先跑一个diagnosisSKILL做症状采集和原因假设然后根据假设类型走不同分支——如果是数据问题走data_samplerSKILL如果是并发问题走concurrency_inspectorSKILL如果是代码逻辑问题走logic_tracerSKILL。编排层在这里的作用是定义分支判断条件。我在编排配置里写的就是after: diagnosis condition: - if: 假设类型包含数据 run: data_sampler - if: 假设类型包含并发 run: concurrency_inspector - if: 假设类型包含逻辑 run: logic_tracer这种模式非常适合把一个资深工程师排查问题的完整思路固化下来。因为我们排查问题时本来就有一个决策树先看症状再假设原因再验证。把这个决策树变成编排逻辑AI就不只是给一个答案而是走一套排查流程——就算它最后给的答案不对它留下的排查过程和中间证据也足够帮我们定位问题。4.3 人机协同编排什么时候该让AI停这是我的核心经验也是我踩过很多坑之后总结出来的编排设计里最重要的事情不是让AI多做而是让AI知道什么时候该停、什么时候该把方向盘交给人。我在所有涉及存量代码改造的编排里都预设了三种停靠点决策停靠点影响面确认、方案确认这种需要人来拍板的节点AI输出完整信息后必须停下来等人确认不允许自动继续。风险停靠点编码过程中遇到方案外的情况比如发现一个方案没覆盖的调用方、一个测试失败原因不明AI必须停下来报告不允许自行扩大改动范围。结束停靠点全部分步执行完后AI不要急着说完成了必须先生成术后复查报告等人确认后流程才算结束。这三个停靠点救过我很多次。有一次在一个支付模块的改造中AI在分步执行的第三步突然检测到一个不在影响面清单里的定时任务调用了被改方法。它没有静默处理而是按风险停靠点的规则停下来输出了一份异常发现报告。我当时一看冷汗就下来了——那个定时任务每天凌晨跑一次如果没被拦下来线上对账必出问题。这就是人机协同编排的意义让AI在不确定的时候把问题交给人而不是自作聪明。5. 从踩坑到落地SKILL编排的几条保命经验方法讲完了说点实在的踩坑经验。这套东西我从零搭起来大概用了三周中间踩过的坑比预想多得多挑几个最有代表性的分享给你。5.1 第一次失败教训SKILL写得太粗AI根本没法执行我最初写的第一个SKILLDescription写的是帮助用户对存量代码进行安全改造。很抽象对吧我把这个SKILL丢给AI让它对订单模块加备注字段。结果AI压根没走流程直接开门见山改起了代码——因为它根本不知道这套流程是什么。问题出在哪我后来才意识到我写的SKILL没有一个明确的执行步骤定义Description里也没说清楚这个任务分几步走、每一步做什么。改法很简单把执行步骤写得像菜谱一样具体## Steps 1. 扫描项目结构识别核心模块与依赖关系输出模块地图。 2. 基于变更点分析影响面输出影响清单标注风险等级。 3. 设计最小改动方案逐项列出改动文件、位置、类型、理由。 4. 分步执行修改每步修改后运行相关测试。 5. 执行全局diff复查输出术后复查报告。写完之后AI的表现立刻变了它开始像模像样地先出地图、再做分析、再出方案、再动手。我这才理解SKILL的精髓就是用足够具体的步骤序列去锚定大模型的执行路径你写得越具体AI跑得越稳。一切都模糊的话大模型只会给你它最习惯的那个反应——直接给答案。5.2 模板文件比你想的更重要它是产出格式的锚点另一个深刻教训是references目录里的模板文件绝对不是摆设。早期我写的SKILL只有SKILL.mdAI产出的影响面报告每次格式都不一样有时是表格有时是列表有时直接一段话夹带几个代码引用。格式不稳定带来了一个具体问题——下一个SKILL解析上一份报告的时候经常因为格式差异解析失败或者漏读信息。后来我建立了统一的报告模板放在references/impact_analysis_template.md里SKILL.md里明确写影响面报告必须严格遵循模板文件格式不得改动章节结构。模板里定义好了章节影响范围、变更点、风险清单、兼容性说明、待确认事项。从那以后AI产出的报告结构稳定如复制粘贴下游SKILL解析的准确率大幅提升。这个经验推广到所有SKILL任何需要下游继续消费的产物都必须配模板。没有模板的产出就像没有规格的零件装上就打架。5.3 编排不是越自动越好人工确认点不要省我以为把整个流程做成全自动会很爽真做了之后发现那是灾难。有一版编排我取消了中间所有人工确认点让AI一条龙跑完七处改动结果它跑完给我交了一份全部完成、测试通过的报告。我review代码的时候发现它在第三步改DTO转换时把另一个方法里一个类似的转换逻辑也顺手改了——但因为那个方法不在影响面清单里所以全局diff复查时它自己也给漏了。我看了半天才发现。从那以后我彻底学乖了所有关键决策点必须保留人工确认这是安全底线也是练习代价最小的止损手段。5.4 起步建议从最小闭环开始再逐渐加厚最后给想入坑的朋友一个实在的建议。不要一开始就设计一个七SKILL互相调用的宏大编排我第一批SKILL就是这么over-engineered的搞到后面自己都维护不动。先从一个最小闭环跑通它选一类你最常做的存量代码任务比如加一个字段或修复一个bug。写一个SKILL只包含三步影响面分析 → 方案设计 → 分步执行。人工跑两三遍每次把AI没做好的地方、漏掉的地方往SKILL.md的约束区里补一条规则。等这一个SKILL稳定了再加第二个SKILL做手术前扫描把它俩用一个简单编排串起来。再往后按实际需求慢慢增加模板、脚本、更多SKILL。我现在的legacy_code_surgeon这套东西就是从最初一个极简的SKILL迭代了十几版才长成现在这个完整度的。最初的版本连模板都没有就一个大步骤加一个改动前先列影响清单的约束。就是这一点点的约束沉淀让AI的表现每次都比上一版稳一点。跑久了你会发现真正让AI从偶尔好用的玩具变成可靠的生产工具的从来不是某个灵光一现的魔法prompt而是这套把方法论不断沉淀成流程、把流程度量成产物、把产物回灌给流程的笨功夫。