ask-codex

ask-codex 是做什麼的？

用於呼叫 OpenAI 的編碼代理 Codex 進行 codex exec（非互動模式），以進行設計與實作諮詢、深度調查以及程式碼審查的技能。

Codex 傾向於堅持不懈地調查以提高準確性，因此適合做為第二視角或用於需要高準確度的深度調查。

Codex 每次皆以冷啟動方式執行，對當前的對話、計劃以及先前的調查結果一無所知。 前提、意圖、限制與相關檔案必須在每次的提示中明確交代（請參閱下方「任務陳述的撰寫方式」與範例）。

前提

• 已安裝並驗證 codex CLI（可透過 codex --version 確認）。
• 若驗證過期，則需要進行 Codex 端的設定，請告知使用者。

執行前

在呼叫 Codex 之前，應先簡短告知使用者要諮詢的主題。無需等待批准，告知後即可直接執行。

基本呼叫模式

Codex 是唯讀的上級審查者，因此預設使用 -s read-only。為避免 shell 跳脫問題，提示應透過 stdin 傳遞（codex exec -）

核心做法有兩點：

1. 在呼叫 Codex 的同一命令內完成回答的取出（cat）。使用 OUT=$(mktemp …) 建立的 $OUT 會在下一次 shell 呼叫（不同的 shell）中消失，因此若後續使用 Read 來讀取，將會遺失路徑。在同一命令內進行 cat 即可在不假設任何行為的情況下可靠地取得回答。
2. 不要將 Codex 本身的 stdout/stderr 流入上下文。Codex 會將進度日誌、標頭、警告、hook、結尾回顯以及 tokens used 輸出到 stderr，而僅將最終訊息輸出到 stdout 與 -o 檔案（「做了什麼 / 想了什麼」全部在 stderr 端）。由於我們只需要結論，因此捨棄 stdout，並將 stderr 暫存到臨時檔案，僅在失敗時顯示。這樣 tool result 只會包含 cat "$OUT" 的最終訊息，而當驗證過期、無效旗標等錯誤發生時，則可在失敗時看到原因。

根據用途分為兩種正規食譜。

A. 簡短諮詢與小型審查（前景）

回答（僅最終訊息）會回傳到 shell 執行的 tool result 中。無需額外的 Read。

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' "$PROMPT" | codex exec - -s read-only -C <DIR> -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
cat "$OUT"

B. 耗時較長的呼叫（背景）

codex exec 可能耗時數分鐘，前景執行可能會因環境因素而被中斷。對於深度調查或使用 codex exec review 進行程式碼審查等耗時較長的任務，應透過 harness 的背景執行機制來投遞（指定方式由 harness 端決定）。命令主體根據用途選擇 codex exec -（諮詢/調查）或 codex exec review（diff 審查，詳見下文）。

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' "$PROMPT" | codex exec - -s read-only -C <DIR> -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

完成後 harness 會發出完成通知，該背景輸出中會包含 === ANSWER === 之後的回答。請 Read 該輸出（若內容較長，可 Grep === ANSWER === 之後的內容）。請勿自行實作使用 sleep / pgrep 進行輪詢的迴圈（harness 會通知完成）。

旗標的意義

• codex exec -: 從 stdin 讀取提示。可安全地傳遞長文、程式碼區塊與特殊字元。
• -s read-only: 僅允許讀取。此技能預設加上此旗標（因為是提供建議/審查的角色，無需寫入）。這並非 CLI/config 本身的預設值。僅適用於 codex exec，不適用於 codex exec review（加上會報錯）。
• -C <DIR>: codex exec 的工作根目錄。指向要調查/審查的儲存庫。省略時為當前目錄。codex exec review 沒有 -C，因此 review 需在同一命令內先 cd <DIR> 再呼叫（詳見下文）。
• -o <FILE>: 僅將 Codex 的最終訊息寫入此檔案。僅在完成時寫入（執行期間為空），請勿在完成前讀取。正規食譜中以此作為回答的來源。
• stdout: Codex 也會將最終訊息輸出到 stdout，但正規食譜中從 -o 取得，因此用 >/dev/null 捨棄（避免重複顯示以節省上下文）。
• stderr: 會輸出進度日誌、標頭、警告、hook、結尾回顯、tokens used，以及錯誤（驗證過期、無效旗標、repo check 失敗等）。若簡單地用 2>/dev/null 捨棄，當 cat "$OUT" 為空時將無法得知原因，因此將其暫存到臨時檔案（$ERR），僅在失敗時顯示 cat "$ERR"。成功時不會進入上下文，僅在失敗時能看到原因。
• mktemp /tmp/codex_answer.XXXXXX.txt: 結尾的 XXXXXX 會被隨機替換，產生不衝突的唯一路徑。即使並行投遞多個任務，每次呼叫都會產生不同的 mktemp。

