Day 15: 多 Agent 協同工作流 (Multi-Agent Workflows)：觀念介紹與架構設計 (Multi-Agent Workflow Architecture)

本日核心價值 (Core Focus): 用 Planner → Implementer → Tester → Reviewer 的閘道與共享 artifacts/，說明何時該拆 Codex subagent、何時不該拆，並讓 Implementer 可寫、Reviewer 唯讀，以控制權限與 token 成本。

概念說明與實戰情境 (Overview)

單次 codex exec 適合「一個契約、一個檔案、一次驗證」。當任務同時包含規劃、改程式、補測試、資安審查時，把四件事塞進同一個可寫 session，模型容易邊審邊改、finding 對不上 diff。多 Agent 不是比較聰明，而是分工與權限：Planner 產出機器可讀的 plan.json；Implementer 只實作計畫內檔案；Tester 跑測試並留下報告；Reviewer 對照 Day 12 的 REVIEW.md 做閘道。官方 Codex 可用 subagent / custom agents：子代理預設繼承父層 sandbox，但可在 agent 檔覆寫 sandbox_mode。Implementer 用 workspace-write，Reviewer 用 read-only。每個 subagent 都有自己的模型與工具迴圈，token 與延遲會疊加，所以簡單任務不要拆。

關鍵操作與範例 (Implementation & Example)

四個角色與產物固定，避免口頭交接：

順序不要倒過來：沒有計畫就實作，Reviewer 會對空氣審查。

{
  "goal": "Accept flat user_id on POST /orders and keep Decimal pricing",
  "files_in_scope": ["app/orders.py", "tests/test_create_order.py"],
  "files_out_of_scope": ["pricing.py", "docs/api.md"],
  "acceptance": [
    "create_order reads user_id without KeyError",
    "pytest -q tests/test_create_order.py passes",
    "REVIEW.md checklist has no new Critical"
  ],
  "review_gate": "block-merge-on-critical-or-high"
}

sequenceDiagram
    participant P as Planner
    participant I as Implementer
    participant T as Tester
    participant R as Reviewer
    P->>P: 寫入 artifacts/plan.json
    P->>I: 只實作 files_in_scope
    I->>I: workspace-write 改程式
    I->>T: 變更檔清單
    T->>T: 寫測試並執行 pytest
    T->>R: artifacts/test-report.md
    R->>R: read-only 對照 REVIEW.md
    alt 有 Critical 或 High
        R->>I: artifacts/review.md 退回
        I->>T: 最小補丁後重跑測試
    else 放行
        R->>P: gate=pass
    end

Codex 概念對應（不要把四個角色都做成會改生產程式的 worker）：

• 內建 worker：偏實作與修復，適合 Implementer。
• 內建 explorer：偏唯讀探索，適合 Planner 蒐證。
• 自訂 reviewer：官方示例把 sandbox_mode = "read-only" 寫在 .codex/agents/reviewer.toml。

# .codex/agents/implementer.toml
name = "implementer"
description = "Apply plan.json with the smallest source change."
sandbox_mode = "workspace-write"
developer_instructions = """
Read artifacts/plan.json first.
Only edit files_in_scope. Do not expand the task.
After edits, stop; let the tester agent run pytest.
"""

# .codex/agents/reviewer.toml
name = "reviewer"
description = "PR reviewer: correctness, security smells, tests."
sandbox_mode = "read-only"
developer_instructions = """
Follow REVIEW.md.
Emit Severity table Critical/High/Medium with file evidence.
Do not modify application source.
Do not write exploit payloads.
"""

父層 Prompt 要寫清「誰先誰後、產物放哪」，否則會平行亂改同一檔：

Use subagents. Do not do all roles in the parent thread.

1) Planner (read-heavy): write artifacts/plan.json only.
2) Implementer custom agent, sandbox workspace-write: apply the plan.
3) Tester: add/run unit tests; write artifacts/test-report.md with
   command + exit code + failing assertion excerpts (no full logs).
4) Reviewer custom agent, sandbox read-only: review the diff using REVIEW.md.
   Gate: any Critical or High blocks. Return artifacts/review.md.

