AI 驱动的代码现代化：项目启动前的六步准备法

在 Anthropic「现场笔记」系列中，前线部署工程师会分享来自真实客户部署的最佳实践。本文总结了他们管理大型代码现代化项目的经验。

过去，代码现代化常被规划成持续数年、全员投入的大工程；如今，它可以在几个月甚至几周内完成。但项目两端的组织性工作往往没有变化。

例如，银行核心系统的每一次变更都必须经过变更管理、审查和审批。正是这些流程让关键系统变得可信，而它们建立在两个假设之上：每一次修改由人编写，每一个差异由人审查。当智能体开始大幅加速代码修改后，瓶颈就从“生产变更”转向“调动组织接住这些变更”。

本文将讨论企业在现代化正式开始前必须完成的工作：定义什么叫“完成”、一次变更必须携带哪些证据、经过认证的变更如何进入生产，以及必须提前准备什么，项目才能真正启动。

整个过程分为六步：

1. 定义目标：明确现代化后的代码应具备的技术栈和行为。
2. 制定证书：确定变更在目标状态下必须满足哪些条件才算正确。
3. 制定晋升策略：规定已认证变更如何按照产出速度进入生产。
4. 准备前置条件：环境、CI/CD、评审能力和审批流程。
5. 构建并打磨智能体工作流：用自定义的 Claude Code 动态工作流，把现代化任务拆成大量并行运行的子智能体工作流。它以目标、证书和晋升策略为核心。
6. 运行现代化：先在代码库的一小部分上端到端验证工作流，再扩大规模。

第一步：定义目标

目标是现代化完成后要达到的终态。期望的终态决定了项目属于以下三种现代化中的哪一种。

确定现代化类型

类型	含义	适用场景	目标内容
升级式	同一技术栈内的版本升级，例如从 C++11 升到 C++20。	技术栈本身没有问题，但版本已经落后：运行时停止支持、安全问题未修补，或依赖项无法继续升级。	运行时版本和依赖包集合。
转换式	跨技术栈重写，同时保持行为不变，例如从 COBOL 转到 Java。	问题出在技术栈，而现有行为值得信任。	升级式所需的全部内容，再加上新代码必须遵循的语言、框架和架构约定。
重塑式	在新架构上从零重建，并修改系统行为。	行为也需要随代码一起改变。	转换式所需的全部内容，再加上书面化的新系统行为规格。

一个组织内部经常会争论应该选择哪一类现代化。根据 Anthropic 的经验，最接近生产环境的人通常希望只更换技术栈、保持行为不变，以控制风险，也就是转换式现代化；另一边的工程师长期维护这套代码库，希望借现代化偿还技术债，而业务相关方则希望趁机提出新需求，也就是重塑式现代化。

两种立场都合理。但如果这个问题没有被解决，它之后会反复变成“这次修改究竟是否正确”的争论。就选择哪条路径达成共识会增加前期摩擦，却能让整个项目更加顺畅。

绘制代码库并建立行为规格

理解现有系统通常是定义目标的第一步。提取旧代码实际做了什么、盘点当前行为，可以更容易判断哪些部分应修改或删除，从而决定项目属于转换式还是重塑式。这项工作也常常会暴露此前无人知晓的业务逻辑和边缘情况。

Claude 可以完成其中大量发现工作，例如绘制依赖关系，并为那些已经没人记得如何构建的工作流补充文档。代码现代化插件的 assess、map 和 extract-rules 命令会挖掘业务规则，并附带可供工程师核查的源码引用。

不过，仅靠 Claude 的发现不一定能完整还原遗留系统的真实行为。与业务用户和开发者访谈，以及查阅内部文档，可以填补这些空白。前期收集上下文可能需要一些时间，但上下文质量会影响工作流后续做出的每一个决定。

如果采用重塑式现代化，定义目标还需要额外工作：必须写下详细的行为规格，并与用户群体达成一致。

明确项目价值和目标

