Codex 看到的內容都有容量限制

開發者把錯誤紀錄、整個專案、需求文件與多輪對話交給 Codex 時，這些資訊都會進入 AI 用來推測的上下文（Context）中。

上下文還可能包含 AGENTS.md、先前訊息、Codex 讀取的檔案，以及測試或命令產生的輸出。這些內容共同構成 Codex 當下理解任務與進行分析的工作材料。

上下文視窗（Context Window）是模型一次能處理的資訊容量，通常以 Token 數量計算。

Token 是模型切分文字的單位，可能是一個字、詞的一部分、標點或程式符號，因此中文字數、程式行數與 Token 數量之間沒有固定換算比例。

提示內容、對話紀錄、檔案內容、工具回傳結果與模型輸出都會占用上下文空間。一次貼入五萬行日誌時，即使內容可以完整顯示在畫面上，大量訊息也可能掩蓋任務目標、第一個錯誤與專案規則。

即使容量還足夠，無關資訊過多仍會增加 Codex 辨識關鍵線索與建立關聯的難度。

今天會使用一個固定錯誤案例。某筆議題同時帶有 bug 與 security 標籤，命令列結果只將它計入 bug，security 顯示為 0。

接下來會整理一份「最小上下文包」，只提供任務目標、相關檔案、關鍵錯誤、測試輸出與 AGENTS.md 規則，讓 Codex 根據這些資訊分析問題原因。

這一輪一樣是會先停在分析階段，不修改程式。

Token 數量與資訊品質是兩件事

Token 可以用來描述模型輸入與輸出的大小，也常作為計算模型使用量的單位。

上下文管理關心的則是有限的上下文視窗中放入哪些資訊。即使還沒有碰到使用額度或費用限制，過長的對話也可能混入過時假設、失敗嘗試與重複輸出，增加 Codex 重新確認現況所需的步驟。

同一份錯誤資訊可以有不同的資訊密度。完整測試日誌可能有數千行，其中真正有助於定位問題的內容，可能只有測試名稱、預期值、實際值、堆疊頂端與執行命令。

依賴安裝訊息、重複警告與成功測試若全部保留，Codex 還需要從大量噪音中找出失敗位置。

程式碼也不需要預先全部放進提示。可以先提供入口檔、相關函式、測試檔與資料範例，再讓 Codex沿著匯入與呼叫關係查看下一層，保留清楚的因果路徑。

一開始就放入整個 src/、test/、建置輸出與套件目錄，名稱相似的檔案與實作會同時進入上下文，增加判讀負擔。

管理 Token 時，可以先判斷一段內容是否會改變 Codex 對問題、修改範圍或驗證方式的判斷。能回答這三件事的資訊應優先進入上下文。其餘內容可以保留在檔案中，等 Codex需要時再讀取指定檔案或區段。

巨大日誌要先縮成可定位的錯誤

命令測試失敗後，先記錄實際執行的命令與結束狀態，再找到第一個與任務相關的失敗。

截取內容包括測試名稱、錯誤訊息、預期值、實際值，以及錯誤前後少量行數。堆疊追蹤可以留下第一個指向專案程式碼的呼叫位置，套件內部重複出現的框架堆疊先省略。

本文案例先將測試輸出整理成下列形式。這段內容說明哪條命令失敗、哪個行為不符合預期，以及問題出現在哪個測試檔。

被省略的內容仍留在原始日誌中，後續需要追查執行環境或其他錯誤時再補充。

執行命令：npm test -- --runInBand
結果：失敗，1 個測試失敗，其餘測試通過

失敗測試：counts an issue in every matching target label
測試位置：test/label-stats.test.js
預期：{ bug: 1, feature: 0, documentation: 0, security: 1 }
實際：{ bug: 1, feature: 0, documentation: 0, security: 0 }

第一個專案堆疊位置：test/label-stats.test.js:42
原始輸出：保存在本機，已省略成功案例與重複框架堆疊

若錯誤可能和執行環境有關，還需要補上作業系統、執行環境版本與相依套件安裝狀態。若單一測試已能穩定重現問題，先維持這組資訊，不需加入其他服務日誌。

