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 知道问题大概发生在哪些文件、哪些层。常见形式ControllerServiceMapper / XMLVO / DTO / DO前端页面示例相关文件 1. OrderController 2. OrderServiceImpl 3. OrderMapper 4. OrderMapper.xml4.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 - XML7.3 让 Codex 主动读取规则文件如果项目里有规则或约束文件一定要明确要求它先读这些文件。常见规则文件包括AGENTS.mdCLAUDE.mdREADME团队规范文档部署脚本说明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. 标准操作流程1. 明确目标2. 收集必要上下文3. 组织成结构化输入4. 先让 Codex 理解与分析5. 如有需要补充上下文6. 再进入修改/执行阶段7. 最后按验证标准收口9. 第一步先明确你到底缺什么结果在给上下文前先判断你需要 Codex 产出什么。常见类型项目理解方案分析bug 定位代码修改测试补充文档生成为什么重要因为不同任务对上下文要求不同。例如项目理解更需要结构和模块信息bug 定位更需要现象、日志和调用链代码修改更需要文件位置、约束和验证标准10. 第二步优先给“最影响判断”的上下文不是所有信息都同样重要。最优先给的通常是目标当前现象相关文件约束如果这些都没有哪怕你贴了很多代码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. 团队落地建议如果你想把这套方法推广到团队里建议这样做统一一份“上下文输入模板”把高频任务的上下文示例沉淀下来把“上下文不够先补信息”写进团队 AI 规范在AGENTS.md中加入上下文提供要求用真实项目案例持续优化模板22. 一句话总结给 Codex 足够完整的上下文不是为了“多说一点”而是为了让它准确理解目标、边界、位置、限制和验证标准从而更稳定地产出高质量结果。23. 快速上手清单先说目标再说当前这一步再给项目背景和相关文件再补现象、约束、风险再说输出要求和验证标准信息不够时主动让 Codex 列缺口