如何用 Codex 做一次可靠的项目重构：方法、节奏和可复用提示词

如何用 Codex 做一次可靠的项目重构：方法、节奏和可复用提示词

很多人第一次让 AI 参与重构时，习惯把需求压缩成一句话：帮我把这个项目重构一下。

这句话当然能启动对话，但很难启动一场可靠的工程协作。因为真正的重构往往不是"把代码换一种写法"，而是在不破坏业务规则的前提下，把旧系统迁入新结构、把历史逻辑接回当前工程、把分散的实现统一成可维护的模式。

这类任务里，AI 最容易出问题的地方不是不会写代码，而是太快开始写代码。它可能会凭文件名猜业务含义，凭模板经验改接口，凭局部页面判断全局规则，最后得到一个"看起来能跑，但关键契约已经变了"的结果。

我更推荐把 Codex 当成一个工程协作者，而不是代码生成器。让它先读、先问、先设计，再分批改、分批验证。这样 AI 的速度才会变成优势，而不是风险放大器。

一、先把任务从"写代码"变成"建立证据链"

项目重构的第一步，不是让 Codex 改文件，而是让它读清楚事实来源。

通常至少有四类信息需要先建立优先级：

• 目标项目：现在要落地的工程结构、技术栈、代码风格、组件模式、测试方式
• 源项目：需要保留的业务逻辑、字段含义、交互流程、权限规则和边界条件
• 接口或数据契约：后端接口、数据结构、错误码、分页方式、鉴权方式
• 参考实现：可以参考的设计或代码组织，但不一定是最终事实

这些来源经常会冲突。目标项目的风格可能更现代，源项目的业务规则却更真实；参考实现可能更好看，但里面也可能带着别的系统假设。没有优先级，Codex 就只能替你做判断。

所以开局最重要的提示词，不是"开始重构"，而是要求它先建立上下文。

请先阅读当前项目、源项目、接口文档和参考资料，整理重构前的上下文。

请重点输出：
1. 当前项目的技术栈、目录结构、通用组件、状态管理、路由和请求封装
2. 源项目中需要保留的业务规则、字段、接口契约、权限逻辑和关键交互
3. 接口文档中影响全局设计的数据结构、鉴权方式、错误处理和分页方式
4. 参考实现中可以复用的部分，以及不能直接照搬的假设
5. 本次重构最容易出错的风险点

在完成这一步之前，不要修改任何文件。

这段提示词的作用，是把 Codex 从"执行者"切换成"调查员"。它需要先证明自己看过上下文，再开始设计方案。

二、给高风险决策设置确认闸门

重构时有些问题不能让 AI 自己拍板，例如：

• 登录和鉴权流程
• 权限模型
• 导航或菜单来源
• 数据分页协议
• 接口错误处理
• 是否允许修改后端字段
• 是否允许引入新依赖
• 是否保留旧业务流程

这些点一旦走错，后面几十个文件都会跟着错。最好的做法是要求 Codex 在这些地方先停下来，给方案，等你确认。

以下内容属于全局契约：登录鉴权、权限模型、导航来源、分页协议、接口错误处理、后端字段是否变更。

遇到这些问题时，请先停止编码，给出 2-3 个可选方案：
- 每个方案的实现方式
- 对前端、后端、数据和历史功能的影响
- 风险和维护成本
- 你的推荐方案和理由

等我确认后，再进入设计文档或代码修改。

这个"确认闸门"非常重要。它不是降低效率，而是防止 AI 在关键位置替你做业务决策。

三、先写设计文档，再写代码

大型重构里，设计文档不是形式主义。它的价值在于把边界固定下来。

一份足够好的重构设计文档，应该回答这些问题：

• 当前项目保留什么
• 源项目保留什么
• 哪些规则以接口文档为准
• 参考项目只能参考什么
• 全局适配层有哪些
• 第一阶段先做什么
• 哪些功能暂不处理
• 每一批怎么验证

可以这样要求 Codex：

请根据已确认的方案写一份重构设计文档。

