QA Agent Operating Framework — 6 層平台架構落地紀錄 · Williams Liu

寫在前面

這篇文章寫給一種人：你剛接到一個從 0 到 1 的 QA 任務、又有機會跟 AI 協作，正想著「該怎麼開始」。

工具會越來越多、能力會越來越強，但架構與治理層面的概念，到每一間公司都不太一樣。如果你正在學習 AI Agent、把測試大量交給 Agent 處理、想把 AI 加進工作流卻不知道從哪個角度切，也許這篇可以給你一點想法。

不是教科書，是一份踩雷紀錄。

一切要從一個念頭講起

當初有個想法是這樣的：既然 AI 現在做得不錯，那不如創造一個 QA 主管，讓他去帶他的 QA 組員，一起幫我打造一個夠強的 QA 組織。

聽起來中二，但實際做下去後，這個比喻反而救了我。

我那時其實已經在管多個產品線的測試，自己一個人。再多塞幾個 prompt、再裝幾個 MCP，憑直覺就覺得「應該夠了吧」。試了兩週，整個崩盤 — 規則記不住、跨產品的決定永遠跟同事（agent）對不齊、機敏資訊差點被 commit 出去⋯。

後來才理解：缺的不是工具，是組織結構。一個沒有主管、沒有 SOP、沒有共享記憶的 QA 團隊，不管成員技術多好，產品線一多就會炸。

於是有了下面這份 framework。它的定位不是工具、不是 MCP，是平台層 — 規範一群 AI Agent 怎麼在組織內協作、知識怎麼分層、機敏怎麼隔離、版本怎麼控管。

6 層 QA Agent Operating Framework

A Agent Topology Orchestrator + Project Agents
B Knowledge Architecture 三層記憶分層（全域 / 專案 / 工單）
C Governance 鐵律 · 自學 · 啟發
D Sync & GitOps 跨層推版 · pre-commit lint
E Secret & Cloud L1 公開 / L2 私有 / L3 本機
F Tool Capability Issue Tracker · TCM · Chat · 機敏分發

為什麼是「平台層」而不是「再寫一個 agent」

實際做之後，我陸續踩到 5 個痛點。每個痛點都對應一個現在的設計決策：

痛點	反推出的設計決策
同樣的錯誤跨 session 重複犯	規範寫進啟動腳本，不只寫在 prompt
個人經驗無法傳承給新進 agent	錯誤統一固化成自學規則
多 agent 各自改 shared 程式碼導致衝突	多 agent 分工，但禁止橫向修改框架
想分享架構但內部資訊絕不能洩漏	框架 / 配置 / 機敏分三層 Git Repo
不想被綁在 Claude / Codex / Gemini 任一家	AI 平台中立

這 5 條不是事先想好的設計理念，是踩雷後反推出來的。後面一層一層拆。

Layer A — Agent Topology（誰主管誰）

回到「QA 主管 + 組員」的比喻。

最自然的對應就是 Hub-and-Spoke：頂層放一個 Orchestrator Agent 當「主管」，下面是各產品線各自的 Project Agent 當「組員」。

              ┌─────────────────────┐
              │  Orchestrator Agent  │
              │  - 跨產品線視角       │
              │  - 框架升級 / 規則制定 │
              │  - 跨專案同步         │
              └─────────┬───────────┘
                        │ 唯讀分享框架
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
   ┌────────┐      ┌────────┐      ┌────────┐
   │ Proj A │      │ Proj B │      │ Proj C │  ...
   │ Agent  │      │ Agent  │      │ Agent  │
   │ 執行+回報│      │ 執行+回報│      │ 執行+回報│
   └────────┘      └────────┘      └────────┘

中間我有想過幾個替代方案。

「單一個超大 agent 一次管所有產品」 — 試了之後 context window 大概管到幾個產品就爆掉，而且只要它失手一次，所有產品同時受害。

「全 peer-to-peer 多 agent」聽起來很民主，但實際上沒有主管的團隊在這種多人工作的環境，永遠在開會。跨產品規則沒人拍板、責任邊界永遠模糊。

Hub-and-Spoke 之所以贏，是因為跨產品變更有單一進入點、責任清楚、每個 Project Agent 的 context 範圍有界、不會把其他產品的雜訊餵給彼此。

關鍵的一條鐵律：Project Agent 對共享框架是唯讀的。它可以執行、可以回報、可以建議，但不能直接改框架。任何跨產品變更都得由 Orchestrator 拍板。

Layer B — Knowledge Architecture（記憶要分層）

早期我犯過一個經典錯：把所有 AI 要用的資訊都塞在同一份 memory.md 裡。

幾週後，這份檔案出現兩種互斥的災難：

全域規則被工單編號污染 — 6 個月後讀到「BUG-1234 修正後必須回測」這條，根本不記得 BUG-1234 是什麼，但這條規則卻被當鐵律每次啟動都讀
單次工單紀錄淹沒鐵律 — 真正重要的規則（例如推版前必須繁中確認）被一堆「2024-08-14 修了訂單頁排版問題」這種紀錄淹沒，agent 直接視而不見

