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 更少猜、更少越界、更容易驗證。