代码现代化从几年缩到几周，瓶颈从写代码转向组织配合

在我们的“一线手记”（Notes from the Field）系列中，Anthropic 的前向部署工程师（forward deployed engineer，指深入客户现场落地 AI 解决方案的工程师）分享了来自真实客户部署的最佳实践。本文介绍我们管理大型代码现代化项目的经验。

过去需要以“年”为单位、全员投入的代码现代化，现在可以在几个月（甚至几周）内完成，但前后端的组织工作往往没有改变。例如，对关键银行系统的任何更改都必须经过变更管理、评审和批准。这是一个稳健的流程，因为监管机构、审计人员和业务方都需要它。正是这些流程让关键系统变得可信——它们的前提是：每个变更都由人类编写，每个 diff 都有人类评审。一旦智能体（agent）加速了变更的编写，瓶颈就从“产出变更”转移到了“调动整个组织来配合这些变更”。

本文介绍企业在现代化开始前必须完成的工作：定义“完成”意味着什么、每个变更需要携带哪些证据、经过认证的变更如何进入生产环境，以及要启动运行需要先准备什么。我们把这个过程拆解为六步：

- 定义目标：现代化后的代码必须具备的技术栈和行为。
- 创建证书：变更在被视为“目标状态下正确”时必须满足的条件。
- 设定推广策略：经认证的变更以其产生速度进入生产环境的路径。
- 落实前置条件：环境、CI/CD、评审容量和审批。
- 构建并完善智能体工作流：自定义 Claude Code 动态工作流，将现代化工作分散到许多并行子智能体工作流中，由它们产出变更。这个工作流围绕目标、证书和推广策略构建。
- 运行现代化：在代码库的一小部分上端到端验证工作流，然后扩展规模。

第1步：定义目标

目标（target）是现代化的最终状态。期望的最终状态决定了你正在做三种现代化中的哪一种，如下表所示。

确定现代化类型

在一个组织内部，究竟选择哪种现代化类型往往会引发讨论。根据我们的经验，最贴近生产环境的人希望换掉栈、保持行为不变，从而控制风险（transform 现代化）。另一侧通常是长期与代码库打交道的工程师，他们希望通过现代化来偿还技术债务；还有业务干系人，希望借机提出新的需求（reimagine 现代化）。两种立场都有道理，但如果这个问题悬而未决，它会在日后重新浮现为“某个变更是否算正确”的争论。在走哪条路上达成共识虽然会带来一些前期摩擦，但能让整个项目更顺畅。

映射代码库并创建行为规格说明

理解现有系统通常是定义目标的第一步。提取旧代码实际做了什么，并建立当前行为的清单，可以让你轻松决定哪些部分应该修改或删除，从而判断现代化是 transform 还是 reimagine。这也常常暴露出未知的业务逻辑和边界情况。

Claude 可以做大量这类探索，比如映射依赖关系、记录没人记得是谁构建的工作流。代码现代化插件（code modernization plugin）的 assess、map 和 extract-rules 命令可以挖掘业务规则，并附上源代码引用，供工程师审查。

然而，仅靠 Claude 的探索可能无法完全捕获遗留系统的行为。与业务用户和开发者的访谈、内部文档可以填补这些空白。上下文收集前期可能耗时，但其质量会影响工作流后续的每一个决策。

对于 reimagine，定义目标需要额外的工作：应该写下一份详细的行为规格说明，并与用户群体达成一致。

确立项目理由与目标

在定义目标的同时，组织还应该思考为什么值得进行这次现代化。现代化遗留系统可以降低持续的维护和运营成本，但根据我们的经验，成本降低并不是大多数现代化项目的主要驱动力。

风险降低往往是最重要的现代化收益。在讨论是否要开展项目时，要考虑“不现代化”的风险。例如，一个带有未修补漏洞的系统，可能导致网络攻击或严重宕机，甚至危及业务本身。不受支持的运行时或懂该系统的人越来越少，都会加剧风险。

像 Claude Code 这样的智能体编程工具缩短了现代化周期，但预算仍然难以估算，这导致了惰性。我们已经发布了一些大规模现代化的成本（其他人也发布了），可以作为粗略基线；本指南底部还有更多关于预算估算的建议。启动这类项目的主要挑战通常是建立内部共识，并让拥有系统的团队和依赖系统的团队做出承诺。在领导层层面构建商业论证并设定项目目标，可以让这部分流程更容易。这也有助于在接下来的证书（certificate）和推广策略（promotion policy）中锚定权衡取舍。当干系人对一个变更能承担多大风险意见不一致时，“不现代化”的风险就是另一个砝码。

第2步：定义证书

证书（certificate）是一组条件或测试，每个现代化变更都必须满足。选择那些能提供最强累积证据的条件，以证明变更相对目标是正确的。

每个条件都应该可以在没有人工参与的情况下检查，这样智能体工作流可以在一个变更上反复迭代，直到满足证书；如果无法满足，则标记为需要人工审查。

证书的内容取决于目标，但通常来自以下清单：