後續每增加一段資訊，都應說明它與失敗行為的關係。當某項線索已經排除，也可以從目前的上下文中移除，讓 Codex 繼續聚焦在尚未確認的原因。

檔案要沿著行為路徑選擇

相關檔案可以從可觀察行為往內追。本次的外部行為是命令列顯示錯誤的標籤數量，因此先確認輸出入口、標籤統計函式、失敗測試與使用的測試資料。

package.json 用來確認測試命令，AGENTS.md 提供專案規則。其他檔案等到呼叫路徑出現依賴時再加入。

可以先請 Codex 只做檔案定位，並說明每個檔案與錯誤的關係。開發者抽查路徑與函式名稱後，再整理成上下文包。這能避免把搜尋結果中所有含有 label 的文件、範例與舊程式一起帶入分析。

請針對以下錯誤做唯讀探索：一筆 issue 同時具有 bug 與 security 標籤時，命令列輸出的 security 數量為 0。

請找出命令列輸出入口、標籤統計函式、直接保護此行為的測試、測試資料來源，以及 package.json 中的測試命令。

每項結果附上檔案路徑、函式或測試名稱，以及它和錯誤的關係。
不要修改檔案、安裝套件或執行完整測試。

收到結果後，先確認 Codex 找到的是否為實際執行入口，並檢查測試是否直接驗證多標籤計數。

README 中與功能相關的描述可以作為行為依據，只需保留對應段落與位置，不必把整份文件放進上下文包。

設計文件與議題紀錄也可以用相同方式裁切，只留下會影響問題理解、修改範圍或驗證方式的內容。

建立這次分析需要的最小上下文包

最小上下文包是一份針對單一問題整理的分析材料。每段內容都要有明確用途，也要讓另一位開發者能依照相同資訊重現問題。

建議固定保留五類資料：任務目標、相關檔案、錯誤片段、測試輸出，以及目前生效的 AGENTS.md 規則。

可以先在專案外的暫存筆記整理內容，避免把分析檔誤提交到儲存庫。若團隊需要保存除錯紀錄，再依專案規則放到指定位置。

檔案內容過長時，只記錄路徑、函式名稱與相關行數附近的片段。等到 Codex 需要更多上下游資訊時，再回到原始檔案查找。

# 最小上下文包：多標籤統計遺漏 security

## 任務目標
找出同一筆 issue 具有 bug 與 security 標籤時，security 未被計數的原因。
本輪只分析，不修改檔案。

## 可觀察行為
輸入標籤：bug、security
預期輸出：bug = 1、security = 1
實際輸出：bug = 1、security = 0

## 相關檔案
- 命令列入口：填入已確認的路徑與函式名稱
- 統計邏輯：填入已確認的路徑與函式名稱
- 失敗測試：test/label-stats.test.js，填入測試名稱
- 測試資料：填入 fixture 路徑或內嵌資料位置
- 命令來源：package.json，填入 script 名稱

## 關鍵錯誤與測試輸出
貼入失敗測試、預期值、實際值與第一個專案堆疊位置。
原始日誌保留在本機，需要時再查閱。

## AGENTS.md 規則
貼入和本次分析直接相關的測試命令、禁止修改區域與安全限制。

## 已確認與待確認
已確認：錯誤可由指定測試重現。
待確認：統計函式是否在找到第一個符合標籤後停止檢查。

「待確認」用來區分事實與假設。像是「迴圈提早停止」可以列為需要查證的方向，在讀到相關程式前，不應直接寫成問題原因。

上下文包完成後，再逐項確認檔案路徑存在、測試名稱正確、錯誤內容與實際輸出一致，並確認引用的規則來自目前生效的 AGENTS.md。完成這些檢查後，再把上下文包交給 Codex 進行分析。

用上下文包要求 Codex 分析原因

把整理好的內容交給 Codex 時，要限制分析依據，只使用提供的證據與專案檔案。

提示中可以允許 Codex 沿著已確認的呼叫路徑補讀必要檔案，並要求它在擴大範圍前先說明需要哪些資訊及用途。開發者便能掌握哪些內容被加入上下文，以及新增資訊是否真的有助於定位問題。

請依照下方的「最小上下文包」分析多標籤統計錯誤。

