1. 别再散装用AI了先聊聊痛点这几年大伙儿用AI写代码基本都经历过这样的阶段今天让AI补个函数明天让AI解释一段报错后天又让AI帮忙写个单元测试。功能确实有用但用起来总觉得不顺手——每次都要重新描述上下文重复交代项目背景生成的结果也时好时坏。说白了这就是散装AIAI能力像一堆零散的零件散落在工作台各处没有组装成一条完整的产线。尤其是面对存量代码这个问题更加致命。存量代码动辄几万行、几十万行散装AI的典型症状是AI给出的建议只盯着眼前一小块代码完全不顾周边模块的约定让它改A处逻辑它可能连带把B处的风格也改了你希望它只做微创手术它偏偏给你来个大刀阔斧的重构。于是每次改造存量代码要么不敢用AI要么用完提心吊胆地review半天。我自己在几个老项目上踩过不少坑之后慢慢摸索出一套打法用SKILLAgent Skill智能体技能配合workflow工作流编排把AI从随叫随到的临时工改造成懂规矩、走流程、可复用的专业团队。这套方法的核心思路就是给AI划定明确的能力边界和行为规范用编排把多个技能串联成一条稳定的流水线让AI对存量代码做微创手术——精准、低侵入、可回滚。如果你手里正好有一批不敢轻易大改的老代码又希望AI能真正帮上忙而不是添乱这篇文章应该能给你一些可以直接落地的思路和方案。后面我会用一个具体的存量模块改造作为例子把Skill的定制、工作流的编排、质量门禁的设立、回滚预案的设计完整走一遍。提示这篇文章讲的不是某个特定工具的教程而是一套可以迁移的方法论。具体到Codex、opencode、Cursor或者开源框架核心逻辑是通用的。2. 存量代码为什么需要微创手术2.1 存量代码的三个老毛病先说清楚存量代码之所以让人头疼不是因为代码写得烂而是因为它老了。老了就有老了的特征我总结下来是这三个第一约束无处不在。老代码经过多年迭代内部会形成大量隐性的约定。比如某个工具类的调用顺序、某个状态机的流转规则、某个配置项的命名习惯这些约定很少写进文档但散落在代码各处。你要是不知道这些约束就动手改很容易踩雷。第二牵一发动全身。存量代码的模块之间耦合度通常比较高。一个看似独立的函数可能被十几个地方调用你在A模块里加了一个参数B模块编译直接报错。这就是为什么很多人对老代码的态度是能不动就不动。第三测试覆盖大概率不足。老项目的单元测试往往只覆盖核心逻辑边缘分支、异常路径多半是裸奔状态。这时候AI如果帮你改了逻辑你根本没有足够的安全网去验证结果对不对。2.2 散装AI在存量代码前的翻车现场我见过太多散装AI在存量代码面前的翻车现场说几个典型的AI把项目的日志框架从slf4j换成了log4j2的API因为它觉得这样更现代结果整个模块的日志输出格式全变了。AI为了修复一个空指针在方法入口加了一堆防御性判断结果把原本的异常处理逻辑给绕过去了线上出了更难排查的问题。AI生成了一版看起来更优雅的重构代码提交之后发现性能回退了一倍多因为老代码里那些看起来丑陋的写法恰恰是性能优化的结果。这些问题本质上不是AI笨而是它缺少两个东西一是对项目约束的感知能力二是对改动范围和风险的控制能力。散装AI没有这两个能力所以每次出手都像蒙眼手术。2.3 微创手术的核心思路小切口、可控风险、可回退为什么我说要用微创手术的思路来对待存量代码因为存量代码的价值在于稳定运行而不是代码风格好不好看、设计是否优雅。手术的目标是解决一个具体的病灶而不是顺便把全身器官都翻新一遍。微创体现在三个层面小切口每次改动只限定在一个明确的功能点或业务场景内不涉及无关代码。可控风险改动的每一步都有检查和验证机制AI每次提交的修改都必须经过测试或静态检查才能进入下一步。可回退任何一步出了问题都能快速恢复到改动前的状态绝不带着问题继续往下走。要做到这三点光靠给AI一两句prompt是不够的必须把AI的能力拆解成单个的Skill然后用工作流把它们编排成一条固定的工序链。3. Skill与Workflow的基本概念拆解3.1 Skill到底是什么一段可复用的能力封装这东西刚出来的时候很多人把它当成普通的prompt模板来用其实差别挺大。Skill是一段可复用的、针对特定任务的能力封装它包含的不仅是指令文本还有执行该任务所需的背景知识、工具调用方式、输出格式约定甚至包括质量标准和自检清单。你可以把Skill理解为给AI配了一本岗位说明书。说明书里写清楚了这个岗位的职责边界、工作流程、交付标准和常见禁区。AI接到Skill时不是听了一句指令而是进入了一个工作角色。举个例子。一个Code Reviewer Skill的说明书里会包含该项目的代码风格约定、review时要关注哪些风险点并发安全、资源泄漏、异常处理、输出review意见的格式模板、哪些情况可以直接打回。AI加载了这个Skill之后再用它去review代码质量和稳定性就比随口一句帮我看看这段代码有什么问题高得多。3.2 Skill和传统Prompt、插件的关键区别很多用过ChatGPT或Claude的人容易混淆几个概念Prompt、Plugin插件和Skill。我个人的理解三者的差异可以这样概括维度传统Prompt插件/工具Skill本质一次性指令外部能力扩展角色流程标准的能力封装复用性弱每次要重新描述中可重复调用强多场景复用上下文感知依赖临时描述依赖接口对接自带项目背景和约束质量控制无内置机制无内置机制内置自检清单和质量标准这个区别非常关键。传统Prompt的问题是说过就忘下次还得重新说插件的问题是只管执行不管质量——它能帮你执行命令、查资料但是对于这个活干得怎么样没有判断能力。Skill则把两者结合起来它既是一套可复用的指令集又是一套质量控制机制。3.3 Workflow编排把Skill从单点能力变成流水线单个Skill解决的是单个环节的效率问题但存量代码改造这种活儿从来不是一个环节能搞定的。你需要先理解现状再定位病灶然后设计改动方案接着生成补丁再跑测试验证最后还要做代码审查。这些环节串起来才是一次完整的微创手术。Workflow编排做的事情就是把这些环节组织成一条明确定义的流水线每个环节调用哪个Skill、输入是什么、输出是什么、如何判断是否满足进入下一环节的条件。一旦编排完成整个过程就变成可重复执行的标准流程——这周改订单模块能走这个流程下周改支付模块还能走这个流程。编排的好处是把复杂度锁在流水线内部使用者只需要关心我要修什么问题不需要关心AI具体是怎么一步步完成这件事的。而且每个环节都有检查点哪里出问题就停在哪里不会一路错到底。4. 项目落地从零搭建一套SKILL编排体系4.1 术前规划梳理项目现状与改造目标正式开始之前我建议你先做一个术前检查。这里说的不是代码review而是把项目现状梳理清楚明确改造的目标边界。这一步花30分钟后面省的不止3小时。我的习惯是列三张清单第一张领域清单。把项目按照业务模块拆开比如订单模块、库存模块、用户模块、支付模块。每个模块记录一下核心职责、主要入口、依赖关系。第二张约束清单。记录改造时要遵守的硬性约束比如必须使用项目现有的日志框架、数据库访问必须走DAO层、禁止改变对外接口签名、禁止修改公共工具类。这些约束会写进Skill的角色设定里相当于手术的红线。第三张目标清单。明确这次要解决的到底是什么问题。是修一个反复出现的bug还是把一段逻辑迁移到新框架还是优化某个接口的响应时间目标越具体后面的改造越有章可循。我见过很多人省掉这一步直接让AI开工结果AI改到一半发现连要干什么都没说清楚生成了一堆离题万里的代码。术前规划不是形式主义它是给整个流程定航线。4.2 定制Skill四个必备的存量代码改造技能基于大量实操我把存量代码改造需要的Skill分成四类每一类承担流水线上的一个环节。这套分类不依赖具体工具你可以把它适配到Codex、opencode、Cursor或者任何支持Skill机制的AI环境中。第一个是代码探测Skill我习惯叫它内窥镜。这个Skill的作用是让AI先理解一段代码的现状再做任何修改。它要求AI完成梳理函数调用关系、标注关键变量的流转路径、识别潜在的隐式约束、输出一段代码现状说明。输出格式有固定模板不能直接给结论必须按模板输出结构化的分析结果。第二个是方案设计Skill扮演主刀医生的角色。AI拿到探测结果之后需要提出改动方案。这个Skill的指令里明确要求方案必须控制在最小范围内、必须列出受影响的上下游模块、必须给出风险等级评估。如果方案涉及超过N个文件的改动Skill会要求AI说明必要性否则直接建议拆分成多个阶段的改动。第三个是补丁生成Skill相当于手术器械。这个Skill要求AI严格基于方案生成代码补丁不能夹带私货。指令里明确写了禁止顺手重构、禁止修改无关代码、禁止改变既有代码风格。这一步特别重要因为AI最容易在这里跑偏——它倾向于生成更漂亮的代码而不是更合适的代码。第四个是质量审查Skill也就是术后检查。AI生成完补丁后不能直接提交必须先过这一关。审查Skill会检查改动是否严格对应方案、是否引入新的依赖、是否遵守了约束清单、是否存在边界情况遗漏。审查通过才能进入下一步否则打回给补丁生成环节重新做。注意这些Skill的指令和模板要根据自己的项目来定制不要直接照搬网上的通用Skill。通用Skill最大的问题是不了解你的项目的隐性约束而存量代码改造恰恰最依赖这些隐性约束。4.3 搭建工作流把四个Skill编排成一条流水线有四个Skill下一步就是把它们编排成工作流。编排的关键是定义清楚每个环节的输入输出和验收标准。我的工作流设计大概是这样的环节一探测与理解。输入是问题描述目标代码路径调用代码探测Skill输出的是一份结构化的现状分析报告。这一环节的验收标准是分析报告里必须包含完整的调用链和已识别的约束项如果AI漏掉了约束项后面的环节直接失控。环节二方案设计与确认。输入是现状分析报告调用方案设计Skill输出是改动方案。这里有一个人工介入点AI生成的方案需要开发者确认确认通过才进入补丁生成。不要跳过这一步因为方案的合理性只有人才能最终判断AI的优化视角有局限。环节三补丁生成。输入是确认过的方案调用补丁生成Skill输出是具体的代码diff。验收标准是diff中涉及的文件数量和改动行数必须在方案预估范围内超出则视为不合格。环节四质量审查与修复。输入是代码diff调用质量审查Skill输出是审查意见。如果发现问题AI需要根据审查意见自行修复修复后再走一遍审查。这个循环可以重复多次直到审查通过或者达到最大重试次数。环节五测试验证。工作流不在这里结束还要自动触发相关测试用例如果项目测试覆盖不足至少要求AI补充边界场景的验证。这一步的目的是给微创手术加上最后的保险。我实践中强烈建议把工作流可视化。很多支持编排的工具都带节点图当初看没觉得有啥用后来发现可视化对于调试工作流特别有价值——当某个环节卡住时你一眼就能看出是哪一步的问题不用对着配置JSON发呆。4.4 工具选型Codex、opencode还是通用Agent框架Skill和编排不是某个工具的专属概念但不同工具的落地方式有差异简单说一下我在实际项目里接触过的几个方向。Codex这块它的Skills机制和项目上下文结合得比较紧。如果你用Codex可以把它原生的skills目录当作Skill的存放地每个子目录对应一个Skill包含SKILL.md指令文件和可选资源文件。它的优势是模型本身对代码库的理解能力强Skill和代码库的上下文可以无缝结合。opencode走的路线更开放Skills就是普通的Markdown文件加可选脚本可以放到项目里跟随代码库一起走。它的安装和使用门槛很低适合想快速尝试、又不想被绑定在某个特定IDE里的场景。opencode的Skill机制还支持模板参数适合需要动态传入上下文的场景。通用Agent框架比如各类支持多智能体编排的开源框架更适合复杂场景。如果你的改造链路不只是代码生成还涉及多轮工具调用、多个子系统的协同用框架来管理Skill和Workflow会更灵活。网上有不少人在讨论用这类框架把多个智能体编排起来做代码改造方向和我这里讲的一致只是抽象层级更高。选型建议只有一条从自己最熟悉、能最快跑通的工具入手不要一上来就搭特别复杂的框架。Simple Skill Simple Workflow 跑通一个端到端的案例再逐步加复杂度这个路径基本不会错。提示不管你用哪个工具Skill文件本身建议纳入版本管理。Skill是会迭代的——项目约束变了、团队规范变了Skill的指令也要跟着改。纳入版本管理改起来才有迹可循。5. 实操实录一个真实的存量改造全流程5.1 案例背景订单模块的一个老龄化问题为了不让这套方法停在概念层面我用一个小案例把流程走一遍。假设有个老项目订单模块里有一段计价逻辑过去半年已经出过两三次价格计算偏差的问题。每次修完没过多久又复发属于典型的存量代码老毛病。我用前面说的工作流来改造这段计价逻辑走的步骤包括定位病灶、分析根因、生成最小改动、自检、测试验证、回滚预案。下面把每一步的实际操作和产出都说一下。5.2 步骤一工作台准备动手之前先把手术室搭好。我在工作目录里做了三件事一是把订单模块的核心文件路径整理出来包括计价服务、价格策略、优惠计算这几块的代码位置。二是把约束清单写入代码探测Skill。我给这个项目定的约束包括不允许修改数据库表结构、不允许改动对外接口签名、优惠计算必须保持原有优先级规则、日志输出必须走项目统一的LoggerFacade。这些约束是硬性的AI生成的任何方案都不能违反。三是配置好测试回归命令。把这个项目已有的单元测试命令、静态检查命令整理成了一个checklist后面AI每次改动都要跑这个checklist。这一步看起来琐碎但它是整个微创手术的地基。前期准备的质量直接决定了后期执行的顺畅程度。5.3 步骤二调用探测Skill做术前诊断我让AI用内窥镜对订单计价逻辑做了一个诊断。AI输出的现状说明包括计价流程的三个核心步骤、每一步涉及的数据来源和计算规则、上一次修复留下的代码痕迹注释和防御性判断、以及一个值得注意的隐性约束——优惠计算有先满减后折扣的顺序硬编码在这段逻辑的最深处没有任何配置项控制。这份诊断报告帮了大忙。之前几次修这个bug都是直接在表象上打补丁没有人注意到优惠顺序是被硬编码的。AI用结构化的方式把这段逻辑完整捋了一遍病灶的源头才浮出水面。5.4 步骤三方案设计与人工确认基于诊断报告AI用方案设计Skill给出了三个候选方案方案A是最小改动只修复当前的计价偏差不碰优惠顺序的硬编码方案B在方案A的基础上把优惠顺序硬编码提取到配置项方案C是重构整个计价模块统一所有价格计算入口。我直接否决了方案C——这就是典型的大刀阔斧违背微创原则。方案A和方案B之间我犹豫了一下最后选了方案A。理由是这个模块的历史包袱太重提取配置项虽然更优雅但涉及配置加载机制、缓存策略、升级兼容性等一堆连带问题风险太高。本次的目标是修复计价偏差不是优化架构。这个决策过程必须由人来完成AI给不出这种基于业务风险的判断。这也是我在工作流里坚持保留人工确认节点的原因。注意方案设计Skill产出的方案绝对不能直接当最终结果用。我建议把方案当作参考选项列表来理解而不是唯一答案。因为AI的优化目标函数和你的业务目标函数大概率有偏差偏差只能靠人来纠正。5.5 步骤四补丁生成与自检确认方案A之后补丁生成Skill开始工作。AI生成的diff只有两个文件、十一行改动修改了两个条件分支的判定逻辑加了一个空值保护。改动量很小符合微创的预期。之后我让AI自己也执行了一轮质量审查对照方案检查有没有超出范围的改动、检查新增代码是否遵循了项目的命名规范、检查异常分支是否被覆盖到。第一轮自检还真发现了一个问题——AI在空值保护那里用了项目里不存在的Optional工具类方法如果直接跑起来会编译失败。审查Skill把这个错误拦住了AI修正为项目自带的判空工具才通过了自检。这就是审查Skill的价值它能把AI的审美偏好按回项目的技术规范里。5.6 步骤五回归验证与回滚预案改动从AI手里出来之后我还做了一轮严格的验证主要包括单元测试跑了一遍订单模块的所有现有用例全绿。静态检查按项目的checkstyle规则跑了一遍没有新增违规项。人工Code Review重点看那个空值保护有没有可能影响上游调用方确认无影响。灰度回归把改动部署到预发环境用历史订单数据跑了一次计价对账偏差率降到了0。回滚预案这一步也很重要。我在动手之前就把改动前的commit hash记下来了并且明确告诉AI如果验证阶段任何一环失败直接回退到改动前版本不做二次修改。很多线上事故就是因为出了小问题还想顺便再修一下结果越修越大。微创手术的铁律是出了问题先回到术前状态重新评估再进手术室。5.7 该案例的收益复盘这段计价逻辑从反复出问题到稳定下来整个过程花了不到半天。复盘收益主要有三点一是改动量可控。最终合入主干的diff就是那两文件十一行代码审查的负担极低团队成员不用面对几百上千行的AI生成代码头疼。二是过程可复用。这套Skill和Workflow沉淀下来之后同一项目的其他存量模块改造可以直接套用不需要重新设计流程。三是隐性约束被显性化。探测Skill发现的优惠顺序硬编码问题虽然没有在这次改动中处理但已经记录在案下一次优化就有据可循了。6. 避坑指南实战中总结的六条重要经验6.1 边界控制是第一生命线Skill里最核心的内容不是让AI做什么而是让AI不做什么。我见过太多AI改造项目翻车几乎都是因为AI越过了边界动了不该动的代码。所以每一条Skill都建议写入边界清单禁止改动哪些文件、禁止修改哪些接口、禁止调整哪些逻辑顺序、禁止引入哪些新依赖。如果AI生成的diff越过了边界工作流应该直接拦截而不是让代码流到测试环节。这里有个技巧边界清单可以细到文件名级别。比如订单模块改造时禁止修改payment-utils.jar的调用方式这种粒度虽然看起来啰嗦但对AI的约束效果极其显著。6.2 会话长度和上下文污染需要处理AI在处理长流程时会话上下文会越来越长后面生成代码时可能会遗忘最开始设定的约束。这个问题在编排多环节工作流时尤其明显。我的做法是两个一是把关键约束写进每个Skill的指令开头不依赖上下文传递——就算AI忘了之前说了什么只要它加载Skill就必须先看到边界清单二是每个环节开始前重置上下文只把上一个环节的结构化输出传给下一个环节不摊大饼似地把所有历史对话都带上。这样做的效果是每个环节的AI都在一个干净的上下文里工作不会被前面环节的讨论所干扰。6.3 动态调试比一次性配好更现实第一次编排出来的工作流几乎不可能直接跑通。我之前还幻想能一次配好后来发现这种想法太理想化。实际过程中大概率要在不同的手术中反复调整某个环节的输出格式不对下一个环节解析不了某个Skill的指令覆盖了一个边缘场景AI在那边卡了很久。我的建议是不要把工作流当作一个一次性的配置任务而是一个持续维护的工程资产。每跑完一次改造复盘一下哪个环节耗时最长、哪里发生返工有针对性地调整Skill指令和工作流节点。迭代五六次之后工作流才会进入一个比较稳定的状态。6.4 建立先验证、后采纳的质量门禁AI生成的东西默认按不可信处理。这是我在整个实践中最大的心得。不管你用的模型多强、Skill写得多细AI的输出都必须经过质量门禁验证才能进入下一步。质量门禁可以设计成这样一个是最小改动门禁diff行数不能超过预估范围超过就要求解释原因一个是编译测试门禁改动必须通过项目现有的编译和测试一个是人工门禁核心逻辑改动必须有真人review。三关都过了才算真正完成一次微创手术。6.5 回滚预案要提前备好别等出问题再想每一次AI辅助改动开始之前先记录好当前稳定版本的commit hash确认回滚路径是通的。这个动作两分钟就够但关键时刻能救命。实战中我有一条很粗的规矩如果改动在十分钟内无法验证通过先回滚再排查。不是因为改动一定有问题而是因为小问题很容易升级成大麻烦。保持随时可以回到术前状态的底气后面各种操作才能放得开。6.6 存量代码改造先改流程再改代码追加一条经验用AI改造存量代码很多时候真正的瓶颈不是AI能力而是流程太散。团队里每个人都在用自己的一套方法调AI有人用长prompt有人用临时插件有人干脆复制粘贴到网页里聊。这种情况下就算单个环节跑得再顺整体效率依然上不去。Skill和Workflow编排的价值就是把个人经验转化为团队流程。沉淀出的一套Skill可以给团队里所有人用新成员也能快速上手一套成熟的工作流。这种效率的提升是散装AI永远给不了的。7. 从微创走向康复让改造后的代码持续健康每次改造完成后我强烈建议顺手做两件事一是把这次改动牵涉到的约束和坑位沉淀成新的Skill条目下次再用AI碰这个模块时它一上来就知道这里有什么雷区二是给这次改动补上欠下的测试AI辅助改造省下来的时间值得拿出一点来回馈给项目的安全网。我在实践中发现用Skill编排做过两三轮改造的模块后面的改动会越来越顺——因为每一轮沉淀下来的约束和知识都被复用到了下一轮。这不是一次性的手术而是一个让代码库逐步恢复健康的正循环。那些让人头疼的老模块就在这一轮轮的微创中慢慢变得可以被理解、被维护、被放心修改。最后想说存量代码从来不是技术债它是公司业务演进的活化石。对待活化石我们需要的是稳定的手、精准的刀和一套能反复使用的外科手术流程。Skill加编排值得一试。