通常不需要的選項

• --skip-git-repo-check: 僅在 git 儲存庫之外執行時需要。在儲存庫內則不要加上。
• -s workspace-write: 僅在需要讓 Codex 編輯時使用。此技能的角色（唯讀審查者）不適用，原則上不使用。

模型指定

若想使用特定模型，可加上 -m <MODEL>（例如: -m gpt-5.5）。未指定時則遵循 Codex 的設定預設。請勿隨意指定，僅在使用者要求時才加上。

網路搜尋

若 ~/.codex/config.toml 中設定了 web_search = "live"，Codex 即可使用網路搜尋。網路搜尋是 Responses 的原生工具，因此 -s read-only（僅限制 shell 執行）不會阻止它。若想確認函式庫、API、CLI 的具體規格，請在提示中明確要求「用網路搜尋確認官方文件」。codex exec 本身沒有 --search 旗標，而是透過 config 中的 web_search 控制。

顯示說明

可使用 codex exec -h 顯示說明。

任務陳述的撰寫方式

LLM 擅長遵循範例，因此請直接將下方各範例中傳遞給 printf 的提示主體視為良好任務陳述的範本。將一次諮詢限定於單一判斷 / 審查 / 計劃 / 調查，並在單一提示中包含以下內容：

• 意圖・背景・限制: Codex 是冷啟動，因此務必寫明想做什麼、為什麼以及前提
• 相關檔案: 使用 @path/to/file 內聯方式標示。若希望查看當前變更，請明確要求「用 git diff 確認差異」
• 具體寫明關注點 / 想比較的替代方案 / 希望尋找的風險
• 指定輸出形式（例如：排序後的風險 / 權衡表 / 建議的計劃變更等）
• 寫明要忽略的項目（例如：命名、格式化）以防止範圍蔓延
• 若需確認外部規格，請明確要求「用網路搜尋確認官方文件」
• 審查時應要求先比對意圖 → 再檢查實作（先根據意圖判斷是否合理，再檢查實作）

提示主體應使用單引號包圍 printf '%s' '…'，這樣主體中的 $ 和反引號就不會被 shell 解讀，較為安全（僅當主體包含 ASCII 的 ' 時才需要改用其他包圍方式）。

按用途分類的使用範例

1. 第二意見・多方案比較（食譜 A）

用於設計/實作決策的第二意見。具體寫明要比較的方案、限制與輸出形式，有助於提升回答品質。

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' '意圖: 想決定認證權杖的重新整理方式。目前每次 API 呼叫時都會檢查期限並同步重新整理（@src/auth/client.ts），在高頻並行請求下會發生雙重重整。

想比較的方案:
(1) 共用重新整理中的 Promise 以統一化
(2) 在期限前於背景主動更新
(3) 收到 401 後僅重新整理一次並重試

限制: 必須同時適用於 SSR 與 CSR。不想增加新的函式庫。
輸出: 以 correctness / 複雜度 / 失敗模式 為欄位的權衡表、建議的預設方案與備援方案、以及在何種條件下應換用其他方案。忽略命名與格式化。' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
cat "$OUT"

2. 程式碼審查

重要限制: codex exec review 的範圍旗標（--uncommitted / --base / --commit）無法與自訂指示 PROMPT（無論是透過 - 的 stdin 還是位置引數）併用（已於 codex 0.142.4 確認。併用會導致 error: the argument '--uncommitted' cannot be used with '[PROMPT]' 並立即失敗）。因此根據用途分為兩種情況。

