返回文章列表实践教程

让 AI 改造旧系统:先分清这三种情况,再动代码

用客户导出项目讲清升级环境、替换服务和改变业务规则三种改造。附依赖图、验收案例、Onevium 会话分工和可运行练习,帮助团队把试点推进到上线。

更新于 约 12 分钟Markdown
本页内容8 个章节

“升级一下”里面,藏着两个不同的需求

交给 AI 之前,先定清楚什么必须保留,再选能发现错误的证据,并约好由谁确认可以上线。 这几步决定了拿回来的代码能否用上,也能减少“功能都写完了,大家却说不清对不对”的返工。

团队准备让 AI 重写一个老旧的客户导出服务。开发想让代码好维护些,销售补了一句:“重复客户顺便合并一下,再按编号排序。”财务却只关心一件事:月底能不能照常把这份文件导入自己的系统。

看似一个“升级”任务,验收标准已经分成了两套。换实现,要保留约定好的行为;合并客户,则要主动改变结果。拿同一把尺子检查这两件事,正确的改动也可能被判错。

Anthropic 在 2026 年 9 月 23 日发布的代码现代化文章,重点就在这些准备工作。下面用一个虚构团队的客户导出项目,把升级环境、替换服务、改变业务规则三种情况讲清楚,再给一份能运行的小练习。案例、图解和练习均为独立教学设计,不是一次实际 AI 迁移的成果报告。

先找出这份文件会影响谁

沿着一次导出操作走一遍:销售选择客户,服务检查访问权限,读取客户记录,再生成 CSV。财务拿文件做导入,归档任务留一份供以后对账。重写导出函数只改了其中一块,结果却会经过好几个环节。

虚构客户导出流程:权限检查与客户记录进入导出服务,输出被财务导入和归档使用;三个问题标出容易遗漏的约定。

让负责调查的会话先读调用处、查询、序列化函数,以及能找到的导入规范。每条依赖都带上代码位置、已观察到的行为和待确认的问题。例如:“查询没有明确排序,导出函数保留收到的顺序;财务是否依赖这个顺序?”前两项可以从代码确认,最后一项要找财务负责人问清楚。

这一轮有用的产物,是一张附有疑问的依赖图。团队据此知道先查哪里、找谁确认,再决定兼容性范围。节点画得多不等于调查充分,关键是能解释哪条关系会让这次改造出问题。

原文用一张 CardDemo 系统依赖截图 展示这项调查。这里把图缩到一个导出任务,突出真正决定改造范围的调用方与使用方。

案例一:升级运行环境,导出的文件保持不变

第一个任务可以很窄:把服务升级到团队已经批准的运行时与依赖版本,接口、客户选择和 CSV 规则都不变。原文把这类改造称为 uplift,可以理解为“升级底座”。

拿虚构输入 B02 / Bea、A01 / Ada 做检查。升级后仍应先输出 B02,再输出 A01;表头和末尾换行也要符合原有约定。空选区的结果要保留,没有访问权限的请求仍须在导出前被拒绝。

在 Onevium 中打开现有项目,可以先发这样一个任务:

为客户导出服务制定运行环境升级方案。
先读当前版本、锁文件、CI 配置和已有测试。
目标版本以我们批准的升级需求单为准。
列出不兼容点,以及需要改动的文件。
保持接口、权限、行顺序和 CSV 格式不变。
这次不增加排序和客户合并。
先指出缺少的检查和待确认事项,再进入实现。

方案确认后,在旧环境和目标环境分别跑相关测试,并用允许使用的样本比较导出文件的字节。把环境版本、执行命令和实际输出留在改动记录里。只在开发者原来的环境跑绿,不能证明环境升级成功。

一个容易漏掉的失败: CSV 测试全过了,替换的认证依赖却把正常用户挡在门外。所以依赖图里要有权限链路,验收范围也要覆盖一次完整导出请求。

案例二:换一套实现,核对使用方真正收到的结果

团队接着想把服务换成另一套实现,甚至换一种语言,但使用者看到的行为应该保持一致。原文称之为 transform。旧语言的单元测试未必能直接搬过来,约定好的输入输出仍然可以用。

