03 · Codex 看到的上下文从哪里来

Codex 的输出质量，很大程度取决于它拿到的上下文质量。不是信息越多越好，而是事实更清楚、范围更相关、状态更当前。

如果只说“保存按钮没反应”，Codex 只能猜。补上页面路径、控制台报错、最近改动和项目规则后，它才有证据定位问题。

五层上下文

Codex 看到的上下文可以拆成五层：

flowchart TB
    Task["任务上下文<br/>本次要解决什么"]
    Project["项目上下文<br/>技术栈、目录、命令"]
    Local["局部代码上下文<br/>相关文件和调用链"]
    Rules["规则上下文<br/>AGENTS.md、团队规范、禁止事项"]
    Feedback["反馈上下文<br/>测试、构建、报错、审查意见"]

    Task --> Project --> Local --> Rules --> Feedback
    Feedback -. "产生新证据" .-> Task

每层回答的问题不同：

• 任务上下文回答“这次要完成什么”。
• 项目上下文回答“这个 repo 怎么工作”。
• 局部代码上下文回答“应该改哪里”。
• 规则上下文回答“哪些做法不能用”。
• 反馈上下文回答“改完是否真的有效”。

缺哪一层，Codex 就会在哪一层靠猜。

上下文不足时会怎样

“Codex 乱改”通常不是模型突然失控，而是缺少边界信息。

flowchart LR
    MissingScope["范围缺失"] --> BroadChange["改动扩散"]
    MissingRules["规则缺失"] --> WrongTool["用错包管理器或风格"]
    MissingValidation["验收缺失"] --> WeakFinish["只说改完但无法证明"]
    MissingFacts["事实缺失"] --> WrongCause["沿错误根因修改"]

常见表现：

• 没有限定目录，最后改了无关模块。
• 没说明不能新增依赖，最后引入不必要工具。
• 没给验证命令，最后跑了不相关检查。
• 没提供真实报错，最后按猜测修了错误方向。

解决方式不是反复说“别乱改”，而是补上范围、事实、禁止事项和验收方式。

好上下文的三个标准

好上下文同时满足三个条件：

1. 真实：来自文件、命令输出、日志、截图、明确业务输入，而不是印象。
2. 相关：直接影响当前任务，而不是把整个项目都堆进来。
3. 当前：反映现在的工作树、依赖版本和报错状态。

优先级是：真实高于相关，相关高于数量。

一个不真实但看起来相关的信息，会比没有信息更危险。例如你说“项目应该用 npm”，但 repo 里只有 pnpm-lock.yaml，Codex 就可能污染 lockfile。

给 Codex 上下文的四步法

第一次进入项目，不要马上让 Codex 改代码。先让它建立地图。

请只读分析当前项目，不要修改文件。
输出项目用途、技术栈、主要目录职责、启动命令、测试命令。
把确认事实和推断分开写。

然后让它定位任务：

我要修复设置页保存失败问题。
请先收集上下文，不要修改文件。
列出相关文件、调用链、风险点，以及还缺什么信息。

再让它分类信息：

请把当前信息分成：
- 事实：从文件或命令确认的内容
- 推断：基于事实推出来的判断
- 不确定：会影响实现但还没确认的点
- 下一步：需要继续读取或验证什么

最后才进入修改：

只修改设置页保存逻辑相关文件。
不新增依赖，不改全局样式，不改无关 API。
改完运行现有测试；如果无法运行，说明原因和替代验证。

这四步的价值，是把“开放猜测”变成“证据驱动的任务执行”。

AGENTS.md 是长期上下文

每次都在 prompt 里重复项目规则，维护成本很高。稳定规则应该写进 AGENTS.md。

适合写进 AGENTS.md 的内容：

• 项目使用的包管理器和运行命令。
• 目录职责和禁止触碰的区域。
• 代码风格、测试要求、提交前检查。
• 多人协作时的文件边界和并发规则。
• 敏感信息、部署、发布相关红线。

不适合写进去的内容：

• 单次任务目标。
• 临时 bug 现象。
• 一次性的实验参数。
• 会频繁变化的模型、价格、活动、版本列表。

规则文件越稳定，Codex 每次启动时的默认上下文越可靠。

多 Agent 或多人协作时的上下文

当同一仓库里有其他人或其他 agent 在改，Codex 需要额外上下文：

• 当前自己负责哪些文件。
• 哪些 dirty files 属于别人，不能碰。
• 是否允许修改共享脚本或配置。
• 每批最多改多少文件。
• 验证失败是否来自自己改动，还是来自工作树已有状态。

这类信息必须在任务开始前确认。否则即使 Codex 技术上能改，也可能覆盖别人的工作。

最小可执行模板

可以用这个模板给 Codex 任务上下文：

目标：
{要完成的具体结果}

范围：
只处理 {目录或文件}。
不要修改 {排除范围}。

上下文：
已知事实：{从文件、日志、报错确认的内容}
不确定项：{还需要只读确认的内容}

执行：
先只读分析并列计划；确认后再改。

验证：
运行 {测试/类型检查/构建命令}。
无法运行时说明原因和替代验证。

上下文工程的目标不是让 prompt 更长，而是让 Codex 更少猜、更少越界、更容易验证。