CODEX 认知、学习、使用

图 1：Codex 十大技巧总览。本文基于图片中的 10 个技巧展开，同时补充 Codex 的能力介绍、代码操作实例、提示词模板和团队落地建议。（图片为网上下载）

1. 文档目标

这份文档不是只讲概念，而是帮助你把 Codex 真正用到日常开发里。读完之后，你应该能解决下面几件事：

• 知道 Codex 适合做什么，不适合做什么
• 知道怎样给出高质量需求，让 Codex 更贴近项目实际
• 知道怎样让它读代码、改代码、查问题、补文档
• 知道怎样把单次使用，升级为稳定的团队协作方式

2. Codex 是什么

Codex 可以理解为一个面向真实工程环境的开发协作助手。它和普通对话式 AI 的区别，不只是"会写代码"，而是更擅长在项目上下文中完成任务，例如：

• 阅读仓库并总结项目结构
• 理解已有代码后进行定点修改
• 协助排查日志、报错和接口异常
• 生成脚本、文档、测试和重构建议
• 按要求逐步执行，而不是只给一段演示代码

换句话说，Codex 更像一个可以配合你工作的"开发搭档"。

3. Codex 常见能力介绍

在实际使用中，可以把 Codex 的能力理解为下面几类。

3.1 代码理解

适合做的事：

• 阅读项目结构并解释模块职责
• 说明某个接口、类、方法的调用链
• 分析配置文件、SQL、脚本和依赖关系

示例：

请先帮我理解这个项目。
重点阅读 README、pom.xml、启动类和 yudao-module-system 模块。
输出项目结构、模块职责、主要技术栈和后续开发注意事项。

3.2 代码修改

适合做的事：

• 修复 bug
• 实现小型功能
• 做局部重构
• 补充校验、日志、异常处理

示例：

请帮我修改用户分页查询逻辑。
目标：支持按手机号模糊查询
约束：不要改接口入参，不影响已有姓名和状态筛选
先分析相关代码，再给最小修改方案。

3.3 问题排查

适合做的事：

• 根据报错日志定位问题
• 分析空指针、SQL 异常、接口 500、序列化问题
• 帮你提出验证路径和修复建议

示例：

下面是报错日志和复现步骤，请帮我判断根因。
我希望你先定位问题，再给出最小修复方案和验证步骤。

3.4 文档与规范沉淀

适合做的事：

• 生成模块说明文档
• 整理接口说明
• 编写团队 AI 使用规范
• 生成 AGENTS.md / CLAUDE.md

3.5 自动化执行

当目标、边界和规则足够清晰时，Codex 还可以直接执行更完整的开发流程，例如：

• 先读代码，再给计划
• 按计划修改多个文件
• 运行验证命令
• 输出结果和风险说明

这类能力很强，但前提一定是：目标清晰、上下文完整、约束明确、可回退可验证。

4. 图中 10 个技巧详解

4.1 先让 Codex "理解项目"

技巧要点

在动手前，先让 Codex 读懂目录结构、关键模块、技术栈和约束文件。

实操建议

• 从 README、依赖配置、启动类和核心业务目录开始
• 让它总结模块职责、依赖关系和代码规范
• 明确告诉它哪些目录最重要

示例提示词

先不要改代码，先帮我理解项目。
请阅读 README、pom.xml、启动入口和主要业务模块，
输出：项目结构、模块职责、技术栈、后续开发约束。

4.2 学会拆任务

技巧要点

复杂任务不要一次性全部抛给 Codex，而要拆成多个小目标。

实操建议

• 按"分析 -> 定位 -> 修改 -> 验证"拆分
• 一次只解决一个核心问题
• 每一步都保留检查点

示例提示词

这个任务分四步完成：
1. 先定位相关代码
2. 再分析修改点
3. 然后实施最小改动
4. 最后给出验证步骤
每一步先输出结果，再进入下一步。

4.3 小步迭代比一次生成更强

技巧要点

先拿到可用版本，再逐步增强，通常比一次追求"完美大改"更稳。

实操建议

• 先做最小可用版本
• 每轮只改一个主要问题
• 每次改完都验证

4.4 Git commit 是"保命技巧"

技巧要点

让每个关键阶段都可回退，尤其是在 AI 辅助高频改动的场景里。

实操建议

• 关键修改前先形成快照
• 一个 commit 对应一个目标
• commit 信息尽量描述业务意图

