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

⏱️ 预计阅读 13 分钟 ｜ 🎯 目标：把 Codex 的判断从「凭直觉」换成「凭证据」

上一篇讲 Codex 任务管线 7 步。第 3 步「收集上下文」是一切的地基。 这一篇要回答：上下文具体由哪些东西组成？为什么"上下文质量 = Codex 输出质量"？怎么用 AGENTS.md（项目规则文件）让上下文长期稳定？

🎬 同一个 bug，给不同上下文会怎样

你遇到一个问题：

点击保存按钮后没反应。

你直接把这句话扔给 Codex 会怎样？看下面四阶段，Codex 给的答案完全不一样：

🤔 不是 Codex 突然变聪明，是你给了它能推理的证据。

✋ Codex 输出质量 ≈ 上下文质量。这是这一篇的核心。

🧱 上下文不是一团信息，是 5 层栈

很多新手把上下文理解成"我在聊天框里写过的话"。这远远不够。Codex 的真实上下文有 5 层，每层来源不同，作用也不同：

stateDiagram-v2
    direction TB
    [*] --> Task

    Task: 1️⃣ 任务上下文<br/>（本次要做什么）
    Project: 2️⃣ 项目上下文<br/>（项目怎么组织）
    Local: 3️⃣ 局部代码上下文<br/>（任务相关的文件）
    Rule: 4️⃣ 规则上下文<br/>（AGENTS.md / 团队规范）
    Feedback: 5️⃣ 反馈上下文<br/>（测试 / 报错 / 审查）

    Task --> Project: 决定方向
    Project --> Local: 决定工作方式
    Local --> Rule: 决定具体怎么改
    Rule --> Feedback: 决定不能做什么
    Feedback --> Task: 决定下一步调整

    note right of Task: 来自你的提示词
    note right of Project: 来自 README / package.json / 目录
    note right of Local: 来自 Codex 主动读文件
    note right of Rule: 来自 AGENTS.md 等规则文件
    note right of Feedback: 来自命令运行结果

💡 5 层合起来才是 Codex 真正的"工作现场"。少哪一层，Codex 就在哪一层"靠猜"。

后面 §🎯 给上下文的 4 步法、§📜 AGENTS.md 章节会逐层落地。

🤔 为什么 Codex 经常"乱改"？

新手抱怨最多的是「Codex 乱改」。但拆开看，"乱改"几乎都是上下文缺失的症状：

flowchart LR
    A1[范围缺失] -->|"优化登录体验"| B1[改 UI / API / 路由 / 状态<br/>全部都改]
    A2[禁止事项缺失] -->|"没说不能装新依赖"| B2[安装第三方表单库]
    A3[验收标准缺失] -->|"没说怎么算完成"| B3[跑个不相关测试就交差]
    A4[项目规则缺失] -->|"没说项目用 pnpm"| B4[执行 npm install<br/>污染 lock 文件]

    style A1 fill:#fee2e2,stroke:#ef4444
    style A2 fill:#fee2e2,stroke:#ef4444
    style A3 fill:#fee2e2,stroke:#ef4444
    style A4 fill:#fee2e2,stroke:#ef4444

🎯 解决"乱改"不是骂它"别乱改"，而是把缺失的上下文补回去。

📐 上下文质量的 3 个维度：怎么算"好上下文"？

不是堆得越多越好。好上下文同时满足 3 个维度。先看「真实性 × 相关性」的 2×2 矩阵：

💡 右上角才是你想要的。其他三格各有各的麻烦，最危险的是左下→左上的高危误导（看着相关其实假）。

⚠️ 3 维度排序：真实 > 相关 > 时效。 真实但跑题，至少不会带偏方向；不真实即使相关，也会让 Codex 朝错方向加速。

🎯 怎么给 Codex 好上下文？4 步法

不要一上来直接让 Codex 改代码。下面 4 步是稳妥顺序：

第 1 步 · 让它画地图

第一次进入项目，先要项目级地图：

请阅读当前项目，不要修改文件。
请输出：
- 项目用途
- 技术栈
- 主要目录职责
- 启动和测试命令
- 你认为最重要的 5 个文件
- 哪些是确认的、哪些只是推测

第 2 步 · 让它定位任务

针对具体任务，让它指出相关文件：

我要做：{任务}
请先收集上下文，不要修改文件。
输出：
- 涉及哪些文件、它们的关系
- 还需要我补充什么
- 哪些地方修改风险最高
- 建议的最小修改范围

第 3 步 · 让它分类信息

要求它把已有信息分四类，避免把推测当事实：

请把当前掌握的信息分四类：
- ✅ 事实：从文件 / 命令 / 明确输入确认的
- 💭 推断：基于事实推出的、说明依据
- ❓ 不确定：还不能确认的、会影响任务的
- 🚀 下一步：为确认不确定信息要做什么

第 4 步 · 你确认后才执行

如果 ❓ 不确定项里有关键问题，先问、先查、不动手。

flowchart LR
    Map[1️⃣ 画地图] --> Locate[2️⃣ 定位任务]
    Locate --> Classify[3️⃣ 分类信息]
    Classify --> Check{你审查}
    Check -->|关键不确定| Ask[问 / 查 / 只读分析]
    Check -->|信息齐了| Execute[4️⃣ 执行]
    Ask --> Locate

    style Check fill:#fef3c7,stroke:#f59e0b
    style Execute fill:#dcfce7,stroke:#22c55e

💡 这 4 步都不写代码。听起来慢，实际比"猜了一通改完再回滚"快得多。

📜 AGENTS.md：项目门口的工作说明