除了定义目标，组织还应思考为什么这项现代化值得做。现代化遗留系统可以降低持续维护和运营成本；不过根据 Anthropic 的经验，降低成本并不是多数现代化项目的主要驱动力。

降低风险往往是现代化最重要的收益。在讨论是否启动项目时，应同时考虑“不做现代化”会带来什么风险。

例如，一个存在未修补漏洞的系统可能导致网络入侵，或造成足以危及企业本身的严重宕机。运行时不再受支持，或理解系统的工程师越来越少，也会进一步放大风险。

Claude Code 这类智能体编码工具缩短了现代化的周期，但预算仍然难以估算，进而导致组织犹豫不决。Anthropic 已经公布过一些大型现代化的成本，LG CNS 等企业也发布过类似数据。这些信息可以作为粗略基准。

启动这类项目的主要挑战，通常是让系统的所属团队和依赖团队形成内部共识并作出承诺。由领导层推动商业论证、设定项目目标，可以让这一阶段更顺利，也为后续证书和晋升策略中的风险权衡提供依据。当利益相关方对“一次变更能承担多少风险”意见不一致时，“不做现代化的风险”就是必要的制衡。

第二步：制定证书

证书是每一次现代化变更都必须满足的一组条件或测试。应选择那些能够累积形成最强证据、证明变更符合目标的检查项。

每项条件都应无需人工介入即可检查，这样智能体工作流就能持续修改代码，直到满足证书要求；如果始终无法满足，也可以标记出来交给人工审查。

证书包含哪些内容取决于目标，但通常会从以下清单中选取：

• 原有测试套件全部通过。
• 现代化过程中由 Claude 编写的测试全部通过。
• 测试覆盖率超过约定阈值。
• 性能基准保持在约定范围内。
• 由 Claude 在全新上下文窗口中进行的独立对抗性审查没有发现阻塞性问题。
• 如果涉及用户界面，由 Claude 驱动的计算机操作没有发现回归。
• 当前版本和目标版本对同一输入产生相同输出，输入可以是实时数据、录制数据或 Claude 生成的数据。
• 持久化状态和通信格式可以在当前版本与目标版本之间完成往返转换。
• 变更在预发布环境中运行约定时间后，错误率、延迟或告警均无回归。
• 静态分析和安全扫描没有发现新问题。
• 如果目标语言需要编译，构建必须干净且类型检查通过。

证书必须与负责审查和批准生产变更的人共同制定。在证书和智能体工作流仍在设计时，就让依赖这套代码库的开发者、用户群体和业务负责人参与进来。

他们的专业判断会决定证书衡量什么，而早期参与也会让变更进入审查时更容易获得认同。检验证书是否合格的一个好方法，是看这些审查者是否愿意仅凭证书证据就批准合并。如果他们能在证书中看到自己认可的标准，第三步制定的晋升策略就可以更轻量。

证书以什么为参照、如何验证，取决于现代化类型。

• 升级式现代化：以原始代码库为行为基准，原有测试套件可以成为证书的核心。
• 转换式现代化：同样以原始代码库为基准，但原测试套件通常无法在新栈上运行。此时主要依靠生产流量回放、新旧系统差分测试，以及生产并行部署。
• 重塑式现代化：证书以行为规格为锚点，也是难度最高的情况。规格不像现有系统那样可以直接对比，需要更多模型判断，因此结果波动也更大。证书主要依赖根据规格编写的测试、由 Claude 对照规格进行的独立对抗性审查，以及在保留旧行为部分开展的新旧差分检查。随着规格逐渐清晰，要预期证书也会被修订：规格中的空白会最先在这里暴露。

老旧系统往往测试覆盖不足、测试不稳定，且缺少遥测数据。定义证书的一部分工作，就是识别这些缺口。如果现有条件下很难支撑一份强有力的证书，这个阶段最有效的工作之一，就是让 Claude 补齐证据，例如搭建生产并行环境、构建回放工具，或补充更多测试。

第三步：制定晋升策略

