場景
你接手一個 multi-tenant 專案,系統有 5 個角色(sysadmin / 主委 / 警衛 / 戶長 / 住戶),不同角色有不同 RBAC 權限。你建了 AGENTS.md 派 1 RD + 1 QA,以為這就是 multi-agent team。
然後出事了。
本系列【入門篇】· 給「想知道為什麼」的人
| 這篇談 | 為什麼 multi-agent 工程需要 cycle file workflow + 5 種 agent type |
| 怎麼用 | 8 幕劇 · 第一人稱故事 · 真實踩坑反推 |
| 下一步 | 讀完想看 怎麼做(8-stage SOP / 4 個檔範本 / bootstrap)→ 進階篇 |
本篇路線圖
| 幕 1 | AGENTS 兩角色跑起來 → 局部檢測 + 不會按角色測(第一次嚴重問題) |
| 幕 2 | 要求按角色登入測試 → 一天 flip-flop(換角色每次都不對) |
| 幕 3 | 小白角色誕生 — 不問對錯 / 按 SPEC 走 / 問 PM |
| 幕 4 | PM 回到多元職能 → 原本「開發+QA」結構無意義 |
| 幕 5 | 後來踩 R12 — 11 輪 self-audit 還是漏 P1 |
| 幕 6 | C29 派 5 個 persona — Newbie 多元化 |
| 幕 7 | 從踩坑反推 5 個 type 的形狀 |
| 幕 8 | 每個 cycle 派幾個 — dynamic staffing |
AGENTS 兩角色跑起來:局部檢測 + 不會按角色測
當時我以為「2 個 agent ping pong」就是 multi-agent。AGENTS.md 配:
跑起來幾輪後問題顯現,QA 的 audit 有兩個結構性缺陷:
| QA 在做什麼 | 缺陷 | 為什麼致命 |
|---|---|---|
| ① 局部檢測 | 只看單一 resolver / 單一 endpoint · 看不到跨檔/跨系統的互動 | 系統整體性沒被驗 |
| ② 不會按角色切換進入測試 | QA 都用「一個視角」測,從來沒登入過不同 RBAC 角色看是不是被擋對 / 看到對的東西 | RBAC 路徑(最重要的安全特性)完全沒檢查 |
為什麼「不會按角色測」是嚴重問題
| RBAC 角色 | 看到什麼 / 能做什麼 | 沒測會怎樣 |
|---|---|---|
| sysadmin | 跨社區管理 | cross-tenant leak 沒驗 |
| 主委 | 本社區管理 | 能看到別社區?能改別人家? |
| 警衛 | 處理包裹/訪客 | 能看到住戶資料嗎? |
| 戶長 | 管自己家 | 能看到別家的包裹? |
| 住戶 | 看自己包裹 | 能查到別人寄件? |
第一次嚴重問題:QA 表面綠燈,但 RBAC 跟多租戶隔離這兩條最重要的安全路徑完全沒被驗過——因為 QA agent 從來沒登入過不同角色。系統最該被守住的地方,變成最暴露的地方。
要求按角色登入測試:一天 flip-flop
我介入,告訴 Claude:「不要只在後端查 code,實際用各個角色帳號登入測。」
它真的開始用 sysadmin / 主委 / 警衛 / 戶長 / 住戶 五個帳號登入測。但很快變成:
| 輪次 | 用哪個角色測 | QA 說 | RD 動作 |
|---|---|---|---|
| 輪 1 | sysadmin | 抓到 5 個淺問題 | RD 修 |
| 輪 2 | 主委 | 「剛剛修的東西在主委角度看是不對的」 | RD 改 |
| 輪 3 | 警衛 | 「警衛角度又不對」 | RD 又改 |
| 輪 4 | 戶長 | 「戶長角度又不對」 | RD 又改 |
| 輪 5 | 住戶 | 「住戶角度又不對」 | RD 又改 |
| 輪 6 | 回到 sysadmin | 「現在 sysadmin 角度又不對了」(因為剛改的把 sysadmin 弄壞) | RD 又改 |
| … | 5 個角色輪流 | 每換一個角色就抓到「上輪修壞了」 | 永遠在改 |
這樣無限循環了一天
每輪都是「淺淺檢測 5 個問題 → RD 修 → 換角色又不對」
最後我叫停。
失敗 insight:QA 每次按角色測都對(以那個角色的視角看),但加起來都不對(角色之間有衝突)。沒有公共的「對」基準——每個角色都是 QA 自己定義的「對」,沒有 SPEC 在中間定錨。
小白角色誕生:不問對錯 / 按 SPEC 走 / 問 PM
叫停之後我重新設計。問題不在「QA 不努力」,在「QA 一邊測一邊自己定義對錯」——這個 mode 永遠 flip-flop。
新角色:小白。他長這樣:
| 小白特性 | 具體動作 | 解掉什麼 |
|---|---|---|
| ① 不問對錯 | 只報「我看到什麼」,不下「這對 / 這不對」的判決 | QA 自己定義「對」→ flip-flop |
| ② 按 SPEC 走 | 拿 spec 文件去測,測 spec 寫了什麼。Spec 沒寫的就算了 | QA 一邊測一邊提新需求 → 規格膨脹 |
| ③ 有問題問 PM | 看到不對勁但不確定 → 報 OPEN finding,送 PM 判 | QA 直接 ping RD 修 → 沒人擋 |
小白的本質不是「換一種 audit 風格」,是把「判對錯」這件事從 audit 角色拿走,送回 PM 那裡。Audit 只負責觀察,PM 才負責對 SPEC double-check。
PM 回到多元職能 → 原本的 AGENT 結構無意義
小白把「判對錯」送回給 PM 之後,PM 不能只當「triage 一個動作」。PM 的職能本來就多元,只是 R35 兩角色設定下我把這層拿掉了。現在它回來了:
| PM 職能 | 具體動作 | 為什麼需要 |
|---|---|---|
| ① 對 SPEC double-check | 每個 finding 拿 SPEC 比對:是不是 bug?還是小白看錯? | 提供公共「對」基準 |
| ② Finding 4 選 1 分判 | bug(該修) · feature(進 backlog) · usage(改 docs) · not_issue(close) |
不讓所有 finding 都進 fix loop |
| ③ 規格定錨 | 小白報「這應該也要 work」→ PM 判斷該不該加進 SPEC,加的話寫 INV-XXX-NNN | 擋 spec 漂移 |
| ④ 跨角色視角整合 | 這個 finding 在 sysadmin 角度跟主委角度有衝突 → PM 拿 SPEC 判哪個角色該贏 | 解掉幕 2 的「換角色 flip-flop」 |
原本的 AGENTS.md 結構變無意義
| 最早 AGENTS.md(失敗) | 小白 + PM 出現後 |
|---|---|
| RD agent | RD 還在,但只接 PM triage 過的 bug |
| QA agent(直接 ping RD) | 變小白(不問對錯 / 按 SPEC / 報 PM) |
| (沒有 PM) | PM 多元職能進場 |
| 結構:RD + QA ping pong | 結構:小白 → PM → RD 三角入口 |
學到的事 → Multi-agent 不是「派幾個 agent」的問題,是「agent 之間誰擋誰、誰判對錯」的問題。沒有公共 SPEC + PM 守門,任何 audit 方式都會撞 flip-flop。
後來踩 R12:11 輪 self-audit 還是漏 P1
小白 + PM 結構穩定後 cycle 順暢很多。我以為角色設計問題解了。然後 R12 cycle 出事。
| R12 cycle 條件 | 數字 / 結果 |
|---|---|
| 我自己跑 audit | 11 輪 |
| 場景文件覆蓋 | 132 個 |
| 所有人簽 ✅ | RD ✅ · PM ✅ · 我 ✅ → merge |
| 事後發現 | P1 漏掉:戶長能看到整個社區的資料 |
為什麼 11 輪 + 132 場景還漏?
| 11 輪 self-audit | 11 個獨立檢查 |
|---|---|
| 同一個視角(我自己)跑 11 次 | 11 個不同視角各跑一次 |
| 寫的時候的盲點,驗的時候也是盲點 | 不同視角會覆蓋不同盲點 |
| 132 場景由同一視角設計 | 不同視角會想到不同場景 |
| ≠ 等號不成立 |
解法:把小白進化成「fresh newbie」(零 context)
| Newbie 條件 | 全新 sonnet,沒給過去 11 輪的 audit context · 不知道之前抓過什麼 |
| 紀律 | 沿用小白規矩(不問對錯 / 按 SPEC / 問 PM),只是「context 比小白更乾淨」 |
| 結果 | 第一輪就抓到那個 P1 |
學到的事 → 小白本身不夠,要再進化成「零 context」的 fresh newbie——避免「跑著跑著也累積成跟原 audit 同視角」的退化。
C29:派 5 個 persona 平行 audit
一個 fresh newbie 補一個盲點。不同 newbie 帶不同假設 → 平行補多個盲點。所有 finding 仍走 PM triage,不直接給 RD。
| # | Persona | 他的世界假設 | 抓到的盲點 |
|---|---|---|---|
| ① | 高吞吐警衛阿伯 | 每天 300 件包裹,每秒都要省 | FAB 排太多 · 批次掃描藏在三點選單 |
| ② | 無棟透天主委 | 12 戶共一棟,沒有「A 棟 B 棟」 | 後端硬擋空「棟」欄位 |
| ③ | 多棟社區主委 | 5 棟,選戶必須先選棟 | picker dropdown collision |
| ④ | 老年用 iPhone 11 | 375px 螢幕、視力差 | FAB 不在拇指區、按鈕找不到 |
| ⑤ | 跨租戶 RLS 測試者 | 拿 A 社區帳號戳 B 社區資料 | RLS policy 守不守得住 |
5 個 persona 抓出 23 個 finding
4 個 cycle blocker · 全部都是 PM + 我自己漏掉的
小白 → newbie → persona newbie 的進化線
| 代 | 設計 | 解掉什麼 |
|---|---|---|
| 第一代 小白 |
不問對錯 / 按 SPEC / 問 PM | QA 自己定義對 → 換角色 flip-flop |
| 第二代 Fresh Newbie |
零 context · 不知道過去 audit 結果 | 小白跑久了累積成跟原 audit 同視角 → shared assumption |
| 第三代 Persona Newbie |
多 persona 平行 · 各自帶不同世界假設 | 單一視角必有盲點 → 多視角覆蓋 |
從踩坑反推:5 個 type 的形狀
走過這幾個踩坑,5 個 agent type 不是想像出來的,是反向工程的結果:
| Type | 動作 | 並行? | 從什麼反推 |
|---|---|---|---|
| Writer | 寫 code / spec / migration | NO(單線程) | 原本 RD 角色 · 兩 writer 平行會打架 |
| Verifier | scope 鎖死 1-3 INV 的 audit · 按 SPEC 走 | YES | 第一代小白 · 解「QA 自己定義對」 |
| Triage | 對 SPEC double-check · 4 選 1 分判 · 規格定錨 · 跨角色整合 | NO(人類) | PM 多元職能 · 解「換角色 flip-flop」 |
| Comparison | 零 context 的獨立 verifier · 不知道原 audit findings | YES | 第二代 fresh newbie · R12 11 輪漏 P1 · shared assumption |
| Newbie | Adversarial persona-driven audit | YES | 第三代 persona newbie · C29 23 finding · 單一視角盲點 |
| 傳統 8 職稱 | 這 5 個 type |
|---|---|
| 架構師 / PM / UI-UX / 後端 / Flutter / DBA / QA | Writer / Verifier / Triage / Comparison / Newbie |
| 組織圖長相 · 看起來工整 | 動作類型(寫不寫 / 並行不並行 / 判不判對錯) |
| 寫進 AGENTS.md 之後 cycle 跑起來,只有 PM/QA 對應到事故學到的 | 每個 type 對應一條真實踩坑 |
每個 cycle 派幾個?
5 個 type 有了。但每個 cycle 派多少?不同 cycle 規模需要不同編制:
| Cycle 規模 | 派誰 | 總 RAM | 為什麼 |
|---|---|---|---|
| 改 1 行 typo | RD-Sonnet + Verifier-Haiku | ~1.0 GB | 簡單變動 · 簡單覆蓋 |
| 中等 PR | RD-Sonnet + 2 Verifier-Haiku + Comparison-Haiku | ~2.2 GB | 中等變動 · 需 cross-check shared assumption |
| 大改 schema(含 RBAC) | RD-Opus + 3 Verifier-Sonnet + Comparison-Haiku + 5 Persona-Newbie | ~5.5 GB | 大變動 + 跨角色 · 需多視角補 RBAC 盲點 |
| 固定編制(每 cycle 都派同樣 N 個) | Per-cycle dynamic staffing |
|---|---|
| 小 cycle 浪費資源 | 小 cycle 派 2 個 agent |
| 大 cycle 漏 perspective | 大 cycle 派 9 個 agent |
| 9 Opus 撐爆 16 GB 機器 | 每 cycle 算一次 budget |
規劃 vs 執行 staffing 分離
AGENTS.md | 不變部分(taxonomy + RAM 上限 + Iron Rules) · 半年不變 |
docs/cycles/Cn-*.md Header | 具體 staffing(派誰 / 什麼 model / 多少 RAM) · 每 cycle 重算 |
| 前者性質 | 規劃文件 |
| 後者性質 | 執行契約 |
結語:cycle file 是這故事的結晶
| 維度 | 補丁 | 從什麼反推 |
|---|---|---|
| 角色 | 5 個 type taxonomy + PM 多元職能 + 小白進化線 | 局部檢測 / 不會按角色測 / 換角色 flip-flop / shared assumption / 單一視角盲點 |
| 流程 | 8-stage SOP + 小白 → PM → RD 三角入口 | 沒收斂條件 / 沒規格定錨 / 沒 SPEC 守門員 |
| 資源 | per-cycle dynamic staffing | 固定 9 Opus 撐爆機器 |
cycle file workflow 的價值不是「設計得多漂亮」,是「每個設計選擇都對應到一個踩過的坑」。Multi-tenant + RBAC 系統的盲點不是「LLM 不夠強」,是「沒有公共 SPEC 守門員 + 多元視角覆蓋」就會撞牆。
你接手新專案那天
| 需要什麼 | 4 個檔案 + 一段 bootstrap prompt |
| 完整版在哪 | 進階篇 |
系列文章
| 第一篇 | 「56 條 INV 全綠,user 點一次抓出 4 個 bug」— Multi-Agent 業界共識的五個自家補丁 |
| 進階篇 | Cycle File:Multi-Agent 工程的狀態接力棒 — 完整 SOP / 8-stage / 4 個檔範本 |
| 呼應業界 | Multi-Agent 架構再探: 三省六部反模式和業界收斂共識(愛好 AI 工程) |
發佈留言