文档需要覆盖：
1. 重构目标和非目标
2. 信息来源优先级
3. 总体架构和迁移边界
4. 登录鉴权、权限模型、导航来源、分页协议、接口错误处理等全局设计
5. 页面或模块迁移原则
6. 参考实现的复用边界
7. 风险清单和验证方式
8. 分阶段实施建议

请先只写设计文档，不修改业务代码。写完后自查是否存在占位内容、前后矛盾、未决问题或范围漂移。

设计文档通过后，再让 Codex 写实施计划。

设计文档已确认。请写第一阶段实施计划。

要求：
1. 把任务拆成可以独立验证的小批次
2. 每个批次说明要修改的范围、预期结果和验证方式
3. 优先建立全局适配层，再迁移业务页面或功能模块
4. 不要一次性迁移所有页面
5. 每批改完都要说明已验证项、未验证项和剩余风险

这一步能让重构从"大而散"变成"小而稳"。

四、先做地基，再搬业务

很多项目重构失败，是因为一开始就搬页面或模块。页面越搬越多，才发现请求协议不一致、权限判断不一致、数据结构不一致、路由规则不一致。

更稳的顺序是先做地基：

1. 请求封装和错误处理
2. 登录与鉴权状态
3. 权限与导航适配
4. 分页或列表数据协议
5. 通用弹窗、详情、表格、表单等组件模式
6. 一个低风险页面或模块作为样板

提示词可以这样写：

请先完成重构地基，不要急着迁移所有业务模块。

第一批只处理：
1. 请求封装和错误处理适配
2. 登录鉴权状态接入
3. 权限与导航数据适配
4. 分页或列表协议适配
5. 一个低风险页面作为样板

要求：
- 保持当前项目的代码风格和组件模式
- 不改变已确认的业务契约
- 不顺手重构无关代码
- 每完成一个小批次都运行项目已有检查
- 汇报时说明修改范围、验证结果和剩余风险

这类提示词能让 Codex 把"基础设施"和"业务迁移"分开处理，减少返工。

五、迁移模块时，要求它同时对齐三件事

每迁移一个模块，都要同时看三条线：

• 视觉和交互：向目标项目靠拢
• 字段和业务：向源项目靠拢
• 接口和数据：向接口契约靠拢

只对齐其中一条都不够。页面长得像新系统，但业务字段错了，不行；字段对了，但交互风格像旧系统，也不行；接口能调通，但权限和状态没对齐，还是不行。

可以给 Codex 这样的模块迁移提示词：

请迁移 [模块名称] 到当前项目。

迁移要求：
1. 先阅读当前项目中相似模块的实现方式，复用已有组件、状态管理、请求封装和样式规则
2. 再阅读源项目中该模块的页面、字段、操作、权限判断和边界逻辑
3. 以接口文档或数据契约确认请求参数、返回结构、错误处理和分页方式
4. 页面体验向当前项目靠拢，业务规则向源项目靠拢，数据契约向接口文档靠拢
5. 不引入未经确认的新依赖
6. 不修改无关模块
7. 完成后运行项目已有检查，并给出差异核对结果

如果模块比较复杂，可以再加一句：

如果发现当前项目模式、源项目逻辑和接口文档之间存在冲突，请先停下来说明冲突，不要自行选择。

这句话能避免 AI 用一个"看起来合理"的实现覆盖真实业务规则。

六、用户反馈要变成下一轮约束

使用 Codex 重构时，用户的反馈不是打断，而是校准。

比如你发现：

• 某个按钮位置不符合原业务习惯
• 某个流程不能简化
• 某个参考实现不能照搬
• 某个字段必须保留
• 某个接口规则不能改
• 某个入口需要保持历史行为

不要只说"这里不对"，最好把反馈变成新的约束。

请按下面约束修正上一轮实现：

1. [具体行为] 必须与源项目保持一致
2. [某个参考实现中的假设] 不适用于当前项目，不要采用
3. [某个入口或流程] 需要保留历史行为
4. 本轮只修这些问题，不扩大修改范围

