用 Codex 现代化旧代码库

引言

Codex 经过训练，可以阅读并推理大型、复杂的代码库，与工程师一起规划工作，并产出高质量的改动。代码现代化很快成为它最常见、最有价值的用途之一。在这种协作方式中，工程师专注于架构与业务规则，Codex 承担繁重部分：翻译遗留模式、提出安全的重构方案，并让文档与测试随系统演进而保持同步。

本 cookbook 说明如何使用 OpenAI 的 Codex CLI 以如下方式现代化一个遗留仓库：

• 新工程师能够理解
• 架构师与风险团队能够审计
• 可以作为可重复的模式推广到其他系统

我们用一个基于 COBOL 的投资组合系统作为贯穿示例，并选择一条试点流程重点推进。你可以替换成任何遗留技术栈（例如 Java 单体、PL/SQL），只要其中有遗留程序、编排（作业、调度器、脚本）或共享数据源。

高层概览

我们把工作拆成 5 个阶段，围绕一份执行计划（简称 ExecPlan）展开。ExecPlan 是一份设计文档，智能体可以按照它交付系统变更。

原文此处有一张示意图，见原文。

我们会为选定的试点流程创建 4 类文档：

• pilot_execplan.md——统筹试点的 ExecPlan，回答：范围是什么、为什么重要、按什么步骤推进、如何判断完成。
• pilot_overview.md——涉及哪些遗留程序（本例是 COBOL）、编排作业（这里是 JCL）和数据源，数据如何在它们之间流动，以及业务流程实际做了什么。
• pilot_design.md——系统的目标形态：由哪个服务或模块承接这条流程、新的数据模型，以及对外 API 或批处理入口。
• pilot_validation.md——定义如何证明行为一致：关键场景、共享输入数据集、如何并行运行遗留版与现代版，以及“输出一致”在实际操作中意味着什么。

这 4 份文件帮助说明：要改哪些代码、新系统应是什么样、以及如何检查行为没有回退。

阶段 0 - 设置 AGENTS 与 PLANS

目标：给 Codex 一份轻量约定，说明本仓库如何做规划，同时不让人被流程压垮。

我们借鉴 Using PLANS.md for multi-hour problem solving 这篇 cookbook，创建放在 .agent 目录下的 AGENTS.md 与 PLANS.md。

• AGENTS.md：如果仓库里还没有 AGENTS.md，建议先用 /init 生成。生成后，在 AGENTS.md 中加一节，指示智能体参考 PLANS.md。
• PLANS.md：以 cookbook 中提供的示例为起点。

这些文件说明 ExecPlan 是什么、何时创建或更新、放在哪里，以及每份计划必须包含哪些章节。

Codex CLI 能帮什么

如果你希望 Codex 针对具体仓库收紧 AGENTS 或 PLANS，可以运行：

Please read the directory structure and refine .agent/AGENTS.md and .agent/PLANS.md so they are a clear, opinionated standard for how we plan COBOL modernization work here. Keep the ExecPlan skeleton but add one or two concrete examples.

阶段 1 - 选择试点并创建第一份 ExecPlan

目标：对齐一条现实但范围有限的试点流程，并用一份 ExecPlan 记录阶段 1 的计划。

关键产物：pilot_execplan.md

1.1 选择试点流程

如果一时没有想好用什么流程试点，可以让 Codex 提议。下面是从仓库根目录使用的提示词示例：

Look through this repository and propose one or two candidate pilot flows for modernization that are realistic but bounded.
For each candidate, list:
- COBOL programs and copybooks involved
- JCL members involved
- The business scenario in plain language
- End with a clear recommendation for which flow we should use as the first pilot

在这个例子里，我们选择一条报表流程作为试点。

原文此处有一张示意图，见原文。

1.2 让 Codex 创建试点 ExecPlan

Create pilot_execplan.md following .agent/PLANS.md. Scope it to the daily reporting flow. The plan should cover four outcomes for this one flow:
- Inventory and diagrams
- Modernization Technical Report content
- Target design and spec
- Test plan for parity
Use the ExecPlan skeleton and fill it in with concrete references to the actual COBOL and JCL files.

这份计划现在就是所有试点工作的“大本营”。

阶段 2 - 盘点与发现

目标：记录试点流程今天实际做了什么：程序、作业、数据流和业务规则。工程师不必逐行阅读遗留代码，也能理解这次改动。

关键产物：pilot_reporting_overview.md

工程师可以重点关注：

• 确认哪些作业确实在生产环境运行
• 补上 Codex 无法从代码推断的信息（SLA、运行上下文、负责人）
• 复核示意图与描述是否合理

2.1 让 Codex 起草概览

Create or update pilot_reporting_overview.md with two top-level sections: “Inventory for the pilot” and “Modernization Technical Report for the pilot”.
Use pilot_execplan.md to identify the pilot flow.

