SKILL编排：让AI在存量代码改造中不闯祸

最近这两个月我一直在折腾一件事用 SKILL 编排的方式把一批跑了六七年的存量代码一点点洗干净。不是推翻重写而是像做微创手术一样在尽量不动外部行为的前提下把里面的隐患、坏味道、重复逻辑逐个处理掉。折腾下来最大的体会是AI 本身并不稀缺稀缺的是怎么让 AI 在存量代码里不闯祸。过去我试过最“散装”的做法是开一堆对话窗口让 AI 看一个文件改一个文件改完合入跑挂了再回去让 AI 修。一顿操作猛如虎回头看 diff 全是格式化噪音和顺手“优化”真正要改的那一行反而被淹没了。后来我把思路换成了 SKILL 编排先把改造流程拆成一个个可复用的技能包再像流水线一样按顺序执行每个环节都有输入、有输出、有验收。这套打法对内有多凶险的存量代码外有多挑剔的验收标准都适用。这篇文章我把整个思路、实操流程、踩过的坑都梳理一遍。如果你也在给老项目做 AI 辅助改造或者被散装 AI 改崩过代码这篇应该能给你一个能直接抄作业的路线。1. 为什么“散装 AI”治不好存量代码的毛病1.1 “散装 AI”的三宗罪断上下文、乱漂移、无闭环先说散装 AI 在存量代码里最常见的翻车现场。第一宗罪是上下文断裂。每次开新对话AI 就像失忆了一样你得把模块的背景、业务规则、历史坑重新解释一遍。更麻烦的是同一个代码库的不同文件之间本来就有隐式关联散装对话根本没法把这些关联串起来经常出现改 A 文件时完全不知道 B 文件里的调用方对它有依赖。第二宗罪是方向漂移。你让 AI 修一个资源未释放的小问题它改着改着顺手把整个文件的函数签名重命名了还把一段 200 行的业务逻辑“优化”成了新写法。你说它有错吧改得确实更“现代”了你说它对呢这次任务只是修三行代码。方向漂移的本质是任务边界不清晰AI 在长对话里会不自觉扩大改造范围这对存量代码来说是致命的。第三宗罪是没有验证闭环。散装模式下AI 经常给你一句“已完成”但没有任何测试、没有回归、没有行为对比。存量代码本来就缺测试结果就是改完靠肉眼 review合入靠玄学。我见过不少团队AI 改完上线线上报错后第一反应是“AI 写的代码不靠谱”其实问题不在 AI在于整个流程里没有人给 AI 上紧箍咒。1.2 存量代码和绿地代码是两种完全不同的物种绿地代码想怎么设计都行目录结构、依赖关系、测试体系都是白纸一张。存量代码完全反过来它是另一个物种。第一文档和需求早就丢了业务规则全埋在代码里有些还是上一批离职同事留下的“艺术品”第二测试覆盖率低到可以忽略很多模块一跑就报依赖错误更别提自动化回归第三隐藏依赖特别多全局状态、环境变量、配置文件、外部服务三者之间互相纠缠。在存量代码里不能谈“重写”原因很现实没人敢在缺少测试、缺少行为基线的情况下推倒重来。业务还在跑线上还在用谁重写谁背锅。但全盘不动也不行技术债每天在累积利息。这就逼出了一个结论只能做微创手术而不是装修拆墙。装修可以全砸了重来反正住户搬走了手术不行病人还躺在手术台上你只能先定位病灶画好切口在尽量不伤害周边组织的前提下把问题摘除掉。存量代码改造也是这个逻辑目标不是“把它重新写漂亮”而是“在行为不变或最小变化的前提下解决具体问题”。2. SKILL 编排的思路把 AI 从临时工变成专科医生2.1 SKILL 到底是什么我理解的 SKILL就是把特定场景下的工作流程、领域知识、约束条件和验收标准打包成一份可复用的结构化指令。它不是普通 prompt。普通 prompt 是一次性口述说完就没了SKILL 是一份沉淀下来的 SOPAI 每次接到同类任务都按这份协议干活。一个标准的 SKILL 通常包含这几块任务目标、输入信息、执行步骤、约束条件、负面清单、输出要求、验收标准。下面是我在一个改造项目里实际用过的 SKILL 骨架你可以直接拿去改--- name: legacy_safe_modify description: 对存量代码模块做最小差异的安全修改 --- ## 任务目标 在保持对外行为不变或最小变化的前提下 修复指定代码片段中的具体问题。 ## 输入 - 目标文件路径 - 函数/方法名 - 问题描述越具体越好 - 行为快照文件路径 ## 执行步骤 1. 阅读目标文件确认函数所在模块的上下文 2. 阅读行为快照明确哪些行为是不可改变的 3. 定位问题点设计最小改动方案 4. 修改代码禁止改动与本问题无关的行 5. 执行测试命令确认全部通过 6. 输出 diff 自检报告 ## 约束条件 - 禁止修改公共 API 签名 - 禁止格式化、重命名、重构无关代码 - 禁止改动异常处理逻辑除非任务明确要求 - 每次只处理一个函数改动控制在 20 行以内 ## 负面清单 - 不要顺手“优化”注释 - 不要引入新依赖 - 不要修改 import 顺序与格式 ## 输出要求 - 返回改前改后代码对比 - 返回测试执行结果 - 返回本次改动的行为影响说明 ## 验收标准 - 原有测试全部通过 - diff 中不包含无关修改 - 行为快照中的输入输出样例全部一致这里最关键的设计是“约束条件”和“负面清单”。你在约束里写“注意安全”没有任何用AI 不知道什么叫安全你得写“禁止修改公共 API 签名”“每次只处理一个函数”“改动控制在 20 行以内”机器才能真的遵守。负面清单更是刚需我试过一个 SKILL 里没写负面清单AI 每次都忍不住去“美化”代码加完负面清单之后这个毛病基本根治了。2.2 编排是怎么运转的技能链、输入输出契约、检查点单个 SKILL 解决不了复杂改造复杂改造一定需要多个 SKILL 协作这就是编排。编排的核心是把一个大任务切成若干子任务每个子任务由一个 SKILL 负责前一个 SKILL 的输出作为后一个 SKILL 的输入中间还穿插人工检查点。具体到存量代码改造我的编排链路通常是这样的code_map生成模块调用图→ behavior_snapshot记录行为基线→ safe_modify执行最小改动→ test_and_review测试 自检每个环节都有明确的输入输出契约。比如 behavior_snapshot 的输入是目标函数和一组固定输入样例输出是一份行为快照文件safe_modify 的输入是目标文件、问题描述和行为快照输出是 diff 和自检报告。有了这种契约AI 在执行不同环节时不需要重新解释上下文直接读文件就行。编排还有一层隐含的好处它天然对抗了长上下文的注意力衰减。存量代码改造往往涉及几百上千行代码全塞进一个上下文里AI 很快就“记不住”约束条件了。编排后每个子任务只聚焦一个切片上下文短了约束的保持率高得多。2.3 编排带来的三个实在好处可复用、可审计、可收敛第一个好处是可复用。这次给订单模块做改造沉淀下来的 code_map、behavior_snapshot、safe_modify 这几个 SKILL下次给支付模块、用户模块做同类改造时可以直接复用不需要重新调教 AI。团队里任何一个人拿到这套 SKILL 和方法都能达到接近的改造质量。第二个好处是可审计。散装 AI 改完代码你只能看到最终结果中间发生了什么全是黑盒。编排模式下每一步都有产物调用图、行为快照、diff 自检报告、测试输出。出了问题往回追溯一目了然是哪个环节跑偏了。第三个好处是可收敛风险。编排把一次大改造拆成了多个小切口每个切口都有人工检查点。我见过最差的 AI 改造事故是一次性让 AI 改了三十多个文件合入后线上服务直接雪崩。用编排之后一个 SKILL 只动一个点即使出了问题回滚范围也小得多。3. 落地实操给一段存量代码做“微创手术”下面用一个我实际处理过的案例来讲完整流程方便你照着复现。场景是这样的一个老 Python 服务模块里有个全局缓存字典多线程环境下并发写入时偶尔会读到脏数据同时fetch_data函数在异常时把错误吞掉了调用方拿不到任何提示问题定位非常困难。这次手术的目标很明确缓存并发访问要加锁保护异常要记录日志但保持原有返回值不变除此之外不做任何其他改动。3.1 术前准备先建立基线再动刀任何手术前都要先确认病人的基础状态存量代码改造也一样。第一步确认工作区干净记录当前 git commit保证随时能回滚。第二步跑一遍模块现有的测试不管测试覆盖多少先记下当前是绿还是红。第三步给目标函数补两条冒烟测试一条正常路径、一条异常路径先把行为的“底线”钉住。这一步很容易被跳过但我强烈建议不要省。没有基线后面所有的改造是否成功都无从判断。行为基线还不是写测试就完事最好再补一个行为快照给定几组固定输入记录当前函数的真实输出。异常路径也要记录比如当前异常时返回 None那这条行为在术后也必须保持 None除非需求方明确说允许变化。3.2 设计手术切口划定改动边界术前准备做完接下来是切口设计。很多人拿到改造任务就急着让 AI 动手其实最该花时间的恰恰是这一步。你要先回答三个问题改什么、不改什么、预期变化点是什么。改什么这次是fetch_data函数内部缓存访问要加锁异常路径要加日志。不改什么公共函数签名、调用方接口、返回值语义异常仍返回 None。预期变化点并发场景下不再出现脏数据异常时日志有记录。这三个问题写清楚后变成一个“改造说明”文件作为 safe_modify SKILL 的输入。设计切口时有一个常见误区想借着这次改造顺手把别的问题也解决了。比如“既然都打开这个文件了把那个废弃函数也删掉吧”。这种想法一定要克制住。微创手术的精髓是每次只处理一个病灶切口越小并发症越少。一个改造任务只解决一个问题其他问题单独排期这是我能给的最大建议。3.3 用 SKILL 驱动实施小步快跑每刀都有验证实施阶段我按前面说的编排链路来。先调用 code_map 生成模块调用图确认fetch_data只有两个调用方且都不依赖内部缓存的具体行为手术区域不会波及外围。再调用 behavior_snapshot 拿到行为基线这时候术前补的测试和快照文件就派上用场了。接下来执行 safe_modify。目标文件路径、问题描述、行为快照作为输入SKILL 会自己读代码、设计方案、改代码、跑测试。我这次要求的改动其实很小加一把锁再在异常分支补一条日志。改完后 AI 输出了一份 diff 自检报告我 review 了一遍发现它按负面清单老老实实没动其他行连注释多余的空格都没碰。这一刀改动小风险低可以直接走测试和自检。如果任务复杂就得多调度几轮上一刀验证通过才允许开下一刀。这个过程就像真正的微创手术每一刀下去之前都要确认不会伤到神经和血管确认后再落刀。有个细节值得单独说一下在执行层AI 改代码一定要基于“当前工作区最新版本”不要让它拿着旧代码改完再合入。如果前一步有人改了同一个文件后一步执行前先重新拉取最新内容不然会出现“改的版本早已过期”的诡异问题。3.4 术后缝合验收与回滚预案改完代码只是完成了一半验证才是微创手术的缝合段。我习惯按三个层次验收。第一层跑全部相关测试确认术前补的冒烟测试和目标模块的原本测试全部通过。第二层做行为快照对比术前记录的输入输出样例术后跑一遍逐条核对。异常路径我尤其看重如果术前是异常返回 None术后也必须返回 None只是多了一条日志。第三层人工看 diff。不要只扫一遍就合入要逐文件看重点盯“无关修改”。我见过 SKILL 明明写了负面清单AI 还是会偶尔漏一两个“顺手优化”。所以每次合入前我都会跑一下git diff --stat如果看到文件变更数或行数与手术范围明显不匹配直接打回重改。万一验证出了问题处理原则是直接回滚不要让 AI 继续“缝缝补补”。回滚到术前 commit或者用 git revert 回退指定 commit都比让 AI 在错误基础上继续改更安全。存量代码的毛病本来就多一次回滚的成本远比一次失控改动带来的连锁反应低。4. SKILL 的编写与积累从一次性改造走向体系化4.1 写一个好用 SKILL 的核心要素操作次数多了你会发现 SKILL 的质量直接决定 AI 改造的下限。我总结下来一个好 SKILL 必备五个要素。第一目标单一。一个 SKILL 只解决一个场景问题不要搞“全能型技能”。code_map 就专注于生成调用关系safe_modify 就专注于改代码混在一起时 AI 的注意力会被稀释。这个体验跟人一样岗位职责越清晰执行越到位。第二约束具体。写“不要乱改”等于没写写“禁止修改公共 API 签名”“禁止改动异常处理逻辑”才是有效约束。最好是每一条都能在 diff 里被客观检查这样 AI 违反约束时你能立刻发现。第三验收可执行。验收标准写“保证代码质量”没用要写“原有测试全部通过”“行为快照一致”“diff 中不包含无关修改”。可执行意味着有确定性的检查命令或比对步骤而不是靠感觉。第四示例优先。在 SKILL 里放一两个输入输出示例比写十句说明奏效。AI 对 Few-shot 的模仿能力远强于对抽象规则的理解这是大模型的天性。我通常在 SKILL 里加一个“参考示例”小节直接贴正例和反例。第五负面清单必选。告诉 AI 不要做什么比告诉它要做什么更能防止跑偏。我自己的 SKILL 里“负面清单”永远独立成节放在“执行步骤”之后确保 AI 在生成过程中能高频看到。负面清单的另一个作用是约束范围AI 看到“不要引入新依赖”时就不会擅自改 requirements。第五个也很重要的点是写 SKILL 的人最好自己踩过对应的坑。让一个没做过存量代码改造的人写 legacy_safe_modify写出来大概率是空话。SKILL 是经验的产品化没有真实场景支撑它就是一份漂亮的废纸。4.2 SKILL 的版本维护和团队协作SKILL 跑了一段时间后团队里会积累一批技能这时候维护问题就来了。我的做法是给 SKILL 建一个独立的 git 仓库和业务代码分开。目录结构大致长这样skills/ code_map/ SKILL.md examples/ sample_call_graph.json behavior_snapshot/ SKILL.md safe_modify/ SKILL.md negative_examples.md test_and_review/ SKILL.mdSKILL 的变化也需要走评审。我见过最典型的问题是有人为了让 AI 更快完成任务往 SKILL 里偷偷删掉了一条约束结果后续所有改造都开始放飞。所以 SKILL 的变更记录要留痕每次修改都要写清楚原因。我和团队现在的规则是SKILL 变更必须有至少两个人 review跟业务代码评审同等对待。还有一个经常被忽略的点SKILL 会过期。代码库的目录结构变了SKILL 里写的路径就要同步更新工具的接口变了SKILL 里的执行命令也要跟着改。建议每季度做一次 SKILL 盘点把半年没被调用的技能标记为待审查要么让它重新活跃要么直接归档。技能库不维护最终会变成和存量代码一样的另一笔技术债。4.3 和现有工具链结合让 SKILL 编排跑得更顺SKILL 编排不是孤立存在的它要跟团队的现有工具链捏合在一起。第一层是执行环境。AI 跑 SKILL 时需要能直接调用命令行工具比如用 AST 工具解析代码结构、用 git diff 检查差异、用测试框架跑回归。如果 AI 只能看文本不能执行命令很多 SKILL 的效果会大打折扣。第二层是 CI 集成。术后缝合阶段的行为快照对比、测试执行完全可以挂进 CI作为每次合入的自动关卡。术前录音、术后对账这一套逻辑跟自动化测试天然兼容。CI 脚本里加一步behavior_snapshot verify跑挂了就不让合入这一步能挡住大量低级回归。第三层是人工评审通道。SKILL 编排产出的 diff 自检报告、行为快照、测试日志要能方便地附在评审请求里。评审者看到的不只是几百行 diff还包括 AI 自己产出的“本次改动影响说明”评审效率会高很多。如果你用了一些开源的 Agent 运行时或编排框架SKILL 也可以直接注册成可调用的工具让编排层按流程自动路由。多智能体的场景下每个智能体专注一个 SKILL互相之间的交接就靠输入输出契约这条思路和前面讲的是完全一致的。5. 常见问题与避坑指南5.1 AI 改错逻辑怎么办症状SKILL 里明明写了“禁止修改异常处理逻辑”AI 还是把异常改成了抛出。原因通常是约束写在了“执行步骤”之后AI 在长任务执行过程中把步骤中段的约束给忘了。解决办法有两个方向一是把最关键约束放到任务目标正下方让 AI 在最开始就高频看到二是加一个事后自检环节让 AI 在输出 diff 前先对照约束清单逐条自查。如果自检还是挡不住就在编排链路里加一个专门的 verification SKILL。它的唯一职责是检查 AI 产出的 diff 是否违反了约束规则用规则引擎把“不能改什么”固化成可执行检查。这是最后一道闸门也是我实测下来最稳的姿势。切记不要靠“重新对话让 AI 认错再改”来兜底散装模式的所有缺点在纠错环节会全部重演。5.2 SKILL 越堆越多不知道怎么选症状团队跑了一个月技能库膨胀到几十个 SKILL执行 AI 改造时不知道调哪个。解法是给 SKILL 做分层底层是原子技能负责通用操作比如生成调用图、记录行为快照、执行测试上层是场景技能沉淀具体业务场景的经验比如“链路压测前做静态检查”“订单模块权限点梳理”。原子技能数量少、复用率高场景技能数量多、针对性强最好按模块或业务线分类存放。让执行者知道调哪个一个好办法是给每个 SKILL 写够质量的 description。很多 Agent 运行时支持根据描述自动匹配技能描述写得含糊选错的概率就高。参考标准描述里要说清楚“这个技能处理什么场景、需要什么输入、产出什么结果、在什么情况下不要用”。5.3 团队觉得流程重不想用症状引入 SKILL 编排后每次改造都要先写基线、补测试、走三四个环节团队抱怨“以前十分钟提交现在一小时起步”。这个抱怨其实指向一个真实问题不是所有改动都需要全流程手术。我认可用分类处理的思路单点 bugfix、一行配置调整这种“微创小修补”走精简版流程一个安全修改 SKILL 加一轮测试就够了跨模块重构、性能优化、架构调整这种“结构性微创”才走完整编排链路。流程重不是问题流程重了但没有换来等价的收益才是问题。让团队接受新方法最好的方式是挑一个收益最直观的任务先试点比如修一个长期存在的隐蔽 bug用 SKILL 编排做干净把对比结果摆给团队看。价值前置流程自然就推得动了。最后再说两句心里话折腾了这两个月最深的感觉是SKILL 编排最大的价值不是让 AI 一次写得更快而是让产出可复制、可检验、可学习。以前散装 AI 改完代码我心惊胆战现在每走一步都有对照物心里踏实多了。如果你也在存量代码里被 AI 坑过建议从最简单的 code_map 加 behavior_snapshot 两个 SKILL 开始跑先补上“看得清、比得对”这两件事再谈自动化改造。微创手术的核心永远是那四个字先别闯祸。