1. 散装AI的病灶存量代码为什么总在“最后一公里”翻车接手一个跑了八年的支付模块时我本以为能用AI快速搞定“多币种汇率换算”这个增量需求。结果那两周我过得极其痛苦——项目组每个人都尝试了AI辅助改造但大家的做法完全不在一个频道上有人用网页版对话AI一段一段地问Java接口逻辑有人攒了十几个一次性脚本挨个分析文件还有人把提示词存在自己的笔记软件里离开工位就什么都没了。这些做法听起来都是“用了AI”实际效果却和没有AI差不多代码改了三轮回归测试挂了两回最后还是靠一个老同事凭记忆手填了一张汇率表才临时上线。后来我复盘这件事发现问题的根子不在AI能力而在组织方式。我给这种状态起了个名字叫“散装AI”——每个人都有AI但每份AI能力都是孤立、临时、不可复用的。散装AI用在零散问答上没毛病可一旦要用它动存量代码问题就全暴露了。而破解它的关键就是用SKILL编排把AI能力变成一把把标准化“手术刀”再通过编排层对老代码做精准的“微创手术”。这篇文章就围绕这套方法展开我把两次真实项目的做法、踩过的坑、沉淀下来的步骤都写出来适合正在用AI改造老系统的开发者或技术负责人参考。1.1 我见过最典型的五种“散装”现场先说症状再开药方。散装AI在存量代码改造中的表现大概有五种基本覆盖了绝大多数团队的状态提示词搬家式协作。每个人电脑里都存着若干份提示词功能互相重叠但写法完全不同。让两个人分别用AI分析同一个模块产出的结论结构都不一样没法合并更没法沉淀成团队资产。一次性脚本堆积。分析某个接口写一个Python脚本分析另一个模块又写一个脚本之间没有复用关系。加了新需求旧脚本全得推倒重来等于每次都在从零开始。上下文断裂。存量项目动辄几十万行代码单次对话的上下文窗口塞不下。于是大家只能对着单个文件问AI跨文件的调用链、依赖关系全靠人脑拼拼错了还没人知道。结果不可复现。同样的输入周一让AI分析的结果和周四让AI分析的结果经常不一样。做技术评审时你甚至无法说清楚这个结论是“哪一轮对话、哪个上下文下”生成的。没有验证护栏。AI给出改造方案后直接照着改改完没人跑回归测试。老系统本来就缺测试改完出了线上问题反而把“AI改造”这件事情背上了黑锅。这五种情况单独看都不致命但它们叠加在一起就会让存量代码改造变成一场灾难。我把散装AI和SKILL编排做个对照维度散装AISKILL编排能力组织散落在个人提示词里打包成标准SKILL单元入库管理上下文管理每次对话自行拼接编排层按需派发局部上下文结果一致性依赖随机输出不稳定固定指令自检清单结果可控可复用性差换人即失效高全员共用同一套技能验证闭环基本缺失内置回归测试和检查点过程可审计无靠记忆有每一步都可追溯所以结论很直接存量代码改造缺的不是更强的AI而是一套把AI能力组织起来的编排机制。1.2 存量代码的体质决定了只能做“微创”为什么强调“存量代码”因为新项目可以直接用AI生成一版框架老项目不行。存量代码有几个共同体质决定了它没办法“推倒重来”耦合度高。支付模块看似独立实则和订单、账务、风控、消息队列全都牵连。牵一发动全身说的就是这类代码。测试覆盖极低。我接手的那套系统核心模块的单元测试覆盖率不到20%很多方法注释写着“历史遗留勿动”。文档基本过期。设计文档停在五年前真实的业务规则藏在代码分支和配置中心里比文档靠谱得多。隐性依赖多。有些逻辑不体现在代码里而在运维脚本、定时任务、数据库触发器里。AI如果只读代码看不到全貌。对这些代码全量重写基本等于自杀。业界有个“重写神话”的说法——总觉得重写一次就能把历史包袱甩干净结果往往是在重写过程中把多年沉淀的业务规则全部弄丢最后上线后急着把老代码里的逻辑一行一行搬回去劳民伤财。所以对存量代码最稳妥的策略就是像做外科手术一样找到最精准的切口只动必须动的地方每一步都用测试确认没伤到周围组织状态不对随时可以停下来退回原样。这种思路就是“微创手术”。而要让AI在这台手术里真正发挥作用就得先把AI的能力拆成手术器械——也就是SKILL——再靠编排层来做主刀。2. SKILL编排的原理从“会聊天的助手”到“可复用的手术器械”很多朋友对SKILL的理解有个误区以为它只是“更长的提示词”。实际完全不是。SKILL的本质是把一个AI能稳定执行的任务固化成**“指令 参考资源 脚本 自检清单”**的组合体。它不是一段提示词而是一个可版本化、可测试、可复用的工作单元。2.1 SKILL单元长什么样先说SKILL这个词的生态背景。Claude的Agent Skills、Cursor的.skill目录、Codex的skill机制、OpenCode的skill插件以及各类Agent框架里说的“技能”都是同一个思想的不同实现把某个场景下的能力封装成独立模块让模型在调用时能稳定地按一套流程工作。核心载体通常是一个名为SKILL.md的文件结构大致如下--- name: change-point-locator description: 在存量代码中定位指定需求的改动点输出调用链和影响面 --- ## 使用场景 当需要在不重写现有逻辑的前提下新增功能或修改行为时调用。 ## 执行步骤 1. 读取目标目录的代码结构识别模块边界。 2. 按需求关键词搜索相关方法、接口和配置项。 3. 对候选改动点做调用链追踪找出所有上游调用方。 4. 标注每个候选改动的风险等级输出影响面清单。 ## 参考资源 - 读取 config/ 目录下的路由配置确认下游服务依赖。 ## 自检清单 - [ ] 是否覆盖了所有上游调用方 - [ ] 是否识别了与需求相关的隐式配置 - [ ] 每个改动点是否都标注了风险等级这个SKILL.md文件本身没有魔法魔法在于它把“如何稳定做好一件事”的流程固化了下来。和普通提示词相比它有四个明显优势稳定性。同一个SKILL无论谁来调用执行路径基本一致结果可控可评审。可测试。自检清单就是模型输出的验收标准相当于给AI设了质检线。可版本管理。SKILL.md放进Git仓库有做GIS的团队甚至可以给SKILL加标签记录每次调整的原因。可组合。一个SKILL只干一件事多个SKILL可以像积木一样搭在一起形成流程。我特别强调“自检清单”这个设计。在没有自检清单的时候让AI分析一段老代码它很可能只会给你一个“这段代码大致实现了什么”的模糊描述。而有了自检清单AI会强迫自己去查调用链、找配置项、标风险等级输出的质量立刻就不一样了。2.2 编排器为什么不是“又一层抽象”有了SKILL单元下一步是编排。编排层做的事情简单说就是按顺序调用多个SKILL在每个环节传递上一步的产出并把中间结果落盘以便审计和回滚。它存在的价值不是多加一层抽象而是让多步骤任务可跟踪、可恢复、可审计。我用一个简单的Python伪代码来说明编排器的工作方式# orchestrator.py —— 最小可用的编排器 from dataclasses import dataclass dataclass class TaskResult: skill_name: str output: dict checkpoint: str # 可回滚标识比如git commit hash class Orchestrator: def __init__(self): self.steps [] self.context {} def add_step(self, skill_name: str, params: dict): self.steps.append((skill_name, params)) def run(self): for idx, (skill_name, params) in enumerate(self.steps): params {**params, context: self.context} result run_skill(skill_name, params) # 实际调用模型 self.context[fstep_{idx}_output] result.output save_checkpoint(result) # 每一步都记录快照 return self.context这段代码里最关键的是save_checkpoint。改造存量代码时最可怕的是AI改到第N步时突然跑偏你发现前面所有步骤都建立在错误的前提上。有了检查点你可以随时恢复到某个正确的中间状态重新调整后续步骤而不用整个流程重跑。实际工程里编排器不一定非要自己写。现在也有一些成熟的workflow编排工具可以做同样的事比如Dify、n8n这类工作流平台甚至直接用GitHub Actions把SKILL步骤串成CI流水线。具体选哪种取决于你的团队是更习惯写代码还是更习惯拖流程。但无论用什么编排的核心职责不变保证步骤顺序、传递上下文、留痕可回滚。为什么说编排不是“又一层抽象”因为对于存量代码改造这种复杂任务拆成多个SKILL按顺序跑和让AI一次性“想想该怎么办”质量差距是数量级的。一次性生成方案时AI很容易忽略细节分步执行时每一步都有明确的输入输出出了问题能定位到具体环节。这就好比让一个实习生直接去啃整套老代码他会手足无措但如果你把任务拆成“先画模块图再标数据流再做影响面分析”每一步都给他明确的操作模板他的完成质量就会立刻上升。3. 一台完整的微创手术实录支付模块接入多币种汇率铺垫了这么多上一台真实的手术。这个案例我脱敏处理过但流程和思路完全可以照搬。项目背景某系统的支付核心模块payment-coreJava技术栈约四十万行存量代码没有完善测试业务逻辑高度耦合。需求是接入多币种汇率换算即订单金额在入账时可以按配置的汇率换算成另一种货币入账同时不能影响原有的单币种流程。在散装AI模式下这种需求通常的做法是让AI直接“改造支付入账模块”然后AI给出一大堆修改建议大家边问边猜最后心惊胆战地提交。而用SKILL编排我把整个过程拆成了三把“手术刀”按顺序上场。3.1 术前测绘用codebase-map生成代码地图第一把刀我给它的命名是codebase-map。作用很简单让AI在动手前先把项目“摸一遍”生成一份结构化的代码地图——哪些目录是核心模块、各模块间的依赖关系、哪些文件是历史遗留死代码。我写的SKILL.md核心执行步骤有这么几条扫描目标目录下所有源文件按功能聚合出模块清单。识别每个模块对外提供的接口和内部主要类。标记出疑似无引用的死代码并给出依据。输出Markdown格式的地图包含模块名、关键文件、依赖方向。实际执行时我先让AI只扫描payment-core/src/main/java/com/example/payment下的文件然后让它在dep.txt中记录每个模块的import依赖。这份代码地图最终会存档进项目仓库以后任何人接手都能用。这一步看起来不起眼但它是整台手术的地基。存量代码改造最怕的是在错误的模块里找改动点。有了地图后续所有SKILL都跑得更准。而且代码地图本身就是可以持续更新的知识资产我后来甚至把它接入了半个月一次的自动重跑防止新代码把地图弄过期。3.2 切口定位change-point锁定真正要动的三处代码第二把刀是change-point-locator——定位改动点。这个SKILL要做的不只是搜索关键词而是输出一份“影响面报告”。我给它规定了输出格式# 改动点影响面报告 需求支持订单金额的多币种汇率换算 候选改动点 1. OrderSettlementService#convertAmount() - 上游调用方OrderController, RetryTask, ReportGenerator - 当前行为无汇率换算直接返回原金额 - 风险等级高影响核心结算链路 2. CurrencyConfig#getCurrencyCode() - 上游调用方OrderSettlementService - 当前行为读取固定单币种配置 - 风险等级中 3. DEFAULT_AMOUNT_SCALE 常量定义 - 影响范围金额精度处理 - 风险等级低 建议 - 新增 ExchangeRateHandler 作为适配层避免修改结算主流程。 - 原 convertAmount 保留新增重载方法以便灰度切换。这份报告的含金量在于它没有让AI直接“改代码”而是先逼它把改动点和影响面都摊开。我在自检清单里加了一条强制要求“如果候选改动点少于三处需要重新扩大搜索范围。”为什么加这条因为存量系统里一个看似简单的汇率换算极可能牵涉到订单导出、对账、财务入账等多个模块AI如果只找到一个改动点多半是漏了周边逻辑。实际跑完这份报告我发现AI不仅锁定了三处核心改动点还顺带找出了一条隐藏的定时任务路径每天凌晨2点系统会用一个旧汇率表跑前一天的对账汇总。这个逻辑在文档里完全没提只在定时任务的配置文件中存在。如果不是因为SKILL里写了“检查与金额计算相关的定时任务”这个雷大概率会在灰度后被对账差异炸出来。3.3 术后缝合test-harness给回归测试上保险第三把刀是最容易被忽视的test-harness。它的职责是让AI为每一次改动生成回归测试验证方案。老系统没有测试我们至少在改造涉及的路径上补齐一层防护网。我的做法是在每次修改代码后让AI做三件事找到本次改动影响的所有方法。为这些方法生成最小可行的测试用例包括正常路径和边界值。如果老代码没有测试框架先生成轻量的测试骨架从最核心的断言开始。以汇率换算为例AI生成的测试用例大致覆盖了不同币种换算、汇率为0时抛异常、保留小数位精度、旧单币种流程不受影响。这些测试不一定全部纳入CI但至少在开发阶段能跑一遍确认改动没有破坏原有行为。我处理这类场景有个心得给存量代码补测试不要追求全覆盖而是追求“让本次改动可置信”。每次手术只补与手术区域相关的测试合到主干时能证明“我动的地方没弄坏东西”就够了。等手术多了测试的覆盖面自然会一点一点大起来。4. 手术台上最容易被忽略的三个细节三把刀跑下来几次实操之后我总结出三个在存量代码微创手术中特别容易被忽略的细节。这三个地方如果不处理手术大概率会出问题。4.1 隐式契约才是最大的雷老代码里最坑人的不是逻辑复杂而是“代码之外的东西”。我从这个项目里学到的教训AI读代码时只能看到代码本身但存量系统真正的业务规则往往藏在配置文件、数据库存储过程、消息队列Topic约定甚至运维脚本里。例如我们这次改汇率原以为只需要改Java代码。结果发现订单导出模块里有一段硬编码的货币字段直接用CNY写死了数据库里还有一个currency_ratio表每天由外部脚本更新但没有任何代码调用它。这些都属于“隐式契约”——系统运行依赖它们但代码仓库里看不到全貌。我的解决办法是在codebase-map和change-point-locator这两个SKILL里都加上“检查非代码依赖”的步骤强制AI扫描配置目录、SQL脚本、定时任务清单。把这个写进SKILL执行步骤之后漏检率明显下降。这个经验反过来也提醒我SKILL不能只覆盖“写代码”的环节更要覆盖“发现代码之外的约束”的环节。4.2 上下文窗口不够用怎么办存量代码动辄几十万行任何单次对话都塞不下完整代码库。我在早期踩过一个坑为了省事把一个大模块的全部文件都丢给AI结果AI读到一半就糊涂了输出的方案前后矛盾。后来我调整策略采用“分层摘要 局部上下文”的方式第一层先让AI只读目录结构和关键类注释生成模块地图。第二层根据地图定位到相关文件和调用链再让它精读。第三层精读时只提供与当前改动相关的代码片段和上下文避免整文件夹投喂。这其实就是编排的价值把“大问题”拆成多轮“小问题”让每一轮的上下文都足够聚焦。codebase-map的产出恰好是第二层和第三层的输入。所以我始终建议SKILL编排的流程设计要围绕“如何给下一步提供更精准的小上下文”来展开而不是一股脑把整个仓库都喂给模型。4.3 编排器必须自带保险丝散装AI模式下改造过程最多也就“改错了再改回来”还勉强能接受。但在编排流程下一旦某个SKILL步骤基于错误的前提输出了荒谬的结果后续步骤会一路错下去直到最后一步才发现返工成本更高。所以编排器在每一个SKILL执行后都要做一件事对输出结果做快速合理性校验把明显有问题的中间结果拦截下来。我叫它“保险丝”。我用的几个简单校验规则change-point-locator输出中如果改动点没有覆盖到核心结算路径直接判定可疑。codebase-map的模块数量和历史基线差异过大比如从10个模块突然变成2个需要重新执行。任何SKILL输出中如果出现“不确定”“可能”“建议人工确认”等含糊措辞一律视为未完成打回重跑。这个规则听起来很粗暴但非常有效。它逼着AI每一步都给确定性的答案而不是骑墙观望。好几次“保险丝”都在AI给出过度乐观的结论时起了作用避免了我们带着错误方案进入下一步。5. 从一台手术到一套手术室SKILL编排的进阶玩法第一次跑通这套流程之后我开始琢磨怎么把“一台手术”复制成“一间手术室”。毕竟存量代码又不只支付模块一处整个系统到处都是被历史包袱压着的地方。SKILL编排最大的回报不在于一次性的效率提升而在于复用——能力沉淀成SKILL流程编排成模板下一次改造同类模块时直接套用即可。5.1 把SKILL做成原子化的“手术刀”什么样的SKILL才能真正复用我的标准是“原子化”只做一件事输入输出尽量窄。codebase-map只管测绘不要让它顺手输出改造建议change-point-locator只管定位改动点不要让它顺手写实现代码test-harness只管生成验证方案不要让它顺手改业务逻辑。每个SKILL的参数和输出都明确写进SKILL.md的元信息。这样组合时非常灵活哪一步需要重新执行单独重跑那一个SKILL就好其他步骤的结果不用作废。比如改配置后我只需重跑change-point-locator而不用把代码地图也重画一遍。5.2 让知识沉淀进SKILL库手术做完之后有一件事特别重要把这次学到的业务规则、隐式依赖、踩坑点回写到SKILL库里。比如这次我们发现的“每日凌晨汇率更新脚本”就固化成了一个独立知识点并在后续的编码地图SKILL中保留。不这样做下次做类似手术还是可能踩同一个坑。SKILL的价值不只是“让AI跑得更快”更是“让团队的知识积累不随个人记忆消失”。我把这些更新统一提交到仓库的skills目录每次都附带说明这次为什么改、改了影响哪些业务流程。5.3 团队级维护SKILL也要过评审最后一条经验来自团队协作层面。SKILL是团队资产所以它也应该像代码一样过评审、走版本管理。我们规定新增或修改SKILL必须附一份“用例说明”写清楚什么场景下用、输入什么、期望输出什么。评审时重点关注两件事一是SKILL描述是否准确不要让AI在实际调用时产生歧义二是自检清单是否够硬能不能保证输出质量下限。经历过一段时间的运转之后这套SKILL库从最初的三个单元扩展到了十几个几乎覆盖了项目里常见的改造场景——加字段、换接口、改定时任务、拆模块。新同事接手老代码时的上手速度也明显比之前快。这就是从“一台手术”到“一间手术室”的转变。手术做多了我自己最大的体会是AI改造存量代码最重要的不是让AI一步到位给出完美方案而是把它嵌进一个可控制、可复查、可回退的流程里让每一次修改都像微创手术一样有边界、有护栏、有记录。散装AI时代已经够乱了是时候给AI装上一套正经的手术器械了。