Codex 上下文提供详解与操作指南

1. 文档目标

这份文档解决的是一个非常实际的问题：

• 怎么给 Codex 足够完整的上下文
• 什么信息是必须给的，什么信息是可选但高价值的
• 怎样让 Codex 在一次任务里快速进入正确状态
• 怎样避免“我已经说了很多，但结果还是不对”
• 怎样把上下文提供方式变成可复用的方法

读完后，你应该能够：

• 判断一个任务当前缺少哪些关键上下文
• 用结构化方式给出更高质量输入
• 让 Codex 更快、更准地理解项目、问题和目标
• 在开发、排错、测试、文档场景中稳定复用这套方法

2. 为什么上下文这么重要

Codex 并不是靠“猜”来完成工程任务的，它依赖上下文建立工作判断。

如果上下文不足，就很容易出现下面这些问题：

• 输出过于泛化
• 理解错真实目标
• 给出不贴合项目的建议
• 改了不该改的文件
• 忽略已有约束和风险

一句话理解：

Codex 的能力上限，不只取决于模型本身，也取决于你是否把足够正确的信息交给它。

3. 什么叫“足够完整的上下文”

很多人以为“上下文多一点”就够了，但真正高质量的上下文，不只是信息量大，而是信息结构正确。

一个足够完整的上下文，通常要回答下面几个问题：

• 你希望 Codex 做什么
• 当前问题是什么
• 相关代码或模块在哪里
• 哪些规则必须遵守
• 哪些内容不能改
• 最终结果要长什么样
• 怎样验证任务是否完成

4. Codex 最需要的 8 类上下文

4.1 目标上下文

这是最核心的。

要告诉 Codex：

• 最终要完成什么
• 当前这一步只要完成什么
• 成功标准是什么

示例

目标：修复订单分页接口手机号筛选失效问题。 当前这一步：先定位问题和最可能根因，不要直接改代码。 成功标准：明确是参数、Java 逻辑还是 SQL 条件导致的问题。

4.2 项目上下文

要告诉 Codex 当前项目的基本情况，例如：

• 项目类型
• 技术栈
• 核心模块
• 启动方式

示例

项目背景：这是一个 Java / Spring Boot + MyBatis 项目。 涉及模块：订单管理、用户管理、系统管理。

4.3 代码位置上下文

要让 Codex 知道问题大概发生在哪些文件、哪些层。

常见形式

• Controller
• Service
• Mapper / XML
• VO / DTO / DO
• 前端页面

示例

相关文件： 1. OrderController 2. OrderServiceImpl 3. OrderMapper 4. OrderMapper.xml

4.4 现象上下文

要明确告诉 Codex：

• 当前看到的现象是什么
• 哪一步会触发这个现象
• 表现出来的是报错、空数据还是行为不一致

示例

现象：订单分页接口在带手机号筛选时返回空数据，不带手机号时正常。

4.5 约束上下文

这是很多人最容易漏掉的部分。

要告诉 Codex：

• 什么不能改
• 什么必须兼容
• 什么不允许顺手优化

示例

约束： 1. 不修改接口路径 2. 不改变入参结构 3. 不做无关重构 4. 不影响其他筛选条件

4.6 风险上下文

高风险区域一定要提前说。

例如

• 涉及事务
• 涉及 SQL
• 涉及权限
• 涉及支付
• 涉及公共组件

示例

风险提示：这个修改涉及 SQL 动态条件和分页逻辑，请优先最小改动，并说明影响范围。

4.7 输出要求上下文

要告诉 Codex 你希望它怎么回答。

例如

• 先分析再修改
• 先给计划再执行
• 只输出验证方案
• 最后给一份总结

示例

输出要求： 1. 先分析根因 2. 再给最小修改方案 3. 最后给验证步骤

4.8 验证上下文

告诉 Codex 怎样算完成。

例如

• 编译通过
• 接口返回符合预期
• 日志不再报错
• 前后端联调通过

示例

验证目标： 1. 手机号筛选能正常返回数据 2. 其他筛选条件不受影响 3. SQL 日志符合预期

5. 推荐的上下文提供结构

