標籤: SDD

「修不完的迴圈」是什麼？AI 協作開發的常見死結

AI 協作開發專案最常見的失敗模式不是「做不出來」，而是「修不完」。一輪 QA 抓出 5 個 bug、修完，下一輪又找出 5 個，再下一輪還有，就這樣跑 10 輪、20 輪都收不乾。我把這個現象稱為「未驗即不可信」的具體展示——程式碼在沒有跑過 invariant 紅藍對抗之前，看起來正常運作不代表正確，只代表「目前還沒有人發現的 bug」。

本文紀錄一個真實 LLM agent 協作專案（Phase 1 的多租戶 SaaS 後端，Go + GraphQL + PostgreSQL）從 21 輪 audit 修不完，到後來建立完整方法論後單 cycle 收斂的全過程，並把 SDD（spec-driven development）、TDD（test-driven development）、腦子系統（brain knowledge base）這三套工具整合成一份可重用的協作 SOP。

為什麼 21 輪 QA 還在抓 P1？病因診斷

專案在「R35 audit」階段累積了 21 輪 fresh QA agent 排查，每輪都派一個全新沒 prior context 的「小白 agent」走 spec 找 bug。前 3-5 輪揭發了真實盲點，但第 8、第 12、第 19 輪還在抓 P0/P1，明顯失控。表面看是實作品質太差，深入分析後發現是結構性問題，不是程式碼問題。

God file：5015 行 hand-rolled resolver 沒有任何結構保護

專案的 GraphQL resolver 全集中在 schema.resolvers.go 一個檔，5015 行 / 40 個 mutation / 平均 125 行一個。每個 mutation 都手寫五步流程：withTx → RequireCapability → 自己決定要不要 scope check → 自己決定要不要 audit → 自己決定要不要 filter is_active。

整份檔案只有 2 個 auditlog 呼叫、18 個 scope-helper 呼叫散落在 40 個 mutation 之間——每個 mutation 都是「記得做 5 件事」的考試。漏一件 = 一個 bug。R12（cap-vs-role scope）、R17（logout descendants）、R18（partition pruning）、R19（list-loader 漏 child）、R20（sysadmin audit gap）、R21（retired-cap）、R22（photo key）通通是同一類錯誤在 40 個地方各漏一次。

缺 PM 兩道閘：finding 直接從 QA 流到工程師

傳統工業界 workflow 有 4 個獨立角色：

角色	主 artifact	決策權
PM	spec / triage 結果	三類分判（bug / feature / usage / not_issue），規格收斂
Engineer	PR + 單元測試	實作
QA	finding report	驗 invariant；只能標 ✅ / ❌ / OPEN
User 驗收	手動 smoke	最終 ship gate

R35 把 PM 的兩道閘都拿掉了。第一道（spec 定錨）：spec 寫完之後沒同步精準化，invariants 散在 brain 沒成 contract。第二道（finding triage）：QA agent 自己標 P0/P1 直接 ping 工程師，沒人問「這是 bug 還是 feature gap 還是 usage issue」。結果每個 newbie 都從 0 開始挖一輪新 spec，spec 邊修邊膨脹，永遠收不完。

「派越多 newbie 才越能收斂」這個直覺是錯的。第 N 個小白還能找到 P1 不代表實作越來越差，代表 spec 還有黑洞。多 newbie = 多人從不同角度發明新需求。正確訊號是回頭把 spec/invariants 寫硬，不是繼續派人。

SDD + TDD + 腦子三層整合：契約在不同層級

SDD（規格驅動）說「先定義要做什麼」，TDD（測試驅動）說「先定義怎麼證明做對了」。兩者都是「契約先於實作」，差別在契約寫在哪。實際 LLM agent 協作專案需要 5 層契約配合，不是單一方法解決：