4.5 善用 Suggest / Auto Edit / Full Auto

建议理解方式

• Suggest：适合拿方案、问思路、做评估
• Auto Edit：适合精确改动指定文件
• Full Auto：适合边界清晰、流程较完整的复杂任务

使用建议

• 需求没想清楚时，先 Suggest
• 已明确改哪里时，用 Auto Edit
• 已有计划、规则、验证路径时，再考虑 Full Auto

4.6 给完整上下文

技巧要点

上下文越完整，结果越贴近真实需求。

建议提供的信息

• 目标
• 当前现象
• 相关文件
• 约束条件
• 期望结果

4.7 用日志帮 Codex Debug

技巧要点

日志、堆栈、请求体、返回值，是定位问题最直接的线索。

实操建议

• 提供完整错误信息
• 说明复现步骤
• 附带关键代码和参数

4.8 Prompt 要写"目标 + 约束"

技巧要点

好 Prompt 不只是提需求，而是把目标、边界和输出格式说清楚。

通用结构

• 目标
• 上下文
• 约束
• 输出要求

4.9 让 Codex 先出计划

技巧要点

复杂任务先审计划，再执行，可以显著减少误改风险。

适合场景

• 多模块联动
• 涉及接口和数据库
• 你自己也还没完全确定方案

4.10 用 CLAUDE.md / AGENTS.md 固化规则

技巧要点

把团队约束写进规则文件，能让 Codex 每次都更稳定地按照同一套标准做事。

可沉淀内容

• 项目结构说明
• 代码风格和命名规范
• 提交规范
• 测试要求
• 禁止修改项

5. 代码操作实例

这一部分是本文最重要的"上手区"。下面给出几个最常见的 Codex 代码协作场景，每个场景都包含目标、提示词写法和预期收益。

5.1 实例一：先读代码，再解释模块关系

场景

你刚接手一个仓库，不知道从哪里开始看。

可以这样问

请先不要改代码，先帮我理解这个项目。
重点阅读：
1. README
2. pom.xml
3. 启动类
4. yudao-module-system 模块

输出要求：
1. 项目整体结构
2. 每个核心模块负责什么
3. 模块之间大致调用关系
4. 如果我要改用户管理功能，应该优先看哪些文件

你会得到什么

• 一份项目阅读路径
• 一份模块职责说明
• 一套更高效的后续排查入口

5.2 实例二：让 Codex 帮你定位 Bug

场景

某个接口报 500，但你暂时没看出根因。

可以这样问

请帮我定位一个接口报错问题。

现象：
用户提交订单时接口返回 500。

复现步骤：
1. 登录后台
2. 提交订单
3. 服务端返回异常

已知信息：
1. 下面附上完整报错堆栈
2. 相关代码在 OrderController、OrderServiceImpl、OrderMapper

要求：
1. 先判断根因
2. 再告诉我需要重点排查哪些代码
3. 如果能确认问题，请给最小修复方案
4. 最后给验证步骤

代码操作思路

Codex 通常会先：

• 读报错堆栈，定位大致异常点
• 结合控制器、服务层和数据层分析调用链
• 判断是参数、SQL、空值还是事务问题
• 输出修改建议和验证方法

5.3 实例三：让 Codex 做最小范围改代码

场景

你已经知道问题在哪，希望它只做精准修改，不要扩散。

可以这样问

请帮我修改这段逻辑。

目标：
给用户列表增加"手机号模糊查询"能力。

涉及文件：
1. UserPageReqVO
2. UserServiceImpl
3. UserMapper.xml

约束：
1. 不修改接口路径
2. 不影响已有姓名、状态筛选
3. 优先最小改动
4. 不做无关重构

输出要求：
1. 先说明准备改哪些地方
2. 再实施修改
3. 最后告诉我如何验证

预期收益

• 修改范围可控
• 风险更低
• 便于 review 和回退

5.4 实例四：让 Codex 帮你补日志

场景

线上问题不好复现，想通过日志先增强可观察性。

可以这样问

请帮我在这段订单提交流程中补充关键日志。

目标：
让我能判断失败发生在参数校验、库存校验、还是落库阶段。

约束：
1. 不打印敏感信息
2. 日志要能串起整个请求过程
3. 不要加入无意义的重复日志
4. 保持现有代码风格

适合补哪些日志