在测试环境,把同一份允许使用的样本请求分别交给新旧实现。这个导出服务要比较 CSV 字节、HTTP 状态、文件类型和文件名,也要覆盖非法请求与权限失败。如果替换的模块还会写入数据,就再检查新旧程序能否读取彼此写出的格式。

新旧导出实现收到 B02、A01 两条记录;约定结果保留这个顺序,擅自排序的新实现输出 A01、B02,虽然记录一样,检查仍应失败。

图中的排序结果看起来挺合理,却违反了这个例子里明确保留顺序的约定。只检查行数或 HTTP 200 就发现不了。换成 JSON 接口时,也许应该比较关键字段的含义,而非整个响应文本;先围绕使用方依赖什么确定比较方法,需要忽略的差异也要提前写清楚。

可以让 Onevium 中负责验证的会话先做这一步:

根据已确认的导出约定,提出独立的输入和预期结果。
覆盖顺序、空输入、转义、非法数据和权限错误。
还没确定的规则单独列出,不猜答案。
用例确认后,建立可重复运行的新旧结果比较。
不要把调用旧服务当成生成全部正确答案的方法。
不要为了适配新实现而修改预期结果。

旧服务本身也可能有错。两个版本一起算错,单纯比较仍会通过;独立确认的预期值能挡住这种情况。如果准备顺便修一个旧缺陷,就把它记成经过确认的差异,写出新的预期结果,并检查会影响哪些使用方。

案例三:真的要合并客户,就先写出新的正确答案

销售仍然希望文件简单些:“每个客户编号只留一行,姓名用最新记录,再按编号排序。”这已经主动改变了业务行为,属于原文的 reimagine。此时,新旧输出相同不再是成功标准。

先拿具体数据讨论,比反复说“智能去重”有用:

输入记录姓名更新时间(UTC)
B02Bea2026-09-01T09:00:00Z
A01Ada2026-09-01T10:00:00Z
B02Beatrice2026-09-03T09:00:00Z

新规则的预期是 两行:先 A01 / Ada,再 B02 / Beatrice。旧规则则按输入顺序保留三行。把这两份结果放到销售和财务面前,确认后再写代码。财务也许恰好要用旧记录对账,那就应该增加一种导出选项,而不能直接替换它正在使用的文件。

再补三个小例子,没说清楚的规则就会浮出来:同一编号、同一时间却有两个不同姓名;记录缺少时间;最新姓名为空。空值要不要覆盖原来的姓名?这些是待决策的需求,不能让助手自行猜成“合理的边界处理”。

确认后,实现任务就能引用这份有答案的例子表。保留旧导出的检查,给新选项增加测试,再验证用户选回旧模式时仍拿到原来的结果。小范围试用时,也要明确试用人群,观察导入被拒绝和业务结果有异议的情况,不能只看接口调用成功了多少次。

这个案例演示的是需求准备方法。文末下载包里的序列化函数没有实现客户合并,九项检查通过也不能用来验收这条新业务规则。

在 Onevium 里,按问题分工,再交接给下一步

文末的小练习,一个会话就够了。换成真实服务时,依赖调查和独立设计验收用例可以拆开做。分工时看各自要回答什么、何时把结果交出去,别让几个会话一起重写同一个模块。

工作应该交出什么交给谁继续
调查依赖调用方、使用方、代码位置和未确认规则负责人确认行为约定
准备验证输入、预期答案,以及能被检查挡住的错误示例实现者使用已确认的约定
改造一个边界范围明确的差异和实际测试输出审查者检查代码与证据

用输入框的 @ 选入项目文件,把约定和报告保存在大家约好的位置。需要队伍协作时,按 Team 的配置与使用流程选择 @ → Team,确认 team Skill 与 Sessions 工具可用;先由主会话提出分工和依赖,确认后启动成员,后续各阶段也按该流程确认。

调查和用例准备可以并行,负责人同时处理未确定的问题。实现要等规则确认,最终审查要等真实改动完成。共享文件指定一个写入者;发现和结论通过主会话与文件交接。成员不会自动共享全部上下文,工作目录也不会自动隔离。

已有 Git 项目可以用文件、终端与 Review查看约定、运行检查、阅读最终差异。成员汇报“完成”后,审查者仍要核对证据是否对应准备发布的那一版代码。

先把一个小模块走到上线,再扩大范围

