# Codex Agent Roles

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

## 使用原則

- 先由主 agent 直接處理任務。
- 只有在任務明確分流、風險高、或需要獨立驗證時，才套用角色分工思維。
- 角色說明用於規劃與 reviewer 心智模型，不代表一定要建立 12 個常駐子代理。
- 若任務可以由一位 Codex 在單一上下文完成，優先不要切分。
- AI 自動化任務若使用 12 角色思維，收尾必須至少經過 `critic`，並更新 ADR / memory / SOT / guide 的必要索引。

## 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`
- AI 自動化閉環任務收尾讀 `docs/guides/ai_automation_session_sop.md`

## 來源註記

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