• 请求入口参数摘要
• 关键分支判断结果
• 外部接口调用结果
• 异常捕获点
• 最终成功或失败状态

5.5 实例五：让 Codex 帮你生成测试思路

场景

你改完了代码，但不想只靠"看起来没问题"来判断。

可以这样问

这次改动已经完成，请帮我补充验证方案。
要求输出：
1. 需要覆盖的正常场景
2. 需要覆盖的异常场景
3. 如果要写单元测试，建议测试哪些方法
4. 如果要做接口测试，建议准备哪些输入

价值

• 帮你从"实现完成"走到"验证完成"
• 特别适合代码 review 前做自查

6. 一个完整的代码协作示例

下面给出一个比较完整的示例，展示怎样和 Codex 一步步完成一个需求。

需求

给用户列表增加手机号模糊查询。

第一步：让它理解上下文

请先帮我看用户管理相关代码，不要急着改。
我想给用户列表增加手机号模糊查询。
请先定位相关接口、请求参数对象、Service 和 Mapper。

第二步：让它先出计划

请输出这个需求的实施计划：
1. 需要改哪些文件
2. 每个文件大概改什么
3. 风险点是什么
4. 如何验证是否成功

第三步：再让它修改

按刚才的计划执行修改。
要求：
1. 只做最小必要改动
2. 不改接口结构
3. 不做无关重构
4. 修改后告诉我影响范围

第四步：让它补验证方案

请基于这次改动，补充验证清单。
包括：
1. 正常查询场景
2. 空参数场景
3. 与姓名筛选组合场景
4. 可能的边界场景

这套流程的优点

• 每一步都可检查
• 修改目标清晰
• 不容易走偏
• 特别适合团队协作和代码 review

7. Java / Spring Boot 项目专用实例

这一部分更贴近后端 Java 项目，尤其适合 Spring Boot、MyBatis、分层架构项目使用。

7.1 实例一：定位 Controller -> Service -> Mapper 调用链

场景

你接手一个接口问题，但只知道入口 URL，不清楚它具体经过哪些类。

可以这样问

请帮我梳理这个接口的调用链。
目标接口：用户分页查询接口
请从 Controller 开始，继续往 Service、Mapper、XML 或 SQL 方向追踪，
输出：
1. 入口控制器
2. Service 调用链
3. Mapper/SQL 位置
4. 分页、筛选条件、数据转换分别在哪一层处理

适合的项目结构

