Harness Engineering 採納策略 — Fowler 框架對照 YiBi MVP

Context

觸發

閱讀 Martin Fowler 的 Harness Engineering for Coding Agent Users 後，對照 YiBi MVP 專案目前的 Claude Code User Harness 體系（CLAUDE.md / rules / hooks / skills / agents / OpenSpec），進行差距分析，並取得兩個外援模型的第二意見：

Codex（gpt-5.5）：全面批評分析的方法論缺陷，重新排序優先級
Gemini（0.42.0）：Flutter/Mobile 邊界 harness 的專項盲點分析

完整對照分析見 ~/.claude/plans/https-martinfowler-com-articles-harness-memoized-aurora.md。

文章核心框架

Agent = Model + Harness
User Harness = Guides（前饋）+ Sensors（反饋）
兩種 Sensor 來源：
  - Computational（確定性、毫秒級）
  - Inferential（語義、慢且貴）
三個調節維度：Maintainability / Architecture Fitness / Behaviour
目標：trust through evidence，而非 inventory count

現況快照（2026-05-25）

類型	數量	備註
Path-scoped rules	21	`.claude/rules/`
PreToolUse/PostToolUse hooks	17	含 protect-*、auto-format
Skills	36（project）+ 全域	含 Spectra family、pr-review-cycle-mob
Agents	4	全部 reviewer 角色，0 verifier/implementer
OpenSpec specs	65	E01–E26 epics + feature specs
P0 critical path tests	5	auth/onboarding/content/device/quick-reaction
DoD Gates	5	Implementation/Test/Quality/PR/Agent Self-Check
MEMORY.md 條目	38	84% feedback 類

外援共識（兩個模型均同意）

分析方法論的根本問題：以 inventory 數量評估 harness 品質，等同 Fowler 的反模式。真正的 harness 品質指標是「trust through evidence」：哪些 defect class 被阻止了？false positive rate 多少？hooks 被繞過的頻率？
P1-A 分類錯誤：把 api-contract-reviewer LLM agent 放進 CI blocking gate 是「inferential sensor 做 computational sensor 的工作」。LLM 是非確定性的，作為 gate 會導致 flakiness 與 bypass 文化。
Approved Fixtures 優先級低估：原分析標為 P3，兩個外援都認為這是行為 harness 最關鍵的缺失，應大幅提前。

Decision

結論：採納三個新 P1（Telemetry with outcome、Coherence Audit、Post-fix Evidence Block），修改原 P1-A 為計算型 gate，提前 Approved Fixtures 與三條 Mobile P0 tests，延後 Verifier Agent。

採納（Adopted）

[A] Hook Outcome Telemetry（取代原 P1-C fire-rate）

記錄欄位：date、hook_name、exit_code、duration_ms、files_touched_count、repo、branch。

寫到：~/.agents/hook-firings.jsonl（本機）＋ CI artifact upload（讓 telemetry 可跨機器聚合）。

每月跑 /retro 讀取：找 30 天沒 fire 的 hook（死碼候選）、exit_code 異常的 hook（flaky 候選）。

為何修改設計：Codex 指出「hook fired」是 low-signal。duration（快不快）、exit_code（誰 fail）才能分辨「健康」vs「永不觸發 = 死碼」。

[B] Harness Coherence Audit（新增，Codex 提出）

對現有 21 rules、36 skills、17 hooks 做一次審查：

相互矛盾的指引
重複覆蓋（consolidate 候選）
過期指引（基於不存在的工具或模式）
沒人用的 skills（dead code 候選）

為何是 P1：65 specs + 21 rules + 36 skills 的系統，在沒有 coherence 保障下，「指引互相矛盾」比「缺少指引」風險更高。Fowler 在文章後半明確提到 coherence problem。

[C] Approved Fixtures 升格（P3 → P2）