- 原始测试套件通过。
- 现代化过程中由 Claude 编写的测试全部通过。
- 测试覆盖率达到约定阈值。
- 性能基准保持在约定范围内。
- Claude 独立进行的对抗性审查（每次都在全新的上下文窗口中）没有发现阻塞性问题。
- 对于用户界面，Claude 驱动的计算机使用（computer use）没有发现回归。
- 当前版本和目标版本对相同输入产生相同输出（可以是实时、录制或 Claude 生成的输入）。
- 持久化状态和线格式（wire format）在当前版本与目标版本之间可以往返（round-trip）。
- 变更在预发布环境运行约定的时间，错误率、延迟或告警没有回归。
- 静态分析和安全扫描没有新增问题。
- 对于编译型目标，构建干净且类型检查通过。

证书要与那些负责审查和把变更推入生产环境的人一起编写。在证书和智能体工作流还在设计时，就把依赖当前代码库的开发者、用户群体和业务负责人请进来。他们的专业知识塑造了证书的衡量内容，而他们的早期参与是后续变更进入审查时获得他们认可的关键。对已完成证书的一个良好检验是：他们是否愿意仅凭证书中的证据就进行合并。如果他们在其中看到了自己的标准，第3步的推广策略就可以更轻量。

证书衡量什么、如何衡量，取决于现代化类型。

对于 uplift 现代化，对等性（parity）是相对于原始代码库的，原始测试套件可以成为证书的核心。

对于 transform 现代化，对等性同样是相对于原始代码库，但原始测试套件很少能在新栈上运行。此时主要依靠回放生产流量、新旧系统之间的差异测试（differential testing），以及平行部署到生产环境（prod-parallel deployment）。

对于 reimagine 现代化，证书锚定在行为规格说明中。这是最难的情况。规格说明不如现有系统客观，因此需要更大程度的模型判断，这可能导致更多变的结果。此时证书依赖从规格说明编写的测试、Claude 对每个变更对照规格说明进行的独立对抗性审查，以及检查新系统是否保留旧系统行为的差异检查。随着规格说明被澄清，你会预期修改证书：规格说明中的缺口往往首先在这里暴露。

旧系统通常测试覆盖薄弱、测试不稳定、遥测很少。定义证书的一部分就是识别这些缺口。如果很难支撑一个强证书，这一步最有用的做法之一是直接用 Claude 来构建缺失的证据，无论是建立 prod-parallel 环境、构建回放工具，还是编写更多测试。

第3步：设置推广策略

智能体会以远超任何人类团队逐 diff 审查的速度产出变更。推广策略（promotion policy）是一个提前写入并达成一致的分级审查路径，它设定了变更的人工审查深度，使现代化能在可接受的时间线上完成。

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

- 按爆炸半径（blast radius）和智能体置信度对变更进行分级。如果组织有自己的变更或风险分类，就使用它。对关键路径保留完整人工审查。
- 从源头修复反复出现的标记。持续汇总和分析被标记的变更。当同一种标记反复出现时，在智能体工作流或证书中修复原因，而不是逐个审查。
- 与审查者一起设计输出格式。就哪些信息和格式能让审查最快，以及哪些信号比其他信号更能给与信心，达成一致。让审查者在第5步中审查早期样例输出。
- 有效分配 SME 时间。SME（主题专家）不会读每一个最终 diff，但他们的判断仍然是最稀缺的输入。让他们能够直接进入最高风险分级中的变更，以及其中被标记的智能体决策，而不必费力浏览大型 diff。这样少量专家时间就能覆盖风险最高的变更。

这些规则中有许多是把 SME 时间前置，在项目早期就引入他们的参与。他们的反馈会在全面现代化开始之前调优证书和智能体工作流。他们对样例的签字也会成为“在高置信度区域采用更轻量审查路径”的进一步理由。这与传统的非智能体模式相反——传统模式中审查发生在最后。

推广策略还应反映现代化在“速度 vs 审查深度”光谱上的位置。一个为了硬性截止日期（比如运行时失去支持）而冲刺的现代化，需要更快的策略、更轻的人工审查，并明确约定每个变更接受更多风险。而时间线更长的现代化可以承受更深的人工审查和更慢的切换。干系人会根据自身的风险偏好和约束落在光谱的不同位置，因此在工作开始前锁定这一策略是值得的。

在受监管环境中，对任何变更采用更轻的人工审查路径都会带来实实在在的不适。单独的审批人因为承担着坏变更的风险而不敢签字，而领导层则承担着系统老化的更大风险。根据我们的经验，最好让推广策略的指令来自组织最高层。提前达成一致也很重要，这样一旦有 bug 进入生产环境，责任是共同承担的，而不是归咎于某个批准变更的人。

所有这些仍然依赖于一份足够详细的证书作为真实证据，也依赖于审查者对 Claude 如何得出某个变更的理解足够深，从而能够信任它。

第4步：把前置条件落实到位