新手最强大的杠杆是 AGENTS.md（Codex 的项目规则文件）。写一次，长期生效，不用每次提示词重复说。

它是什么？

AGENTS.md 是面向编程 Agent（智能代理）的开放格式，类似给 Agent 看的 README。规范由 OpenAI Codex 与 Cursor、Amp、Jules、Factory 等共同支持，目前由 Linux Foundation 下的 Agentic AI Foundation 维护。

Codex 怎么读它？（指令链 / instruction chain）

Codex 启动时按"全局 → 项目根 → 当前目录"逐层串联：

flowchart TB
    G["🌐 全局<br/>~/.codex/AGENTS.md<br/>（或 AGENTS.override.md）"]
    P["📁 项目根<br/>repo/AGENTS.md"]
    S["📂 子目录<br/>repo/src/AGENTS.md"]
    C["📍 当前目录<br/>repo/src/feature/AGENTS.md"]

    G --> P --> S --> C --> Final["🎯 最终指令链<br/>越靠近 cwd 优先级越高"]

    style Final fill:#dcfce7,stroke:#22c55e,stroke-width:2px

📖 来源：OpenAI 官方文档 · Custom instructions with AGENTS.md、配置参考

该写什么进 AGENTS.md？

✅ 适合：
- 启动 / 测试 / 构建命令（pnpm dev / pnpm test ...）
- 包管理器（用 pnpm，不要用 npm）
- 目录职责（src/api 是后端、src/ui 是前端）
- 编码风格（用 TypeScript 严格模式）
- 禁止事项（不要改 db migration、不要碰 .env）
- 验收要求（提交前必须 pnpm test 通过）

❌ 不适合：
- 一次性临时要求（写在本次提示词里）
- 商业秘密 / 个人偏好（私有，别开源）
- 大段产品文档（超过 32 KiB 会被截断）
- 时效性强的事实（很快过期）

⚠️ 超过 32 KiB 怎么办？ 拆到子目录下分别写，或调高 project_doc_max_bytes 上限（但更建议拆分）。

⚖️ 上下文 vs 记忆 vs 提示词：边界在哪？

很多新手把这三个混用。其实它们生命周期完全不同：

🎯 判断口诀：

• 这个项目里每个人都该知道？→ 写 AGENTS.md
• 这次任务临时要这样？→ 写当前提示词
• 跨项目都要遵守？→ 写记忆 / 全局 ~/.codex/AGENTS.md
• 当前这一步的证据？→ 命令输出 / 报错粘贴

🎓 3 个上下文管理习惯

① 让它先分类，再行动

把「事实 / 推断 / 不确定 / 下一步」四分要求写进每个复杂任务的提示词：

请把当前信息分四类输出：
✅ 事实  /  💭 推断  /  ❓ 不确定  /  🚀 下一步

➡️ 显著减少幻觉（hallucination，AI 把推测当事实输出）。

② 上下文不足时停下来，不要硬上

如果缺少关键信息，不要猜，不要修改文件。
先列出缺口和需要确认的问题。

➡️ 涉及支付 / 数据迁移 / 权限 / 删除 / 生产发布时尤其重要 —— 缺上下文硬做的代价远大于停下来问的代价。

③ 给读取预算和阶段

请先读取最相关的 10 个文件。
如果需要扩大范围，先说明原因。

或者分阶段：

第一阶段只建立目录地图。
第二阶段追踪具体功能。
第三阶段才提出修改方案。

➡️ 防止 Codex 一上来全库扫描几十个文件，拿到一堆相似 / 旧 / 生成文件后判断变慢。

🚫 常见误解 → ✅ 正确理解

🔍 想再深一层（点击展开）

请不要把我的描述都当成事实。
请用项目文件验证关键假设，并标出哪些是确认的、哪些仍是推测。

sequenceDiagram
    participant 你
    participant Codex
    participant 项目
<br />
    你->>Codex: 点击保存按钮没反应
    Codex->>你: 5 个可能原因都猜一遍（噪音）
<br />
    Note over 你,Codex: ⬇️ 加上下文 ⬇️
<br />
    你->>Codex: + 页面是 /settings/profile
    Codex->>项目: 读 ProfileForm.tsx
    Codex->>你: 找到 onSubmit handler
<br />
    你->>Codex: + 控制台报 Cannot read 'email' of undefined
    Codex->>你: 方向变了：数据缺字段，不是事件没绑
<br />
    你->>Codex: + 昨天把 /api/user 改成 /api/profile
    Codex->>项目: 对比新 API 返回结构
    Codex->>你: 根因：profile 接口返回结构变化，<br/>前端仍按旧字段读取

请为下面任务建立高质量上下文，不要修改文件。
<br />
任务：
{写任务}
<br />
请按下面格式输出：
<br />
一、确认事实
- 只写从文件 / 命令输出 / 明确提示中确认的信息
- 每条标出来源（文件路径 / 命令名）
<br />
二、合理推断
- 写根据事实推断出的信息
- 每条说明依据
<br />
三、不确定信息
- 写还不能确认但会影响任务的信息
<br />
四、需要补充的问题
- 问最关键的 3 到 5 个
<br />
五、建议下一步
- 上下文足够：给计划
- 上下文不足：先列缺口，不动手

📝 本章自检

✅ 过关标准（这次放在折叠块里）：

📚 下一篇

• ➡️ 04 · AGENTS.md 为什么能改变 Codex 行为 —— 把这一篇里 AGENTS.md 那段展开成完整方法
• 📖 编写项目规则文件
• ⚙️ 配置 Codex 基础选项
• 🧠 使用记忆能力