In the inventory section, include:
1. The COBOL programs and copybooks involved, grouped as batch, online, and utilities if applicable
2. The JCL jobs and steps that call these programs
3. The data sets or tables they read and write
4. A simple text diagram that shows the sequence of jobs and data flows

In the modernization technical report section, describe:
1. The business scenario for this flow in plain language
2. Detailed behavior of each COBOL program in the flow
3. The data model for the key files and tables, including field names and meanings
4. Known technical risks such as date handling, rounding, special error codes, or tricky conditions

这份文档能帮助工程师在不读完所有代码的情况下，理解试点的形态与行为。

pilot_reporting_overview.md 中的流程示意图示例：

原文此处有一张示意图，见原文。

2.2 更新 ExecPlan

概览完成后，让 Codex 保持计划同步：

Update pilot_execplan.md to reflect the new pilot_reporting_overview.md file.
- In Progress, mark the inventory and MTR sections as drafted.
- Add any notable findings to Surprises and discoveries and Decision log.
- Keep the ExecPlan readable for someone new to the repo.

阶段 2 结束时，你会得到一份试点概览文档，同时承担系统盘点报告与现代化技术报告的角色。

阶段 3 - 设计、规格与验证计划

目标

• 决定试点流程的现代版本应该是什么样
• 描述目标服务与数据模型
• 定义如何通过测试与并行运行证明行为一致

到本阶段结束时，我们会明确要构建什么，以及如何证明它可用。

关键产物

• pilot_reporting_design.md
• pilot_reporting_validation.md
• modern/openapi/pilot.yaml
• modern/tests/pilot_parity_test.py

3.1 目标设计文档

Based on pilot_reporting_overview.md, draft pilot_reporting_design.md with these sections:

# Target service design
- Which service or module will own this pilot flow in the modern architecture.
- Whether it will be implemented as a batch job, REST API, event listener, or a combination.
- How it fits into the broader domain model.

# Target data model
- Proposed database tables and columns that replace the current files or DB2 tables.
- Keys, relationships, and any derived fields.
- Notes about how legacy encodings such as packed decimals or EBCDIC fields will be represented.

# API design overview
- The main operations users or systems will call.
- A short description of each endpoint or event.
- A pointer to modern/openapi/pilot.yaml where the full schema will live.

3.2 API 规格

我们把试点流程的对外行为写进 OpenAPI 文件，让现代系统有一份清晰、与语言无关的契约。这份规格会成为实现、测试生成与后续集成的锚点，也让 Codex 有具体依据来搭建代码与测试。

Using pilot_reporting_design.md, draft an OpenAPI file at modern/openapi/pilot.yaml that describes the external API for this pilot. Include:
- Paths and operations for the main endpoints or admin hooks
- Request and response schemas for each operation
- Field types and constraints, aligning with the target data model

示例输出：

原文此处有一张示意图，见原文。

3.3 验证与测试计划

Create or update pilot_reporting_validation.md with three sections:

# Test plan
- Key scenarios, including at least one happy path and a couple of edge cases.
- Inputs and outputs to capture for each scenario.

# Parity and comparison strategy
- How you will run the legacy COBOL flow and the modern implementation on the same input data.
- What outputs will be compared (files, tables, logs).
- How differences will be detected and triaged.

# Test scaffolding
- Notes about the test file modern/tests/pilot_parity_test.py, including how to run it.
- What needs to be filled in once the modern implementation exists.

然后让 Codex 搭建测试骨架：

Using pilot_reporting_validation.md, create an initial test file at modern/tests/pilot_parity_test.py.

Include placeholder assertions and comments that reference the scenarios in the test plan, but do not assume the modern implementation is present yet.

3.4 更新 ExecPlan

Update pilot_execplan.md so that Plan of work, Concrete steps, and Validation and acceptance explicitly reference:
1. pilot_reporting_overview.md
2. pilot_reporting_design.md
3. pilot_reporting_validation.md
4. modern/openapi/pilot.yaml
5. modern/tests/pilot_parity_test.py

阶段 3 结束时，你会有一份清晰的设计、一份机器可读的规格，以及一份说明如何证明行为一致的测试计划与骨架。

阶段 4 - 实现与对比

目标：实现现代版试点，与 COBOL 版本并行运行，并证明在计划场景下输出一致。

关键产物

• modern/<stack>/pilot 下的代码（例如 modern/java/pilot）
• modern/tests/pilot_parity_test.py 中完成的测试
• pilot_reporting_validation.md 中描述实际并行运行步骤的章节

4.1 生成现代代码初稿

Using pilot_reporting_design.md and the COBOL programs listed in pilot_reporting_overview.md, generate initial implementation code under modern/<stack>/pilot that:
- Defines domain models and database entities for the key records and tables.
- Implements the core business logic in service classes, preserving behavior from COBOL paragraphs.
- Adds comments that reference the original COBOL paragraphs and copybooks.
- Treat this as a first draft for engineers to review.

你可以多次运行这一步，每次聚焦不同模块。

4.2 接上一致性测试