这一步的很大一部分要经过现代化之外的团队：平台或基础设施团队负责主机，QA 或发布工程团队负责测试容量，安全和合规团队负责审批。这些团队通常都有自己的积压工作或审批流程，所以要尽早开启对话——一旦你确定了需求，通常在第1步到第3步仍在进行时就要开始。

环境

- 一个专用的远程主机，用于运行工作流，代码库和其他相关源可以被 Claude 访问。
- 证书所要求的测试容量。
- 任何能强化证书的东西：生产遥测、prod-parallel 环境，或用于回放的生产数据。

代码库与 CI/CD

- 基于构建和编译日志、导入分析或运行时追踪得到的代码库依赖关系图。注意：插件的 map 命令是一个很好的起点，但根据代码库的大小和历史，可能还需要进行更广泛的前期工作。
- 针对任何依赖或包的既定处理方案，作为目标定义的一部分。
- 如果需要，准备好在 CI/CD 中增加兼容性检查。
- 如果你是在原地进行现代化，一个各方同意的代码冻结（code freeze）策略。
- 面向活跃开发者的沟通计划，涵盖代码冻结和新的兼容性要求。

团队与审查

- 依赖该代码库的其他团队对如何参与的协议，比如签署证书或按推广策略审查，并预留出审查者时间。

安全与合规

- 审批通过的、供 Claude Code 访问源代码的模型访问路径。
- 智能体工作流的最小权限：只写现代化分支，不持有生产凭据。
- 现代化分支中的密钥和 PII 已清理或脱敏。
- 每个变更都可追溯，PR 关联到智能体转录和证书证据。
- 对新依赖的许可证和漏洞检查。

第5步：构建并完善智能体工作流

使用 Claude Code 为代码库现代化开发一个定制的动态工作流。我们建议从代码现代化插件开始，并把工作流可能需要的一切放到文件系统或 MCP 中，让 Claude 可以访问。这包括目标、证书、推广策略、代码库、文档，以及证书所需的任何数据源或工具。你也可以把本文作为上下文提供给 Claude。这就构成了项目的中央知识库。

有了这些基础，构建现代化工作流就很容易了。让 SME 按需审查 Claude 的工作，包括任何代码库特定的技能或提取出的规则，避免下游依赖尚未审查的内容。

通过将工作流应用于代码库的小块来完善它，让 SME 审查它产生的变更、智能体的过程，以及满足证书的证据。当出现问题时，你应该修改工作流本身，而不是修改单个变更。目标是建立信心：一旦扩展到全量，变更几乎处处都能满足证书，审查者也会乐意按推广策略进行合并。

第6步：运行现代化

首先，在代码库的一小部分上端到端完成现代化，包括通过推广策略进行审查和落地变更。在仍然廉价的阶段修复任何有问题的地方，重复这个过程直到你有信心，然后扩展到整个代码库。

transform 和 reimagine 现代化是在现有系统旁边构建目标系统，完成后切换；而 uplift 有第二种选择：在活跃的代码库上原地现代化，同时开发继续。当系统不能停机，或者代码库变化太快以至于难以保持一个独立的现代化副本同步时，通常选择原地现代化。这种情况下行之有效的做法是：把代码库从叶子向根部切成逻辑分区；一次冻结并现代化一个分区；在 CI/CD 中设置门禁，确保一旦某个分区现代化后，新的提交就不能再撤销它。

关于成本

我们经常被问到这样的现代化会花费多少 token。每次现代化各不相同，但主要成本驱动因素包括：

- 代码库中有多少是只读的，多少需要修改。
- 证书的复杂程度（在受监管环境中，验证通常比编写变更占更大份额）。
- 证书要求多少新的测试编写和测试修复。
- 在运行期间，其他团队围绕你合并带来的对账（reconciliation）工作量。

在代码库的一小部分上完成现代化时，测量 token 用量，并用它推算整个运行的用量。把试点无法看到的因素（例如活跃代码库上的对账）视为未知数。这样你可以得到全量现代化成本下限的估计。

试点的测量结果也会显示在哪里优化智能体工作流以降低成本。找到工作流中消耗 token 最多的部分，思考如何提高效率。把计算密集的验证信号移到更便宜的门后面，这样它们只在较简单的检查通过后才运行。

考虑在证书完全检查的机械化、高工作量工作中使用像 Sonnet 这样在成本与能力之间取得平衡的模型。把更智能的模型留给困难转换和验证正确性的对抗性审查。你也可以在较便宜的模型无法满足证书时升级到更昂贵的模型，但在试点时要仔细分析重试率，因为几次便宜的尝试可能比一次昂贵的尝试更贵。如果你让 Claude 同时访问工作流和试点数据，它可以和你一起完成大部分分析。

现代化之后

现代化的代码库只是一个产出。其他产出还包括：生成它的工作流、一份写明“什么是正确”的证书、你的变更管理流程已经接受的推广策略，以及每个落地变更的证据痕迹。把这份行动手册（playbook）编码为可复用资产，让模式在下次升级或重写时已经就位。