请先重新阅读相关当前实现和源项目实现，再修改。修完后说明哪些地方已经对齐，哪些地方仍需要真实环境验证。

这种写法能让 Codex 把反馈沉淀进当前任务，而不是只做表面修补。

七、差异审查比"我完成了"更重要

大型重构最怕一句"完成了"。真正有价值的是差异审查。

你可以要求 Codex 在迁移后做一轮审查：

请按源项目对当前重构结果做差异审查，先不要修改代码。

审查范围：
1. 列表字段和查询条件
2. 新增、编辑、删除、审核、提交等操作流程
3. 详情页或详情弹窗
4. 权限判断和按钮显示
5. 数据刷新逻辑
6. 接口参数和返回数据使用
7. 错误处理和空状态
8. 与当前项目通用组件模式的一致性

输出格式：
1. 确认存在的差异：说明当前表现、源项目表现、影响范围和建议修复方式
2. 已核对且未发现明显差异的部分
3. 不确定或需要我确认的部分

请只基于文件、接口文档或运行结果下结论。推断内容必须标注为推断。

这段提示词能逼 Codex 用证据说话。它会从"完成感"回到"可验证状态"。

八、验证要分层，不只看构建通过

构建通过只能证明代码能编译，不能证明业务对齐。

比较完整的验证应该包括：

• 静态检查：格式、lint、类型检查
• 构建检查：项目能否打包
• 路由或入口检查：用户能否进入对应页面
• 数据契约检查：请求参数和响应解析是否符合接口文档
• 业务差异检查：是否保留源项目关键规则
• 浏览器检查：关键页面是否渲染正常
• 工作区检查：是否混入无关改动

可以这样提示：

请对本轮重构做分层验证。

至少检查：
1. 项目已有的 lint、类型检查或格式检查
2. 项目构建
3. 本轮涉及入口或页面是否可达
4. 请求参数、响应解析、分页和错误处理是否符合接口契约
5. 与源项目关键业务规则的差异
6. 是否存在无关文件改动

最后按三类汇报：
- 已完成并验证
- 已完成但只能静态验证
- 未验证或需要真实环境验证

这比单纯要求"跑一下 build"可靠得多。

九、把经验沉淀成项目规则

如果一个项目会长期维护，重构结束后不要只留下代码，还要留下规则。

这些规则可以是项目文档、开发约定，也可以是 Codex 可读取的本地技能或提示词模板。内容可以包括：

• 当前项目的通用组件使用方式
• 请求、分页、权限、导航的约定
• 常见业务模块的页面结构
• 审查清单
• 验证命令
• 不能照搬的历史假设
• 常见坑和处理方式

提示词可以这样写：

请把本次重构经验沉淀成当前项目的维护规则。

要求：
1. 只基于当前项目已经确认的实现总结
2. 不包含敏感路径、真实接口、账号、域名或业务私密信息
3. 覆盖页面开发、接口适配、权限导航、验证流程和差异审查
4. 写成后续 Codex 或开发者可以直接阅读执行的规则
5. 增加一份自查清单，避免后续修改偏离当前项目模式

这一步能把一次性的协作经验变成下一次的起点。

十、一套可以直接复用的完整提示词

下面这段可以作为任何项目重构的起始提示词。把方括号里的内容换成你的项目名称、路径或说明即可。

我要使用 Codex 协助完成一次项目重构。

项目关系：
- 当前项目：[目标项目说明]，这是最终要落地的工程
- 源项目或旧实现：[源项目说明]，这是业务规则和历史行为的重要来源
- 接口或数据契约：[接口文档、数据结构、协议说明]
- 参考资料：[参考项目、设计稿、历史文档等，可选]

总体目标：
- 保留当前项目的技术栈、工程风格、目录组织、通用组件和验证方式
- 保留源项目中已经确认的业务规则、字段含义、权限逻辑和关键交互
- 以接口或数据契约为准处理请求参数、响应结构、错误处理、分页和鉴权
- 参考资料只能作为参考，不能覆盖已确认的业务契约