Extend modern/tests/pilot_parity_test.py so that it:
- Invokes the legacy pilot flow using whatever wrapper or command we have for COBOL (for example a script that runs the JCL in a test harness).
- Invokes the new implementation through its API or batch entry point.
- Compares the outputs according to the “Parity and comparison strategy” in pilot_reporting_validation.md.

4.3 记录并行运行步骤

不必另写 parallel_run_pilot.md，直接复用验证文档：

Update the Parity and comparison strategy section in pilot_reporting_validation.md so that it includes a clear, ordered list of commands to:
- Prepare or load the input data set
- Run the COBOL pilot flow on that data
- Run the modern pilot flow on the same data
- Compare outputs and interpret the results
- Include precise paths for outputs and a short description of what success looks like

4.4（如需要）用 Codex 迭代修复

当测试失败或行为不一致时，用短循环推进：

Here is a failing test from modern/tests/pilot_parity_test.py and the relevant COBOL and modern code. Explain why the outputs differ and propose the smallest change to the modern implementation that will align it with the COBOL behavior. Show the updated code and any test adjustments.

每完成一块有意义的工作，就让 Codex 更新 ExecPlan：

Update pilot_execplan.md so that Progress, Decision log, and Outcomes reflect the latest code, tests, and validation results for the pilot.

你会看到 ExecPlan 的“进度”和“结果”章节被更新成类似下面的内容：

Progress  
- [x] Inventory and diagrams drafted (`pilot_reporting_overview.md` plus supporting notes in `system-architecture.md`).  
- [x] Modernization technical report drafted (`pilot_reporting_overview.md` MTR section).  
- [x] Target design spec drafted (`pilot_reporting_design.md` and `modern/openapi/pilot.yaml`).  
- [x] Parity test plan and scaffolding documented (`pilot_reporting_validation.md` and `modern/tests/pilot_parity_test.py`).

Outcomes  
- `pilot_reporting_overview.md`, `pilot_reporting_design.md`, and `pilot_reporting_validation.md` now provide an end-to-end narrative (inventory, design, validation).  
- `modern/openapi/pilot.yaml` describes the API surface, and `modern/python/pilot/{models,repositories,services}.py` hold the draft implementation.  
- `modern/tests/pilot_parity_test.py` exercises the parity flow using placeholders and helpers aligned with the validation strategy.  
- Remaining work is limited to updating the operations test appendix and wiring the services to the real runtime.

阶段 5 - 把试点变成可扩展的做法

目标：为其他流程提供可复用模板，并给出一份在本仓库使用 Codex 的简短指南。

关键产物

• template_modernization_execplan.md
• how_to_use_codex_for_cobol_modernization.md

6.1 模板 ExecPlan

Look at the pilot files we created:
1. pilot_reporting_overview.md
2. pilot_reporting_design.md
3. pilot_reporting_validation.md
4. pilot_execplan.md

Create template_modernization_execplan.md that a team can copy when modernizing another flow. It should:
1. Follow .agent/PLANS.md
2. Include placeholders for “Overview”, “Inventory”, “Modernization Technical Report”, “Target design”, and “Validation plan”
3. Assume a similar pattern: overview doc, design doc, validation doc, OpenAPI spec, and tests.

6.2 操作指南

Using the same pilot files, write how_to_use_codex_for_cobol_modernization.md that:
1. Explains the phases at a high level (Pick a pilot, Inventory and discover, Design and spec, Implement and validate, Factory pattern).
2. For each phase, lists where coding agents helps and points to the relevant files and example prompts.

收尾

如果按照本 cookbook 的步骤推进任何试点，你最终会得到大致如下的一组文件：ExecPlan、三份试点文档、一份 OpenAPI 规格、一个试点模块，以及一套一致性测试。你还可以把 Markdown 文件进一步放进 pilot 与 template 子目录，让结构更清楚。

原文此处有一张示意图，见原文。

你会注意到 modern/python/pilot 里还没有可运行的入口，因为 models.py、repositories.py、services.py 只是起步用的初稿模块。如果想在本地试验，有两种选择：

• 使用交互式 shell 或一个小脚本
• 自己写一个 runner（例如 modern/python/pilot/main.py），把 repository 与 service 接起来

虽然本 cookbook 用 COBOL 试点流程作为贯穿示例，同样的模式也适用于非常不同的重构。例如，有客户把数百个 Jira 工单交给 Codex，让它标出高风险工作、暴露横切依赖、起草代码改动，再由独立的校验器审查与合并，从而迁移一个大型 monorepo。

现代化 COBOL 仓库只是常见的案例之一；同样的方法适用于任何遗留技术栈或大规模迁移：把“现代化我们的代码库”拆成一系列小而可测试的步骤（一份 ExecPlan、几份文档、以及以一致性为先的实现）。Codex 承担理解旧模式、生成候选迁移、收紧一致性的苦活，你和团队则专注于架构与取舍，让现代化更快、更安全，并能在每个决定推进的系统上重复。