第五章：品質保證機制

5.0 概述

本系統的品質保證架構建立在一個核心信念上：AI 系統的輸出品質不能依賴事後人工校閱，必須在流程的每個環節內建機制性防線。

本章描述三道獨立且互補的品質防線：

1. Hooks（即時） — 在 AI 寫入任何檔案的瞬間，由系統自動執行程式碼層級檢查
2. Cross-Review（流程中） — 在分析流程內部，由多個具有不同立場的 AI agent 進行對抗性審視
3. Eval（事後） — 以量化 scorecard 驗證 skill 的實際輸出品質，並建立可重現的 baseline

這三道防線各有不同的時序、粒度與設計目的，共同構成一套可觀測、可稽核、可迭代的品質管控體系。

5.1 品質保證的三道防線

┌─────────────────────────────────────────────────────────────────────┐
│  第一道防線：Hooks — 即時守門                                         │
│  觸發點：PostToolUse(Write)                                           │
│  作用：在 AI 每次寫檔時，自動執行格式與認識論合規性檢查               │
│  特性：同步執行（blocking 模式可阻擋寫入）、毫秒級回饋                │
├─────────────────────────────────────────────────────────────────────┤
│  第二道防線：Cross-Review — 流程中對抗性審視                          │
│  觸發點：分析流程各關鍵階段（每個 skill 的 stage 之間）               │
│  作用：讓具有不同框架的 AI agent 對同一數據產生有效衝突               │
│  特性：異步執行、質化、可發現系統性盲點                               │
├─────────────────────────────────────────────────────────────────────┤
│  第三道防線：Eval — 事後量化驗證                                      │
│  觸發點：skill 結構級變更前後、baseline 建立期                        │
│  作用：以標準化案例對比 with_skill vs. without_skill 的輸出差異       │
│  特性：可重現、可量化、驅動 skill 迭代決策                            │
└─────────────────────────────────────────────────────────────────────┘

三道防線的設計原則是互補而非重疊：Hooks 捕捉格式與合規問題，Cross-Review 捕捉邏輯與視角盲點，Eval 捕捉整體輸出品質的系統性退化。沒有任何一層可以單獨承擔全部品質責任。

5.2 第一道防線：Hooks 系統

5.2.1 架構概覽

Hooks 是 Claude Code 原生提供的事件驅動機制，允許在 AI 執行特定操作時，自動觸發外部腳本。本系統目前掛載的 hooks 如下：

注意：實際掛載狀態以 ~/.claude/settings.json 為準；REGISTRY.md 是人可讀的 canonical reference，供審計使用。

5.2.2 quality-gate.sh — 認識論合規性守門

檔案位置：/home/ubuntu/.claude/hooks/quality-gate.sh 觸發事件：PostToolUse:Write（AI 寫入任何 .md 檔案時） 執行模式：同步（sync），逾時 10 秒

設計目的

研究與行銷分析系統的最大風險之一，是 AI 將推測性結論以確定語氣呈現，誤導決策者。quality-gate.sh 的核心任務是在分析文件落地的那一刻，自動檢查關鍵品質要件是否存在。

三項檢查內容

檢查一：分析檔案內容完整性

• 對象：stage[0-9]/ 或 mkt-stage[0-9]/ 目錄下的分析檔案
• 規則：內容不得少於 5 行
• 原因：防止 AI 以極度精簡的佔位輸出（placeholder）充當完整分析

檢查二：認識論標記（Epistemic Tags）

• 對象：stage*/、mkt-stage*/、cross-review/、tournament/ 目錄下的分析檔案
• 規則：必須至少出現一個 [L1] 至 [L5] 的信心度標記
• 原因：L1-L5 標記系統是本系統的事實紀律核心（見 5.3.3 節）。缺乏標記意味著 AI 的推論與確定事實無法區分，對決策者構成誤導風險

檢查三：來源引用

• 對象：stage*/、mkt-stage*/ 下的分析檔案
• 規則：必須包含至少一個 URL 引用或來源標注
• 原因：無來源的數據在本系統視為不可信；來源引用是報告可被外部核實的最低要件

執行模式說明

目前 quality-gate.sh 以 advisory 模式運行（所有路徑均以 exit 0 結束），即發現問題時輸出警告至 stderr，但不阻擋寫入操作。如需啟用強制阻擋模式，將最終 exit 0 改為 exit 2 即可，無需修改其他邏輯。

排除清單：SKILL.md、CLAUDE.md、README.md、REGISTRY.md、protocol、template、checklist、framework 等基礎設定檔不受檢查，避免誤殺非分析性寫入。

5.2.3 debate-quality-judge.sh — 辯論品質量化記錄

