ewoooc/docs/guides/codex_agent_roles.md

Codex Agent Roles

目的：把本專案歷史上的 12 位 Agent 工作執掌，改寫成符合 Codex 官方建議的角色矩陣。 原則：角色是「思考與分工模板」，不是每次 session 都必須全文載入的正式入口。

使用原則

• 先由主 agent 直接處理任務。
• 只有在任務明確分流、風險高、或需要獨立驗證時，才套用角色分工思維。
• 角色說明用於規劃與 reviewer 心智模型，不代表一定要建立 12 個常駐子代理。
• 若任務可以由一位 Codex 在單一上下文完成，優先不要切分。

12 角色矩陣

角色	核心職掌	適用情境	不該濫用
planner	先切問題、定順序、收斂風險與交付邊界	多階段任務、重構、跨檔案修復、部署前盤點	小修小補也先開長計畫
critic	專注找 regression、風險、遺漏測試、隱性副作用	大改後 review、上線前、關鍵路由與資料流改動	把 critic 當實作者，或在還沒成形前反覆 review
debugger	追根因、讀 log、縮小故障範圍、建立最小重現	線上異常、排程失敗、Telegram 斷訊、快取錯亂	還沒看 log 就直接改碼
fullstack-engineer	在既有架構下完成端到端功能或修復	一般功能開發、API + template + service 串接	用來做純探索、純審查或超大型拆遷規劃
refactor-specialist	拆大檔、去重、解耦、模組化收尾	app.py 拆分、Blueprint 清理、模板重整	在需求不明或測試不足時先大搬家
migration-engineer	處理 schema、資料轉換、路由遷移、兼容期策略	migration、欄位對齊、callback prefix、資料搬遷	跳過回滾與相容性設計直接硬切
onboarder	幫新 session 或新協作者快速讀懂脈絡	新人接手、長期專案重啟、需要入口整理	把 onboarding 文件當正式治理真相來源
tool-expert	決定用哪個工具最穩、最省成本、最可驗證	shell、hook、CI/CD、MCP、部署流程選型	用工具炫技取代簡單做法
vuln-verifier	站在攻擊者角度驗證防線是否真能擋住	hook、防注入、secret 掃描、權限邊界	只有猜測沒有驗證就宣稱安全
web-researcher	補官方文件、規格、外部事實、版本現況	API/SDK 變更、平台規則、供應商文件核對	拿次級來源取代官方來源，或把外部研究帶入所有 session
db-expert	聚焦資料模型、查詢、索引、交易與 ORM 對齊	漏表、慢查詢、schema drift、pgvector、create_all 問題	把所有 bug 都歸咎資料庫
explorer	快速查碼、定位檔案、回答具體 codebase 問題	「這段在哪裡」、「誰在呼叫它」、「有哪些 duplicate route」	與主實作重複探索同一題，浪費 context

Codex 化映射

歷史角色	Codex 中的建議用法
planner	先做本地高階規劃；必要時只輸出簡短 plan
critic	以 code review mindset 檢查 bug、風險、缺測
debugger	先看 log、traceback、runtime 訊號，再改碼
fullstack-engineer	預設主實作者角色
refactor-specialist	僅在結構性清理值得付出風險時啟用
migration-engineer	與 DB / API / callback 相容性變更綁定使用
onboarder	產出入口索引、接手說明、交接文檔
tool-expert	幫忙選 shell / script / CI / browser / MCP 的最小可行解
vuln-verifier	對安全修補做 adversarial 驗證
web-researcher	只在需要最新外部事實時查官方來源
db-expert	聚焦 schema / ORM / SQL / index / transaction
explorer	對應 Codex 的 codebase-specific explorer 心智模型

建議派工順序

1. 一般功能

1. planner
2. fullstack-engineer
3. critic

2. 線上故障

1. debugger
2. fullstack-engineer
3. critic
4. vuln-verifier（若涉及安全）

3. 大型重構

1. planner
2. explorer
3. refactor-specialist
4. critic

4. DB / migration 類

1. planner
2. db-expert
3. migration-engineer
4. critic

5. 外部規格變動

1. web-researcher
2. tool-expert
3. fullstack-engineer
4. critic

最小入口版

若要把這份文件壓縮成最省 token 的心法，只要記住：

• 先 planner
• 出問題先 debugger
• 做功能用 fullstack-engineer
• 拆結構找 refactor-specialist
• 動 DB 找 db-expert 或 migration-engineer
• 上線前一定要有 critic
• 涉及安全加 vuln-verifier
• 需要最新外部事實才叫 web-researcher

來源註記

• 本文件整理自本 repo 歷史文件中可確認的角色名稱與職掌脈絡。
• 若未來還原到更多舊 agent 定義，可再細化，但正式入口仍應維持精簡。