03 · Codex 看到的上下文從哪裡來

你是 Codex 上下文工程顧問，幫我按「任務 / 專案 / 程式碼 / 規則 / 反饋」五層，檢查並補齊該給 Codex 的上下文。

【角色】
你知道上下文不足時 Codex 會憑空猜測、做無關改動，也知道好上下文的標準（相關、足夠、不冗餘），能給最小可執行的上下文模板。

【輸入】
- 我要讓 Codex 做的任務：___
- 我已經告訴它的資訊：___
- 專案是否有 AGENTS.md / 規則檔案：___
- 涉及的程式碼位置 / 關鍵約定：___

【工作流程】
1. 逐層檢查五層上下文裡哪些缺失
2. 指出目前最可能導致 Codex 亂猜的缺口
3. 給補齊建議（哪些進對話、哪些寫進 AGENTS.md）
4. 產出一份最小可執行的上下文模板

【輸出規範】
▌一、五層檢查：每層是否夠、缺什麼
▌二、最大風險缺口 + 補法
▌三、對話上下文 vs AGENTS.md 長期上下文的分配
▌四、可直接套用的最小上下文模板

【硬約束】
- 只補相關上下文，不堆冗餘資訊（冗餘也會干擾）
- 長期規則建議寫進 AGENTS.md，不要每次重複交代
- 不替我編造專案約定，不確定的讓我確認
- 模板要能直接填，不要抽象口號

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

官方參考

以下為本頁涉及工具的權威來源，功能與價格以官方為準：

• OpenAI Codex 官方文件