内容
在我们的《实地笔记》系列中，Anthropic 派驻的工程师分享源自真实客户部署的最佳实践。本文将分享我们在大型代码现代化项目中的管理经验。
曾经需要耗时数年、全员参与才能完成的代码现代化项目，如今可以在几个月（甚至几周）内完成，但项目前后的组织工作往往并无改变。
例如，对关键银行系统的每一次变更都必须经过变更管理、审查和审批。这是一个严谨的流程，因为监管机构、审计人员和业务方都需要它。
这些流程是保障关键系统可信度的基石，它们建立在这样的假设之上：每项变更由人编写，每份差异由人审查。一旦 Agent 加速了变更的编写工作，瓶颈就从产出变更转移到围绕变更动员整个组织。
本文涵盖的是现代化实施前企业必须完成的工作：明确“完成”的定义、变更必须携带的证据、经过认证的变更如何进入生产环境，以及需要做哪些准备工作才能启动运行。
我们将这一流程分解为六个步骤：
- 定义目标： 现代化代码必须具备的技术栈和行为。
- 制定认证标准： 变更必须满足的条件，才能被视为在目标状态下正确。
- 设定晋升策略： 经过认证的变更以其产生的速度进入生产环境的路径。
- 落实前置条件： 环境、CI/CD、审查能力及审批流程。
- 构建并优化 Agent 工作流： 定制化的 Claude Code 动态工作流，将现代化工作分布到多个并行的小型子 Agent 工作流中以产出变更。这一工作流围绕目标、认证标准和晋升策略构建。
- 执行现代化： 先在小部分代码库上端到端验证工作流，然后扩大规模。
步骤 1：定义目标
目标是现代化的最终状态。期望的最终状态决定了你要进行的三种现代化类型，如下表所示。
确定现代化类型
| 升级（Uplift） | 同技术栈版本升级（如 C++11 → C++20）。 | 技术栈本身没问题，但版本已落后：生命周期终止的运行时、未修补的安全问题、无法继续升级的依赖项。 | 运行时版本和软件包集。 |
|---|---|---|---|
| 转型（Transform） | 保持行为不变的跨技术栈重写（如 COBOL → Java）。 | 技术栈是需要解决的问题，而行为本身是可信的。 | 升级所需的一切，外加新代码必须遵循的语言、框架和架构规范。 |
| 重构（Reimagine） | 在新架构上重新构建，可能修改行为。 | 代码和行为都需要改变。 | 转型所需的一切，外加新系统的书面行为规范。 |
确定进行哪种类型的现代化往往是组织内部争论的焦点。根据我们的经验，最贴近生产环境的人希望在不改变行为的前提下更换技术栈以控制风险（转型现代化）。而另一方通常是长期维护代码库的工程师，他们希望现代化能够偿还技术债务，还有其他业务相关方希望借此机会提出新的需求（重构现代化）。
两种立场都有其合理性，但如果问题悬而未决，它会在后期以“某项变更是否正确”的争论形式再次浮现。就选择哪条路径达成共识会增加初始摩擦，但能简化整个项目。
梳理代码库并创建行为规范
了解现有系统往往是定义目标的好第一步。提取旧代码的实际功能并创建当前行为的清单，可以轻松决定哪些部分应该修改或丢弃，从而判断现代化是转型还是重构。这一过程还常常揭示未知的业务逻辑和边界情况。
Claude 可以完成大部分这项发现工作，包括映射依赖关系并记录没有人记得构建的工作流。代码现代化插件的 assess、map 和 extract-rules 命令可以挖掘带有源代码引用的业务规则，供工程师后续审查。
然而，Claude 的自动发现可能无法完全捕捉遗留系统的行为方式。与业务用户和开发人员的访谈以及内部文档可以填补这些空白。上下文收集可能需要一些前期时间，但这些上下文的质量将影响工作流后续做出的每一个决策。
对于重构，定义目标需要额外的工作：应该编写详细的行为规范并与用户组达成一致。
代码现代化插件的交互式依赖图示例。
确立项目的正当性和目标
除了定义目标外，组织还应考虑为什么要进行这项现代化改造。现代化遗留系统可以降低持续的维护和运营成本，然而根据我们的经验，成本降低并非大多数现代化项目的主要驱动力。
降低风险通常是现代化最重要的收益。在讨论是否进行项目时，请考虑不进行现代化的风险。
例如，携带未修补漏洞的系统可能意味着网络攻击或严重故障，甚至危及企业自身。支持的运行时版本停止维护或了解该系统的工程师越来越少，都会加剧这种风险。
像 Claude Code 这样的 Agent 编码工具已经缩短了现代化时间表，但预算仍然难以估算，这导致了惯性。我们已经公布了一些大规模现代化的成本，其他企业也是如此。这些可以作为粗略的基准，我们在指南末尾还提供了预算预测的额外指导。
启动这些项目的主要挑战通常是建立内部共识并获得系统所有方和依赖方的承诺。构建业务案例并设定项目目标（通常在领导层）可以使这一部分工作更加顺畅。这也有助于锚定后续认证标准和晋升策略中的权衡。当相关方对变更可以承受多少风险存在分歧时，不进行现代化的风险就是平衡的砝码。
步骤 2：定义认证标准
认证标准是每项现代化变更必须满足的一组条件或测试。选择能给变更正确性提供最强累积证据的条件。
每个条件都应该能够在没有人工介入的情况下进行检查，这样 Agent 工作流就可以对变更进行迭代，直到满足认证标准，或者在无法满足时标记给人工审查。
认证标准包含什么取决于目标，但通常会从以下列表中选取：
- 原始测试套件通过
- 现代化过程中由 Claude 编写的测试全部通过
- 测试覆盖率满足约定的阈值
- 性能基准保持在约定的范围内
- 由 Claude 在全新的上下文窗口中进行独立的对抗性审查，未发现阻断性问题
- 对于用户界面，由 Claude 驱动的计算机操作未发现回归
- 当前版本和目标版本从相同输入产生相同输出，可以是实时数据、录制数据或由 Claude 生成的数据
- 持久化状态和有线格式在当前版本和目标版本之间可以往返
- 变更在预发环境运行约定的时段，错误率、延迟或告警无回归
- 静态分析和安全扫描未发现新问题
- 对于编译目标，构建干净且类型检查通过
与将审查和晋升变更进入生产环境的人员共同编写认证标准。 在认证标准和 Agent 工作流仍在设计阶段时，就邀请依赖代码库的开发者、用户组和业务负责人参与。
他们的专业知识决定了认证标准衡量什么，而他们的早期参与是在变更到达审查阶段时获得他们认可的关键。一个检验最终认证标准是否良好的标准是：他们是否仅凭认证标准的证据就愿意合并代码。如果他们能在认证标准中看到自己设置的门槛，步骤 3 中的晋升策略就可以更宽松。
认证标准检查什么以及如何检查，取决于现代化类型。
- 对于升级现代化，对比基准是原始代码库，原始测试套件可以作为认证标准的核心。
- 对于转型现代化，对比基准同样是原始代码库，但原始测试套件很少能在新栈上运行。生产流量回放、新旧差异测试以及与生产并行部署可以承担大部分验证工作。
- 对于重构现代化，认证标准以行为规范为基础。这是最困难的情况。规范不如现有系统那样有客观的差异对象，因此涉及更大程度的模型判断，可能导致更多变的结果。在这种情况下，认证标准依赖从规范编写的测试、由 Claude 进行的独立对抗性审查（检查每项变更是否符合规范），以及差异检查（新系统保持旧系统的行为）。预期随着规范的明确化需要修订认证标准：规范中的缺口会首先在这里显现。
旧系统通常测试覆盖薄弱、测试不稳定、遥测数据不足。定义认证标准的部分工作就是识别这些缺口。如果难以支持强有力的认证标准，在这一步骤中最有用的事情之一就是使用 Claude 来构建缺失的证据，无论是搭建生产并行环境、构建回放工具，还是编写更多测试。
步骤 3：设定晋升策略
Agent 产出变更的速度将远远快于任何人工团队逐个差异地进行审查。晋升策略是一套分层审查路径——预先书面化并达成一致——它为每项变更设定人工审查的深度，以便现代化项目能够在可接受的时间范围内完成。
与认证标准一样，请与审查人员共同完成这一步骤，并尽可能将其融入组织现有的变更管理流程。细节会因组织及其面临的风险权衡而异，但有几条规则放之四海而皆准：
- 按影响范围和 Agent 置信度对变更进行分级。 使用组织自身的变更或风险分类（如果有的话）。对关键路径保持完整的人工审查。
- 从源头修复反复出现的问题。 对标记的变更进行分组和分析。当同类型的标记反复出现时，修复 Agent 工作流或认证标准中的原因，而不是逐个审查每个问题。
- 与审查人员共同设计输出格式。 就哪些信息和格式能使审查最快、以及哪些信号比其他信号更能增强信心达成一致。在步骤 5 中让他们审查早期样本输出。
- 有效分配 SME 时间。 SME 不会阅读每个最终差异，但他们判断仍然是稀缺资源。让他们能够直接关注最高风险等级的变更，以及每个等级中被标记的 Agent 决策，而无需在大堆差异中跋涉。少量专家时间就能覆盖风险最高的变更。
许多这些规则通过在项目早期就让 SME 参与来前置 SME 的工作时间。他们的反馈在全面现代化开始之前就调整了认证标准和 Agent 工作流。
他们对样本的签字确认也进一步证明了高置信度区域可以采用更轻量的审查路径。这与传统非 Agent 模式相反——传统模式下审查发生在最后。
变更从生成到生产的路径。
晋升策略还应反映现代化在速度和审查深度之间的位置。处于硬性截止日期压力下的现代化（如某个运行时即将失去支持）需要更快的策略和更轻量的人工审查，并明确同意每项变更承受更多风险。
时间线较长的现代化可以负担更深入的的人工审查和更缓慢的切换。相关方会根据自身的风险偏好和约束落在这一频谱的不同点上，因此在工作开始前锁定它是值得的。
在监管环境中，为任何变更采用更轻量的人工审查路径都可能引起真正的担忧。个别审批人员会因为承担坏变更的风险而犹豫，而领导层则承担着系统老化的更大风险。
根据我们的经验，晋升策略的指令最好来自组织高层。最好事先达成一致，这样生产环境中出现问题的责任是分担的，而不是落在批准变更的人身上。
所有这些仍然依赖于足够详细的认证标准以作为真实证据，以及对 Claude 如何得出变更有足够理解的审查人员，以便信任它。
步骤 4：落实前置条件
这一步骤的大部分工作需要通过现代化团队以外的团队来完成：平台或基础设施团队负责主机，QA 或发布工程团队负责测试能力，安全和合规团队负责审批。这些团队通常都有自己的待办事项或审批流程，因此要尽早开启对话，一旦确定了需求就立即开始，通常还在步骤 1 到 3 进行期间。
环境
- 用于运行工作流的专用远程主机，Claude 可以访问代码库和其他相关资源
- 认证标准要求的测试能力
- 任何能增强认证标准的东西：生产遥测、生产并行设置或用于回放的生产数据
代码库和 CI/CD
- 代码库的依赖图，基于构建和编译日志、导入分析或运行时追踪。注意：插件的 map 命令是一个很好的起点，但根据代码库的规模和年代，可能需要做更广泛的前期工作
- 作为目标定义的一部分，规划任何依赖项或软件包的处理方式
- 如有需要，准备好在 CI/CD 中添加兼容性检查
- 如在原地进行现代化，需要约定代码冻结策略
- 针对活跃开发者的沟通计划，涵盖任何代码冻结和新兼容性要求
团队和审查
- 依赖代码库的其他团队同意参与方式，如签署认证标准或在晋升策略下进行审查，并预留审查时间
安全和合规
- 批准用于源代码的 Claude Code 模型访问路径
- Agent 工作流的最小权限访问：仅写入现代化分支，不使用生产凭据
- 从现代化分支中清除或屏蔽密钥和 PII
- 每项变更可追溯，PR 关联 Agent 记录和认证标准证据
- 新依赖项的许可和漏洞检查
步骤 5：构建并优化 Agent 工作流
使用 Claude Code 为代码库的现代化开发定制的动态工作流。
我们建议从代码现代化插件开始，并将工作流可能需要的一切放在文件系统或通过 MCP 访问，让 Claude 能够获取。这包括目标、认证标准、晋升策略、代码库、文档，以及认证标准所需的任何数据源或工具。你也可以将本文作为上下文提供给 Claude。这就构成了项目的中央知识库。
在此基础上，构建现代化工作流是比较容易的部分。根据需要让 SME 审查 Claude 的工作，包括任何代码库特定的技能或提取的规则，确保下游不会依赖未经审查的内容。
通过将构建好的工作流应用到代码库的小部分来进行优化，由 SME 审查它产生的变更、Agent 的过程以及认证标准满足的证据。
当问题暴露时，应该修改工作流，而不是修改每个变更。目标是建立信心：在扩大规模后，变更几乎在任何地方都能满足认证标准，审查人员也愿意在晋升策略下合并代码。
步骤 6：执行现代化
首先，在代码库的一小部分上完成端到端的现代化，包括通过晋升策略审查并落地变更。趁成本还低时修复任何不工作的部分，重复这一过程直到有信心，然后扩大到整个代码库。
虽然转型和重构现代化涉及在现有系统旁边构建目标系统并在完成后切换，但升级有一条额外路径：在活跃代码库上原地现代化，同时继续开发。
当系统不能宕机，或者代码库变更非常频繁导致难以保持独立的现代化副本同步时，这通常是首选方案。在这种情况下，我们看到有效的方法是从叶子节点向内将代码库划分为逻辑分区；逐个冻结并现代化一个分区；并在 CI/CD 中设置门控，使得新提交无法撤销已现代化的分区。
关于成本的说明
我们经常被问到这样的现代化需要多少 token 成本。每个现代化工作都不尽相同，但主要成本驱动因素包括：
- 代码库需要读取与需要修改的比例；
- 认证标准的复杂程度（在监管环境中，验证而非编写变更通常占更大份额）；
- 认证标准要求的新测试编写和测试修复量；以及
- 运行期间其他团队合并代码带来的协调工作量。
在代码库的一小部分上完成现代化时，测量 token 使用量并用它来推算其余部分的运行成本。将试点阶段看不到的东西（如在活跃代码库上的协调）视为未知。这样你就能获得完整现代化的成本下限估算。
试点的测量还显示了在成本方面优化 Agent 工作流的方向。找出工作流中消耗最多 token 的部分，并考虑如何提高它们的效率。将计算密集型的验证信号放在更便宜的关卡后面，这样它们只有在更容易的检查通过后才会运行。
考虑使用 Sonnet 这样在成本和能力之间取得平衡的模型进行认证标准完全检查的机械性、高容量工作。将更智能的模型保留用于困难的转换和验证正确性的对抗性审查。
你也可以在较便宜的模型无法满足认证标准时升级到更昂贵的模型，但在试点时要仔细分析重试率，因为多次便宜的尝试可能比一次昂贵的尝试花费更多。如果你让 Claude 同时访问工作流和试点数据，它可以帮你完成大部分这类分析。
超越现代化
现代化后的代码库是一个产出。其他产出包括产出它的工作流、关于什么算正确的书面认证标准、变更管理流程已经接受的晋升策略，以及每项落地的变更的证据链。将操作手册编纂为可重用资产，这样下次升级或重写时模式已经就位。
我们的派驻工程师与客户一起完成这些步骤，应对客户最关键的系统。如果你正在准备一项现代化，请联系我们的团队。