智能体产出变更的速度，会远远快于任何人工团队逐行审查差异的速度。晋升策略是一条分层审查路径——必须提前写清并达成一致——它规定不同变更需要多深的人工审查，使现代化能够在可接受的时间内完成。

与证书一样，这一步要和审查者共同完成，并尽可能嵌入组织现有的变更管理流程。具体细节会因组织及其风险权衡而不同，但有几条规则普遍适用：

• 按影响范围和智能体置信度分层。如果组织已有变更或风险分级方法，就直接沿用。关键路径仍必须进行完整人工审查。
• 从源头修复反复出现的问题。持续汇总和分析被标记的变更。如果同一类标记反复出现，应在智能体工作流或证书中修复根因，而不是逐条重复审查。
• 与审查者共同设计输出格式。商定哪些信息和格式能让审查最快完成，以及哪些信号比其他信号更能建立信心。让审查者在第五步检查早期样例输出。
• 高效分配领域专家时间。领域专家不会阅读每一个最终差异，但他们的判断仍是最稀缺的输入。应让他们能直接查看风险最高的变更，以及这些变更中被智能体标记的决策，而不必在大量差异中翻找。这样只需少量专家时间，就能覆盖风险最高的变更。

这些规则中有很多都把领域专家的工作前置。他们在项目早期给出的反馈，可以在全面现代化开始前调整证书和智能体工作流。

他们对样例的签字确认，也会成为高置信度场景下采用更轻量审查路径的依据。这与传统的非智能体模式正好相反：传统模式往往在最后才进行审查。

晋升策略还应反映现代化在“速度”和“审查深度”之间所处的位置。如果项目正在追赶硬性截止日期，例如某个运行时即将停止支持，就需要更快的策略、更轻量的人工审查，并明确同意每次变更承担更多风险。

如果时间线更长，就可以承受更深入的人工审查和更慢的切换。利益相关方会根据自身风险偏好和约束，在这条光谱上选择不同位置，因此应在工作开始前把选择固定下来。

在受监管环境中，让任何变更走轻量人工审查都可能引发明显不安。单个审批人担心为一次错误变更承担责任，因此不愿签字；领导层则承担着系统持续老化的更大风险。

根据 Anthropic 的经验，晋升策略最好由组织最高层下达。同时，提前达成一致也更有利，这样当问题进入生产时，责任由各方共同承担，而不是全部压在最后批准变更的人身上。

所有这些仍然依赖一份足够详细、能够作为真实证据的证书，也依赖审查者理解 Claude 是如何得到某项变更的，并因此能够信任它。

第四步：准备前置条件

这一步中的大量工作要由现代化团队之外的部门完成：平台或基础设施团队负责主机，QA 或发布工程团队负责测试能力，安全与合规团队负责审批。每个团队通常都有自己的需求队列或审批流程，因此一旦明确了需求，就应尽早启动沟通，往往是在第一步到第三步仍在进行时。

环境

• 一台专用远程主机，用于运行工作流，并让 Claude 能够访问代码库和其他相关来源。
• 证书所要求的测试能力。
• 任何能强化证书的资源：生产遥测、生产并行环境，或用于回放的生产数据。

代码库与 CI/CD

• 一份基于构建/编译日志、导入分析或运行时追踪的代码库依赖图。插件中的 map 命令是很好的起点，但规模更大或更老的代码库可能需要更充分的前期工作。
• 作为目标定义的一部分，规划如何处理依赖项和软件包。
• 如有需要，准备好加入 CI/CD 的兼容性检查。
• 如果采用原地现代化，需要商定代码冻结策略。
• 面向活跃开发者的沟通计划，覆盖代码冻结和新的兼容性要求。

团队与审查

• 与依赖该代码库的其他团队达成一致，明确他们如何参与，例如签署证书或在晋升策略下进行审查，并预留评审时间。

安全与合规