客户导出这个试点,即使测试全过,仍有一个实际问题:财务有没有成功导入新文件?还没做就明确写“未验证”。一份有用的审查记录,应该分得清已经观察到的结果和还缺的证据:

试点:替换客户导出实现,保留已确认的行为约定。
代码:本次审查对应的准确版本。
证据:附实际命令、输出和新旧比较结果。
使用方验证:由谁试过导入,结果如何。
未解决差异:还差哪些情况,会影响谁。
发布决定:负责人、试用范围、停止条件。
恢复方法:确认如何切回原服务。

原文区分了 certificate(需要满足的验证条件) 和 promotion policy(进入生产的规则)。放到这个团队里,可以是“兼容性检查通过、财务试导入确认”,再由指定负责人决定开始小范围发布。一次本地测试通过,不能自动替团队做这个决定。

虚构导出试点依次完成本地检查、使用方导入确认、小范围发布和观察;失败回到对应步骤,观察结果符合要求后再扩展。

先跑成本低的构建和单元检查,通过后再做较费时的新旧回放与使用方试导入。这样交给审查者的改动才带着可用证据。原文的验证与发布流程图把两者分得很清楚,也留出了需要人介入处理的路径。

选一个小的服务边界,协调好试点期间谁还会改它,然后走完团队真实的发布流程。记录实现用了多少时间,也记录验证、重试和负责人审查的耗时。用遇到的问题补强下一轮检查,再扩展到其他模块。原文的分批迁移图强调的正是先走通一个试点,再增加工作量。

替换服务时,条件允许就保留旧实现。若新路径写出的数据已经不能被旧版读取,只回退代码也恢复不了服务,需要事先设计数据恢复办法。这里的小型导出案例只读取并导出数据,刻意没有承担这种数据迁移。

动手试一次:让检查挡住一个看起来没错的改动

想先试试新旧比较,可以下载这份可运行练习。里面有一个 CSV 序列化函数、九个固定用例,以及故意写错的替换实现。需要 Node.js 20 或以上;运行练习不用安装包,也不联网。让 AI 协助改代码时,另需可用的模型连接。

解压到新文件夹,在 Onevium 中打开这个已有目录,再从项目创建会话。先自己读 behavior.md 和 cases.json 的预期值。这里的约定是保留顺序与重复编号,明确 CSV 转义和非法行的 TypeError,并且不得改动传入的数据。

node verify.mjs
node verify.mjs --candidate=examples/sorted.mjs
node verify.mjs --candidate=examples/mutates-input.mjs

初始候选只是旧实现的副本,结果应为 9/9 通过、退出码 0。排序示例应为 8/9 通过,input-order 失败,退出码 1。修改输入的示例应为 1/9 通过、退出码 1:每个非空用例的第一条记录都被它改动了,包括抛错的情况。后两项就是要失败,它们能说明为什么只看返回的记录还不够。

接着给会话一个小任务:

先读 behavior.md、legacy.mjs、cases.json 和 verify.mjs。
重构 candidate.mjs,把 CSV 转义提取为有名字的辅助函数。
保留行为约定;只改 candidate.mjs,并新建 review.md。
自己完成一次尝试后再看 examples/。
不改旧代码、预期值和验证器。
运行 node verify.mjs,记录实际输出和未覆盖的情况。
需求与旧行为有冲突时停下来说明。
不提交、不推送、不发布。

自己检查改动文件,再运行一次验证。解压包不是 Git 仓库,README 里有直接比较文件的办法。包内参考实现应通过九项检查;node --test test.mjs 还会检查验证器能否拒绝故意设置的错误。这些是编写好的教学样例,不是 AI 提效实测。

九项检查只覆盖序列化函数,没有验证 HTTP 权限、跨语言迁移、财务软件或生产容量。CSV 转义也防不住电子表格执行公式,面向表格软件导出不可信内容时,需要另定规则。真实试点要使用允许处理、经过适当脱敏的数据,并考虑配置的模型服务商会收到什么。

开始自己的试点时,可以先挑一个必须保留的输出、一个必须继续拒绝的错误,写出预期结果,确认故意写错的候选会失败,再让 AI 改这个边界。任务扩大到整个服务时,就按前面的案例补上使用方和发布证据。