Skip to main content

Architecture Journal

codex-skillsmulti-agentworkflow

Codex Subagent Delivery Demo

這個 repo 的主角不是圖書館 CRUD，而是 AI 參與軟體交付時，規格、責任和驗證證據怎麼被固定下來。它用一個小型 Library Admin Console，示範如何把 scenario、需求、架構、API contract、程式碼、測試與 handoff 串成一條可重現的 delivery workflow。

整個設計可以先看成四個目錄之間的關係：

AGENTS.md
  + .codex/agents/       角色與責任邊界
  + .codex/skills/       每個階段的工作方法與檢查清單
  + docs/workflows/      執行中的狀態、阻塞點與 handoff

AGENTS.md 是 repo-level contract；角色檔決定誰負責什麼；skill 決定工作怎麼做；workflow state 則保存這次流程走到哪裡。這四層放在一起，Agent 才能在換角色、換 session 或中斷後繼續工作。

Subagent：把交付責任拆成角色

.codex/config.toml 負責註冊 subagent，.codex/agents/*.toml 則設定每個角色的 prompt 與 context routing。角色檔不包辦完整實作，只定義責任邊界；真正的工程規範交給對應的 skill。

Role主要責任主要交付物
orchestrator判斷目前 stage、安排下一個角色、維護 workflow state、管理 rework loopworkflow state、handoff、next action
SA從 scenario 整理 FR、NFR 與 acceptance criteriaREQ-LIB-001
Archi做 MVP architecture、NFR trade-off 與系統邊界決策ARCH-LIB-001
SD產出 implementation-ready 的 OpenAPI、schema 與 API flowdocs/openapi.yaml、docs/schema/*、docs/api/*
PG拆任務、凍結 FE／BE 邊界、定義交付 gatedelivery task、FE／BE parallel plan
FE / BE依 frozen contract 平行完成前後端實作apps/web/*、apps/api/*
QA執行 E2E／NFR 驗證，必要時把缺陷送回上游QA report、defect feedback

這種拆法讓每個 Agent 只處理自己該做的決策。orchestrator 也不是萬能 Agent，而是根據上游 artifact 和 workflow state 協調下一步的 workflow coordinator。

Skill：把工程方法寫成可重用規範

.codex/skills/ 放的是可重用的工作方法，不是另一組角色名稱。Skill 會定義角色開始前要讀哪些 artifact、可以修改哪些目錄、要產出什麼格式，以及離開這一階段前要執行哪些驗證。

repo 內的 skill 覆蓋幾個主要階段：

  • workflow-orchestration：讀取狀態、判斷 stage、處理 handoff 與 rework。
  • scenario-requirements-writer、architecture-planner：把 scenario 轉成需求、驗收條件與架構決策。
  • sd-docs-producer：產出 OpenAPI、schema、API flow 與 SD handoff。
  • be-development、fe-development、qa-e2e-verifier：分別規範前後端實作、generated code、測試與 E2E 驗證。

這裡的重點是把團隊方法寫成 Agent 可以遵循的 contract。角色設定回答「誰來做」，skill 回答「怎麼做、做到哪裡才算完成」。

Workflow State：讓交接不依賴聊天紀錄

每條 scenario 都有對應的 workflow state，例如 docs/workflows/WF-LIB-001.md。它記錄 workflow metadata、current stage、current objective、各階段狀態、blockers、open questions、FE／BE 平行計畫、QA loop 與 session handoff notes。

流程形狀如下：

S0 Scenario Discovery
  -> S1 SA
  -> S2 Archi
  -> S3 SD
  -> S4 PG
  -> S5A FE || S5B BE
  -> S6 QA
  -> S7 Done

這個 repo 可以用三種方式閱讀同一條流程：逐角色觀察每一站的輸入與輸出，由 orchestrator 根據 state 自動推進，或在 session 中斷後靠 workflow file resume／handoff。source of truth 是 artifact 和 workflow state，不是某一段聊天上下文。

從規格到實作，再回到 QA

SA、Archi 與 SD 先把 requirements、acceptance criteria、architecture、OpenAPI、schema 與 API flow 做成可交接的規格。PG 再凍結 FE／BE 的 task boundary，讓前後端從同一份 contract 平行實作：

Requirements + AC
  -> SA / Archi / SD artifacts
  -> OpenAPI + generator config
  -> spec-ready commit
  -> FE || BE implementation
  -> Unit / Integration tests + API response
  -> QA verification

Backend Skill 讀取凍結的 OpenAPI，產生 Java interface 與 DTO，再在 handwritten 區域完成 Controller、Service、repository adapter、validation 與 error mapping。Frontend 則使用 generated client／model 開發畫面與互動；最後由 unit、integration、API 與 E2E test 提供交付證據。

demo/20260908-qa 已將這條流程完成為可操作的 Library Mini Admin MVP，包含 Java 21、Spring Boot、H2、Liquibase、Vue 3、OpenAPI Generator、Playwright fixture／Page Object／E2E，以及 workflow state、delivery summary 和 QA report。

QA 報告記錄 AC-001～AC-009 全數通過、Chromium 完整 suite 6/6 通過，並在 2 workers 下驗證沒有跨測試資料污染。過程中曾發現多複本借還問題；後端修正 CK_BOOKS_STATUS_MAPPING 後，兩筆借閱可以逐筆歸還，庫存從 1 / 2 回到 2 / 2，狀態恢復為可借閱。這就是 workflow 裡的 rework loop：缺陷證據回到實作角色，修正後再用 targeted test、integration coverage 與完整 E2E 回歸。

QA 判定為 Pass with limitations；pixel-diff、axe／contrast audit、loading／submit-disabled 的獨立斷言與完整 server-log correlation 未納入本次核心 scenario gate。

如何閱讀這個 repo

main 保留學員起始材料、scenario、AGENTS.md、agent／skill 設定與文件模板；demo/20260908-qa 則提供完整規格、實作、測試與 QA 結果。閱讀時先理解角色與 skill，再追 WF-LIB-001 如何串起各階段，最後用 demo branch 對照完整交付物。

專案連結