先完成以下工作：
1. 核對可觀察行為、測試輸出與 AGENTS.md 規則。
2. 從命令列入口追到標籤統計函式，說明資料形狀如何變化。
3. 提出目前最有證據支持的原因，附上檔案路徑與函式名稱。
4. 將事實、推論與待確認項目分開。
5. 說明下一步需要查看的最少檔案，或需要執行的最小測試。

本輪只分析，不修改檔案、不安裝套件、不建立提交，也不執行完整測試。

若現有內容不足，先指出缺少哪項證據、需要查看哪個位置，以及這項資訊會用來確認什麼。
不要自行補出尚未從專案中確認的行為。

［在此貼入最小上下文包內容］

可用的分析結果應形成完整的證據鏈。例如先說明測試資料如何表示 bug 與 security 兩個標籤，再追到解析後的資料結構，最後指出統計函式在哪個條件或迴圈中漏掉第二個標籤。

若 Codex 只回覆「迴圈邏輯有問題」，可以要求它補上呼叫端、程式符號、相關條件，以及支持這項判斷的程式位置。

分析完成後，再檢查 Codex 新讀取的內容是否確實幫助確認或排除假設。

只提供重複資訊的檔案，下次整理上下文時可以省略。若分析過程找到新的關鍵限制，例如公開輸出格式不得更動，就把這項限制加入上下文包，並記錄它來自哪個檔案或規則。

長任務要定期留下階段摘要

對話經過多輪探索、測試與修正後，早期內容可能混入已被推翻的假設。

Codex 接近上下文視窗上限時，可以透過上下文壓縮（Compaction）摘要較早的資訊，保留空間繼續工作。壓縮後留下的是摘要，部分檔案細節、錯誤原文與判斷過程可能被省略。

因此可以在每完成一個工作階段後主動整理摘要，不必等到上下文接近上限。

摘要應記錄目前目標、已確認事實、已排除假設、相關檔案、驗證結果與下一步。檔案路徑、函式名稱、命令與關鍵錯誤訊息應保留原文，避免只留下「已找到原因」或「測試正常」這類缺少證據位置的結論。

請整理目前階段摘要，供下一輪工作直接使用。

保留任務目標、已確認事實及證據位置、已排除假設與原因、目前相關檔案、執行過的完整命令與結果、AGENTS.md 限制、尚未確認的風險，以及下一個最小步驟。

刪除重複對話、已被推翻的推測、完整成功日誌與無關檔案內容。
不要把未執行的測試寫成已通過。

開啟新的工作階段時，可以提供這份階段摘要、目前差異與必要檔案，再要求 Codex 先核對現況。

摘要記錄的是前一階段的判斷，程式碼與測試結果仍可能因其他提交而改變。恢復工作時，要重新確認目前分支、工作目錄、未提交差異，以及摘要中引用的關鍵程式位置是否仍然有效。

檢查最小上下文包是否足以重現判斷

完成分析後，先確認 Codex 的結論都有對應證據。它引用的檔案路徑、函式、測試名稱與 AGENTS.md 規則，都應能回到專案中查證。

若結論需要尚未取得的環境資訊，應把缺少的內容列為「待確認」，並記錄需要什麼證據才能完成判斷。

接著可以開啟新的工作階段，只提供最小上下文包，要求 Codex 重述問題、目前證據與下一個驗證步驟。

新工作階段應能說清楚輸入資料、預期輸出、實際輸出、相關程式位置，以及目前缺少哪些證據。

若這些資訊能直接從上下文包取得，代表材料已具備交接所需的資訊。若 Codex 必須重新搜尋大量檔案才能理解問題，就要檢查上下文包是否缺少執行入口、呼叫關係、測試位置或其他關鍵連結。

Token 管理不需要追求每次輸入的精確數量。開發任務可以把重點放在標示每段資料的用途、只截取相關區段、沿著呼叫路徑加入必要資訊，以及定期保存階段摘要。

需要重新查證時，再回到原始程式、文件與日誌取得完整內容，不需要長期把所有資料留在對話中。

這次練習停在原因分析階段。最後應留下經過核對的最小上下文包，以及 Codex 根據現有證據整理出的原因、待確認項目與下一個最小驗證步驟。

程式碼維持原狀，開發者先確認目前對問題的理解與證據是否完整，再決定後續修改方式。