如果你手里有一堆跑了好几年的存量代码想在里面引入 AI 又不敢推倒重来这种感觉我太懂了。团队里每个人都在用 AI 聊天、写提示词、做代码补全可这些能力全是“散装”的改个 Bug 问一遍写个单元测试又问一遍每次都要把项目上下文重新交代一遍效率好像提上去了脑子却快被折腾干了。这其实不是 AI 不行是使用方式不行。后来我把目光放到“SKILL 编排”这条路上把 AI 从“随口问”变成“按手术方案执行”用一套可复用的技能体系对一个老项目做了几次低侵入、可验证的局部改造整个过程就像给存量代码做“微创手术”。这篇就把完整思路、具体步骤、踩过的坑都写下来适合手上有老代码、想用 AI 做增量改造又不敢大动的开发者和技术负责人。1. 为什么“散装 AI”救不了存量代码1.1 存量代码的真正困境不是“老”而是“不敢动”许多团队手里的老代码其实没有那么多原罪能跑起来、能撑业务说明核心逻辑经得起考验。问题集中在三件事读不懂、不敢动、不好测。架构文档早已过期业务规则散落在各种 if / else 里单元测试覆盖率一塌糊涂。这时候如果继续用问答式的 AI 用法比如把代码复制给聊天窗口让它分析或者让补全插件在关键方法里乱接一段是极度危险的。“散装 AI ”的本质是缺乏任务定义和约束。Prompt 确实能写但每次写出来的风格不一样答案质量看当天模型心情生成代码确实快但没人敢合入主干。我见过最典型的场景一个小伙伴让 AI “优化一下登录逻辑”结果 AI 顺手把整个鉴权流程重构了review 的时候所有人都沉默了。AI 没有系统边界感它会在你看不见的地方脑补你没有说的东西。1.2 “微创手术”思维不换系统只清病灶真正把 AI 引入存量代码心态要更像做一台微创手术。目标不是换一条腿而是把血管里的斑块清掉。手术之前要有检查报告、手术路径、切割范围、术后观察。SKILL 编排做的事情正是把这套“术前协议”变成格式化、可执行、可回滚的工程资产。对我来说“微创”有几个硬性标准改动范围肉眼可见不碰无关模块每个修改点有明确理由执行之后有自动化手段验证万一出问题可以快速回退到上一个版本。存量代码改造最怕的就是“顺手优化”AI 一旦发挥过度微创就变成大出血。SKILL 的作用就是把手术刀限定在病灶周围。1.3 SKILL、Workflow、Agent、Prompt 到底是什么关系很多人在热词里天天看到 SKILL、Agent、Workflow但实际用起来经常混。这里先给一个快速对照表后面所有实操都建立在这个理解上。概念一句话定义典型形态解决什么问题Prompt一次性指令一段文本临时让模型干一件事SKILL可复用的能力封装SKILL.md 脚本 参数定义让模型按固定流程和专业边界干活Workflow多节点自动化串联节点图 / DAG把多个步骤编排成一条流水线Agent有感知、决策、执行能力的智能体自主循环 工具调用在复杂任务中动态决定下一步SKILL 在工程上的形态通常是一个目录里面包含技能描述、参数约束、步骤指引、以及可选的可执行脚本。你可以把它理解为给模型读的“手术 SOP 手术器械操作手册”。AI 读到这个 SKILL 之后不再自由发挥而是像刚入职的医生拿到了科室标准流程第一步做什么、第二步做什么、什么不能做写得清清楚楚。2. 术前准备设计一个可落地的 SKILL 要抓哪些点2.1 SKILL.md 是核心但不是全部一个合格的 SKILL 文件核心信息基本都堆在 SKILL.md 里。业界比较常见的做法是 Markdown 加 YAML frontmatter 的混合结构Claude Skills 就是这么干的Codex 和 OpenCode 等工具也在跟进类似机制。SKILL.md 至少需要包含四个部分技能标识与描述、参数定义、执行步骤、安全红线。其中 description 是最容易被忽略但又最关键的字段。它决定了模型在什么场景下会调用这个技能。写得太泛比如“帮助优化代码”那 AI 几乎什么任务都会往这里塞写得太窄比如“只处理 user_service.py 第 45 行的异常”那这个技能就没有复用价值。比较理想的写法是明确技能适用的任务类型、典型的触发场景、以及不适用的边界。我自己的习惯是给每个 SKILL 写“适用场景”和“不适用场景”两个小节宁可多写几行也不要让 AI 在意图匹配阶段跑偏。这里有一个反常识的点很多人写 SKILL 是为了让 AI 干活更聪明但实际经验告诉我先让它“干活更规矩”收益大得多。2.2 参数与输出约束是防止 AI 发挥过度的“手术护栏”参数定义这件事表面上是技术细节实际上是安全边界。拿存量代码改造来说你需要给模型定义清楚输入是什么、允许访问哪些文件、必须输出的格式是什么。我强烈建议在 SKILL 里明确指定输出模板。比如改造类 SKILL 的输出必须是问题定位结论、拟修改文件列表、具体代码块或 diff、测试方案、风险提示。这比让 AI 自由输出一段“优化后的代码”强太多。因为当你强制输出结构化内容时模型被迫先分析再动手而不是直接跳到代码生成环节。安全红线同样要写进 SKILL 里。可以是文件级别的比如“禁止修改 db/ 目录下的任何文件”也可以是语义级别的比如“禁止改变对外接口签名”“禁止删除公共函数”。这些红线相当于手术台上的禁忌区域AI 再聪明也得绕着走。2.3 用“手术分级”评估存量代码的 AI 化优先级不是所有代码都适合用 SKILL 来做改造。我在项目里会把存量模块按照“风险 x 收益”分成三个区这个方法是我一直在用的绿区低风险、高收益。典型任务包括生成单元测试、补充注释、统一命名、异常处理迁移、日志格式规范化。这类任务不动核心逻辑改造失败最多是测试文件重写非常适合 SKILL 批量执行。黄区中风险、中收益。比如局部重构、依赖升级、缓存策略调整、配置抽离。这类任务需要精确的上下文理解SKILL 可以辅助但必须有人工 review 兜底。红区高风险、需要深业务理解。比如核心交易链路、并发控制、数据迁移、权限校验。这类代码我建议人类主导AI 只做辅助分析不要用自动化的 SKILL 直接改。SKILL 编排最适合的战场是绿区和黄区。很多团队一上来就想让 AI 重构核心模块结果翻车了就觉得 AI 不行其实是用错了力。2.4 工具链选择Codex、OpenCode、Continue、Cursor 到底怎么挑SKILL 要落地离不开工具支持。最近几个月我把主流工具都试了一轮简单说一下个人感受。CodexOpenAI 的 CLI 工具对 SKILL 相关机制跟进很快适合习惯命令行的工程师。它最大的优势是能比较自然地理解仓库上下文在一个 monorepo 里跑 SKILL 相对省心。OpenCode社区热度很高支持 SKILL 的安装和使用配置方式灵活有很多现成的 SKILL 可以借鉴。它的路线更偏“本地优先”对隐私要求高的团队比较友好。Continue是一个 IDE 插件适合塞在 Pycharm、VS Code 里用。它把 SKILL 这类能力做成了侧边栏对话和代码补全的增强适合不想切命令行的开发者。Cursor自带 Agent 和规则能力SKILL 类机制需要额外配置但它胜在编辑器体验顺滑适合小步快跑。工具没有绝对的最好关键看你的工作流。我个人现在的主力是 Codex OpenCode 双轨Codex 负责和模型沟通、执行 SKILLOpenCode 负责本地技能库的管理和调试。Pycharm 用户也不用慌Continue 插件配合自定义规则也能达到类似效果。3. 实操全记录用三个 SKILL 对一个老项目做微创手术3.1 场景设定一个藏着暗伤的 Python 遗留服务我挑一个真实的例子来走完整流程。假设有一个用户积分服务模块代码是 Python 写的跑了两年多。问题是数据库连接和业务逻辑混在一起、多处硬编码、异常处理基本靠裸 try / except 吞掉、日志格式各家自扫门前雪而且整个模块没有单元测试。这个场景非常典型。直接重构风险太大不处理又天天出幺蛾子。我用三个 SKILL 编排了一台“微创手术”第一个做异常处理迁移第二个做配置抽离第三个为存量函数批量生成单元测试。手术边界我提前定死不动任何对外接口签名不动数据库表结构不改变业务判断顺序。这条边界在每一个 SKILL 的“安全红线”里都有明确声明。3.2 第一个 SKILL异常处理迁移这个 SKILL 的目标是把所有裸 try / except 改成统一异常处理框架同时保留原有的业务逻辑。核心不是让 AI 写多少新代码而是让 AI 按一套固定模式做机械替换。SKILL.md 的关键部分长这样--- name: exception_migration description: 将指定模块中的裸 try/except 迁移到统一异常处理框架。适用于 Python 服务端代码不适用于改动业务判断逻辑。 parameters: target_file: 需要迁移的目标文件路径 exception_framework: 统一异常处理模块的导入名 red_lines: - 不得修改函数签名 - 不得修改业务判断顺序 - 不得删除原有日志调用只能替换为统一日志 steps: 1. 读取 target_file识别所有 try/except 块 2. 对每个 try/except 块分析 except 后的处理逻辑 3. 将裸 except 替换为统一异常处理框架的调用 4. 保留原业务处理逻辑仅调整异常捕获结构 5. 输出修改后的完整代码块和变更说明 ---这个 SKILL 看上去简单但实际执行下来比我想象中要稳。原因是步骤 2 的“分析 except 后的处理逻辑”非常关键AI 必须先理解每个异常块在干什么而不是无脑替换。我在调试时发现只要把步骤写得足够细AI 的偏差就会大幅减少。为什么要有参数里的 exception_framework因为不同的项目有不同的异常处理规范如果让 AI 自己发明一套项目就变成四不像了。把规范作为参数传进去AI 只做迁移不做设计决策这就是“微创”的含义。3.3 第二个 SKILL配置抽离配置抽离比异常处理复杂一点因为涉及字符串识别和替换范围的判断。存量代码里经常出现“魔法值”比如超时时间、重试次数、阈值数字直接散落在业务代码里。人工去改是体力活让 AI 裸跑又会误伤。我设计的“配置抽离” SKILL 有几条特殊约束只识别基础类型常量不识别对象和函数返回值。同一文件内值相等的常量只抽第一次出现的位置后续引用同一个配置变量。抽离后必须在文件头部生成示意图标明配置名、原值、新位置。抽离的配置统一写入项目已有的 config 模块不新建配置文件格式。执行这个 SKILL 时最爽的部分是它输出了一张“变更对照表”。人工 review 的时候一眼就能看出哪几个数字被搬走了是不是误拉了什么常量。中途有一次 AI 把另一段业务代码里的 60代表秒数也当成配置抽了后来我在红线上加了“只抽目标文件内超过两次出现的同值常量”这个问题就消失了。3.4 第三个 SKILL为存量函数生成单元测试第三个 SKILL 的定位更特殊它只读不写业务代码。这个 SKILL 的目标是分析目标模块的每一个函数自动生成 pytest 测试文件。它不修改任何源代码只生成测试代码所以风险最低但价值却非常大。生成测试的 SKILL 有三个难点。第一存量函数往往依赖数据库、外部服务直接跑 pytest 会炸所以必须要求 AI 先分析依赖并标记哪些函数需要 mock第二函数文档缺失AI 只能靠读代码来推断预期行为这需要输出“行为假设”供人工确认第三测试代码要符合项目已有的风格而不是漂亮的但无法兼容的模板。我要求这个 SKILL 的输出格式里必须包含一份“行为假设清单”内容是函数名称、输入样例、预期输出、依赖的外部资源、是否需要 mock。人工 review 时只看这份清单就能判断 AI 是否理解了这个函数如果假设都对了测试代码基本八九不离十。3.5 让三台手术协同SKILL 编排的价值单独用上面三个 SKILL 只是“自动化工具”把它们编排起来才是“手术方案”。编排的核心是确定执行顺序先做异常处理迁移再做配置抽离最后生成单元测试。为什么是这个顺序因为异常处理改了代码结构配置抽离改了代码内容如果先做配置抽离再做异常迁移生成的测试文件可能又要重写。在执行层我建了一个很简单的 Agent 工作流一个主控 Agent 读取任务清单按顺序调用每个 SKILL每完成一步就把 diff 摘要发回来人工确认后再进入下一步。这一步最容易联想到 Workflow 的概念但两者有本质区别Workflow 是预定好的固定流程每一步做什么是死板的我这里的主控 Agent 会在每个 SKILL 执行后判断结果质量不符合预期就触发重新生成这就是 Agent 和 Workflow 的配合。实际跑一遍下来三个 SKILL 加上人工确认大概用了一个小时。如果纯人肉做异常梳理和配置抽离至少要半天单元测试更是遥遥无期。4. 常见问题与排查技巧实录4.1 SKILL 描述写得太泛AI 总是找不对这是最常遇到的问题几乎每个团队都会踩一次。表现是你写了一个“代码优化” SKILLAI 什么任务都往里面套日志分析也调它、CRUD 生成也调它、性能优化也调它结果每个任务都做得不伦不类。排查思路很简单回看 description 是不是写得太宽泛。我后来把每个 SKILL 的 description 改成包含“适用场景 触发关键词 不适用场景”三段式。比如异常迁移那个 SKILLdescription 开头就写着“适用于 Python 服务端 try/except 结构迁移触发词包括裸异常、吞异常、异常处理不规范”。模型在意图匹配时命中率高了很多。4.2 AI 发挥过度动了不该动的代码“微创”手术变成大出血这是存量代码 AI 改造最痛的经历。我见过最夸张的一次是 AI 在一个没有测试的老模块里顺手把函数从一个文件挪到另一个文件理由是“这样分层更清晰”。代码本身没写错但 review 的人差点疯了。解决这个问题只能靠两件事SKILL 里的红线声明 输出强制模板。红线声明要具体到文件名、目录、函数签名不要写“不要改变系统架构”这种模棱两可的话。输出强制模板则让 AI 在“动手”前先产出修改计划和风险说明相当于手术前的知情同意书。宁可在 SKILL 里多写几十行约束也不要省事。4.3 存量代码没有测试AI 改完如何验收这是最现实的问题。老项目普遍测试缺失你用 AI 改完代码怎么证明没改坏总不能再手写几百个测试吧。我的经验是把“生成测试”这件事本身作为 SKILL 编排的一环这不是锦上添花是必备环节。实操上我建议先跑“生成单元测试”的 SKILL再跑改造类 SKILL最后再跑一遍全量测试对比结果。如果改造前后测试全部通过说明行为没有偏移。如果改造后测试挂了马上能定位是哪个函数出了变化审查成本极低。这比纯靠代码 review 靠谱得多。4.4 SKILL 和 Agent 混着用编排乱成一团热词天天都在吵 SKILL 和 Agent 有什么区别实际使用中很多人把 SKILL 当成一个 Agent 挂在那边自主执行结果发现它经常跑偏或者和主控 Agent 抢来做决定。我自己摸索出的边界是SKILL 是“按标准流程执行任务的技能包”Agent 是“决定调用哪个技能包、什么时候调、结果不达标怎么办的调度器”。如果一个 SKILL 里写了“根据情况自行决定”这种话那它不是 SKILL是伪装的 Agent。真正稳定的 SKILL 应该是“只要输入满足条件就按固定步骤输出稳定结果”。4.5 避坑清单速查表问题典型表现解决方案描述太泛所有任务都命中一个 SKILLdescription 写“适用场景 触发词 不适用场景”输出不可控AI 不按格式输出review 困难SKILL 里强制规定输出模板越界改动AI 改了无关代码写清文件级 / 语义级红线验收无依据改完只能看两眼先补测试再改代码再跑回归多模型混用两个 Agent 互相推翻明确 Agent 是调度者SKILL 是被调度者最后再分享一个我自己的体会SKILL 编排这件事真正的门槛不是写 SKILL.md 的语法而是你愿不愿意把“AI 改代码”这件事变成一个有边界、有流程、有验收标准的工程行为。第一次写 SKILL 的时候会觉得麻烦约束比代码还多但用几次之后你会发现自己手里攒下了一套可以反复调用的“手术器械包”。以后再遇到类似的老模块不用从头给 AI 做心理建设直接调 SKILL几分钟就能进入状态。团队如果想推广这套玩法建议从一个绿区小模块开始试点跑通之后再慢慢扩大范围别一上来就想给核心系统做全套 AI 手术。