AI Agent / 系统课时
提供必要项目上下文
提供必要项目上下文
目标清楚但上下文不足时,Codex 仍可能从错误入口开始探索。本课将筛选真正影响决策的文件、技术栈、约束和已知问题,让它快速进入相关代码而不过度扫描仓库。
学习目标
- 识别任务所需的最小项目上下文
- 用路径、符号和错误证据替代宽泛描述
- 区分已知事实、推测和待确认问题
只提供影响决策的信息
必要上下文通常包括相关入口文件、技术栈与版本、项目惯例、可运行命令、已知错误和不能改变的约束。与任务无关的历史背景、整份日志和大量源码粘贴会稀释重点。
优先给出文件路径和符号名,让 Codex 自行读取最新版内容。若你知道调用链,可指出起点和终点;若不知道,应明确要求它先只读定位,不要把猜测写成事实。
使用结构化上下文
下面以修复缓存失效问题为例。路径和版本需要替换为真实项目信息。
text
任务:修复用户资料更新后仍读取旧缓存的问题。
相关上下文:
- 技术栈:Java 21、Spring Boot 3.x、Redis。
- 更新入口:src/main/java/com/example/user/UserService.java 的 updateProfile。
- 读取入口:同类中的 getProfile。
- 缓存键规则:user:profile:<ID>。
- 现有测试:src/test/java/com/example/user/UserServiceTest.java。
- 已知现象:更新成功后,下一次读取仍返回更新前的数据。
- 约束:不要更改公共接口,不要缩短全局缓存 TTL,不新增依赖。
执行要求:
先读取上述文件并解释根因;若证据不足,列出需要继续检查的文件。确认方案后再修改,并运行最相关测试。预期结果
text
Codex 先围绕指定入口和缓存规则定位读写顺序,再基于源码证据提出修复,不会从整个仓库无目标搜索。在支持文件提及的 Codex 界面中,也可以用 @ 搜索并附加相关路径。即使附加了文件,指令中仍应说明每个文件与任务的关系,避免只给一组没有目的的附件。
提供错误的原始证据
排障任务应保留关键错误文本、失败测试名、请求样例和复现步骤。不要只写“接口偶尔报错”,而应说明触发条件、期望结果、实际结果和最小日志片段。
日志过长时,只提供首次异常、完整堆栈的关键部分和请求关联信息,并告诉 Codex 完整日志位于哪个文件。删除访问令牌、密码、私钥和用户隐私数据后再共享。
标注不确定性
上下文中应区分三类信息:已确认事实、当前推测、需要 Codex 验证的问题。例如“怀疑是缓存删除发生在事务提交前”应明确标为假设,并要求它检查事务边界和调用顺序。
这种写法可以防止 Codex 把你的猜测当成结论。若代码证据与假设冲突,应以仓库内容和可复现结果为准。
按自己的节奏,确认真正理解。