使用 Codex 处理大型项目时，最让开发者紧张的情况之一，不是它不会修改代码，而是一下改得太多。

一个看似普通的需求：

把旧的用户权限逻辑统一重构一下。

执行结束后，Git 里可能突然出现：

• 28个文件被修改；

• 6个公共类型发生变化；

• 3个模块被移动；

• 新增多个工具函数；

• 测试文件大量调整；

• package.json和锁文件也发生变化。

代码可能可以运行，但此时已经很难回答一个关键问题：

这些修改真的全部必要吗？

对于大型仓库，Codex最重要的能力不是“一次修改更多文件”，而是能够在明确边界内完成可审查、可测试、可回滚的变更。

这时可以给每个任务设置一个“变更预算”。

一、什么是变更预算？

变更预算可以理解为：在任务开始前，先限定本轮最多允许产生多大的改动。

例如：

本轮变更预算：

最多修改：5个文件
最多新增：2个文件
禁止删除：任何现有文件
禁止新增：第三方依赖
禁止修改：数据库结构

它不是绝对的技术限制，而是一种工程约束。

目的很简单：

当Codex发现任务需要超过预算时，先停止扩张，重新解释原因。

例如可以直接写：

当前任务最多允许修改5个文件。

如果你判断必须超过5个文件，
先停止修改并输出：

1. 为什么当前预算不够；
2. 额外需要修改哪些文件；
3. 每个文件的必要性；
4. 是否可以拆成下一阶段。

这样就不会出现一个小问题演变成全项目重构。

二、为什么大型重构最容易失控？

大型项目中的代码通常存在大量隐式关系。

例如修改：

User

可能继续影响：

UserService
UserController
UserRepository
UserDTO
UserPermissions
UserStore
UserPage
UserTests

Codex发现这些关联后，很容易继续向外扩展。

然后又发现：

UserPermissions

被订单、后台和报表模块引用。

任务范围就可能从：

用户模块

逐渐变成：

用户
+
权限
+
订单
+
后台
+
报表
+
公共类型

从局部逻辑看，每一步都有理由。

但从项目管理角度看，这已经不是原来的任务。

所以大型重构一定要区分：

必要修改

和

顺便可以优化的修改

两者不能混在一轮中。

三、第一轮只做“变更地图”

面对复杂任务，不要直接让Codex开始重构。

第一轮只让它生成变更地图：

当前目标：
统一用户权限判断。

暂时不要修改代码。

请输出：

1. 直接相关文件；
2. 间接受影响文件；
3. 公共模块；
4. 风险最高的文件；
5. 可以暂时不修改的内容。

结果可能是：

直接相关：
- src/auth/permission.ts
- src/store/user.ts
- src/router/guard.ts