• controller/admin/...
• service/...
• dal/dataobject
• dal/mysql/...Mapper.java
• resources/mapper/*.xml

价值

• 快速读懂后端链路
• 明确应该改 Controller、Service 还是 SQL
• 减少"改错层"的概率

7.2 实例二：分析 MyBatis / Mapper XML 查询问题

场景

接口返回结果不对，很可能不是 Java 逻辑问题，而是 SQL 条件拼接问题。

可以这样问

请帮我检查这个分页查询为什么结果异常。
重点查看：
1. 请求参数对象
2. Service 查询组装逻辑
3. Mapper 接口
4. Mapper XML 中 where 条件拼接

要求：
1. 判断问题是在 Java 层还是 SQL 层
2. 如果是 XML 条件问题，请指出具体条件
3. 给出最小修复方案
4. 说明是否会影响其他查询条件

常见排查点

• like 写法是否正确
• null 和空字符串判断是否完整
• 动态 if 条件是否遗漏
• 分页排序字段是否正确
• 联表字段别名是否冲突

7.3 实例三：补充统一异常处理和错误日志

场景

项目里报错信息不统一，前端看到的提示混乱，后端日志也不好排查。

可以这样问

请帮我评估当前异常处理是否规范。
重点查看：
1. 全局异常处理器
2. 业务异常定义
3. Controller 层异常抛出方式
4. 关键日志记录位置

输出：
1. 当前问题
2. 推荐优化点
3. 最小改造方案
4. 哪些地方需要补日志，哪些地方不应该重复打印日志

适合关注的类

• GlobalExceptionHandler
• ServiceException
• ErrorCode
• 各业务 Service 实现类

价值

• 提升问题定位效率
• 让接口错误返回更一致
• 避免重复打印异常导致日志污染

7.4 实例四：排查事务不生效问题

场景

你已经加了 @Transactional，但数据看起来还是部分成功、部分失败。

可以这样问

请帮我分析这个事务为什么可能没有生效。
请重点检查：
1. 事务注解加在什么方法上
2. 是否存在同类内部调用
3. 异常是否被 try-catch 吃掉
4. 是否涉及异步、事件或远程调用
5. 回滚条件是否满足

输出要求：
1. 可能原因按优先级排序
2. 每个原因对应的验证方式
3. 如果确认问题，请给修复建议

常见原因

• 同类内部方法调用导致代理失效
• 捕获异常后没有继续抛出
• 回滚异常类型不匹配
• 事务边界划分不合理

7.5 实例五：让 Codex 帮你补接口联调清单

场景

功能写完了，但你希望更系统地准备接口联调和回归测试。

可以这样问

请基于这个 Spring Boot 接口实现，帮我输出联调清单。
包括：
1. 正常请求示例
2. 参数缺失场景
3. 权限不足场景
4. 分页边界场景
5. 并发或重复提交风险点
6. 需要重点关注的日志和数据库结果

价值

• 非常适合提测前自查
• 也适合直接发给前端或测试同学联调

7.6 实例六：生成 Spring Boot 项目专用规则文件

场景

你希望 Codex 每次都按后端项目规范做事，而不是每次重新说明。

可以这样问

请帮我生成一份适用于 Java / Spring Boot 项目的 AGENTS.md。
要求包含：
1. Controller、Service、Mapper 的职责边界
2. DTO / VO / DO 的命名规范
3. SQL 修改注意事项
4. 日志和异常处理约束
5. commit 和验证要求

建议写入的规则

• Controller 不写复杂业务
• Service 负责业务编排
• Mapper XML 改动后要检查分页和动态条件
• 涉及数据库改动时说明影响范围和回滚方案
• 改动优先最小范围，不做无关重构

8. 常用 Prompt 模板

7.1 理解项目

请先帮我快速理解这个项目。
重点阅读 README、依赖配置、启动入口和核心模块目录。
输出项目结构、主要模块职责、技术栈和后续改动注意事项。

7.2 修复 Bug

请帮我修复一个 bug。
目标：解决 [具体现象]
上下文：[相关模块/文件/日志]
约束：只做最小修改，不改接口定义，不影响其他功能
输出：根因分析、修改方案、验证步骤

7.3 实现功能

请帮我实现一个功能。
目标：[功能目标]
背景：[业务背景]
涉及文件：[文件路径]
约束：[性能/兼容/风格/权限要求]
请先给执行计划，再按计划实施。

7.4 重构优化

请帮我评估这段代码是否值得重构。
先分析当前问题、风险和收益，再给最小可行的重构方案。
如果收益不大，请明确告诉我不建议重构。

9. 推荐工作流

1. 先理解项目

   让 Codex 读懂结构、模块、入口和约束。

2. 再拆任务

   把需求拆成多个可执行小目标。

3. 先出计划

   复杂任务先确认路径和风险。

4. 再执行修改

   优先最小改动，避免无关扩散。

5. 及时验证

   检查编译、测试、日志和接口结果。

6. 最后沉淀

   把有效 Prompt、规则和经验写成文档。

10. 使用 Codex 时的安全提醒

• 不要直接提供生产密钥、账号和敏感数据
• 涉及支付、权限、删除、迁移时，先做风险分析
• 外部代码不要直接照搬，先让 Codex 解释再落地
• 自动化修改完成后，关键代码必须人工复核
• 数据库和脚本类操作优先要求它给出回滚方案

11. 团队落地建议

如果你想把 Codex 从"个人工具"变成"团队能力"，建议这样推进：

• 统一一套常用 Prompt 模板
• 沉淀一份 AGENTS.md 或团队 AI 协作规范
• 从理解项目、修 bug、实现小需求三个高频场景先落地
• 用真实案例沉淀最佳实践
• 强调"先计划、再执行、可验证、可回退"

12. 一句话总结

Codex 不是只会生成代码的工具，而是可以帮助你理解项目、操作代码、分析问题、推进交付的开发协作伙伴。

13. 快速上手清单

• 先让 Codex 理解项目，不急着改代码
• 每次只给一个清晰目标
• 复杂任务先让它出计划
• 提供完整上下文、日志和约束
• 优先小步迭代，不追求一步到位
• 关键节点及时 commit
• 把有效规则沉淀到 AGENTS.md 或团队文档