後來就乖乖拆三層：

層	範例內容	壽命	寫入權限
Global Memory	鐵律 / 自學規則 / 跨產品決策	年	Orchestrator only
Project Memo	產品環境 / 測試帳號 / TCM 設定	月	Orchestrator + Agent（白名單 section）
Agent Memory	單次測試結果 / 工單排查紀錄	日 / 工單級	該 Project Agent only

寫入前該問自己三件事

每次想往記憶寫東西時，先問：

1 個月後還有用嗎？
別的產品 agent 看到會受益嗎？
跟單一工單編號綁定嗎？

任一答否，就該寫進 Agent Memory，不是 Global / Project。

光講規則不夠，要硬擋

光靠 prompt 提醒「請寫對地方」是不夠的，agent 跟人一樣，半年後就會出包。所以另外加了幾層硬保護：

.claude/settings.local.json 用 deny 規則直接擋掉對 Global / Project Memo 的直寫
pre-commit hook 自動 lint，違規工單編號出現在 Project Memo 就 abort commit
寫進 Project Memo 必須走 safe-memo-writer.py，會跑 regex 檢查 + diff 確認後才落筆

這層硬保護救了我至少 3 次。

Layer C — Governance（規矩要剛性遞減）

三層剛性遞減的規則集：

Iron Laws (鐵律)         核心固定集     ← 永不違反，最高優先級
   │
   │ 例：commit / push 前必須繁中向使用者說明並取得明確同意
   │
Self-Learning Rules      持續增長的清單  ← 從歷史錯誤萃取，啟動時必讀
   │
   │ 例：某 TCM 工具的統計引擎只認 API 所接受枚舉值的部分子集 —
   │      要對著真正的統計後端驗證，不能只看 API 回應
   │
Heuristic Rules          少數偏好預設    ← 啟發式偏好，可由情境覆蓋
     例：開 Issue Tracker Bug 應觸發 bug-report skill

為什麼要分三層

說真的，一開始我覺得有規則就好，分什麼三層。後來才發現規則的「剛性」差很多：

鐵律等於「永不」。例如推版前必須繁中說明取得同意。這條是被 agent 自作主張推錯版、花了很長時間 rollback 後寫下來的。永遠不可違反、context 也不可覆蓋。
**M-rule（Self-Learning）**等於「曾經痛過所以學到」。比較強的建議，agent 得有充分理由才能違反。例如某 TCM 工具的結果回寫，API 接受多種枚舉值，但統計引擎只認其中部分子集——必須對著真正的統計後端驗證，不能只看 API 回應。
**R-rule（Heuristic）**等於「通常這樣比較好」。啟發式偏好，情境可以覆蓋。

三層按優先級灌進 agent 的啟動腳本，遇到衝突時鐵律永遠贏。

錯誤要被「固化」，不能只靠記憶

最重要的鐵律之一是「錯誤自學機制」。閉環是這樣的：

AI 犯錯 / 被糾正
     ↓
寫入 Global Memory「錯誤修正記錄」表
     ↓
格式：日期 | 問題 | 修正 | 自我學習規則
     ↓
下次啟動時必讀
     ↓
永不重犯

這條閉環是整個 framework 的靈魂。沒有它，個人經驗永遠是個人的，新進 agent（或同事接手）就得從頭踩。

Layer D — Sync & GitOps（多副本怎麼同步）

當框架被多個 Project Agent 共用、又分散在好幾個 Git Repo 時，最常見的 bug 是：

shared library 改了某個檔，多個產品副本沒同步，下次踩雷找半天找不到原因。

我自己被這個 bug 燒過 2 次，第 2 次決定再也不能靠手動同步。

於是寫了一組同步工具。以下檔名僅為示意 — 採用時請改成你自己的命名：

push-helper.py — 跨層推版助手。自動分類每個變動檔屬於 L1 / L2 / DUAL / PROJECT / SKIP / SECRET 哪一類；偵測到機敏字串直接 abort、連 dry-run 都不讓你跑
sync-scripts.py — 業務腳本改動後同步到多個產品副本，pre-push 自動預檢
pre-commit hooks — 自動跑 lint，違規（例如 Project Memo 含工單編號）直接擋住 commit

推版確認制（鐵律 1）

這條被我列在鐵律 1 是有原因的：

Step 1: Agent 跑 --dry-run 分析變動
   ↓
Step 2: 用繁中向使用者說明（repo / 檔案 / 摘要）
   ↓
Step 3: 取得明確同意
   ↓
Step 4: --go 執行推版
   ↓
Step 5: 回報 commit hash

不允許 agent 自作主張 push。也不允許 agent「自我感覺良好地」說「我覺得這個改動沒問題就推了」。每次 push 都要等明確的 GO 才動。

被 rollback 過一次就知道為什麼。