间接影响：
- src/pages/admin/*
- src/components/PermissionButton.tsx

暂不修改：
- order
- report
- database

然后人为确认：

本轮只处理前三个直接相关文件。

这比让 Codex 自己决定完整重构范围安全得多。

四、给文件划分三个等级

可以把文件分成三类。

A类：本轮必须修改

不修改就无法完成当前任务。

例如：

permission.ts
router.ts
userStore.ts

B类：可能受到影响

需要验证，但不一定修改。

例如：

AdminPage.tsx
PermissionButton.tsx

C类：禁止扩展

即使发现潜在问题，本轮也不处理。

例如：

order/
report/
database/

任务提示可以写成：

A类文件允许修改。

B类文件只检查，不主动修改。

C类目录禁止修改。

如果B类确实必须调整，
请先说明原因。

这样可以把Codex的行为从“自由重构”变成“受控变更”。

五、一个大重构拆成多个可验证阶段

假设要把旧权限系统替换成新的权限模型。

不要一次完成：

旧权限删除
+
新权限实现
+
所有页面迁移
+
测试更新

可以拆成四轮。

第一阶段：建立新能力

增加新权限函数，但暂时不删除旧逻辑。

目标是：

新代码可以运行
旧代码不受影响

第二阶段：迁移一个调用方

例如只迁移后台管理页面。

验证：

• 新权限结果正确；

• 旧页面不受影响；

• 测试通过。

第三阶段：逐步迁移其他调用方

每次只处理一个模块。

第四阶段：删除旧实现

只有确认所有引用都迁移完成后，再清理旧代码。

这种方式虽然提交次数更多，但每一步都可以单独回滚。

六、每一阶段都设置检查点

Codex完成一阶段后，不要直接进入下一步。

先生成检查点：

阶段1完成情况：

修改文件：
3个

新增文件：
1个

测试：
全部通过

旧接口：
仍然保留

公共行为：
未改变

下一阶段：
迁移admin模块

然后执行：

git diff --stat
git diff

确认差异符合预期，再创建提交：

git add .
git commit -m "refactor: introduce new permission evaluator"

这个提交就是一个安全检查点。

如果第二阶段失败，可以回到这里继续，而不是重新处理整个重构。

七、限制单次Git Diff规模

除了文件数量，还可以限制代码行数。

例如：

单轮目标：
Git Diff尽量控制在300行以内。

当然，这不是严格标准。

但如果一个小功能突然出现：

+1800
-1200

就应该重新检查：

• 是否发生全局格式化；

• 是否移动了大量代码；

• 是否重复生成类型；

• 是否修改了任务无关文件；

• 是否应该拆成多个提交。

Diff越大，人工审查发现问题的概率通常越低。

尤其不要把：

重构
+
格式化
+
依赖升级

放进同一次修改。

八、公共类型修改必须单独计算预算

例如修改：

interface User {
  id: number;
  name: string;
}

增加：

permissions: string[];

看起来只增加一行。

但这个类型可能被几十个模块引用。

因此，公共类型的“实际变更成本”不能只按一行代码计算。

可以建立规则：

修改公共类型前：

1. 搜索所有引用；
2. 统计受影响模块；
3. 判断是否属于破坏性变化；
4. 优先新增可选字段；
5. 单独建立提交。

例如：

permissions?: string[];

可能比直接改成强制字段更容易逐步迁移。

九、不要让Codex一次性“清理所有旧代码”

AI很容易发现：

这个函数已经不用了
那个接口可以删除
这个文件可以合并

但大型项目中存在：

• 动态导入；

• 配置引用；

• CLI入口；

• 测试夹具；

• 外部系统调用；

• 旧版本兼容逻辑。

所以“搜索不到直接引用”并不一定等于“可以安全删除”。

删除文件前，可以要求：

不要直接删除。

先检查：

1. 静态引用；
2. 动态引用；
3. 配置文件；
4. 测试；
5. 构建脚本；
6. 外部入口。

确认后只输出删除候选清单。

删除操作最好单独作为一个阶段。

十、为重构建立“禁止顺手优化”规则

这是非常实用的一条规则：

当前任务只解决既定目标。

发现以下内容时只记录，不修改：

- 命名不统一；
- 格式问题；
- 性能优化机会；
- 无关重复代码；
- 其他潜在Bug。

可以让 Codex 输出：

额外发现：

1. order模块存在重复查询
2. report模块类型定义重复
3. utils中存在旧函数

本轮处理：
全部不修改

这些问题可以进入后续任务。

这样能避免一次重构无限扩张。

十一、让Codex在执行前重新确认预算

修改前最后增加一道检查：

当前批准预算：

允许修改：
4个文件

允许新增：
1个文件

禁止：
新增依赖
删除文件
修改数据库
修改公共API

请先确认你的修改计划是否符合预算。

如果不符合，不要开始执行。

这一步看似重复，但大型项目中非常有价值。

因为分析阶段和真正实现阶段，Codex可能发现新的依赖关系。

再次确认可以防止任务悄悄扩大。

十二、自动测试也要遵循变更范围

如果本轮只修改：

auth
router
store

第一轮测试应该优先执行：

auth tests
router tests
store tests

然后再运行完整测试：

npm run test
npm run type-check
npm run build

如果修改公共模块，则需要额外验证所有引用方。

变更预算不仅约束修改，也帮助决定测试预算。

修改范围越大，需要运行的回归验证就越多。

十三、把“变更预算”写进AGENTS.md

长期项目可以增加：

# Codex变更预算

- 一个任务只解决一个核心目标
- 默认单轮最多修改5个文件
- 超出范围必须先解释原因
- 公共类型修改需要单独评估引用
- 不进行无关全局格式化
- 不顺手修改其他潜在问题
- 删除文件必须先输出引用检查
- 大型重构必须拆成多个阶段
- 每阶段完成后生成任务摘要
- 每阶段必须建立可回滚检查点

对于大型仓库，这类规则比单纯写“不要乱改代码”有效得多。

十四、一个完整的大型重构流程

推荐采用：

确定目标
↓
生成变更地图
↓
划分A/B/C文件
↓
设置变更预算
↓
执行第一阶段
↓
检查Git Diff
↓
运行测试
↓
创建Git检查点
↓
进入下一阶段
↓
最终全量回归

整个过程中，每次修改都应该回答：

为什么改？
必须现在改吗？
影响谁？
能否单独回滚？

只要其中一个问题回答不清楚，就不应该继续扩大范围。

十五、Plus还是Pro？

如果日常任务主要是：

• 3—5个文件的小型重构；

• 单模块Bug修复；

• 中小型项目；

• 每轮修改范围明确；

Plus通常已经可以很好地完成这类工作。

如果长期需要：

• 完整仓库重构；

• 一次涉及多个模块；

• 需要连续多轮分析和验证；

• 大量Git Diff审查；

• 多阶段测试；

• 多项目并行开发；

可以根据实际任务连续性评估Pro。

Pro更适合高强度长任务，但不代表应该提高单次修改范围。

实际上，大型项目即使拥有更充足的使用空间，也更应该限制每轮变更预算。

总结

Codex一次修改几十个文件，真正的问题不是“文件数量太多”，而是开发者失去了对修改边界的控制。

通过变更地图、A/B/C文件分类、单轮预算、阶段化重构、Git检查点和禁止顺手优化，可以把一个巨大重构拆成多个可理解、可验证和可回滚的小任务。

真正可靠的AI重构，不是一次把整个项目改完，而是每一步都清楚知道：

当前改了什么、为什么要改、影响哪些地方，以及如果结果不对应该回到哪里。

CSDN文章描述

本文介绍Codex进行大型项目重构时的“变更预算”方法，通过文件范围限制、分阶段修改、Git Diff检查、检查点和AGENTS.md规则，避免AI一次修改过多文件导致代码审查和回滚困难。