工作方式：
1. 先读取当前项目、源项目、接口或数据契约、参考资料，整理上下文和风险，不要先改代码
2. 对登录鉴权、权限模型、导航来源、分页协议、错误处理、后端字段是否变更等全局问题，先给方案并等我确认
3. 方案确认后，先写重构设计文档，再写分阶段实施计划
4. 先建立全局适配层，再迁移具体模块
5. 每次只做一个可验证的小批次，不要一次性大范围改动
6. 每批改完后运行项目已有检查，并做业务差异核对
7. 汇报时说明改动范围、证据来源、验证结果、未验证风险和是否存在无关改动

约束：
- 不要凭经验猜业务规则
- 不要把参考资料中的假设直接带入当前项目
- 不要顺手重构无关代码
- 不要暴露敏感路径、真实接口、账号、域名或私有业务数据
- 如果当前项目、源项目和接口契约之间有冲突，先说明冲突并等待确认

十一、几个高频场景提示词

1. 上下文摸底

请先做重构前上下文摸底，不改文件。

请输出：
1. 当前项目的技术栈、目录结构、关键依赖和通用开发模式
2. 源项目中需要保留的业务模块、关键流程和边界逻辑
3. 接口或数据契约中影响全局设计的规则
4. 参考资料中可复用和不可直接复用的部分
5. 本次重构的主要风险和需要我确认的问题

2. 方案确认

请只分析 [全局问题名称] 的方案，不改代码。

请给出 2-3 个方案，并分别说明：
1. 实现方式
2. 改造范围
3. 对历史业务的影响
4. 对后续维护的影响
5. 风险
6. 推荐方案

等我确认后再继续。

3. 分批实施

请按已确认的设计进行本批次实现。

本批次目标：[写清楚本批次目标]

要求：
1. 先阅读相关当前实现、源实现和接口契约
2. 只修改本批次必要文件
3. 遵循当前项目已有模式
4. 保留已确认的业务契约
5. 改完后运行项目已有检查
6. 汇报修改内容、验证结果和剩余风险

4. 模块迁移

请迁移 [模块名称]。

要求：
1. UI、交互和代码组织遵循当前项目模式
2. 字段、业务流程和权限规则对齐源项目
3. 请求参数、响应解析和错误处理对齐接口契约
4. 如果发现三者冲突，先停止并说明冲突
5. 不引入未经确认的新依赖
6. 不修改无关模块
7. 完成后做差异核对和项目检查

5. 差异审查

请对 [模块名称或本轮改动] 做差异审查，先不要改代码。

请核对：
1. 页面展示
2. 查询条件
3. 表单字段
4. 操作按钮
5. 权限判断
6. 详情展示
7. 数据刷新
8. 接口参数和响应使用
9. 错误处理

请输出确认差异、已核对无明显差异的部分、需要我确认的部分。

6. 定点修复

请只修复以下确认差异：

1. [差异一]
2. [差异二]

要求：
1. 先阅读当前实现和源实现
2. 只改相关文件
3. 不扩大修改范围
4. 保持当前项目风格
5. 修完后运行必要检查
6. 汇报时区分本轮改动和已有无关改动

7. 验证收口

请对本轮改动做收口验证。

请检查：
1. 项目已有 lint、类型检查、测试或构建命令
2. 本轮涉及页面或入口是否可达
3. 数据契约是否对齐
4. 关键业务规则是否对齐
5. 是否存在无关文件改动

最后输出：
- 已验证通过
- 未能验证及原因
- 剩余风险
- 建议下一步

十二、结语

Codex 参与重构时，真正决定结果质量的不是某一句神奇提示词，而是整个协作节奏。

先读证据，再确认方案；先做地基，再搬业务；先小批量修改，再分层验证；先做差异审查，再宣布完成。

当你用这种方式使用 Codex，它就不只是"帮你写代码"的工具，而会变成一个能参与工程判断、执行迁移、发现差异、沉淀规则的协作者。

这才是 AI 在真实项目重构里最值得使用的地方。