檔案位置：/home/ubuntu/.claude/hooks/debate-quality-judge.sh 觸發事件：PostToolUse:Write（寫入 cross-review/ 或 stage5/ 時） 執行模式：異步（async），逾時 10 秒

設計目的

跨代理辯論（Cross-Review）是本系統發現分析盲點的核心機制，但辯論品質本身缺乏可觀測性。debate-quality-judge.sh 在每次辯論記錄寫入時自動觸發，以純文本統計指標（不呼叫 LLM）量化辯論品質，並將結果寫入既有月誌（~/.claude/logs/YYYY-MM.jsonl），供後續 review 使用。

量化指標

資料流

所有辯論品質指標寫入既有月誌，格式為：

{
  "date": "2026-03-10",
  "timestamp": "2026-03-10T14:00:00Z",
  "type": "debate-quality",
  "file": "/path/to/cross-review/cr1-topic.md",
  "metrics": {
    "word_count": 2847,
    "epistemic_tags": 23,
    "source_citations": 8,
    "joker_interventions": 2,
    "debate_rounds": 4
  }
}

設計決策：刻意不建立獨立的辯論日誌系統，而是寫回既有月誌。這符合「不新增平行記錄系統」的系統治理原則，避免日誌分散。

5.2.4 runtime-event-log.sh — 生命週期 Telemetry

檔案位置：/home/ubuntu/.claude/hooks/runtime-event-log.sh 觸發事件：InstructionsLoaded、SubagentStart、SubagentStop、ConfigChange 執行模式：異步（async）

設計目的

系統可觀測性的基礎。每次 skill 執行、子代理派遣與結束，都會在月誌中留下可追溯的結構化記錄，包含：

• Session ID 與 Trace ID（跨事件串接）
• 使用的 skill 名稱與執行模式（quick/full/deep）
• 子代理名稱與所用模型
• 執行結果（completed / blocked）與阻擋原因（rate_limit / auth / unknown）

智慧擴充機制

runtime-event-log.sh 包含兩層進階能力：

1. Transcript 解析：從 Claude Code 的 transcript JSONL 中自動提取 skill 名稱、執行模式與模型資訊，確保即使 CLI 呼叫方式不同，telemetry 記錄也保持完整

2. 結果分類（三層 Tier）：

   • Tier 1：從 structured fields（status/reason）判斷，最高信心，無偽陽性
   • Tier 2：從 last_assistant_message 開頭 200 字元判斷，捕捉 provider 封鎖但 structured fields 為 null 的情境
   • Tier 3：未分類 subagent-stop 且有輸出 → 標記 completed

這三層結構確保封鎖事件不會被漏記，同時避免對正常 agent 輸出造成偽陽性分類。

5.2.5 workspace-claude-sync.sh — 指令一致性保證

檔案位置：/home/ubuntu/.claude/hooks/workspace-claude-sync.sh 觸發事件：SessionStart 執行模式：異步（async）

設計目的

~/CLAUDE.md 是 workspace 層的核心指令檔，但當它是一個可被手動覆寫的普通檔案時，存在版本漂移的風險。workspace-claude-sync.sh 在每個 session 啟動時執行，確保 ~/CLAUDE.md 始終是 ~/.claude/workspace.md（repo-tracked source）的 symlink，而非獨立複本。

如果偵測到 ~/CLAUDE.md 是普通檔案（非 symlink），腳本會先備份原檔（CLAUDE.md.bak.<timestamp>），再建立 symlink，確保不會靜默丟失資料。

品質意義：指令一致性是所有 AI 行為品質的前提。如果 workspace 指令在不同 session 之間不一致，所有 hook 和 skill 的行為都可能產生難以重現的差異。

5.3 第二道防線：Cross-Review 流程中對抗性審視

5.3.1 設計原理

Cross-Review 建立在一個重要的研究發現上：同一份數據，由具有不同專業框架的分析師解讀，會得出性質不同的結論。讓 Strategist（策略師）與 Consumer（消費者視角代理）對同一市場數據進行辯論，比任何單一視角的壓力測試都更能揭露分析盲點。

本系統使用 Claude Code 原生的 Agent Teams 機制執行 Cross-Review，確保每個參與辯論的 agent 真正持有獨立的上下文（context），而非在同一執行緒中模擬不同立場。

5.3.2 辯論結構

Cross-Review 的標準結構：

參與者：
├── 張力雙方（由主控依發現的分析張力動態選定）
│   ├── 例：Strategist（競爭優勢視角） vs Consumer（消費者體驗視角）
│   └── 例：Business Intel（競品數據視角） vs Skeptic（風險視角）
├── 碰撞者（中立立場，協助收斂）
└── Joker（框架外視角，在各方趨向假共識時強制介入）

