Codex Subagents 實戰：批次生成測試、檢查相容性、翻譯註解

情境是這樣的：你有 30 個工具函式檔案，每個都需要寫單元測試。以前只能一個個來，一天可能都搞不完。現在，30 個檔案可以同時跑，總時間和處理 1 個檔案差不多。

核心機制：一個 CSV，啟動一批 agent

你不需要理解底層怎麼運作，只需要記住這個用法模式：

你準備一個 CSV（每行 = 一個任務）
        ↓
Codex 讀取 CSV，每行啟動一個獨立 agent
        ↓
所有 agent 同時平行工作
        ↓
結果彙總寫回輸出 CSV

你的工作是：準備好 CSV，寫清楚每個 agent 要做什麼。剩下的交給 Codex。

情境一：為整個專案批次產生單元測試

痛點

專案裡有幾十個工具函式，一個個手寫單元測試要花一整天，而且寫到後面品質越來越低。

第一步：產生任務清單

讓 Codex 掃描專案，把要處理的檔案整理成 CSV：

掃描 src/utils/ 目錄下所有 .ts 檔案，
產生一個 CSV 檔案 utils-list.csv，
列：file_path, function_count（該檔案裡匯出的函式數量）

幾秒鐘你就拿到一份清單，列出所有待處理檔案。

第二步：平行產生測試

使用 spawn_agents_on_csv 讀取 utils-list.csv，
對每個檔案路徑啟動一個 agent，執行以下任務：
- 讀取 {file_path} 中的所有匯出函式
- 為每個函式產生對應的 Jest 單元測試
- 測試檔案儲存到 __tests__/{file_path對應路徑}.test.ts
- 涵蓋所有正常輸入、邊界值、異常輸入的 case
完成後輸出結果到 test-generation-results.csv，
包含：file_path, tests_generated, status

30 個檔案平行跑，總耗時和跑 1 個檔案接近。手工一天的活，變成等幾分鐘。

status 欄位的價值不要忽略：哪些檔案成功、哪些失敗，一眼看清楚。失敗的可以單獨重跑，不用全部重來。

情境二：批次檢查 API 相容性

痛點

把 React Query 從 v4 升級到 v5，breaking changes 非常多——useQuery 參數結構變了、isLoading 行為變了、cacheTime 改名了……專案裡幾十個檔案都用了，一個個排查根本不現實。

第一步：找出所有受影響的檔案

用 grep 找出專案中所有 import 了 @tanstack/react-query 的檔案，
產生 rq-files.csv，列：file_path

第二步：平行檢查每個檔案

使用 spawn_agents_on_csv 讀取 rq-files.csv，
對每個檔案啟動一個 agent：
- 檢查該檔案中 React Query 的所有用法
- 對照 v5 的 breaking changes 列表，標出不相容的用法
  （重點檢查：useQuery 參數結構、isLoading→isPending、cacheTime→gcTime）
- 給出具體修改建議

結果輸出到 compat-check.csv：
file_path, incompatible_count, issues（JSON格式）, suggested_fix

跑完你會得到一份完整的相容性報告。incompatible_count 為 0 的檔案不用動，有問題的直接看 suggested_fix，改起來有的放矢。

小貼士：issues 用 JSON 格式存，是為了方便後續再讓 Codex 讀這份 CSV、自動批次修復——可以接著再跑一輪 spawn_agents_on_csv。

情境三：批次翻譯註解

痛點

接手了一個全英文註解的舊專案，主管要求全部漢化。檔案幾十個，手動翻譯是不可能的。

這類任務用兩步 prompt 就能搞定：

產生 files-to-translate.csv，掃描 src/ 下所有有英文註解的檔案。

然後用 spawn_agents_on_csv：
- 讀取每個檔案
- 將所有英文註解翻譯成中文（保持程式碼不變）
- 直接寫回原檔案
- 輸出：file_path, comments_translated, status

程式碼邏輯一行不動，註解全部換成中文。這類機械性批次操作，正是這個模式最適合的情境。

三個使用建議

第一：不佔你本機資源。 所有 agent 跑在 OpenAI 的雲端沙盒裡，不是你的電腦上。CSV 有 100 行也不會同時起 100 個行程把記憶體撐爆——系統會按並發上限排隊執行，你的機器只是發了個指令，剩下的在雲上跑。

第二：先小批量測試。 第一次跑新任務，先在 CSV 裡只放 3 到 5 行，確認輸出格式和品質沒問題，再全量跑。全量跑之前發現問題，代價是調一下 prompt；全量跑完才發現問題，代價是重跑全部。

第三：status 欄位必須要。 每個 agent 彙報自己的完成狀態，是這個模式的核心價值之一。沒有這個欄位，你不知道哪些成功、哪些失敗，出了問題只能全部重來。

小貼士：輸出 CSV 裡除了 status，建議也加一列時間戳或錯誤訊息（比如 error_message），方便定位具體是哪一步出了問題。