大型代码库如何使用 Codex：上下文、范围与任务拆分

大型代码库的难点不是文件数量本身，而是依赖关系、隐含约束和验证成本。把整个仓库一次性交给 Codex 并要求“全部优化”，通常会得到范围模糊、难以验证的结果。更可靠的方法是先建立地图，再逐步扩大修改范围。

## 先建立仓库地图

让 Codex 只读分析以下信息：主要模块、启动入口、构建系统、测试目录、数据库迁移位置和部署脚本。要求它给出依据，例如具体文件路径，而不是凭技术栈猜测结构。

仓库地图不需要列出每个文件。它的作用是确认业务边界和验证入口，让后续任务知道应该查哪里、不应该碰哪里。

## 用问题缩小上下文

- 这个行为由哪个入口触发？ - 数据经过哪些服务、实体和接口？ - 当前测试覆盖在哪里？ - 哪些配置或公共类型被多个模块共享？ - 修改后有哪些下游调用方会受影响？

先回答这些问题，再决定修改文件。若答案缺少代码证据，应继续搜索，而不是直接实现。

## 把任务拆成四个阶段

1. 调查：只读定位现状、接口和约束。 2. 方案：列出最小修改集、风险和验收方式。 3. 实现：一次只处理一个边界清楚的改动。 4. 验证：运行相关测试、构建并检查差异。

每个阶段都应有可交付结果。调查结论错误时，可以在写代码前纠正；测试失败时，也能明确是哪个改动引入的。

## 控制文件范围

提供具体目录、文件或符号，比“看看整个项目”更有效。涉及多个模块时，可以先让 Codex列出候选文件并说明理由，人工确认后再写入。对生成文件、锁文件、环境配置和部署目录要单独声明是否允许修改。

## 避免上下文污染

不要把无关日志、历史对话和重复文件全部塞进任务。过多无关信息会掩盖关键约束。长任务进行到新阶段时，重新总结已确认事实、未解决问题和禁止项，保持上下文清晰。

## 验收大型改动

除测试通过外，还要检查实际 diff、跨模块接口、数据库兼容性和回滚方案。要求 Codex 区分“已验证”“根据代码推断”和“尚未确认”，不要把推测写成结论。大型仓库中的高质量协作，依赖的是可追踪的证据链，而不是一次性生成大量代码。