輪次上限：2 輪
依據：S²-MAD 研究顯示同模型辯論超過 2 輪準確率不再提升

記錄：辯論完整記錄 → cross-review/cr[N]-[topic].md
      辯論指標     → ~/.claude/logs/YYYY-MM.jsonl（由 debate-quality-judge.sh 自動記錄）

5.3.3 認識論標記系統（L1-L5）

Cross-Review 的每項結論必須附帶 L1-L5 信心度標記，這是本系統最核心的事實紀律：

硬規則：[L4 假設] 與 [L5 未知] 標記的內容，不得作為核心結論、品牌診斷或策略建議的主要依據。違反此規則是 Cross-Review 的否決條件。

5.3.4 Joker 機制

Joker agent 是 Cross-Review 中專門設計用來打破假共識的角色。當辯論雙方趨向收斂時，Joker 的職責是提出第三路徑或框架外的問題，確保辯論不會過早結束。

歷史教訓（Suzuki 專案）：在 cr1 階段僅使用 Skeptic 單一視角壓力測試，未發現品質認知三層拆分、雙向因果鎖定等關鍵洞察。直到 cr2 導入多視角碰撞，這些洞察才浮現。這個案例確立了「Cross-Review 不可只用單一視角」的系統規則。

5.4 第三道防線：Eval Framework

5.4.1 設計目的

Hooks 和 Cross-Review 解決了流程中的品質問題，但無法回答一個更根本的問題：skill 本身是否真的比沒有 skill 時表現得更好？ Eval Framework 的目的是建立可量化、可重現的答案。

5.4.2 Eval 架構

每個核心 skill 都有一組標準化的評估案例，儲存在 ~/.claude/skills/<skill-name>/evals/evals.json：

{
  "skill_name": "brand-research",
  "evals": [
    {
      "id": 1,
      "prompt": "/brand-research 星巴克 台灣咖啡連鎖",
      "expected_output": "描述完整輸出的預期結構",
      "expectations": [
        "具體、可程式化驗證的輸出要件（8 項）"
      ]
    }
  ]
}

設計原則：每個 expectation 必須是可程式化判斷的命題（true/false），而非主觀評分。這確保評估結果可重現，不受評估者主觀影響。

5.4.3 Scorecard 評分機制

每個 eval 案例的評分基於 expectations 通過率：

scorecard = 通過的 expectations 數量 / 總 expectations 數量

例：brand-research BR-001
  通過：8/8 expectations
  scorecard = 10/10（滿分）

5.4.4 with_skill vs. without_skill 對比

Eval Framework 的核心是對比實驗設計：

with_skill configuration:
  使用完整 SKILL.md 指令 + 多 agent 流程 + 所有品質機制
  → 記錄 scorecard 分數與 pass/fail

without_skill configuration:
  僅使用同等的 prompt，不載入 SKILL.md
  → 記錄 scorecard 分數與 pass/fail

delta = with_skill score - without_skill score

delta 是 skill 實際附加價值的量化指標。正值越大，代表 skill 的設計越有效。

5.5 已建立的 Baseline 數據

以下三組 baseline 於 2026-03-09 完成，是系統品質保證的第一批量化錨點：

BR-001 — Brand Research Baseline

解讀：沒有 skill 時，輸出缺乏認識論標記、來源引用格式不符規範、研究限制聲明缺失等結構性要件。skill 的介入將合規率從 25% 提升至 100%。

MKT-001 — Marketing Baseline

解讀：marketing skill 的多階段 agent dispatch 機制（品質門、驗證層、來源品質閘門）對輸出結構合規性有顯著提升效果。扣分項目已記錄為後續版本改善目標。

成本注記：marketing skill 因涉及多階段 agent 派遣，token 消耗約為基準的 4.6 倍（相較 brand-research 的 2.3 倍、research 的 2.2 倍）。成本優化若涉及階段精簡，需重跑 MKT-001 驗證 delta 不退化。

RES-001 — Research Baseline

解讀：research skill 的 delta 最高，反映 full 模式的多輪 cross-review、InsightCard 格式規範、來源品質閘門等機制，對無結構化指令的基礎 AI 輸出改善幅度最為顯著。

Baseline 彙總

三組 baseline 全部通過，建立了系統的初始品質錨點。

重要限制：目前每組 baseline 只有 1 次 run。依照 eval protocol（skill-eval.md 第 113 行），涉及結構級變更的比較需要 3-run window 才能排除單次執行的隨機性。當前數據作為初始參考基準有效，但不應作為統計顯著性的依據。

5.6 持續改善機制