如果你想让 Codex 更稳定，建议按固定结构给上下文。

6. 最推荐的上下文输入模板

下面这份模板适合大多数工程任务直接复用。

请帮我处理一个任务。 目标： [最终要达成什么] 当前这一步： [当前只需要先完成什么] 项目背景： [项目类型 / 技术栈 / 核心模块] 相关文件或模块： [列出关键文件、类、目录] 当前现象： [具体问题、报错、行为表现] 约束： [不能改什么 / 必须兼容什么 / 不做什么] 风险提示： [高风险点] 输出要求： 1. [先做什么] 2. [再做什么] 3. [最后做什么] 验证标准： [怎样算完成]

7. 如何让 Codex 主动读取更多项目文件、目录和规则

很多时候，你自己并不清楚应该先给哪些文件，这时更好的方式不是“盲贴很多代码”，而是让 Codex 先主动读取一批高价值文件，再基于读取结果继续追踪。

这件事的关键不是一句“你自己看看项目”，而是要明确告诉它：

• 先从哪些入口读
• 重点关注哪些目录
• 要输出什么结果
• 如果信息不够，继续往哪里追

7.1 让 Codex 先读“入口文件”

最稳定的方式，通常是先让它读取一组入口文件：

• README
• 构建文件，例如pom.xml
• 配置文件，例如application.yml
• 启动类或主入口
• 核心模块根目录

示例提示词

请先不要改代码，先主动读取这个项目的关键入口文件，帮助我建立上下文。 请优先阅读： 1. README 2. pom.xml 3. application.yml / bootstrap.yml 4. 启动类 5. 核心业务模块目录 输出： 1. 项目结构概览 2. 技术栈 3. 核心模块职责 4. 接下来还建议继续读取哪些文件

7.2 让 Codex 按目录逐层下钻

如果你已经知道大概在哪个模块，可以让它按目录层级继续读，而不是一下子扫描全仓库。

推荐方式

• 先读模块目录
• 再读模块下核心子目录
• 再追典型业务链路

示例提示词

请先从 `yudao-module-system` 模块开始主动阅读。 先输出： 1. 该模块目录结构 2. 主要子目录职责 3. 你认为最值得继续阅读的类或文件 然后继续追踪一个典型业务链路： Controller -> Service -> Mapper -> XML

7.3 让 Codex 主动读取规则文件

如果项目里有规则或约束文件，一定要明确要求它先读这些文件。

常见规则文件包括：

• AGENTS.md
• CLAUDE.md
• README
• 团队规范文档
• 部署脚本说明
• SQL / 脚本工具说明

示例提示词

请先主动检查这个项目中是否存在规则文件或协作文档。 优先关注： 1. AGENTS.md 2. CLAUDE.md 3. README 4. docs 目录下的规范文档 输出： 1. 找到了哪些规则文件 2. 每个文件大致约束了什么 3. 后续开发时必须优先遵守哪些规则

7.4 让 Codex 不只读文件名，而是读“典型链路”

只看目录还不够，很多真实问题都藏在调用链里。

所以你可以明确要求它继续追：

• 一个典型接口的完整调用链
• 一个典型页面到接口的调用链
• 一个典型查询从入参到 SQL 的链路

示例提示词

在理解完项目结构后，请你主动追踪一个典型业务链路。 目标链路： 订单分页查询 请输出： 1. 入口 Controller 2. Service 调用链 3. Mapper / XML 位置 4. 查询条件在哪一层处理 5. 哪些文件是这个链路的关键上下文

7.5 让 Codex 明确告诉你“下一批该读什么”

这是一个非常实用的技巧。

不要只让它读完当前内容，而要让它继续输出：

• 还缺哪些文件
• 接下来该继续读什么
• 哪些文件最值得优先打开

示例提示词

基于你刚才已经读取的内容，请继续告诉我： 1. 还缺哪些关键上下文 2. 接下来最建议主动读取的 5 个文件或目录 3. 为什么它们重要

7.6 推荐的“主动读取”工作流

7.7 一段可直接复用的通用提示词