Layer E — Secret & Cloud（機敏分三層）

三層 Repo 分離

這層是為了讓框架可以被獨立分享而設計的：

L1: qa-agent-framework  (可獨立分享層)
    ├ 通用框架代碼
    ├ Skill 模板
    └ 公版規則
       ↑ 完全去敏，純架構與機制

L2: qa-agent-config  (公司私有)
    ├ org-config.yml（產品名 / Board / Domain）
    ├ Project memo
    └ 進度紀錄
       ↑ 含公司特定資訊

L3: Local-only  (never committed)
    ├ credentials.local
    ├ token JSON
    └ OAuth credentials
       ↑ .gitignore + pre-commit 雙重保護

核心想法是：同一套框架要能被不同團隊各自部署，差異只在 L2 配置。L1 完全可以拿出去分享、L2 私有、L3 永遠不進 Git。

三層用途明確、邊界清楚 — 想 fork L1 自己用的話，clone 之後配個自己的 L2 / L3 就能跑，不用先刪一堆內部資訊。

想像一下：某條 token 洩漏了。如果機敏散落在各處，你得查每一個 repo、每一份腳本；邊界寫死之後，你只要清 L3，事情就結束。

雲端執行延伸

機敏不能進 Git，但雲端跑測試又要拿到憑證。設計如下：

Service Account → Google Drive → age 加密
         ↓
   Server cron 拉機敏到本機 cache
         ↓
   執行測試（CI / 本機 Playwright）
         ↓
   結果三軌回報：TCM / Markdown 倉庫 / Chat
         ↓
   失敗 trace 上傳 Drive（自動清理 N 天前）

機敏全程加密、本機 cache 有 TTL、失敗 trace 自動 rotate。哪台機器壞掉或哪個帳號離職，可以很快收乾淨。

Layer F — Tool Capability（最底層的具體工具）

以下工具僅為參考實作，可依技術棧替換 — 框架本身是平台中立的。

這一層是直接跟外部系統打交道的部分。目前實作以內部 Python CLI 為主：

Issue Tracker 整合（例：Jira） — 拉工單 / 列待 QA / 開測試子單
TCM 整合（例：MeterSphere） — 建計畫 / 關聯 case / 回寫結果（含步驟層級）
Chat 通知（例：Slack） — Webhook 推週報 / 失敗告警（不維護 Bot，維護成本太高）
機敏分發（例：Google Drive） — Service Account + age 加密
報告倉庫 — 統一 Markdown 格式存放各產品測試報告

要特別說一下：MCP 是這一層可以選擇的協定之一，但不是 framework 的核心。核心價值在 Layer A-E 那五層。後續會把部分 CLI 包成 MCP 讓 Claude Desktop / Cursor / Codex 等 client 也能直接呼叫，但這是擴充，不是重構。

踩過、已固化為規則的雷區

案例
某 TCM 工具的統計引擎只認 API 所接受枚舉值的部分子集 — 要對著真正的統計後端驗證，不能只看 API 回應
TCM UI 顯示陳舊狀態實為瀏覽器 cache，後端 DTO 根本沒有對應欄位
Issue Tracker comment body 在結構化格式（如 ADF）下的攤平結果不等同 UI 實際渲染
自建 Chat Bot 的維護成本通常高於既有 Webhook

這些案例都已寫進 Global Memory 的「錯誤修正記錄」，下次任何 agent 啟動時會讀到，永不重踩。

總結與教訓

過去幾個月做的事整理起來大致是：

Layer A：設計 Orchestrator + Project Agent 拓樸，覆蓋多個產品線
Layer B：把 AI 記憶拆成三層，避免規則被工單紀錄污染
Layer C：累積鐵律 + 自學規則 + 啟發規則
Layer D：寫出跨層推版 / 副本同步 / pre-commit lint 工具
Layer E：完成三層 Git Repo 分離設計
Layer F：多支內部 CLI 對接 Issue Tracker / TCM / Chat / 機敏分發 / CI

如果你也要做類似的事

回到「寫在前面」那段。如果你也是剛接到 0 到 1 的 QA 任務、也想跟 AI 協作搞測試 infra，幾條我會建議的思路：

不要從 prompt 開始，從規範開始 — prompt 會被 context window 沖走，規範要寫進啟動腳本
錯誤要被固化，不要靠 agent 記憶 — 寫進 Global Memory，下次啟動讀，永不重犯
多 agent 一定要有單一進入點 — 跨產品變更走 Orchestrator，不要讓組員自己改 SOP
機敏分層從 Day 1 開始 — 不要 commit 才發現「等等這個不能公開」
AI 平台中立可以延後做，但別寫死 — 框架不要假設只能跑在某一家

工具會變化、能力會成長，但架構與治理是 AI 協作的重要基石。

希望這篇對你有點幫助。

Repo 版本：完整的 framework 文件（雙語 README + CC BY 4.0 授權）放在 GitHub — github.com/twilliamsliu/qa-agent-framework。