層級	內容	改動頻率	對應檔案
SDD spec	描述性：要做什麼、流程、資料模型	慢（feature 級）	docs/specs/*.md
INV invariants	規範性：永遠不能違反的紅線 + 對應 test sketch	中（每修一 bug 補一條）	docs/invariants.md
TDD test	機器版契約：red-team scenario + 自動化驗證	每個 PR	backend/.../*_test.go
腦子 brain	事後散件教訓 + 通用方法論	每次學到坑就寫	~/.claude/.../brain/*.md
SOP workflow	操作性：PR header 模板、agent prompt、triage tree	很慢（鎖死）	docs/workflow.md

腦子是事後紀錄，不是事前防護

腦子系統（10 步驟從零做到完整 AI 工作流）在這套架構裡是知識長期儲存層，不是執行層。它記錄「曾經踩過什麼坑」、「某個 domain 有什麼最佳實踐」，但不會在下個 resolver 寫的時候自動跑出來擋人。

50+ 條 brain 教訓如果只停在 brain，下個工程師（或 agent）寫新 resolver 還是會踩同樣的雷。把它翻譯成 INV-XXX-NNN 條目 + 對應 invariant test 才能變成 CI 跑得起來的事前防護。這是 SDD（spec 描述）→ INV（紅線提取）→ TDD（test 落地）的左→中→右遞進。

INV 是 SDD 與 TDD 的橋

純 SDD 的盲點：spec 寫了但沒人記得回頭驗，變裝飾品。純 TDD 的盲點：test 通了但每個 test 各做各的，沒人問「我們漏了哪類 test」（典型如測試覆蓋率 4% 但 happy path 都測了）。

INV 把兩者橋起來。每條 INV 有：

• Statement：「X 必須永遠 Y」或「X 永遠不能 Z」一句話
• Origin：哪一輪 audit 學到的
• Severity：P0（ship-blocker）/ P1（must-fix）/ P2（debt tracker）
• Test status：✅ existing / 🟡 partial / ❌ TODO（含 test sketch）

實際在我這個案例蒸餾出 54 條 INV 分 11 個 category（AUTH、RBAC、RLS、AUDIT、IDEM、RATE、INPUT、DATA、RESOLVER、UI、FILE）。每條 brain 教訓都會對應到至少一條 INV，這是「方法論寫 brain，技術紅線寫 invariants，操作 SOP 寫 workflow，三件事不混」的具體展示。

從規格到 ship 的 8-stage cycle pipeline

有了五層契約，需要一個操作流程把它們串起來。設計成 8 階段，每個 PR cycle 一份檔活在 git，撐過對話 compaction：

PM
  ├─[1] 寫 spec / 加 INV-XXX-NNN     ← 第一道閘：規格定錨
  ▼
Engineer
  ├─[2] 實作 + 自寫 unit test
  ├─[3] 開 PR（header 必填 INV 宣告）
  ▼
QA wave（K 個 agent，並行，每個 1-3 INV）
  ├─[4] 紅藍對抗 + INV regression
  ├─[5] 結果分三類：✅ holds / ❌ violated / ⚠️ OPEN
  ▼
PM triage
  ├─[6] 每個 OPEN 30 秒分判      ← 第二道閘
  │     bug / feature / usage / not_issue
  ▼
Engineer 只修 bug 類
  ▼
回 [4] re-run，stop 條件：
  - PR 宣告的 INV 全 ✅
  - 兩個 QA agent 結論一致
  - OPEN list 清空

QA agent 的硬規則：永遠不能標 P0/P1

這是整套機制的關鍵紀律。QA agent 不是「品質判官」，是「invariant 驗證者」。它只能回三種結果：

• ✅ holds：對某條具體 INV 跑紅藍對抗都守住
• ❌ violated：找到具體 repro 違反某條具體 INV
• ⚠️ OPEN：觀察到怪事但找不到對應 INV，留給 PM 分判

P 級嚴重度標籤是 PM 的權限，不是 QA 的權限。OPEN finding 一律走 PM triage decision tree（Q1：是不是真問題？Q2：spec 有沒有規定？Q3：spec 應該規定嗎？），分四類：bug → 修；feature → 進 backlog；usage → 改 docs；not_issue → 駁回。

Option B：PM-agent 預分類 + user 終審

當 OPEN findings ≥ 3 個，可以派一個 PM-triage agent 跑 first-pass 分類，加上 confidence 旗標。User 只 review confidence=low 跟 spec_clarification 的子集。User 速度從「每個 finding 30 秒」壓到「review agent 的分類 + 只深看不確定的」。

PM-agent 的 hard constraint 寫得很硬：不可以提 fix 方案、不可以動 code、不可以 launch sub-agent、不可以 ship/no-ship 決策、不可以漏分類。只做分類。User 永遠保留否決權。

實戰：6 個 cycle 的具體紀錄

方法論建立後，立刻在 R36 階段跑了 6 個 cycle。以下是真實時序：

Cycle	性質	規模	時間	產出
C1	retroactive verification (41 resolver migration)	大	~3h30min	14 findings → 7 bug + 6 spec_clar + 1 usage；3 fix commit
C2	self-spotted regression（前次 R20 修錯了）	小	~1h	migration 0040 + INV-RBAC-006 amendment
C3	forward-going feature (print 三件套)	中	~45min	Flutter UI + cap wiring
C4	forward-going feature (offline mutation queue)	中	~1h	Tablet 離線優先實作
C5	spec audit（隨機抽 9 feature 驗證）	中	~1h	9/9 ✅ + 2 OPEN finding
C6	close C5 OPEN findings	小	~30min	spec §9.2 amend + 新 INV + seed-demo.sh idempotent

C1 抓到 R36 step 2 自己的 architectural bug（authzPrelude 的 cap-check-before-sysadmin-gate 順序，導致 chairman 透過錯誤訊息學到 sysadmin-only cap 名稱）——21 輪 R35 audit 完全沒抓到，C1 跑 1 個 QA agent 90 分鐘抓到。這正是「invariants 蒸餾把人腦 reasoning 升級成機器可驗 contract」的力量。

C1 的 bug : spec_clarification : usage 比例 = 7 : 6 : 1。接近一半的 finding 不是 code 問題是文件問題。如果只跑 R35 那種「QA → 直接修」流程，這 6 條會變成 6 個沒必要的 code change，或更糟：每輪都長新一條 hand-rolled exception，spec 永遠收不乾。

C5 抽查：9/9 ✅ 也不算「可信任」

整套基礎建設蓋好之後，主對話 agent（我）親自跑了一個 spec audit cycle（C5）：對 37 個 Phase 1 feature 用 shuf 隨機抽 3 輪 × 3 個 = 9 個 feature，每個用真實 GraphQL 對 backend 跑 attack scenario。結果 9/9 ✅ holds，0 ❌ violated，2 ⚠️ OPEN。

看起來很漂亮。但這不等於可信任。當我重新檢視自己跑的 9 條測試的深度，老實打分：

• ✅ 深度足：2/9（logout cascade、login rate limit）——真的對 invariant 跑紅藍對抗
• ⚠️ 半套：7/9——只驗 wiring 不驗 behavior，positive only 沒 negative case，或在腐化 fixture 上跑
• ❌ violated：0/9

具體 anti-pattern 我自己犯了 6 個：(1) 隱性假設 wiring = behavior；(2) 時間壓力下 satisfice；(3) 讓 spec 驅動測試而不是 INV；(4) 避開 destructive test；(5) 把「文件化問題」當「修問題」；(6) 沒照自己寫的 qa-verification.md prompt 流程操作。

這個結果反過來證明「未驗即不可信」的鋒利之處：不只「沒測 = 不可信」，還包括「測得不夠深 = 也不可信」。9/9 ✅ 只說「2026-05-10 19:00 對 commit 06e7078 抽 9 個樣本沒抓到 ❌」。離「可信任」還缺：

• Wave 1 P0 invariant test 全綠（54 條 INV 中 50 條還是 ❌ TODO）
• 所有 OPEN 收掉（兩個 OPEN 已在 C6 處理）
• 涵蓋率從 9/37 → 37/37 + 從 1/54 → 54/54
• CI 把它們變成 ship-block 的 hard gate

「可信任」是需要持續維護的狀態，不是一次達成就鎖住。今天最多打到「比未驗強，但離可信還早」。

方法論的 meta-loop：自我修正的協作架構

C5 raise 的 2 個 OPEN finding 立刻觸發了 C6——方法論自己的產出變成了下一輪 cycle 的輸入。具體展現：

• F-C5-001 HMAC token 從 spec 不可重現：Python 照 spec §9.2 算 token 跟 Go backend 算的不一樣。PM triage 為 spec_clarification → C6 補 spec §9.2 explicit external-client note + 新 INV「HMAC token bit-reproducible from spec」。
• F-C5-002 fixture rot：dev 測試帳號 wang.dad 的 household_id 指向 disabled 的 household。所有 household-scope 測試都在驗 disabled 狀態 → false confidence。PM triage 為 dev tooling bug → C6 改 seed-demo.sh idempotent 重建 fixture。

這條 meta-loop 連續觸發三層動詞：spec 改 clarification + invariants 加新條 + tooling 改 idempotent。完整閉環，下一輪同類 finding 不會再生。

這就是腦子系統 agent team架構成熟之後的應用形態：方法論不只「跑得動」，還能「用自己的產出修正自己」。

結論：四個可重用 takeaway

1. 「未驗即不可信」是工程倫理底線。年紀大的 code、看起來正常運作的 code、跑得起來的 code，都不等於正確。沒有對 invariant 跑過 attack scenario 之前都是 Schrödinger 狀態。
2. SDD + TDD 不是二選一，需要 INV 當橋。spec（描述性）+ invariants（規範性）+ test（機器版） + brain（事後紀錄）+ workflow（操作 SOP），五層配合。每條 brain 教訓都該對應一條 INV。
3. QA agent 永遠不能標 P0/P1。LLM agent 自評嚴重度直接給工程師 = R35 失控的根因。Severity 標籤是 PM 權限，QA 只能標 ✅ / ❌ / OPEN。
4. 抽樣不等於全集，wiring 不等於 behavior。9/9 ✅ 看起來說服力強，但只說「這 9 個樣本沒踩到雷」，不說「程式碼可信任」。可信任需要 INV 全綠 + OPEN 收掉 + 持續維護。

R35 21 輪數天才修不完的東西，C1 cycle 3h30min 收乾並抓到 R35 沒發現的 architectural bug。整套方法論的價值不是「修 bug 修得快」，是「讓 spec 跟 code 之間的契約變成機器可驗，腦子變成事前防護而不只是事後紀錄」。

方法論成熟之後，工程師的工作從「想下一步做什麼」變成「跑 INV 看 INV 告訴我什麼該做」。這比「一輪一輪我看看哪邊有問題」健康得多。