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 把你的猜测当成结论。若代码证据与假设冲突,应以仓库内容和可复现结果为准。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

提供必要项目上下文

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通