我接手过一个跑了九年的老系统代码库像一棵根系杂乱的老树线上跑得还算稳但只要有人动它所有人心里都打鼓。我们曾经尝试用 AI 辅助改造结果却更糟团队里每个人都用各自的账号问各自的 AI把生成的结果直接粘进代码库没有任何统一标准也没有验证流程。那段时间代码风格五花八门注释互相矛盾连谁改过哪里都需要开会对齐。我管这种状态叫“散装 AI”——工具是齐的思路是散的最后既没有降低改造风险反而让技术债更厚了一层。后来我用 SKILL 机制配合编排思路换了一种打法不再让 AI 替人轻率地“即兴发挥”而是把 AI 能力封装成一个个可复用的技能单元再按照一套类似手术流程的编排链路去处理存量代码。从诊断到出方案从小切口改到验证回滚每一步都清晰可控。这套打法帮我成功拿下了一个又一个“没人敢碰”的模块也让我彻底告别了之前的混乱状态。适合读这篇文章的人正在维护老系统却被 AI 改造项目反复折磨的工程师、想给团队引入 AI 辅助编码规范却没有头绪的技术负责人以及任何吃过“散装 AI”亏、想用更工程化方式落地 AI 能力的人。下面分享的是我在实际项目中验证过的完整思路与操作细节。1. 当我决定不再“散装”用 AI1.1 “散装 AI”是怎么把代码库越改越乱的先还原一个典型场景。团队里三名工程师分别用 AI 助手处理同一个问题某个订单金额计算函数偶尔多算一分钱。工程师 A 让 AI “分析这段代码”AI 给了三处可疑点工程师 B 直接要求“重写这个函数”AI 给了新版本工程师 C 让 AI “补全注释”AI 又把注释风格改了一轮。三个人都觉得自己用得很好但代码库同时出现了三种风格的代码函数被重写了一半线上问题依然在新引入了一半。最头疼的是没有人能说清楚哪一段逻辑是经过验证的、哪一段是模型生成的推断。“散装 AI”的本质问题不在 AI 本身而在于使用方式。它有三个典型的病灶第一没有统一上下文。每次给模型喂的代码、背景、约束条件全凭个人当时的表达能力和运气第二没有输出协议。AI 回答是自由格式的自然语言没有强制它输出“风险等级”“改动范围”“验证步骤”无法直接进入工程流程第三没有校验闭环。AI 生成完就结束了没有人要求它先跑一遍静态检查、对比编译结果、确认不破坏既有行为。我并不是要否定 AI 在编程中的作用。相反在过去两年里我发现问题不在“AI 不够强”而在于我们把它用成了散装工具。AI 应该像手术室里经过消毒、标准化的手术器械而不是一把随手捡起的剪刀。对待存量代码尤其需要注意这一点。存量代码本身就有大量隐含的业务规则和历史包袱再用散装的方式使用 AI等于在已经脆弱的系统上叠加了一层随机性。1.2 存量代码真正怕的是什么存量代码有几个共性特征文档稀缺、逻辑缠绕、测试覆盖不足、关键技术决策的历史原因已经丢失。以我之前负责的订单系统为例一个计算折扣的方法里嵌套了七层 if-else每层都有对应的业务背景但这些背景分布在六年前的工单、离职同事的口头描述和一段没有注释的提交记录里。这种代码不是“写得差”而是“承载了大量不可见的知识”。面对这样的代码团队通常会有两种极端反应。一种是不敢动像对待博物馆里的展品一样供着任何变更都在上面打补丁最终补丁摞补丁另一种是推倒重来用新框架把老模块重写一遍。事实证明“推倒重来”在存量代码上失败率极高。重写过程中会丢掉隐蔽的业务逻辑用户数据兼容性也会出问题最后往往是新系统上线即翻车旧系统还得继续维护。我参与过的几个遗留系统重写项目不夸张地说大多数都以惨败收场。存量代码真正怕的不是变革而是大范围、高风险、不可回退的改变。病人需要的不是重新长一副身体而是把病灶切除、让原有组织正常工作。这就是“微创手术”思路的由来小切口、低侵入、每一步都保证系统仍然可用并且可以在任何异常时刻退回到手术前的状态。AI 在这里的角色是辅助我们做精准的诊断和切割而不是负责把整台手术做完。1.3 一次典型的“手术”应该长什么样我在多次实践中沉淀出一套可复用的流程它模仿了真实手术的过程术前影像学检查、手术方案设计、小切口执行、缝合修复、术后观察。对应到代码改造上是下面五个阶段诊断阶段通过监控指标、异常日志、需求变更频率等数据找出系统里“最痛”的模块并用静态分析和调用链还原模块的真实结构。方案阶段基于诊断结果生成若干个改动方案明确每个方案涉及的函数、影响范围、风险点和回滚方式。切口阶段选择影响范围最小的改动路径执行局部重构或修复严格限制改动边界。缝合阶段补齐测试用例让改动后的代码通过原有测试和新增的行为验证。观察阶段上线后监控关键指标用流量对比、日志分析确认没有引入回归必要时快速回滚。AI 是这套流程的执行工具但它不能承载决策权。尤其对于存量代码修改哪一行、影响哪些下游依赖、可接受的失败窗口有多大这些问题必须由人来判断。AI 的作用是压缩信息获取的时间、提高方案生成的效率、减少遗漏而不是代替工程师做判断。想做到这一点就需要把 AI 的使用方式工程设计化这就是 SKILL 机制和编排思路存在的价值。2. SKILL 到底是什么它和 Prompt、Agent 有什么不同2.1 从一次复制粘贴到一组可复用资产的转变很多人对 SKILL 的第一反应是“这不就是个高级 Prompt 吗”。我一开始也这么想真正实践之后才知道区别非常大。Prompt 是一次性的口述你每次都要重新描述问题、背景和输出要求就像每次手术前都要重新发明一套工具质量完全取决于操作者当天的表达状态。SKILL 是一个封装好的“手术器械盒”里面固定装配了上下文采集器、规则集、输出协议和自检机制任何人在任何时间调用它得到的是质量稳定、格式统一、可以被后续流程直接消费的结果。举一个更直白的例子。以前我想让 AI 分析某个模块的风险我需要复制代码、粘贴到聊天框、写上“帮我看看哪里可能出问题”。这个过程听起来不难但如果是二十个模块、五个团队成员分别做结果就是灾难。有人只贴了函数签名有人贴了完整文件但没说业务背景有人忘了让 AI 标出置信度于是所有人的输出都不可比、不可汇总。改用 SKILL 之后我只要在代码库根目录放好技能定义文件团队成员输入同样一条命令AI 就会自动读取模块代码、提取调用关系、加载项目规则、输出一份固定结构的风险评估报告。结果是统一的报告可以被脚本自动解析也可以进入下一步编排流程。本质上SKILL 把“AI 使用经验”从个人口袋里拿出来变成了团队的工程资产。这个转变是告别“散装 AI”的关键一步。2.2 SKILL 的四个组成部分上下文采集、规则集、输出协议、自检机制在实践里我通常把 SKILL 拆成四个组件来设计每一块都有明确职责。上下文采集器负责决定“让模型看什么”。存量代码的问题往往不是信息太少而是信息太杂。如果把整个微服务代码塞进上下文模型很快就迷失在无关代码里回答质量直线下降token 成本也高得离谱。所以采集器要做的是把问题域内有用的信息自动抽取出来相关函数源码、调用方与被调方的签名、相关配置文件、最近的异常日志片段、涉及的历史变更记录。它更像给模型准备一份“病历资料”而不是把整个房间的病历都丢过去。规则集负责装载“不可违背的边界”。它包含项目级规范、团队约定、领域约束。例如禁止使用 eval数据库访问必须走统一DAO金额计算必须使用定点数任何对外 API 的返回值格式不允许改变。规则集的另一个功能是补充业务上下文比如“折扣计算的历史规则见 docs/legacy-rules.md若与代码注释冲突以文档为准”。这套规则是沉淀出来的每次线上事故和踩坑之后我都会往里面补一条。输出协议负责约定“返回什么、长什么样”。在自由对话里让 AI 输出自然语言后续处理往往不可依赖。而有了输出协议AI 必须生成结构化的结果。比如要求输出一个 JSON包含 risk_level、affected_files、suggested_actions、confidence、missing_info 这五个字段并且每个字段都有取值范围或格式说明。这样一来结果就可以被脚本解析、被下一步流程使用、被存档追踪。自检机制是最后一道闸门也是很多人忽略的部分。AI 生成的结论不能直接信但它自己可以先做一轮基础检查。比如生成了一个改代码的建议自检机制会让它调用 grep 确认要修改的函数真的存在、调用编译器检查生成的代码能否编译、调用静态分析工具扫描明显的问题。自检通过之后结果才允许被输出。这一步能拦截大量“看起来很专业但根本执行不了”的答案也显著减少了幻觉对下游流程的污染。2.3 SKILL 与 Agent、编排的关系搞清楚 SKILL 与 Agent、编排的关系能让你少走很多弯路。简单地说Skill 是单一能力单元Agent 是具备决策循环的执行者编排是把多个 Skill 按流程串联起来的骨架。我在实际项目中见过两类极端误区。一类是把所有逻辑塞进一个 Agent告诉它“你去把这个模块改造好”指望它自主搞定一切。结果通常很惨因为大范围任务里模型在长链路执行中会逐渐丢失最初的约束中途产生的修改很难被发现和纠正最后得到一堆不可控的变更。另一类误区是只用单个 Skill把所有分析工作一股脑塞进去期望一个 Skill 解决从诊断到重构再到验证的所有问题。这也做不到因为每个环节需要的信息、规则和输出格式完全不同强行糅合只会让每个环节都做得不精。正确的做法是拆成多个 Skill用编排把它们组织成可控的流水线。以存量代码改造为例我通常会拆出“体检 Skill”“方案 Skill”“变更 Skill”“验证 Skill”四个技能编排起来依次执行。每个 Skill 的输出都是下一步的输入每两个 Skill 之间可以有一个人工确认节点。这样做的好处是单步内的复杂度可控单步输出可以被检查任何一步出了偏差都能及时纠正不会等到最后才发现方向全错了。打个生活化的比方Skill 是一把把专用的手术钳Agent 是一个能自己判断“下一刀该往哪切”的外科医生而编排是手术室里的操作流程——切完第一刀必须停下来看出血量、确认没问题再进行下一步。没有流程编排医生再厉害也可能在长手术中出乱子没有专用工具流程再严谨也做不到精细操作。三者结合才是对存量代码做“微创手术”的正确姿态。3. 术前准备给存量代码做一次“影像学检查”3.1 从指标和工单里找痛点不靠感觉选模块做改造最忌讳一开始就选错对象。我见过有团队兴致勃勃去重构某个看起来“代码很烂”的模块做了三个月发现这个模块根本没人用、也不是线上瓶颈真正的问题在另一个调用频率高一百倍的路径上。所以手术前必须有一个客观的“病灶定位”环节而定位的依据应该是数据不是感觉。我的做法是把几类指标放在一起看一是异常指标从监控系统拉出报错次数最高的 Top 模块二是变更频率从代码仓库的提交记录里统计哪些模块在过去一年被修改的次数最多——改得越频繁说明越不稳定、越痛三是业务影响找到用户反馈和工单里被吐槽最多的功能反推到对应的代码模块。最终形成一个“热点模块清单”按“痛感×影响面”排序选出第一个动刀的候选对象。这里有一个很实在的判断标准选改造对象时要避开“复杂度高但没痛点”的模块优先选“痛点明显但改动边界清晰”的模块。第一次做微创手术成功体验比挑战极限更重要。你先在一个中等难度的模块上跑通全流程建立起团队的信心和流程规范再去啃真正的硬骨头会稳妥得多。3.2 梳理模块边界、依赖与调用链选定目标模块之后下一步是搞清楚它的边界。换句话问它从哪里来、到哪里去、和谁发生数据交换、内部有哪些不可破坏的外部约定。这一步的产出是一张可以被 AI 消费的“手术地图”。绘制这张地图有三条情报来源。静态分析能直接生成函数调用关系图和文件依赖列表让模型快速理解代码结构动态追踪可以在测试环境或预发环境对关键路径打点记录真实运行时调用顺序、耗时和参数特征捕捉到静态分析看不见的反射调用和动态分发逻辑数据血缘分析能帮我们理解核心数据的流转路径——比如订单金额字段从创建、计算到持久化经历了哪些函数哪一个节点改变了它的值。这三类信息叠加起来模块的“解剖结构”就非常清晰了。在整理边界时有一个关键任务把“手术中不允许改变的地方”标识出来。比如对外 API 的参数名和返回值结构、数据库表结构、与其他服务之间的 MQ 消息格式。这些就是解剖学里的“大血管”碰到了会引发大出血所以必须在手术地图上醒目标注。我的做法是把这些约束直接写进规则集让所有下游的 Skill 从一开始就被约束住。3.3 建立基线测试给“手术”留一张安全网做完边界梳理还得解决一个非常现实的问题存量代码的测试覆盖通常很差你没有足够的安全网来验证“改动没破坏原有行为”。补全单元测试不现实但我们可以用一种更聪明的办法叫行为快照。行为快照的思路是在改动之前先录制一组“输入-输出”对把它们固化为测试用例。具体操作方法有很多种我常用的是下面两种。第一种是历史日志回放从线上日志或消息队列里捞出一批真实请求把这些请求的数据结构保存下来作为后续回归测试的输入。第二种是接口录制在网关层或者测试环境对目标接口记录请求和响应自动生成一批对比用例。举个例子我在改造旧订单价格计算模块时从生产环境导出了过去七天一万多个真实订单的输入参数和计算结果把它们整理成了基线数据集。改造完成后拿同样的输入跑新代码逐单对比结果差异归零才算通过。这一步极其有价值它相当于手术前给病人的器官做了一份完整的功能造影手术过程中随时可以对照确保没有偏离原有功能。有了这层保护模型生成的改动即使再大胆我们也有底气和它交手。4. 设计第一个 SKILL让 AI 对代码库“说实话”的体检技能4.1 输入设计给模型喂什么不喂什么SKILL 的质量上限很大程度上取决于输入设计的质量。这一点怎么强调都不过分尤其当面对的是动辄上千行、内部状态繁多的存量模块时把什么内容送进模型上下文直接影响输出的可信度。我的输入设计原则是“分层抽取按需投喂”。不是整块代码文件全丢进上下文而是把代码库当成一个可以被查询的对象让采集器逐层拉取。第一层是模块骨架包括文件清单、对外函数签名、核心数据结构定义让模型先建立全局认识第二层是目标函数细节只把本次分析要针对的函数实现源码投进去连同它直接调用的子函数第三层是关联上下文包括调用方代码、配置项、异常日志中与该模块相关的片段。如果第一轮分析之后模型发现还缺信息采集器再按需补拉而不是一开始就灌满。有人会问为什么不把所有信息一次性给足原因有两个。一是信息过载会导致注意力稀释模型看到一千行无关代码之后对关键问题的分析能力会明显下降甚至开始“凑答案”二是成本问题token 开销和响应延迟都会随着上下文长度非线性增长在编排流水线里每一步都在烧钱能省就要省。把输入设计当成一项系统工程来做收益远超想象。4.2 规则集与输出协议强制报告结构化输入设计好之后接下来要定义规则集和输出协议。先看规则集的写法。以 Markdown 格式的 SKILL 描述文件为例我会这样组织# skill: code-diagnosis ## 背景 该技能用于对存量代码模块进行风险诊断输出结构化体检报告。 ## 上下文采集方式 - 读取需要诊断的模块文件清单 - 提取目标函数源码及各函数间调用关系 - 读取项目根目录下的 AGENTS.md 或 RULES.md加载项目级约束 - 若存在 legacy-rules 文档必须优先于代码注释作为业务规则来源 ## 规则集 - 金额、折扣、税率等数值字段必须使用 Decimal 或定点数禁止浮点运算 - 所有数据库访问必须经过统一 DAO 层禁止在业务函数中直接执行 SQL - 对外 API 的返回字段名称与类型不允许变更包括 JSON 字段顺序 - 若发现代码行为与文档矛盾先输出矛盾项再做判断 ## 输出协议 必须输出 JSON 对象格式如下不得输出其他内容 { module_name: 模块名, overall_health_score: 0-100, pain_points: [痛点描述], risk_level: low | medium | high | critical, suggested_actions: [建议动作], affected_files: [受影响文件], confidence: 0-100, missing_info: [依赖什么信息未确认] }这套格式让 AI 的输出被彻底“协议化”。实际跑下来你会发现只要规则集写清了边界、输出协议定义了结构AI 的回答就从“参考意见”变成了“可直接解析的数据”。我可以把这些 JSON 直接扔给下一个 Pipeline 消费也可以自动汇总成团队周报。这种由混乱到规范的变化是工程化落地 AI 最重要的感受之一。4.3 自检机制让技能先过一道“体检”输出协议只解决了格式问题还不能解决正确性问题。模型生成的结论是否站得住脚针对这个问题我在技能里加入了一个容易被忽视的环节——自检。自检不是让 AI 再认真看一遍而是让它调用真实的工程工具来验证自己的判断相当于写完论文之后自己先去查一遍数据是否真实可考。具体做法是在输出之前技能通过命令行工具完成几个检查动作。比如用grep确认自己引用的函数名在代码库中真实存在用python -c import ast; ast.parse(...)检查自己生成的代码是否语法合法用jq校验输出 JSON 的结构是否符合协议条件允许的话甚至可以调用eslint或mypy做静态检查。我把这个自检过程写成脚本挂到 Skill 的末尾用一行命令就能触发。# 在 Skill 的验证阶段对生成的 JSON 报告做基础校验 cat report.json | jq -e .module_name and .risk_level and (.confidence | type number) grep -q compute_discount src/order_service.py || echo 警告: 引用的函数不存在自检机制拦截了多少错误就我实际使用体验来说它能挡住相当一部分“常识性幻觉”。比如模型在报告里断言某个函数返回值是 String真实代码里其实是 Dict自检用 AST 一解析就能发现矛盾。这类错误如果在早期不拦截流到下一个 Skill 里就会像滚雪球一样放大最后出来的方案根本执行不了。让每个 Skill 对自己负责是编排能够稳定运行的基础。5. 端到端实操一个订单利率模块的“微创手术”全流程5.1 场景设定那个没人敢动的价格计算模块用我真实处理过的一个模块来完整走一遍流程。这个模块叫PriceCalculator是订单系统里负责最终支付金额计算的类核心方法compute_total有两百多行里面堆了会员折扣、满减优惠、品类加价、旧系统迁移来的“幽灵优惠”等七层逻辑。可怕的是这个类没有任何单元测试只有几处散落的日志打印。线上偶发的“价格差一分钱”工单有六成都指向这里但历任维护者都不敢动。我先做术前检查。从监控系统看过去 30 天compute_total被调用约一千万次异常率 0.3%P95 延迟比同模块其他方法高出一倍从 Git 历史看这个文件在过去一年被改过 23 次其中 18 次是修回归引入的新缺陷。结论清晰这块骨头必须啃但它只能小步走。基线测试方面我从前端流量录制了七天约五万条真实订单的输入与计算结果按支付方式、用户类型、商品品类做了分层抽样固定成一万两千条基线用例。这期间还发生了个小插曲录制数据时发现有大约三百条订单的金额在历史版本中其实也被计算错过但这些数据被内部账单修正过不能直接用作基线。这个发现差点把整个手术计划打回到诊断阶段好在当时流量录制和数据校验脚本分离得足够透重捞了一遍数据就解决了。5.2 编排链路设计从诊断到验证的四步流水线针对这个模块我设计了四个 Skill 和一条编排链路。四个 Skill 分别是体检 Skill读取模块源码与调用关系输出结构化的风险报告包括健康度评分、痛点定位。方案 Skill接收体检报告结合规则集生成三套改动方案每套方案包含改动文件、改动函数、影响范围、风险等级。变更 Skill在选定的方案下生成实际代码补丁并要求逐行解释改动原因。验证 Skill读取补丁和基线数据集执行行为对照测试输出验证结果。编排链路如下体检 Skill 先跑输出报告送到人工确认觉得没问题再往下走方案 Skill 生成三套方案后由我本人和一位熟悉业务的同事共同选一套选定方案后变更 Skill 生成代码补丁补丁必须经过 code review 才会被应用到代码库最后验证 Skill 用基线数据跑回归通过后进入灰度发布。每一步之间都有一个人工确认节点绝不自动连着跑到底。有同事问过为什么不让四个 Skill 一步到位全自动原因很简单存量代码改造不是流水线生产螺丝钉每一步都可能出现需要人类经验介入的判断。比如方案 Skill 生成“重写 compute_total”的方案看起来风险等级标的是 low但只要稍微了解订单系统的人都知道重写一个承载了大量历史业务规则的类是极度危险的操作。这种判断力现在的模型还不具备必须由人来把关。人工介入点设在流程的关键关节上既保持了效率又守住了安全底线。5.3 关键配置与执行记录解读下面是我实际操作中的一段编排配置为了方便演示做了简化。它用 YAML 描述了流水线的连接方式每个节点都是一个独立 Skill 调用。# 简化版流水线定义 steps: - skill: code-diagnosis id: diagnosis input: module: PriceCalculator - skill: human-confirm id: review_diagnosis input: { source: diagnosis } - skill: refactor-planner id: plan input: { source: review_diagnosis } - skill: human-confirm id: choose_plan input: { source: plan, required: 选择其中一套方案 } - skill: patch-generator id: patch input: source: choose_plan patch_mode: minimal - skill: code-review-gate id: review input: { source: patch } - skill: behavior-validator id: validate input: source: review baseline_path: tests/baselines/price_calculator.jsonl on_fail: action: rollback执行记录节选一下。体检 Skill 首先输出了一份很有意思的报告健康度评分 43风险等级 critical痛点定位清晰指出三处“幽灵优惠”逻辑只有一处有代码注释另外两处完全无据可查。方案 Skill 随后给出三套方案方案 A 是最小补丁只修复“满减与会员折扣叠加顺序错误”方案 B 是中等范围改造将七层 if-else 抽为策略类但保留每个策略的原始行为方案 C 是整体重写。三套方案的风险等级分别是 low、medium、high。业务同事在选择时直接排除了 C因为风险等级 high收益也不明确最终我们选了 B因为痛点清单里的三处缺陷原本就分散在多个条件分支里与其修一处漏一处不如把分支变成独立策略类每一个策略用基线用例验证整体行为有保障。变更 Skill 生成的补丁改动范围比较克制新增了一个strategy文件夹把原本嵌套在compute_total里的三类折扣逻辑迁移到独立的策略类中同时保留了compute_total作为统一入口对外部调用完全透明。这在设计上做到了“内部重构、外部无感”正好符合微创手术的思路。代码 review 阶段同事提了几个关键意见新增策略类的命名没按团队规范、折扣优先级的 Constants 定义重复了两处、有两段迁移代码缺少注释说明来源逻辑在哪次工单中修正过。这些问题在评审中被拦截下来全部修改后才进入验证环节。5.4 结果回填、回滚与经验沉淀验证 Skill 用一万两千条基线用例跑完行为对照结果令人满意一万一千九百八十七条完全一致还有十三条的金额差异都在一分钱以内且经过人工核对是原代码本身的已知舍入误差问题不属于本次改动引入的回归。随后我们把改动灰度发布先打开 5% 流量观察一天再逐步放大到 100%监控面板上 P95 延迟从改造前的 380ms 降到 120ms异常率从 0.3% 降到 0.02%。回滚预案其实我们并没有真正触发但预案本身写得非常清楚改动全部通过增加策略类和调整compute_total内部调用顺序实现没有修改数据库结构和对外接口如果线上出现异常只需要回滚一次代码发布即可恢复。更重要的是这次改造的经验被固化了下来我们把“订单价格相关规则禁止直接内联在业务函数里”“任何金额改动必须跑基线数据集”写进了规则集以后所有的 Skill 在处理这个模块时都会自动遵循这些约束。手术完成后团队对这些“微创手术”的信心有了质的提升。你从没有经历过的状态很难描述当你知道手里有一套可以随时回退、每步都有明确产出的流程时面对存量代码的恐惧感会大幅降低。后面我们又用同样的编排结构处理了三个模块每次只需要替换体检和变更 Skill 里的规则集流水线本身几乎不用动。6. 常见问题与排查技巧实录6.1 上下文太长模型开始“胡言乱语”这是我在使用中遇到频率最高的问题。模型对“关键信息被淹没”很敏感。一个常见场景是流水线的第二个 Skill 需要从上一步拿到分析报告又要把整个目标模块的源码重新送进去结果上下文一下子飙到几万 token模型开始把关系不大的代码也列进影响范围甚至把函数名都编错。排查方法是把每一步 Skill 的输入内容打出来看有没有“重复字段”和“无关内容”。问题通常出现在采集器定义里——我有时候图省事让采集器把整个文件夹都读进去这就是典型的懒做输入设计。解决办法是明确 Skill 边界上一个 Skill 的输出已经完成了分析下一个 Skill 只需要这段分析的结论摘要和少量必要源码不需要重新分析整个模块。可以在配置里规定摘要的最大长度把“输出摘要”写进输出协议,这样每个 Skill 的输入都保持在可控范围内。6.2 Skill 生成“看起来很对但逻辑错误”的代码“看起来很对但经不起推敲”几乎是 AI 编程最容易踩的坑。尤其是在业务规则复杂的存量代码里模型可能生成一段读写路径完全正常的代码但业务逻辑是错的。我遇到过最典型的例子它把折扣叠加的顺序从“先满减后折扣”悄悄改写成了“先折扣后满减”单看代码每一行都没错甚至注释都写得很漂亮但结果对不上。这类问题的根源在于模型看到了代码结构但没有理解业务变量背后暗含的业务流程。对策有几个。第一把领域规则写进规则集甚至明确写出“折扣叠加顺序不得改变若发现原代码有两种语义冲突先报冲突再给方案”第二强制生成的补丁必须附上逐行的“修改原因说明”和“原逻辑与新逻辑对比表”这样 code review 才有据可查第三也是最可靠的让验证 Skill 用基线数据集做行为对照这是最后能拦住业务逻辑错误的高墙。没有基线数据的情况下至少要给变更 Skill 加一条指令“如果改动可能影响金额计算结果必须输出‘已修改计算逻辑’的显式警告。”6.3 编译通过、单测通过上线之后还是出问题这大概是所有改造项目都怕的噩梦。编译和单测都过了说明代码在“设计的输入”下没有问题但真实的线上输入往往比测试数据更刁钻。我们遇到过的情况是新代码对老用户历史数据中的某个“脏字段”没有做兼容处理而这个脏字段在测试数据里根本不存在。单测数据是我们自己造的当然覆盖不到这种边界。解法思路是用真实数据说话。在存量代码改造里人工构造的测试数据永远不够一定要想办法引入线上流量的回放或影子模式。具体做法可以是在网关层复制一份线上请求用同样的参数打给新旧两套代码比对返回差异也可以通过消息队列把真实请求异步降级到预发环境的新版本上运行只做对比、不影响真实业务。我在订单模块改造时用的就是这个思路效果远好于任何手工构造的测试。6.4 团队协作SKILL 库的版本管理与命名规范最后一个问题来自团队协作的规范层面。AI 辅助编码的工程化不只是技术问题更是组织问题。Skill 如果管理不好很快就会变成另一种“散装”只是从“散装的 Prompt”变成了“散装的 Skill”。我给团队定的规范有几条硬性要求。第一SKILL 统一放在代码仓库的skills/目录下和普通代码一样走 PR 评审流程不允许个人在本地私藏 Skill第二命名遵循统一的领域-动作-对象格式例如order-diagnosis-risk、code-generate-patch禁止出现含义不清的命名第三每个 Skill 版本号与代码库主版本绑定修改 Skill 必须更新对应文档并注明变更记录第四Skill 的输入输出协议必须有兼容性说明任何破坏性修改都需要提前周知所有使用方。这些规则落实之后新成员上手几乎零成本团队的 Skill 库越来越厚重复造轮子的情况也基本消失了。最后再分享一点我自己的体会。这套方法走到今天我最大的收获并不是某个具体模块改造成功了而是彻底理解了“AI 工程化”的分量。工程量大于算法量这句话在存量代码改造上体现得淋漓尽致。真正花时间的不是发明巧妙的 Skill 或设计复杂的编排而是理解现有代码的业务真相、定义清楚“什么算完成”、建立可靠的验证手段。AI 在这里是放大器它能把一个高效流程放大成指数级的产出也能把一个混乱流程以同样快的速度放大成灾难。所以如果你正准备动手改造一个老模块我建议你先别急着写代码把时间花在理解业务和搭基线测试上从最小的痛点开始做透第一个 Skill再一步步拓展。存量代码不是需要被推翻的废墟它藏着公司多年的业务逻辑与智慧只要方法得当这些代码完全可以被温柔地、逐步地改造成更健康的状态。这就是“微创手术”真正打动我的地方——不是取代旧世界而是让旧世界平稳地进化到新形态。 告别散装AI：用SKILL机制对存量代码做微创手术
我接手过一个跑了九年的老系统代码库像一棵根系杂乱的老树线上跑得还算稳但只要有人动它所有人心里都打鼓。我们曾经尝试用 AI 辅助改造结果却更糟团队里每个人都用各自的账号问各自的 AI把生成的结果直接粘进代码库没有任何统一标准也没有验证流程。那段时间代码风格五花八门注释互相矛盾连谁改过哪里都需要开会对齐。我管这种状态叫“散装 AI”——工具是齐的思路是散的最后既没有降低改造风险反而让技术债更厚了一层。后来我用 SKILL 机制配合编排思路换了一种打法不再让 AI 替人轻率地“即兴发挥”而是把 AI 能力封装成一个个可复用的技能单元再按照一套类似手术流程的编排链路去处理存量代码。从诊断到出方案从小切口改到验证回滚每一步都清晰可控。这套打法帮我成功拿下了一个又一个“没人敢碰”的模块也让我彻底告别了之前的混乱状态。适合读这篇文章的人正在维护老系统却被 AI 改造项目反复折磨的工程师、想给团队引入 AI 辅助编码规范却没有头绪的技术负责人以及任何吃过“散装 AI”亏、想用更工程化方式落地 AI 能力的人。下面分享的是我在实际项目中验证过的完整思路与操作细节。1. 当我决定不再“散装”用 AI1.1 “散装 AI”是怎么把代码库越改越乱的先还原一个典型场景。团队里三名工程师分别用 AI 助手处理同一个问题某个订单金额计算函数偶尔多算一分钱。工程师 A 让 AI “分析这段代码”AI 给了三处可疑点工程师 B 直接要求“重写这个函数”AI 给了新版本工程师 C 让 AI “补全注释”AI 又把注释风格改了一轮。三个人都觉得自己用得很好但代码库同时出现了三种风格的代码函数被重写了一半线上问题依然在新引入了一半。最头疼的是没有人能说清楚哪一段逻辑是经过验证的、哪一段是模型生成的推断。“散装 AI”的本质问题不在 AI 本身而在于使用方式。它有三个典型的病灶第一没有统一上下文。每次给模型喂的代码、背景、约束条件全凭个人当时的表达能力和运气第二没有输出协议。AI 回答是自由格式的自然语言没有强制它输出“风险等级”“改动范围”“验证步骤”无法直接进入工程流程第三没有校验闭环。AI 生成完就结束了没有人要求它先跑一遍静态检查、对比编译结果、确认不破坏既有行为。我并不是要否定 AI 在编程中的作用。相反在过去两年里我发现问题不在“AI 不够强”而在于我们把它用成了散装工具。AI 应该像手术室里经过消毒、标准化的手术器械而不是一把随手捡起的剪刀。对待存量代码尤其需要注意这一点。存量代码本身就有大量隐含的业务规则和历史包袱再用散装的方式使用 AI等于在已经脆弱的系统上叠加了一层随机性。1.2 存量代码真正怕的是什么存量代码有几个共性特征文档稀缺、逻辑缠绕、测试覆盖不足、关键技术决策的历史原因已经丢失。以我之前负责的订单系统为例一个计算折扣的方法里嵌套了七层 if-else每层都有对应的业务背景但这些背景分布在六年前的工单、离职同事的口头描述和一段没有注释的提交记录里。这种代码不是“写得差”而是“承载了大量不可见的知识”。面对这样的代码团队通常会有两种极端反应。一种是不敢动像对待博物馆里的展品一样供着任何变更都在上面打补丁最终补丁摞补丁另一种是推倒重来用新框架把老模块重写一遍。事实证明“推倒重来”在存量代码上失败率极高。重写过程中会丢掉隐蔽的业务逻辑用户数据兼容性也会出问题最后往往是新系统上线即翻车旧系统还得继续维护。我参与过的几个遗留系统重写项目不夸张地说大多数都以惨败收场。存量代码真正怕的不是变革而是大范围、高风险、不可回退的改变。病人需要的不是重新长一副身体而是把病灶切除、让原有组织正常工作。这就是“微创手术”思路的由来小切口、低侵入、每一步都保证系统仍然可用并且可以在任何异常时刻退回到手术前的状态。AI 在这里的角色是辅助我们做精准的诊断和切割而不是负责把整台手术做完。1.3 一次典型的“手术”应该长什么样我在多次实践中沉淀出一套可复用的流程它模仿了真实手术的过程术前影像学检查、手术方案设计、小切口执行、缝合修复、术后观察。对应到代码改造上是下面五个阶段诊断阶段通过监控指标、异常日志、需求变更频率等数据找出系统里“最痛”的模块并用静态分析和调用链还原模块的真实结构。方案阶段基于诊断结果生成若干个改动方案明确每个方案涉及的函数、影响范围、风险点和回滚方式。切口阶段选择影响范围最小的改动路径执行局部重构或修复严格限制改动边界。缝合阶段补齐测试用例让改动后的代码通过原有测试和新增的行为验证。观察阶段上线后监控关键指标用流量对比、日志分析确认没有引入回归必要时快速回滚。AI 是这套流程的执行工具但它不能承载决策权。尤其对于存量代码修改哪一行、影响哪些下游依赖、可接受的失败窗口有多大这些问题必须由人来判断。AI 的作用是压缩信息获取的时间、提高方案生成的效率、减少遗漏而不是代替工程师做判断。想做到这一点就需要把 AI 的使用方式工程设计化这就是 SKILL 机制和编排思路存在的价值。2. SKILL 到底是什么它和 Prompt、Agent 有什么不同2.1 从一次复制粘贴到一组可复用资产的转变很多人对 SKILL 的第一反应是“这不就是个高级 Prompt 吗”。我一开始也这么想真正实践之后才知道区别非常大。Prompt 是一次性的口述你每次都要重新描述问题、背景和输出要求就像每次手术前都要重新发明一套工具质量完全取决于操作者当天的表达状态。SKILL 是一个封装好的“手术器械盒”里面固定装配了上下文采集器、规则集、输出协议和自检机制任何人在任何时间调用它得到的是质量稳定、格式统一、可以被后续流程直接消费的结果。举一个更直白的例子。以前我想让 AI 分析某个模块的风险我需要复制代码、粘贴到聊天框、写上“帮我看看哪里可能出问题”。这个过程听起来不难但如果是二十个模块、五个团队成员分别做结果就是灾难。有人只贴了函数签名有人贴了完整文件但没说业务背景有人忘了让 AI 标出置信度于是所有人的输出都不可比、不可汇总。改用 SKILL 之后我只要在代码库根目录放好技能定义文件团队成员输入同样一条命令AI 就会自动读取模块代码、提取调用关系、加载项目规则、输出一份固定结构的风险评估报告。结果是统一的报告可以被脚本自动解析也可以进入下一步编排流程。本质上SKILL 把“AI 使用经验”从个人口袋里拿出来变成了团队的工程资产。这个转变是告别“散装 AI”的关键一步。2.2 SKILL 的四个组成部分上下文采集、规则集、输出协议、自检机制在实践里我通常把 SKILL 拆成四个组件来设计每一块都有明确职责。上下文采集器负责决定“让模型看什么”。存量代码的问题往往不是信息太少而是信息太杂。如果把整个微服务代码塞进上下文模型很快就迷失在无关代码里回答质量直线下降token 成本也高得离谱。所以采集器要做的是把问题域内有用的信息自动抽取出来相关函数源码、调用方与被调方的签名、相关配置文件、最近的异常日志片段、涉及的历史变更记录。它更像给模型准备一份“病历资料”而不是把整个房间的病历都丢过去。规则集负责装载“不可违背的边界”。它包含项目级规范、团队约定、领域约束。例如禁止使用 eval数据库访问必须走统一DAO金额计算必须使用定点数任何对外 API 的返回值格式不允许改变。规则集的另一个功能是补充业务上下文比如“折扣计算的历史规则见 docs/legacy-rules.md若与代码注释冲突以文档为准”。这套规则是沉淀出来的每次线上事故和踩坑之后我都会往里面补一条。输出协议负责约定“返回什么、长什么样”。在自由对话里让 AI 输出自然语言后续处理往往不可依赖。而有了输出协议AI 必须生成结构化的结果。比如要求输出一个 JSON包含 risk_level、affected_files、suggested_actions、confidence、missing_info 这五个字段并且每个字段都有取值范围或格式说明。这样一来结果就可以被脚本解析、被下一步流程使用、被存档追踪。自检机制是最后一道闸门也是很多人忽略的部分。AI 生成的结论不能直接信但它自己可以先做一轮基础检查。比如生成了一个改代码的建议自检机制会让它调用 grep 确认要修改的函数真的存在、调用编译器检查生成的代码能否编译、调用静态分析工具扫描明显的问题。自检通过之后结果才允许被输出。这一步能拦截大量“看起来很专业但根本执行不了”的答案也显著减少了幻觉对下游流程的污染。2.3 SKILL 与 Agent、编排的关系搞清楚 SKILL 与 Agent、编排的关系能让你少走很多弯路。简单地说Skill 是单一能力单元Agent 是具备决策循环的执行者编排是把多个 Skill 按流程串联起来的骨架。我在实际项目中见过两类极端误区。一类是把所有逻辑塞进一个 Agent告诉它“你去把这个模块改造好”指望它自主搞定一切。结果通常很惨因为大范围任务里模型在长链路执行中会逐渐丢失最初的约束中途产生的修改很难被发现和纠正最后得到一堆不可控的变更。另一类误区是只用单个 Skill把所有分析工作一股脑塞进去期望一个 Skill 解决从诊断到重构再到验证的所有问题。这也做不到因为每个环节需要的信息、规则和输出格式完全不同强行糅合只会让每个环节都做得不精。正确的做法是拆成多个 Skill用编排把它们组织成可控的流水线。以存量代码改造为例我通常会拆出“体检 Skill”“方案 Skill”“变更 Skill”“验证 Skill”四个技能编排起来依次执行。每个 Skill 的输出都是下一步的输入每两个 Skill 之间可以有一个人工确认节点。这样做的好处是单步内的复杂度可控单步输出可以被检查任何一步出了偏差都能及时纠正不会等到最后才发现方向全错了。打个生活化的比方Skill 是一把把专用的手术钳Agent 是一个能自己判断“下一刀该往哪切”的外科医生而编排是手术室里的操作流程——切完第一刀必须停下来看出血量、确认没问题再进行下一步。没有流程编排医生再厉害也可能在长手术中出乱子没有专用工具流程再严谨也做不到精细操作。三者结合才是对存量代码做“微创手术”的正确姿态。3. 术前准备给存量代码做一次“影像学检查”3.1 从指标和工单里找痛点不靠感觉选模块做改造最忌讳一开始就选错对象。我见过有团队兴致勃勃去重构某个看起来“代码很烂”的模块做了三个月发现这个模块根本没人用、也不是线上瓶颈真正的问题在另一个调用频率高一百倍的路径上。所以手术前必须有一个客观的“病灶定位”环节而定位的依据应该是数据不是感觉。我的做法是把几类指标放在一起看一是异常指标从监控系统拉出报错次数最高的 Top 模块二是变更频率从代码仓库的提交记录里统计哪些模块在过去一年被修改的次数最多——改得越频繁说明越不稳定、越痛三是业务影响找到用户反馈和工单里被吐槽最多的功能反推到对应的代码模块。最终形成一个“热点模块清单”按“痛感×影响面”排序选出第一个动刀的候选对象。这里有一个很实在的判断标准选改造对象时要避开“复杂度高但没痛点”的模块优先选“痛点明显但改动边界清晰”的模块。第一次做微创手术成功体验比挑战极限更重要。你先在一个中等难度的模块上跑通全流程建立起团队的信心和流程规范再去啃真正的硬骨头会稳妥得多。3.2 梳理模块边界、依赖与调用链选定目标模块之后下一步是搞清楚它的边界。换句话问它从哪里来、到哪里去、和谁发生数据交换、内部有哪些不可破坏的外部约定。这一步的产出是一张可以被 AI 消费的“手术地图”。绘制这张地图有三条情报来源。静态分析能直接生成函数调用关系图和文件依赖列表让模型快速理解代码结构动态追踪可以在测试环境或预发环境对关键路径打点记录真实运行时调用顺序、耗时和参数特征捕捉到静态分析看不见的反射调用和动态分发逻辑数据血缘分析能帮我们理解核心数据的流转路径——比如订单金额字段从创建、计算到持久化经历了哪些函数哪一个节点改变了它的值。这三类信息叠加起来模块的“解剖结构”就非常清晰了。在整理边界时有一个关键任务把“手术中不允许改变的地方”标识出来。比如对外 API 的参数名和返回值结构、数据库表结构、与其他服务之间的 MQ 消息格式。这些就是解剖学里的“大血管”碰到了会引发大出血所以必须在手术地图上醒目标注。我的做法是把这些约束直接写进规则集让所有下游的 Skill 从一开始就被约束住。3.3 建立基线测试给“手术”留一张安全网做完边界梳理还得解决一个非常现实的问题存量代码的测试覆盖通常很差你没有足够的安全网来验证“改动没破坏原有行为”。补全单元测试不现实但我们可以用一种更聪明的办法叫行为快照。行为快照的思路是在改动之前先录制一组“输入-输出”对把它们固化为测试用例。具体操作方法有很多种我常用的是下面两种。第一种是历史日志回放从线上日志或消息队列里捞出一批真实请求把这些请求的数据结构保存下来作为后续回归测试的输入。第二种是接口录制在网关层或者测试环境对目标接口记录请求和响应自动生成一批对比用例。举个例子我在改造旧订单价格计算模块时从生产环境导出了过去七天一万多个真实订单的输入参数和计算结果把它们整理成了基线数据集。改造完成后拿同样的输入跑新代码逐单对比结果差异归零才算通过。这一步极其有价值它相当于手术前给病人的器官做了一份完整的功能造影手术过程中随时可以对照确保没有偏离原有功能。有了这层保护模型生成的改动即使再大胆我们也有底气和它交手。4. 设计第一个 SKILL让 AI 对代码库“说实话”的体检技能4.1 输入设计给模型喂什么不喂什么SKILL 的质量上限很大程度上取决于输入设计的质量。这一点怎么强调都不过分尤其当面对的是动辄上千行、内部状态繁多的存量模块时把什么内容送进模型上下文直接影响输出的可信度。我的输入设计原则是“分层抽取按需投喂”。不是整块代码文件全丢进上下文而是把代码库当成一个可以被查询的对象让采集器逐层拉取。第一层是模块骨架包括文件清单、对外函数签名、核心数据结构定义让模型先建立全局认识第二层是目标函数细节只把本次分析要针对的函数实现源码投进去连同它直接调用的子函数第三层是关联上下文包括调用方代码、配置项、异常日志中与该模块相关的片段。如果第一轮分析之后模型发现还缺信息采集器再按需补拉而不是一开始就灌满。有人会问为什么不把所有信息一次性给足原因有两个。一是信息过载会导致注意力稀释模型看到一千行无关代码之后对关键问题的分析能力会明显下降甚至开始“凑答案”二是成本问题token 开销和响应延迟都会随着上下文长度非线性增长在编排流水线里每一步都在烧钱能省就要省。把输入设计当成一项系统工程来做收益远超想象。4.2 规则集与输出协议强制报告结构化输入设计好之后接下来要定义规则集和输出协议。先看规则集的写法。以 Markdown 格式的 SKILL 描述文件为例我会这样组织# skill: code-diagnosis ## 背景 该技能用于对存量代码模块进行风险诊断输出结构化体检报告。 ## 上下文采集方式 - 读取需要诊断的模块文件清单 - 提取目标函数源码及各函数间调用关系 - 读取项目根目录下的 AGENTS.md 或 RULES.md加载项目级约束 - 若存在 legacy-rules 文档必须优先于代码注释作为业务规则来源 ## 规则集 - 金额、折扣、税率等数值字段必须使用 Decimal 或定点数禁止浮点运算 - 所有数据库访问必须经过统一 DAO 层禁止在业务函数中直接执行 SQL - 对外 API 的返回字段名称与类型不允许变更包括 JSON 字段顺序 - 若发现代码行为与文档矛盾先输出矛盾项再做判断 ## 输出协议 必须输出 JSON 对象格式如下不得输出其他内容 { module_name: 模块名, overall_health_score: 0-100, pain_points: [痛点描述], risk_level: low | medium | high | critical, suggested_actions: [建议动作], affected_files: [受影响文件], confidence: 0-100, missing_info: [依赖什么信息未确认] }这套格式让 AI 的输出被彻底“协议化”。实际跑下来你会发现只要规则集写清了边界、输出协议定义了结构AI 的回答就从“参考意见”变成了“可直接解析的数据”。我可以把这些 JSON 直接扔给下一个 Pipeline 消费也可以自动汇总成团队周报。这种由混乱到规范的变化是工程化落地 AI 最重要的感受之一。4.3 自检机制让技能先过一道“体检”输出协议只解决了格式问题还不能解决正确性问题。模型生成的结论是否站得住脚针对这个问题我在技能里加入了一个容易被忽视的环节——自检。自检不是让 AI 再认真看一遍而是让它调用真实的工程工具来验证自己的判断相当于写完论文之后自己先去查一遍数据是否真实可考。具体做法是在输出之前技能通过命令行工具完成几个检查动作。比如用grep确认自己引用的函数名在代码库中真实存在用python -c import ast; ast.parse(...)检查自己生成的代码是否语法合法用jq校验输出 JSON 的结构是否符合协议条件允许的话甚至可以调用eslint或mypy做静态检查。我把这个自检过程写成脚本挂到 Skill 的末尾用一行命令就能触发。# 在 Skill 的验证阶段对生成的 JSON 报告做基础校验 cat report.json | jq -e .module_name and .risk_level and (.confidence | type number) grep -q compute_discount src/order_service.py || echo 警告: 引用的函数不存在自检机制拦截了多少错误就我实际使用体验来说它能挡住相当一部分“常识性幻觉”。比如模型在报告里断言某个函数返回值是 String真实代码里其实是 Dict自检用 AST 一解析就能发现矛盾。这类错误如果在早期不拦截流到下一个 Skill 里就会像滚雪球一样放大最后出来的方案根本执行不了。让每个 Skill 对自己负责是编排能够稳定运行的基础。5. 端到端实操一个订单利率模块的“微创手术”全流程5.1 场景设定那个没人敢动的价格计算模块用我真实处理过的一个模块来完整走一遍流程。这个模块叫PriceCalculator是订单系统里负责最终支付金额计算的类核心方法compute_total有两百多行里面堆了会员折扣、满减优惠、品类加价、旧系统迁移来的“幽灵优惠”等七层逻辑。可怕的是这个类没有任何单元测试只有几处散落的日志打印。线上偶发的“价格差一分钱”工单有六成都指向这里但历任维护者都不敢动。我先做术前检查。从监控系统看过去 30 天compute_total被调用约一千万次异常率 0.3%P95 延迟比同模块其他方法高出一倍从 Git 历史看这个文件在过去一年被改过 23 次其中 18 次是修回归引入的新缺陷。结论清晰这块骨头必须啃但它只能小步走。基线测试方面我从前端流量录制了七天约五万条真实订单的输入与计算结果按支付方式、用户类型、商品品类做了分层抽样固定成一万两千条基线用例。这期间还发生了个小插曲录制数据时发现有大约三百条订单的金额在历史版本中其实也被计算错过但这些数据被内部账单修正过不能直接用作基线。这个发现差点把整个手术计划打回到诊断阶段好在当时流量录制和数据校验脚本分离得足够透重捞了一遍数据就解决了。5.2 编排链路设计从诊断到验证的四步流水线针对这个模块我设计了四个 Skill 和一条编排链路。四个 Skill 分别是体检 Skill读取模块源码与调用关系输出结构化的风险报告包括健康度评分、痛点定位。方案 Skill接收体检报告结合规则集生成三套改动方案每套方案包含改动文件、改动函数、影响范围、风险等级。变更 Skill在选定的方案下生成实际代码补丁并要求逐行解释改动原因。验证 Skill读取补丁和基线数据集执行行为对照测试输出验证结果。编排链路如下体检 Skill 先跑输出报告送到人工确认觉得没问题再往下走方案 Skill 生成三套方案后由我本人和一位熟悉业务的同事共同选一套选定方案后变更 Skill 生成代码补丁补丁必须经过 code review 才会被应用到代码库最后验证 Skill 用基线数据跑回归通过后进入灰度发布。每一步之间都有一个人工确认节点绝不自动连着跑到底。有同事问过为什么不让四个 Skill 一步到位全自动原因很简单存量代码改造不是流水线生产螺丝钉每一步都可能出现需要人类经验介入的判断。比如方案 Skill 生成“重写 compute_total”的方案看起来风险等级标的是 low但只要稍微了解订单系统的人都知道重写一个承载了大量历史业务规则的类是极度危险的操作。这种判断力现在的模型还不具备必须由人来把关。人工介入点设在流程的关键关节上既保持了效率又守住了安全底线。5.3 关键配置与执行记录解读下面是我实际操作中的一段编排配置为了方便演示做了简化。它用 YAML 描述了流水线的连接方式每个节点都是一个独立 Skill 调用。# 简化版流水线定义 steps: - skill: code-diagnosis id: diagnosis input: module: PriceCalculator - skill: human-confirm id: review_diagnosis input: { source: diagnosis } - skill: refactor-planner id: plan input: { source: review_diagnosis } - skill: human-confirm id: choose_plan input: { source: plan, required: 选择其中一套方案 } - skill: patch-generator id: patch input: source: choose_plan patch_mode: minimal - skill: code-review-gate id: review input: { source: patch } - skill: behavior-validator id: validate input: source: review baseline_path: tests/baselines/price_calculator.jsonl on_fail: action: rollback执行记录节选一下。体检 Skill 首先输出了一份很有意思的报告健康度评分 43风险等级 critical痛点定位清晰指出三处“幽灵优惠”逻辑只有一处有代码注释另外两处完全无据可查。方案 Skill 随后给出三套方案方案 A 是最小补丁只修复“满减与会员折扣叠加顺序错误”方案 B 是中等范围改造将七层 if-else 抽为策略类但保留每个策略的原始行为方案 C 是整体重写。三套方案的风险等级分别是 low、medium、high。业务同事在选择时直接排除了 C因为风险等级 high收益也不明确最终我们选了 B因为痛点清单里的三处缺陷原本就分散在多个条件分支里与其修一处漏一处不如把分支变成独立策略类每一个策略用基线用例验证整体行为有保障。变更 Skill 生成的补丁改动范围比较克制新增了一个strategy文件夹把原本嵌套在compute_total里的三类折扣逻辑迁移到独立的策略类中同时保留了compute_total作为统一入口对外部调用完全透明。这在设计上做到了“内部重构、外部无感”正好符合微创手术的思路。代码 review 阶段同事提了几个关键意见新增策略类的命名没按团队规范、折扣优先级的 Constants 定义重复了两处、有两段迁移代码缺少注释说明来源逻辑在哪次工单中修正过。这些问题在评审中被拦截下来全部修改后才进入验证环节。5.4 结果回填、回滚与经验沉淀验证 Skill 用一万两千条基线用例跑完行为对照结果令人满意一万一千九百八十七条完全一致还有十三条的金额差异都在一分钱以内且经过人工核对是原代码本身的已知舍入误差问题不属于本次改动引入的回归。随后我们把改动灰度发布先打开 5% 流量观察一天再逐步放大到 100%监控面板上 P95 延迟从改造前的 380ms 降到 120ms异常率从 0.3% 降到 0.02%。回滚预案其实我们并没有真正触发但预案本身写得非常清楚改动全部通过增加策略类和调整compute_total内部调用顺序实现没有修改数据库结构和对外接口如果线上出现异常只需要回滚一次代码发布即可恢复。更重要的是这次改造的经验被固化了下来我们把“订单价格相关规则禁止直接内联在业务函数里”“任何金额改动必须跑基线数据集”写进了规则集以后所有的 Skill 在处理这个模块时都会自动遵循这些约束。手术完成后团队对这些“微创手术”的信心有了质的提升。你从没有经历过的状态很难描述当你知道手里有一套可以随时回退、每步都有明确产出的流程时面对存量代码的恐惧感会大幅降低。后面我们又用同样的编排结构处理了三个模块每次只需要替换体检和变更 Skill 里的规则集流水线本身几乎不用动。6. 常见问题与排查技巧实录6.1 上下文太长模型开始“胡言乱语”这是我在使用中遇到频率最高的问题。模型对“关键信息被淹没”很敏感。一个常见场景是流水线的第二个 Skill 需要从上一步拿到分析报告又要把整个目标模块的源码重新送进去结果上下文一下子飙到几万 token模型开始把关系不大的代码也列进影响范围甚至把函数名都编错。排查方法是把每一步 Skill 的输入内容打出来看有没有“重复字段”和“无关内容”。问题通常出现在采集器定义里——我有时候图省事让采集器把整个文件夹都读进去这就是典型的懒做输入设计。解决办法是明确 Skill 边界上一个 Skill 的输出已经完成了分析下一个 Skill 只需要这段分析的结论摘要和少量必要源码不需要重新分析整个模块。可以在配置里规定摘要的最大长度把“输出摘要”写进输出协议,这样每个 Skill 的输入都保持在可控范围内。6.2 Skill 生成“看起来很对但逻辑错误”的代码“看起来很对但经不起推敲”几乎是 AI 编程最容易踩的坑。尤其是在业务规则复杂的存量代码里模型可能生成一段读写路径完全正常的代码但业务逻辑是错的。我遇到过最典型的例子它把折扣叠加的顺序从“先满减后折扣”悄悄改写成了“先折扣后满减”单看代码每一行都没错甚至注释都写得很漂亮但结果对不上。这类问题的根源在于模型看到了代码结构但没有理解业务变量背后暗含的业务流程。对策有几个。第一把领域规则写进规则集甚至明确写出“折扣叠加顺序不得改变若发现原代码有两种语义冲突先报冲突再给方案”第二强制生成的补丁必须附上逐行的“修改原因说明”和“原逻辑与新逻辑对比表”这样 code review 才有据可查第三也是最可靠的让验证 Skill 用基线数据集做行为对照这是最后能拦住业务逻辑错误的高墙。没有基线数据的情况下至少要给变更 Skill 加一条指令“如果改动可能影响金额计算结果必须输出‘已修改计算逻辑’的显式警告。”6.3 编译通过、单测通过上线之后还是出问题这大概是所有改造项目都怕的噩梦。编译和单测都过了说明代码在“设计的输入”下没有问题但真实的线上输入往往比测试数据更刁钻。我们遇到过的情况是新代码对老用户历史数据中的某个“脏字段”没有做兼容处理而这个脏字段在测试数据里根本不存在。单测数据是我们自己造的当然覆盖不到这种边界。解法思路是用真实数据说话。在存量代码改造里人工构造的测试数据永远不够一定要想办法引入线上流量的回放或影子模式。具体做法可以是在网关层复制一份线上请求用同样的参数打给新旧两套代码比对返回差异也可以通过消息队列把真实请求异步降级到预发环境的新版本上运行只做对比、不影响真实业务。我在订单模块改造时用的就是这个思路效果远好于任何手工构造的测试。6.4 团队协作SKILL 库的版本管理与命名规范最后一个问题来自团队协作的规范层面。AI 辅助编码的工程化不只是技术问题更是组织问题。Skill 如果管理不好很快就会变成另一种“散装”只是从“散装的 Prompt”变成了“散装的 Skill”。我给团队定的规范有几条硬性要求。第一SKILL 统一放在代码仓库的skills/目录下和普通代码一样走 PR 评审流程不允许个人在本地私藏 Skill第二命名遵循统一的领域-动作-对象格式例如order-diagnosis-risk、code-generate-patch禁止出现含义不清的命名第三每个 Skill 版本号与代码库主版本绑定修改 Skill 必须更新对应文档并注明变更记录第四Skill 的输入输出协议必须有兼容性说明任何破坏性修改都需要提前周知所有使用方。这些规则落实之后新成员上手几乎零成本团队的 Skill 库越来越厚重复造轮子的情况也基本消失了。最后再分享一点我自己的体会。这套方法走到今天我最大的收获并不是某个具体模块改造成功了而是彻底理解了“AI 工程化”的分量。工程量大于算法量这句话在存量代码改造上体现得淋漓尽致。真正花时间的不是发明巧妙的 Skill 或设计复杂的编排而是理解现有代码的业务真相、定义清楚“什么算完成”、建立可靠的验证手段。AI 在这里是放大器它能把一个高效流程放大成指数级的产出也能把一个混乱流程以同样快的速度放大成灾难。所以如果你正准备动手改造一个老模块我建议你先别急着写代码把时间花在理解业务和搭基线测试上从最小的痛点开始做透第一个 Skill再一步步拓展。存量代码不是需要被推翻的废墟它藏着公司多年的业务逻辑与智慧只要方法得当这些代码完全可以被温柔地、逐步地改造成更健康的状态。这就是“微创手术”真正打动我的地方——不是取代旧世界而是让旧世界平稳地进化到新形态。