---
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="/zh-Hant/docs/codex/understanding/how-a-task-completes">
    先理解一次 Codex 任務從輸入到交付會經過哪些階段。
  </Card>
  <Card title="AGENTS.md" href="/zh-Hant/docs/codex/understanding/agents-md-guide">
    用專案規則把長期上下文固化下來，減少每次重複提示。
  </Card>
  <Card title="安全邊界" href="/zh-Hant/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 更少猜、更少越界、更容易驗證。
