上个月复盘团队这半年的AI辅助开发成果我盯着代码库的git历史看了很久越看越心虚。我们明明用上了市面上几乎所有的AI编程工具每个人也都在“用AI写代码”可代码质量不升反降改动散落在各个分支里有些函数被AI“顺手优化”得面目全非有些模块拆到一半就没人管了。我把这种状态叫“散装 AI”——提示词是散装的脚本是散装的每个人脑中的AI工作流也是散装的AI对代码库的操作没有任何统一章法。后来我换了个思路把AI对存量代码的改造从“临时发挥”变成“按规程操作”。具体做法是用SKILL把重构规则、检查清单、工具脚本封装成一个个能力组件再用工作流编排把它们串成一条“手术线”让AI像外科医生一样先做检查、再定方案、小切口下刀、每步都有确认关卡。这套方案跑下来改造效率和对代码的掌控感都回来了。这篇文章就把完整思路和实践过程拆开讲适合那些手里已经有一堆AI工具却总觉得使不上劲的团队和个人。1. “散装AI”病根在哪存量代码改造为什么这么难1.1 存量代码的三个老大难存量代码这个词听起来平淡干过的人才知道里面藏着多少“惊悚”没有测试保护的老模块就像没有安全绳的高空作业命名混乱到你不敢猜一个变量的真实意图模块之间耦合得厉害牵一发动全身。我见过一个600行的函数里面塞了订单校验、折扣计算、库存扣减、日志上报四件事改任何一处都得把另外三处的上下文全看一遍才敢动手。这种代码还有一个特点业务逻辑往往藏在“褶皱”里。表面上的一段循环背后可能是运营拍脑袋定下的规则一个看似多余的if也许正是当年线上事故打上的补丁。这些东西写不进文档只存在于代码本身和少数老员工的脑子里。对AI来说它看到的是“这代码可以优化”对业务来说每一行都可能动不得。所以在存量代码上做改造真正的需求不是“大换血”而是“外科手术级”的精准只动该动的不碰不该碰的每一步都留有余地和退路。这个前提直接决定了后面选择工具和方法论的方向。1.2 散装AI的典型症状工具一堆章法全无我当时统计了一下团队里的AI使用方式大致有几类一些人习惯在聊天窗口里贴长段代码现场编prompt一些人攒了很多“万能提示词”改个名字就换个项目接着用还有一些人写了不少一次性脚本用完就扔在临时目录里。这些方式单独看都没问题凑在一起就成了“散装AI”。散装AI最典型的症状有三个。第一提示词是一次性的。这次让AI“重构orders.py”下次换个文件还得重新解释一遍背景和约束AI没有任何关于“我们团队怎么改代码”的长期记忆顶多能在单个会话里聊出上下文。第二操作路径不可控。你让AI“优化一个函数”它可能顺手把整个模块的命名规范改了因为大模型天生喜欢“自洽”你不约束它它就自己发挥。第三经验无法沉淀。今天踩到的坑、总结出的规则都留在个人聊天记录里团队里的其他人既看不到也复用不了。说到底散装AI的问题不是模型不够强而是人没有给AI建立一个“操作框架”。对全新的小项目AI随便发挥也无所谓但存量代码是另一个物种随便发挥约等于在手术台上让实习生自由发挥。这两个场景的纪律要求完全不同。1.3 为什么偏偏是“微创手术”很多人一提到老代码第一反应是“重写”。我也冲动过但真动手盘点之后就冷静了重写意味着把业务逻辑从代码的褶皱里一点点抠出来再翻译成新代码这个过程中极容易丢东西。而且重写的周期往往比预估长三倍因为你会发现当年很多“奇怪的写法”背后都有不能动的理由。与其推倒重来不如做“微创手术”。微创的价值不在“少写代码”而在“降低风险半径”每一刀都很小切面可控旁边的好组织一点不受影响。哪怕中途发现方向不对缝回去的成本也低。这个理念落到工程上就是小步改动、分批提交、每步验证、随时回滚。而“编排”的意义就是把这种手术纪律变成可执行的流程让AI每一步都按规矩来。所以我在这个项目里的目标很明确不是让AI变得更聪明而是让AI的每一次操作都更规范、更可预期。SKILL体系帮我解决了“规范从哪里来”的问题工作流编排解决了“规矩怎么落地”的问题。2. SKILL到底是什么不是prompt模板是能力组件2.1 解剖一个SKILL包SKILL技能是当前主流AI编程工具里越来越常见的一种机制在不同工具里叫法略有差异本质都类似把一个文件夹放在约定的目录下里面包含一份行为说明和若干配套资源AI在合适的时候会主动加载并按照里面的规则行事。目前包括Cursor、OpenCode以及不少IDE插件在内的主流工具都开始用类似机制加载技能包做法上大同小异。一个标准的SKILL包目录结构大概是这样的legacy-refactor/ ├── SKILL.md ├── checklists/ │ └── safety-checks.md ├── scripts/ │ ├── analyze_deps.py │ └── report_diff.py └── templates/ └── patch-plan.md其中SKILL.md是核心它决定了AI什么时候用、怎么用、边界在哪。文件头部通常有一段元信息比如技能名称和“什么时候该用”的描述AI靠这段描述判断要不要激活这个技能。正文则用自然语言把操作流程、约束条件、注意事项写清楚。别小看这份说明书它其实是在替团队表达“我们认可的做法是什么”。配套资源可以是任何AI不擅长但用脚本能解决的问题。比如依赖分析脚本让AI自己去数一个大函数的调用关系容易数错写成Python脚本用AST去分析又快又准。技能包里还可以放检查清单、代码模板本质上都是把团队的工程规矩固化成文件让AI执行时“有法可依”。这个设计最妙的地方是技能包是纯文本、纯脚本放在代码仓库里就能被多人共享和版本管理。这就像给AI发了一个带操作规程的专用手术器械包——器械是标准化的操作规程是团队定的谁拿起来都能用用坏了还能查版本记录。2.2 SKILL和Prompt、Agent到底差在哪很多人第一次接触SKILL会问这不就是个高级prompt吗其实差别很大。普通prompt是一次性的口头指示“你现在是一个资深Python开发请优化xxx函数”说完就完了AI发挥全靠当时心情。而SKILL是结构化、可复用的能力组件AI每次使用时都要先读说明书再按里面的流程走边界和禁区都写得清清楚楚。我整理过一张简单的对比表写在这里供参考维度普通PromptSKILLAgent复用性低每次都重新解释高一次封装反复使用中看Agent状态可验证性无可带脚本和检查清单依赖框架实现边界控制靠提示词约束说明书里写死红线靠编排和沙箱组合能力弱强多个Skill可串联强但成本高学习成本零低高用一句话概括就是Prompt告诉AI“做什么”SKILL告诉AI“按我们的规矩做什么”Agent则是在多步骤场景中自己做决策。对我们做存量代码改造来说SKILL的关键价值在于“可验证”和“有边界”——这两点恰好是散装AI最缺的。不过SKILL和Agent并不对立。很多agent框架也就是俗称的harness层本身就支持挂载技能让Agent在自主决策时调用这些带约束的技能包。所以你可以理解成SKILL是“能力包”Agent是“发号施令的人”工作流编排则是把这两个东西串起来的“手术流程单”。2.3 编排的真正含义编排这个热词这两年被用滥了但落到存量代码改造上它的内涵很具体定义好步骤顺序、定义好每步的产出、定义好关卡和失败处理。举例来说一个“存量模块拆分”的工作流我会这样编排先跑依赖分析技能输出一份影响面报告然后设一个人工确认关卡——AI不能自己决定方案必须等我把报告看一遍确认哪些函数可以动确认通过后才轮到“小步修改”技能上场每改一个文件马上跑测试全部改完再让“收尾清理”技能干活只处理import顺序、格式这些不痛不痒的东西最后再做一次整体diff审查。这个流程的每一步都是固定、有序的像极了外科手术里的“术前检查→手术方案→下刀→术中监测→术后复查”。这里最容易被忽视的是“关卡”gate的设计。AI对存量代码最大的风险不是不会改而是改得太自信。在关键节点插入人工判断或自动验证等于给手术装了保险丝一旦电流异常立刻熔断。3. 实操给存量代码做“微创手术”全过程3.1 先看看这次要“手术”的对象为了让整个过程可复现我用一个典型场景做演示项目里有个旧模块orders.py里面有个600行的函数process_order把订单校验、折扣计算、库存扣减、日志上报全搅在一起。现状是没有单元测试类型标注缺失异常处理风格混乱不少地方用print调试还留着。目标是在不改对外接口、不改变业务行为的前提下把这个大函数拆成多个小函数统一异常处理补上类型标注。这个场景非常有代表性太老的代码经不起大改但业务还在跑停机窗口几乎为零。定的规矩是对外接口签名一个不能变超过20行的改动必须先出方案每次只允许改一个文件每个文件改完都要能通过现有测试没有测试的就加最小验证脚本。这些约束如果在散装AI模式下就是我贴在那条“重构prompt”里的一堆要求换个人换个工具就失效了。而SKILL模式下这些会变成技能包里的“守则”。3.2 术前准备把改造规则封装成SKILL包第一步是把约束和流程写进SKILL包。我建了一个legacy-refactor技能目录核心的SKILL.md长这样--- name: legacy-refactor description: 对存量代码做最小侵入式安全重构。当需要拆分长函数、统一异常处理、补充类型标注且必须保持对外接口不变时使用。 --- # 存量代码安全重构技能 ## 适用范围 - 已有业务代码改动必须保持行为不变 - 单次改动规模有限制 ## 流程 1. 运行 scripts/analyze_deps.py 目标文件生成依赖影响面报告 2. 基于报告生成 patch-plan列出每个文件的具体改动和理由 3. 每次只修改一个文件单次diff不超过20行 4. 每个文件修改后运行测试命令失败立即回滚 ## 红线 - 不得改变任何对外接口签名 - 不得修改业务逻辑包括看似“多余”的条件判断 - 不得在未生成patch-plan的情况下直接改代码这份说明书的写法有几个讲究。一是description要尽量写得像“触发条件”明确告诉AI在什么场景下启用它才不会在别的场合瞎用。二是流程要可执行不能写“谨慎重构”这种空话要写“运行哪个脚本、输出什么报告”这种具体指令。三是红线要写得绝对大模型对“不”和“禁止”的理解比含糊话强得多。然后我还放了一个安全检查清单checklists/safety-checks.md里面列了AI动手前必须回答的问题这个函数被哪些外部模块引用改动后单元测试能否覆盖有没有隐式的全局状态依赖这一步本质上是把团队里老师傅的经验固化下来AI每次动手前都会被强制“过一遍脑子”。配合的analyze_deps.py用Python的AST把函数定义和调用关系摸清楚输出每个内层函数的被引用次数和依赖模块。脚本我放在技能包里好处是AI自己会去读脚本内容不会出现“AI凭感觉分析依赖”的翻车场景。3.3 编排“手术流程”多个SKILL如何协作单个技能只能解决“怎么改得安全”的问题多个技能才能覆盖“整台手术”的全过程。我在工作流配置里定义了一条完整的链路看起来大概这样workflow: name: legacy-refactor-orders steps: - skill: legacy-analyze output: deps_report.json - gate: human_review prompt: 请确认拆分方案见 deps_report.json - skill: legacy-apply-patches constraint: 每步≤20行逐文件提交 - gate: auto_test command: pytest -q python -m compileall orders.py - skill: legacy-cleanup constraint: 只处理import顺序和格式不改逻辑 - gate: final_review command: git diff --stat pytest -q注意这里的编排不是简单的“按顺序跑一遍”关键是两个gate。human_review把所有“能不能动、怎么动”的决策留给人来做AI只负责提供数据和方案auto_test则是自动闸门只要测试挂了整个流程立刻停下来让AI解释原因并回滚。这套机制保证了AI不会在无人监督的情况下越改越远。为什么编排这一步特别重要因为单看任何一个技能它都能独立工作但独立工作容易各自为政。analyze技能可能建议拆成五个函数apply技能可能觉得拆成三个更“优雅”——中间没人协调最终代码就乱了。编排层解决的就是这个协同问题每个技能只负责自己的任务交接的时候用明确的产出物比如报告、diff来完成信息传递。3.4 执行过程看AI怎么“下刀”配置好之后实操是在编辑器里直接触发工作流。第一步AI调用了analyze_deps.py输出了一份依赖报告显示process_order内部的12个子逻辑块其中三个被外部模块引用四个有内部耦合。看到这份报告我心里就有底了哪些可以拆、哪些要保留纹理一目了然。第二步我确认了拆分方案AI把600行的函数按“校验→折扣→库存→日志”切成四段每段先抽独立函数再逐步替换。真正动手修改的时候AI严格遵守了“单次diff不超过20行”的约束。它先抽取第一个子函数calc_discount复制原逻辑、加上类型标注然后替换原位置调用。每一次替换之后它会主动跑一次编译和最小验证脚本。整个过程跟做手术一样先切开一个小口确认安全再继续下一个切口。最后一轮是清理技能上场把多余的import和print去掉顺手统一了异常处理的写法。我在git里看到的是十几个小commit每个commit都对应一个清晰的动作。这意味着哪怕最后一版有了问题我可以一个commit一个commit地回退而不是面对一整坨“重写后的代码”无从下手。4. 常见问题与排查技巧实录4.1 SKILL不生效先查加载路径和触发描述我在迁移到SKILL模式时踩的第一个坑就是技能明明放好了目录AI却视而不见。排查下来是两个原因一是技能目录放错了位置不同工具约定的加载路径不一样有的是项目根目录下的.skills有的是全局配置目录不放在约定位置就等于没有二是SKILL.md里的description写得太模糊了AI在决定“要不要用这个技能”时靠的就是这段描述如果里面全是“高效重构”这种形容词它完全没理由在工作流里激活。排查建议很简单先把技能目录放到工具官方文档指定的位置然后检查description里是否包含了“在什么场景、碰到什么问题、可以做什么”三要素。测试的时候用一个绕不开的小需求去触发比如明确说“用legacy-refactor技能拆分process_order”看它是否加载。如果还不行看是否要重启IDE或CLI进程很多工具只在启动时扫描技能目录。4.2 AI“切大了”怎么办把红线写进说明书手术最怕切多AI重构也一样。早期我遇到过AI觉得“这个函数既然拆了顺便把依赖也解耦吧”然后开始大范围重构。后来我发现问题出在技能包自己的约束不够——我只写了“单次diff不超过20行”但没写“不得改动未在patch-plan中列出的函数”。补上这一条之后AI的越界行为大幅减少。还有一个实用技巧在SKILL.md里用绝对禁止的句式写红线比如“绝对禁止修改process_order的对外签名”。大模型对这种指令性、否定性的句子敏感度远高于模糊提醒。同时在编排层的gate里加一条“审查diff范围内有没有计划外文件”的脚本出现即中断比事后靠人肉看git diff靠谱得多。4.3 多个SKILL打架靠编排顺序和边界隔离技能一多边界重叠是必然的。我有一次同时挂了legacy-refactor和code-style技能两个技能都想动同一个文件的格式和结构结果AI一会儿按这个规矩改一会儿又按那个规矩改。解决办法是两步走一是在编排里给每个技能划定严格的执行阶段格式清理只放在最后阶段二是让每个技能包都在开头声明“本技能不处理什么”主动让出边界。其实“让出边界”这个概念很值得多说两句。真正好的技能包不是功能越多越好而是范围越清晰越好。就像手术器械包里不会同时放止血钳和电锯每个工具有明确的用途和禁区。编排层把这些工具按手术阶段排好自然就不会互相打架。4.4 给手术装保险回滚和验证的双保险最后一次值得单独讲的坑是回滚。AI重构过程中哪怕每步都有测试也可能出现“测试全绿但业务行为悄悄变了”的情况。应对办法是在动刀之前打一个git tag作为“术前基线”所有改动全部在一个独立分支上进行每个技能每完成一个小步骤就生成一个独立commit。这样整个手术过程就是可回放、可回滚的。再配合数据层面的验证除了跑单元测试我在关键路径上加了断言脚本专门比较重构前后相同输入下的输出。这类“金丝雀测试”在业务代码重构里特别有用能抓住那些单测覆盖不到的隐性问题。止损点越早手术风险越低这点在AI参与改造时尤其重要。5. 我个人的一些体会对存量代码做“微创手术”核心永远不是AI多聪明而是规则多清楚。SKILL体系真正的价值不在于“多了一个新功能”而在于逼着团队把模糊的工程经验写成了可执行文件。你写SKILL.md的过程其实就是把团队里“老师傅知道但没写过”的东西固化下来的过程。我建议每个准备引入这套玩法的人都从整理自己的检查清单开始而不是急着找一堆现成技能来装。再就是别贪大求全。一开始只挑一个最痛、最危险的重构场景做成技能包跑顺了再扩展。技能包和编排流程不是越多越好每多加一个你都要为一个技能负责确保它真的被用上、被维护。闲置的技能和闲置的prompt一样最终都会变成新的“散装资产”。最后分享一个小技巧给技能包写变更日志。我现在的习惯是每个SKILL.md底部留一个changelog区域改一次流程就记一笔。AI改造代码靠的是技能包里的规矩而这些规矩本身也需要持续演进。有了changelog你能清楚地看到团队工程规范是怎么一步步长出来的这比任何管理文档都有说服力。这个方法现在适合任何想把手里的存量代码真正管起来的人。不需要先上一堆重型平台一个技能目录加一个工作流配置就够起步了。跑一段时间你会和我的感受一样——AI还是那个AI代码库的稳定性已经在不知不觉中上了一个台阶。