请先不要改代码，先主动读取这个项目的关键文件、目录和规则文件，帮我建立足够完整的上下文。 请按下面顺序进行： 1. 先读取 README、构建文件、配置文件、启动类 2. 再读取核心业务模块目录 3. 再检查 AGENTS.md、CLAUDE.md、docs 中的规则文件 4. 再主动追踪一个典型业务链路 输出要求： 1. 当前你已经理解了什么 2. 当前项目结构和模块职责 3. 当前找到的规则和约束 4. 当前仍缺哪些关键上下文 5. 下一步最建议继续读取哪些文件或目录

7.8 注意事项

• 不要让 Codex 一上来“全仓库乱扫”，而要给它阅读顺序
• 不要只让它读目录，要让它继续追规则和典型链路
• 如果项目很大，优先先读一个核心模块，而不是试图一次吃完整个仓库
• 如果你知道高价值文件，最好直接点名
• 让它每读完一轮都输出“还缺什么”

8. 标准操作流程

9. 第一步：先明确你到底缺什么结果

在给上下文前，先判断你需要 Codex 产出什么。

常见类型：

• 项目理解
• 方案分析
• bug 定位
• 代码修改
• 测试补充
• 文档生成

为什么重要

因为不同任务，对上下文要求不同。

例如：

• 项目理解更需要结构和模块信息
• bug 定位更需要现象、日志和调用链
• 代码修改更需要文件位置、约束和验证标准

10. 第二步：优先给“最影响判断”的上下文

不是所有信息都同样重要。

最优先给的通常是：

1. 目标
2. 当前现象
3. 相关文件
4. 约束

如果这些都没有，哪怕你贴了很多代码，Codex 也可能还是判断偏。

11. 第三步：先让 Codex 理解，再决定是否执行

对于复杂任务，不要一上来就让它改。

更稳的方式是：

• 先让它理解
• 再看它理解得对不对
• 再补上下文
• 最后再执行

示例提示词

先不要改代码，先基于下面的上下文帮我理解问题。 如果你认为上下文还不够，请明确告诉我还缺什么。

12. 第四步：让 Codex 明确指出“还缺什么上下文”

这是一个非常实用的技巧。

如果你不确定上下文够不够，可以直接问：

基于当前信息，如果你还不能稳定判断，请列出你还需要哪些额外上下文。

这能帮助你从“凭感觉补信息”变成“按缺口补信息”。

13. 第五步：补上下文时优先补“结构化信息”

比起随手再贴一段代码，更推荐补：

• 具体文件名
• 调用链位置
• 完整报错堆栈
• 关键配置项
• 输入参数和返回结果

不推荐的补法

你再看看，还有问题。

推荐的补法

补充信息： 1. 报错发生在 OrderServiceImpl.createOrder 2. SQL 日志如下 3. 当前请求参数如下 4. 相关 XML 条件如下

14. Java / Spring Boot 项目实战实例

场景

订单分页接口在带手机号筛选时返回空数据。

低质量上下文示例

订单接口有 bug，帮我看看。

这个上下文的问题是：

• 没有目标
• 没有现象描述
• 没有相关文件
• 没有约束

高质量上下文示例

请帮我定位一个 bug。 目标： 修复订单分页接口手机号筛选失效问题。 当前这一步： 先判断根因，不要直接改代码。 项目背景： 这是一个 Spring Boot + MyBatis 项目。 相关文件： 1. OrderController 2. OrderServiceImpl 3. OrderMapper 4. OrderMapper.xml 当前现象： 带手机号筛选时返回空数据，不带手机号时正常。 约束： 1. 不修改接口路径 2. 不改变入参结构 3. 不影响其他筛选条件 4. 不做无关重构 输出要求： 1. 先分析根因 2. 再判断问题更可能出在参数、Java 逻辑还是 SQL 条件 3. 最后给最小修复建议 验证标准： 1. 手机号筛选恢复正常 2. 其他筛选条件不受影响

为什么这个上下文更好

因为它把目标、现象、位置、约束和验证标准都说清楚了。

15. 功能开发实战实例

场景

要给会员资料管理新增customerLevel字段。

推荐上下文写法