5.6.1 Eval 數據驅動 Skill 迭代的決策路徑

┌─────────────────────────────────────────────────────────┐
│  觸發條件                                                 │
│  ├── 結構級變更（新增/移除階段、修改 agent 組合）          │
│  ├── 成本優化（涉及 token 削減的設計調整）                │
│  └── 定期品質審視（季度 review）                          │
├─────────────────────────────────────────────────────────┤
│  執行步驟                                                 │
│  1. 在 new_skill 和 old_skill 兩種 config 下各跑 eval     │
│  2. 每種 config 至少跑 3 次（3-run window）               │
│  3. 比較兩組 delta 的均值與變異                           │
│  4. 若 new_skill delta 未退化 → 合併變更                  │
│  5. 若 new_skill delta 退化 → 回滾並記錄失敗原因          │
├─────────────────────────────────────────────────────────┤
│  記錄要求                                                 │
│  ├── Baseline ID 採版本化命名（BR-001 v1 / BR-002 v1）    │
│  ├── 不覆寫舊 baseline，保留歷史數據供追溯                │
│  └── 變更決策記錄於 skill 的 DECISIONS.md                 │
└─────────────────────────────────────────────────────────┘

5.6.2 三條後續路線

路線 B（已就緒，待觸發）：結構級變更比較

• 條件：任一核心 skill（brand-research / marketing / research）進行結構級變更
• 執行：new_skill/old_skill config pair + 3-run window
• 所有基礎設施（protocol、registry、evals.json、run_eval.py）已就緒，待變更觸發時即可執行

路線 A（需定案）：Expectation 進化

• 目標：從 BR-001 / MKT-001 / RES-001 進化到 BR-002 / MKT-002 / RES-002（更嚴格的 expectations）
• 前置：定案 Benchmark ID 版本化規則，確保新版 baseline 不覆蓋舊版，保留對比能力

路線 C（需設計）：Description Trigger Lane

• 目標：評估非 slash command 觸發的 skill（如 brainstorm、tool-research 類）
• 前置：設計 multi-skill trigger 評分機制（現行 run_eval.py 只支援單 skill 二元判定）

5.6.3 Telemetry 作為長期品質信號

除了主動 eval，runtime-event-log.sh 累積的 telemetry 資料提供另一條品質信號路徑：

• SubagentStop 結果分布：正常 completed vs blocked 的比率，若 blocked 比率上升，代表系統穩定性問題
• skill + mode 使用分布：哪些 skill 的哪個模式被實際使用，驗證 agent portfolio 設計是否符合實際需求
• 評估時機：每月檢視一次 telemetry 摘要，每季做一次 agent portfolio 與 skill 架構的系統性審視

審視節奏規則：至少累積 10 次核心 skill run 後才做 monthly review；至少累積 30 天使用資料後才判定 agent merge/deprecate。用數據驅動決策，不憑感覺砍能力。

5.7 品質管控體系的治理原則

本品質保證機制遵循以下不可違背的治理原則：

1. 不建立平行系統 所有品質記錄（eval 結果、辯論指標、生命週期事件）寫回既有 ~/.claude/logs/YYYY-MM.jsonl。禁止為品質保證另建獨立資料庫或日誌系統。

2. 可觀測性優先 任何未被記錄的品質事件等同於未發生。Hooks 的 telemetry 覆蓋、eval 的 scorecard 記錄、辯論品質的 JSONL 寫入，三者共同確保系統的完整可觀測性。

3. Baseline 不可被覆寫 已建立的 baseline（BR-001、MKT-001、RES-001）作為歷史錨點永久保存。新版本測試採版本化 ID（v2、v3），不覆蓋舊版。

4. 品質門可升級為阻擋 quality-gate.sh 目前以 advisory 模式運行。當系統成熟度足夠、已驗證誤殺率可接受時，可將 exit 0 改為 exit 2，在不修改任何其他邏輯的前提下，將建議層升級為強制阻擋層。

5. 數據驅動，非感覺驅動 所有 skill 結構調整、agent 合併/退役決策，必須有 telemetry 或 eval 數據支持。沒有數據的主觀判斷不得作為架構變更的理由。

5.8 章節小結

本章描述的品質保證體系已通過三組 baseline（BR-001、MKT-001、RES-001）的初始驗證，確認 skill 機制相較於無結構化指令的 delta 在 +0.62 至 +0.81 之間。系統的設計使得品質標準可隨業務需求提升（收緊 expectations、啟用阻擋模式、增加 eval 案例），而不需要重構基礎架構。

文件屬於：ceo-high-level-insights 專案系統架構說明書 下一章：第六章 成本管控與 Token 效率