Shared folder: artifacts/. Do not duplicate the plan inside chat prose.
If the task is a one-line rename, do NOT spawn subagents.

何時不要用多 Agent（先看這張表再決定要不要 spawn）：

官方文件也提醒：subagent workflow 會增加用量，因為每個子代理做自己的模型與工具工作。架構上要設 agents.max_concurrent_threads_per_session，並禁止「四個 agent 同時寫 orders.py」。共享資料夾是唯一真相：聊天摘要會過期，artifacts/plan.json 不會。

成本可先用「次數」估：四個角色若各自讀一遍 AGENTS.md、REVIEW.md 與相關原始碼，光是重複 ingest 就接近四次單代理對話。Planner 產出的 JSON 應短；把長討論留在父層一次，不要讓 Reviewer 再讀完整需求散文。平行只適合互不寫入同一檔的探索（例如 explorer 找呼叫點、docs 核對 OpenAPI），Implementer 與 Reviewer 必須串列，否則審查的 diff 不是最終 diff。合併權仍在人類：gate=pass 只表示清單上沒有 Critical/High，不表示可以略過 PR。

權限是架構的一部分，不是事後再加。Reviewer 若繼承父層的 workspace-write，就可能在審查時直接改 SQL——Day 12 要避免的「邊審邊改」會再出現。Implementer 若只拿到 read-only，則會交一份「建議 patch」卻沒落地，Tester 對空 repo 跑測試。父層互動 session 的 /permissions 會影響子代理繼承；非互動 codex exec 要把 sandbox 與角色寫進 custom agent 檔，不要靠口頭。

明日（Day 16）會把 Tester 紅燈自動送回 Implementer，形成自我修復迴圈。本日先把閘道與產物定住：沒有 review.md 的 pass，就不算完成。Tester 報告只要命令、exit code、失敗 assert 摘錄；不要把整份 pytest 輸出貼進 Reviewer 的 context，否則 token 會被 traceback 填滿，嚴重度表反而變短。

實務啟動順序是：父層先寫 artifacts/ 目錄約定，再 spawn。沒有目錄就先建空的 plan.json 模板，避免 Implementer 與 Planner 搶著建立不同檔名。Day 16 會把 Tester 紅燈自動送回 Implementer；本日若 Reviewer 已標 High，不要在同一輪讓 Tester 再發明新測試範圍，否則自我修復會修錯檔。

注意事項與常見失敗 (Pitfalls)

• 為展示而拆四個 agent：一次改一個函式名稱卻開齊 Planner/Reviewer。修法：上表「不要用」優先於「可以拆」。
• 子代理沒有共享 artifacts/：各自在對話裡重述計畫，scope 漂移。修法：計畫只以 JSON 檔為準。
• Reviewer 可寫原始碼：審查與修復混在一起。修法：sandbox_mode = "read-only"，補丁另開 Implementer。
• 忽略 token：平行三個高 reasoning 審查。修法：預設串列閘道；平行僅用於互不共享寫入的探索。
• 父層 sandbox 過寬：custom agent 檔的 sandbox 在某些流程仍可能被父層 runtime override。修法：非互動審查用 codex exec --sandbox read-only 跑 Reviewer；實作用另一趟 workspace-write。

本日總結 (Takeaways)

• 角色是 Planner / Implementer / Tester / Reviewer，順序是 plan JSON → code → tests → review gate。
• 簡單任務不要多 Agent；拆分的理由是權限隔離與可檢查產物，不是「比較 AI」。
• 共享 artifacts/：plan.json、test-report.md、review.md。
• Codex：Implementer workspace-write，Reviewer read-only；子代理預設繼承父層，需在 custom agent 覆寫。
• 每個 subagent 都計費；先估成本再平行。

明日預告 (Next)

明天進入 Codex 自我修復機制：建立 Self-Correction Loop 讓 AI 自動跑 Test 並修復 Bug，把本日 Tester 的紅燈證據接回 Implementer，在有限次數內收斂，而不是無限重試。