请帮我处理一个功能开发任务。 目标： 给会员资料管理新增 customerLevel 字段，并最终支持新增、编辑、分页筛选和列表展示。 当前这一步： 先只分析影响范围并列出应修改的模块，不直接改代码。 项目背景： 这是一个 Java / Spring Boot + MyBatis 项目，前后端联动开发。 相关模块： 1. MemberController 2. MemberServiceImpl 3. MemberMapper / MemberMapper.xml 4. ReqVO / RespVO / SaveVO 5. 前端列表和表单页面 约束： 1. 优先最小改动 2. 不做无关重构 3. 保持既有接口风格 4. 需要兼容现有列表和筛选逻辑 输出要求： 1. 输出影响范围 2. 输出建议修改文件 3. 输出风险点 4. 输出建议的执行顺序

16. 测试任务实战实例

场景

一个需求已经做完，希望让 Codex 帮忙补测试范围和验证清单。

推荐上下文写法

请帮我补充测试方案。 目标： 为本次 customerLevel 字段扩展补充测试范围和回归清单。 当前这一步： 只输出测试点和验证清单，不修改代码。 项目背景： Spring Boot + MyBatis，涉及会员列表、编辑表单和分页筛选。 已完成改动： 1. 后端字段流转已完成 2. SQL 筛选已支持 3. 前端展示已完成 输出要求： 1. 功能测试点 2. 异常测试点 3. 边界测试点 4. 联调清单 5. 回归清单

17. 上下文不够时的典型信号

如果你看到下面这些现象，通常说明上下文不够：

• Codex 输出过于通用
• 建议明显脱离当前项目
• 一直在猜测你的真实目标
• 一上来就想大改
• 反复漏掉你在意的限制条件

这时不要急着否定结果，更应该先补上下文。

18. 常见误区

17.1 误区一：只给需求，不给项目背景

问题：

• 容易得到泛化答案

17.2 误区二：只贴代码，不说目标

问题：

• Codex 不知道你到底想解决什么

17.3 误区三：不给约束

问题：

• 容易改到不该改的地方

17.4 误区四：不给验证标准

问题：

• 很难判断结果是否真正可用

17.5 误区五：信息很多，但没有结构

问题：

• 看起来给了很多，实际上判断成本很高

19. 注意事项

• 目标一定要清晰
• 复杂任务优先先理解再执行
• 高风险任务必须显式给出风险和约束
• 信息不够时，主动让 Codex 列出缺口
• 能结构化表达，就不要散乱表达
• 能分阶段提供上下文，就不要一口气混成一团

20. 高质量提示词模板

20.1 通用模板

请帮我处理一个任务。 目标： 当前这一步： 项目背景： 相关文件或模块： 当前现象： 约束： 风险提示： 输出要求： 验证标准：

20.2 项目理解模板

请先不要改代码，先帮我理解这个项目。 请重点阅读： 1. README 2. 构建文件 3. 启动入口 4. 核心模块 5. 典型调用链 输出： 1. 项目结构 2. 模块职责 3. 技术栈 4. 风险区域 5. 后续开发应注意的规则

20.3 Bug 定位模板

请帮我定位一个 bug。 目标： 当前这一步： 项目背景： 相关文件： 当前现象： 约束： 输出要求： 1. 先分析根因 2. 再给最小修复建议 3. 最后给验证步骤

21. 团队落地建议

如果你想把这套方法推广到团队里，建议这样做：

1. 统一一份“上下文输入模板”
2. 把高频任务的上下文示例沉淀下来
3. 把“上下文不够先补信息”写进团队 AI 规范
4. 在AGENTS.md中加入上下文提供要求
5. 用真实项目案例持续优化模板

22. 一句话总结

给 Codex 足够完整的上下文，不是为了“多说一点”，而是为了让它准确理解目标、边界、位置、限制和验证标准，从而更稳定地产出高质量结果。

23. 快速上手清单

• 先说目标
• 再说当前这一步
• 再给项目背景和相关文件
• 再补现象、约束、风险
• 再说输出要求和验证标准
• 信息不够时主动让 Codex 列缺口