2a. 傳達審查觀點與意圖的審查（此技能的主要用途與建議方式）: 由於無法同時使用範圍旗標與觀點指示，請改用 codex exec -（食譜 A/B），並在提示中要求確認 git diff 等方式來指定範圍。這樣可以直接使用 -s read-only / -C / stdin，也能避免跳脫問題。

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' '意圖: 此變更應僅在抑制閒置通知音時改變行為，不應影響使用者輸入要求音的播放。請用 git diff（必要時也可用 git diff --cached 或 untracked）確認未提交的變更。先根據意圖判斷是否合理，再檢查實作。
關注點: 條件反轉、預設值變化、client/server 間語意的落差。
輸出: 依序為 建議 → 附有證據的發現 → 未經驗證的假設。忽略命名與格式化。' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

2b. 不指定觀點的純粹差異審查: 若不需要自訂指示，可直接使用 codex exec review 的範圍旗標（因為未加上 PROMPT，所以不違反上述限制）。與 codex exec 不同，此模式沒有 -C 與 -s 選項，因此請先 cd 到目標儲存庫再呼叫。

OUT=$(mktemp /tmp/codex_review.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
cd /path/to/repo || exit 1
codex exec review --uncommitted -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

範圍旗標的替換（替換上面 codex exec review … 一行。皆不加 PROMPT）:

codex exec review --uncommitted -o "$OUT" >/dev/null 2>"$ERR"   # 未提交（staged + unstaged + untracked）
codex exec review --base main   -o "$OUT" >/dev/null 2>"$ERR"   # 與基礎分支的差異
codex exec review --commit <SHA> -o "$OUT" >/dev/null 2>"$ERR"  # 特定提交

• 需要傳達審查觀點的審查請使用 2a（codex exec - + git diff）。範圍旗標與自訂指示無法併用。
• review 必須在目標儲存庫內執行（因為沒有 -C，所以需先 cd 再呼叫）。若在儲存庫之外，可以使用 --skip-git-repo-check，但若沒有要審查的 diff 則無意義。

3. 計劃・遷移的合理性驗證（食譜 B）

在實作前對計劃/遷移步驟進行壓力測試，找出應在著手前解決的落差。在唯讀模式下確認現有程式碼的契約。

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' '請審查實作前的計劃，僅列出應在開始編碼前解決的落差。
計劃: 當事件同步被伺服器拒絕時，設定 repair_required 旗標，傳送壓縮的快照，僅在伺服器確認整合序列後才恢復增量事件。
相關: @src/sync/event-syncer.ts @src/db/sync-state.ts @api/types.ts。
請先閱讀現有程式碼以確認目前的契約，再進行評估。
關注點: schema 相容性、快照的大小上限、恢復序列的邊界條件、backfill/migration 的影響、測試不足。
輸出: 僅列出著手前必要的計劃變更，並加上一句「是否可以安全地就此實作」的判定。' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

4. 深度調查（食譜 B）

針對錯誤、測試失敗的根本原因、競爭條件、過期快取等進行堅持不懈的調查。若能附上可驗證的成功條件，更能發揮 Codex 深度調查的特性。由於耗時較長，請使用背景執行。

OUT=$(mktemp /tmp/codex_answer.XXXXXX.txt)
ERR=$(mktemp /tmp/codex_err.XXXXXX.txt)
printf '%s' '測試 foo_test.go 中的 TestBar 在 CI 中偶爾會失敗。請調查根本原因。
成功條件: 以 檔案:行 的形式定位重現條件與原因位置，並提出最小的修正方案。
若懷疑是外部函式庫所致，請用網路搜尋確認該函式庫的官方文件。' \
  | codex exec - -s read-only -C /path/to/repo -o "$OUT" >/dev/null 2>"$ERR" \
  || { echo "codex failed:"; cat "$ERR"; exit 1; }
echo "=== ANSWER ==="; cat "$OUT"

結果的處理

• 從回答（食譜 A 為 tool result，食譜 B 為完成通知後的背景輸出）中提取重點告知使用者。若內容較長，請摘要並引用重要的指出事項。
• Codex 有時會提出極端防禦性的建議（例如過度的向後相容性考量）。請自行判斷哪些指出事項應採納、哪些應拒絕。不要全盤接受，僅採納合理的部分。