---
title: "03 · Codex 看到的上下文从哪里来"
description: "理解任务、项目、代码、规则和反馈五层上下文，减少 Codex 凭空猜测和无关改动。"
canonical: "https://xiangyugongzuoliu.com/openai-codex-context-engineering"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

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

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

> [!IMPORTANT]
> 上下文工程不是把所有文件塞给 Codex，而是把“当前任务需要的证据”组织出来。缺证据时应先只读分析，不要直接修改。

<Cards>
  <Card title="任务管线" href="/docs/codex/understanding/how-a-task-completes">
    先理解一次 Codex 任务从输入到交付会经过哪些阶段。
  </Card>
  <Card title="AGENTS.md" href="/docs/codex/understanding/agents-md-guide">
    用项目规则把长期上下文固化下来，减少每次重复提示。
  </Card>
  <Card title="安全边界" href="/docs/codex/understanding/sandbox-approval">
    上下文越充分，越要配合权限和审批边界使用。
  </Card>
</Cards>

## 五层上下文

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

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

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

每层回答的问题不同：

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

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

## 上下文不足时会怎样

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

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

常见表现：

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

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

## 好上下文的三个标准

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

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

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

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

## 给 Codex 上下文的四步法

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

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

然后让它定位任务：

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

再让它分类信息：

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

最后才进入修改：

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

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

## AGENTS.md 是长期上下文

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

适合写进 `AGENTS.md` 的内容：

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

不适合写进去的内容：

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

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

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

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

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

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

## 最小可执行模板

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

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

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

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

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

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

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