Mobile 必要性（Gemini）：Flutter UI 開發不能被 backend 可用性 block。必須能用 fixture 把 UI 逼進 loading / error / empty / partial data 等狀態。
不需等 backend DI 重構：在 mobile/lib/features/*/repository/ 層引入 Mock repository，以 golden JSON fixture 驅動 widget test，與現有 freezed model 完全相容。
目標：讓 widget test 能覆蓋「miserable path」（no network、500 error、permission denied）。

[D] 補齊三條 Mobile P0 Tests（Gemini 提出）

新 P0	說明	觸發路徑
Offline access	離線時不崩潰、能看到 cached content	connectivity、cache、offline_storage
App cold start	從零啟動到可互動的時間門檻	main.dart、router、首頁 widget
Deep linking	從 push notification 或外部 URL 正確進入對應頁面	GoRouter、notification handler

P0 tests 從 5 條升到 8 條。這三條是「使用者真實遭遇 bug 的高頻情境」，不是品質修飾品。

修改後採納（Adopted with Modification）

[E] API Contract Gate：計算型優先，LLM 改為 advisory

不採納原 P1-A（LLM agent 作為 blocking CI gate）。改為兩層：

計算型 gate（blocking）：FastAPI endpoint → 自動生成 OpenAPI JSON → 比對 freezed model 欄位名稱 / 型別 / nullable 屬性。確定性、毫秒級。
LLM reviewer（advisory PR comment）：api-contract-reviewer agent 提出語義疑問（如「欄位命名不一致但型別相符」），不 block merge。

Codex 理由：blocking gate 必須是 deterministic。LLM 作為 gate 訓練開發者 bypass 它。

[F] Post-fix Evidence Block（取代 Verifier Agent 早期版本）

不建 Verifier Agent（Codex：premature，需先有 failure mode 的 evidence）。改為：

在 pr-review-cycle SKILL.md 加入 Step 2.5「Post-fix Evidence Block」：fix 完後，agent 必須輸出結構化 evidence block，列出「跑了哪些測試、改了哪些測試、remaining risk」。沒有 evidence block → Step 2.5 不通過。

觀察期：等 MEMORY.md 累積 3+ 條「修了但沒真正修好」feedback 後，再評估是否建 verifier agent。

延後（Deferred with Trigger）

項目	延後理由	重啟觸發條件
Verifier agent（完整版）	Evidence Block 先做，累積 evidence	出現 3+ 次「修了但沒真正修好」pattern
Garbage Collection drift scan	spectra-drift skill 已存在，先確認現有 drift 範圍	E2E test pass rate 系統性下滑
Mutation testing	P0 先補完八條，再評估品質	P0 pass rate > 95% 後
Edit-time inferential sensor	成本/速度 trade-off 待評估	有具體「LLM 在 edit-time 攔住 semantic bug」use case
Harness health dashboard UI	CLI report 先	CLI report 用 3 個月後

不做（Rejected）

項目	理由
LLM agent 作為 CI blocking gate	Inferential sensor 不能做 computational 工作；訓練 bypass 行為
Multi-agent Janitor Army	Coherence audit 先跑，增角色前先 audit 現有的

Codex 完整 revised priority：(P1) deterministic contract check + hook telemetry with outcome + coherence audit；(P2) approved fixtures + drift scan + verifier workflow after evidence；(P3) mutation testing + janitor + dashboard。本 ADR 採納全部 Codex P1，其餘按 Codex 建議調整。

Gemini 的 schema-first 方案（比 E-modified 更激進）：FastAPI + Pydantic → 生成 OpenAPI → freezed codegen，兩端都從同一 schema 生成，contract 問題在根本上消滅。理論上最正確，但需要 backend + mobile 同時重構工具鏈，不在本 ADR 範圍。保留為未來演化路徑。

Gemini 補充的 mobile harness 盲點（尚未採納，待後續 spec）：

State & Lifecycle harness（app background/foreground/termination）
Visual regression testing（iOS/Android 外觀差異）
Riverpod anti-pattern sensor（dependency cycles、excessive rebuilds）
Build environment complexity（Gradle/Xcode + flavor/scheme）
Native dependency conflict sensor（CocoaPods、Gradle）

維持現狀：不採納。Codex 明確指出分析是「too automation-positive」，但不做 coherence audit 的代價是現有 harness 的矛盾和漂移風險持續累積。

Consequences

好：

Harness 評估從「數量」轉為「evidence」：telemetry + coherence audit 提供首個客觀指標
API contract gate 變為 deterministic → 不再 flaky
Mobile P0 從 5 條升到 8 條，覆蓋離線/冷啟動/深連結
Approved Fixtures 提前，Flutter widget test 可覆蓋 miserable path

壞 / 代償：

Coherence audit 是一次性重負債：21 rules + 36 skills 審查要 1-2 天
API contract 計算型 gate 需要先把 FastAPI OpenAPI output 管線化
三條新 Mobile P0 test 要實作，offline 和 cold start 比 happy path 難

中性：

Verifier agent 延後不是放棄，Evidence Block 同時作為觀察期資料收集
Gemini 的 schema-first 方案保留為 E-modified 的演化路徑