• 为 Claude Code 提供经过批准、可用于源代码的模型访问路径。
• 智能体工作流遵循最小权限原则：只能写入现代化分支，不能持有生产凭据。
• 从现代化分支中清除或遮蔽密钥与个人身份信息。
• 每次变更都可追踪，每个 PR 都关联智能体运行记录和证书证据。
• 对新依赖项进行许可证和漏洞检查。

第五步：构建并打磨智能体工作流

使用 Claude Code 为代码库开发一套定制化的动态工作流。

建议从代码现代化插件开始，并把工作流可能需要的一切放到文件系统或 MCP 后面，让 Claude 能够访问，包括目标、证书、晋升策略、代码库、文档，以及证书需要的任何数据源或工具。这篇文章本身也可以作为上下文交给 Claude。它们共同构成项目的中央知识库。

有了这些基础，构建现代化工作流反而是最容易的部分。必要时让领域专家审查 Claude 的工作，包括任何针对特定代码库的技能或提取出的规则，再让下游流程依赖它们。

把工作流应用到代码库的一小部分来持续打磨。领域专家应审查它产出的变更、智能体的执行过程，以及证书得到满足的证据。

问题出现时，应修改工作流，而不是逐条修改变更。目标是建立信心：扩大规模后，变更几乎在任何地方都能满足证书，而审查者也愿意按照晋升策略合并它们。

第六步：运行现代化

首先，在代码库的一小部分上端到端完成现代化，包括通过晋升策略进行审查并落地变更。趁修复成本还低，解决所有不可用的问题，反复执行这一过程，直到建立信心，再扩展到整个代码库。

转换式和重塑式现代化会把目标系统与现有系统并行构建，完成后一次性切换。升级式现代化还有第二种选择：在开发继续进行的活代码库上原地现代化。

当系统无法停机，或代码库变化太快、很难让单独的现代化副本持续同步时，通常就会选择这种方式。实践有效的做法是：从叶子节点开始，把代码库拆成逻辑分区；一次冻结并现代化一个分区；同时在 CI/CD 中设置门禁，防止新提交撤销已经完成现代化的分区。

关于成本

经常有人问，这样一次现代化会消耗多少 token。每个项目都不同，主要成本驱动因素包括：

• 代码库中有多少内容需要读取，有多少需要修改。
• 证书的复杂程度。在受监管环境中，验证通常比编写变更占更大成本。
• 证书要求新增和修复多少测试。
• 运行期间其他团队持续合并代码，带来多少协调与冲突处理工作。

在代码库的一小部分上完成现代化时，测量 token 用量，并据此推算整个运行过程。试点看不到的因素，例如活代码库上的协调成本，应作为未知量处理。这样可以估算完整现代化的成本下限。

试点测量还能指出工作流中哪些环节值得为成本优化。找出消耗 token 最多的部分，并考虑如何提高效率。把计算量较大的验证信号放到更便宜的门禁之后，只有在简单检查通过后才执行。

对于证书能够充分检查的机械性、大批量工作，可以考虑使用 Sonnet 这类兼顾成本与能力的模型。把更强的模型留给困难转换和验证正确性的对抗性审查。

如果较便宜的模型无法满足证书，也可以升级到更昂贵的模型，但在试点期间要仔细分析重试率。多次便宜尝试的成本可能高于一次昂贵尝试。如果让 Claude 同时访问工作流和试点数据，它可以帮助完成大量此类分析。

现代化之外

现代化后的代码库只是产出之一。其他产出还包括：生成这些变更的工作流、书面化的“何为正确”证书、已被变更管理流程接受的晋升策略，以及每次落地变更的证据链。应把这套方法固化为可复用资产，让下一次升级或重写可以直接复用已有模式。

延伸资源

• Claude Code 公开代码现代化插件
• AI 原生软件开发生命周期手册
• 代码现代化手册
• 用 AI 推进 COBOL 现代化：突破成本障碍

原文来源：How to prepare for AI-driven code modernization projects，Anthropic 发布于 2026 年 9 月 23 日。