代理框架架構 2026：圖表參考

重點摘要： Claude Code不是一個能存取檔案的聊天框。它是一個可程式化的執行環境，具備22個生命週期事件，每個事件都可透過 shell 腳本掛鉤，模型無法跳過。將 hooks 堆疊成 dispatchers，dispatchers 組成 skills，skills 組成 agents，agents 組成 workflows，便能打造出一套自主開發 harness——強制執行約束、委派工作、跨工作階段保存記憶，並協調多代理審議。本指南涵蓋這套架構的每一層：從單一 hook 到10個代理的共識系統。不需要任何框架，全部使用 bash 和 JSON。

Andrej Karpathy 為圍繞 LLM 代理成長的東西創造了一個術語：爪子（claws）。那些讓代理得以觸及上下文視窗之外世界的 hooks、腳本和編排機制。¹ 多數開發者把 AI 程式碼代理當作互動式助手使用——輸入提示、看它編輯檔案、然後繼續下一件事。這種思維模式將生產力上限鎖定在您個人能親自監督的範圍內。

基礎設施的思維模式截然不同：AI 程式碼代理是一個以 LLM 為核心的可程式化執行環境。模型採取的每一個動作都會經過您控制的 hooks。您定義的是策略，而非提示詞。模型在您的基礎設施中運作，就像網頁伺服器在 nginx 規則中運作一樣。您不會坐在 nginx 前面輸入請求，而是設定它、部署它、監控它。

這個區別至關重要，因為基礎設施會產生複利效應。一個在 bash 指令中阻擋憑證的 hook，能保護每個工作階段、每個代理、每次自主執行。一個編碼了您評估標準的 skill，無論是您手動呼叫還是代理自動呼叫，都能一致地套用。一個審查程式碼安全性的代理，無論您是否在旁監看，都會執行相同的檢查。²

關鍵要點

• Hooks 保證執行；提示詞無法保證。 對於程式碼檢查、格式化、安全檢查，以及任何必須在每次執行時都運行——不受模型行為影響——的事項，請使用 hooks。Exit code 2 會阻擋動作，Exit code 1 僅發出警告。³
• Skills 編碼可自動啟動的領域專業知識。 description 欄位決定一切。Claude 使用 LLM 推理（而非關鍵字比對）來判斷何時套用某個 skill。⁴
• Subagents 防止上下文膨脹。 為探索和分析提供隔離的上下文視窗，讓主工作階段保持精簡。最多可同時並行運行10個。⁵
• 記憶存在於檔案系統中。 檔案能跨上下文視窗持久保存。CLAUDE.md、MEMORY.md、rules 目錄和交接文件構成了一套結構化的外部記憶系統。⁶
• 多代理審議能發現盲點。 單一代理無法挑戰自身的假設。兩個具有不同評估優先順序的獨立代理，能捕捉到 quality gates 無法解決的結構性缺陷。⁷
• Harness 模式即是整個系統。 CLAUDE.md、hooks、skills、agents 和記憶並非各自獨立的功能，它們組合成您與模型之間的確定性層，隨著自動化程度的提升而擴展。

如何使用本指南

每個章節都建立在前一章的基礎上。末尾的決策框架提供了一份查找表，幫助您為每種問題類型選擇正確的機制。

五分鐘黃金路徑

在深入探討之前,這是從零到建立可運作 harness 的最短路徑。一個 hook、一個 skill、一個 subagent,一個成果。

步驟 1:建立安全 hook(2 分鐘)

建立 .claude/hooks/block-secrets.sh:

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -qEi '(AKIA|sk-|ghp_|password=)'; then
    echo "BLOCKED: Potential secret in command" >&2
    exit 2
fi

在 .claude/settings.json 中串接:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/block-secrets.sh" }]
      }
    ]
  }
}

結果:Claude 執行的每一個 bash 指令都會被篩檢是否洩漏憑證。模型無法略過此檢查。

步驟 2:建立程式碼審查 skill(1 分鐘)

建立 .claude/skills/reviewer/SKILL.md,包含 frontmatter(name: reviewer、description: Review code for security issues, bugs, and quality problems. Use when examining changes, reviewing PRs, or auditing code.、allowed-tools: Read, Grep, Glob)以及檢查清單:SQL injection、XSS、硬編碼密鑰、缺漏的錯誤處理、超過 50 行的函式。

結果:每當您提及審查、檢查或稽核時,Claude 會自動啟用這項專業能力。

步驟 3:派出 subagent(30 秒)

在任何 Claude Code session 中,請 Claude 使用獨立代理審查最近 3 次 commit 的安全問題。Claude 會派出一個 Explore agent 讀取 diff、套用您的審查 skill,並回傳摘要。您的主要 context 保持乾淨。

您現在擁有什麼

一個三層 harness:決定性的安全關卡(hook)、會自動啟用的領域專業知識(skill),以及保護您 context 的隔離分析(subagent)。以下每一節都會深入擴展這三層中的一層。

為什麼 Agent Architecture 至關重要

Simon Willison 用一個觀察點出了當前的時刻:撰寫程式碼現在很便宜。⁸ 沒錯。但隨之而來的推論是,驗證現在才是昂貴的部分。缺乏驗證基礎架構的廉價程式碼,只會大規模製造 bug。真正值得投資的不是更好的提示詞,而是模型周圍那套能捕捉模型遺漏之處的系統。

有三股力量讓 agent architecture 成為必要:

Context window 是有限且會耗損的。每一次檔案讀取、工具輸出與對話輪次都會消耗 token。Microsoft Research 與 Salesforce 針對 15 個 LLM 進行了超過 20 萬次模擬對話測試,發現從單輪互動到多輪互動平均效能下降 39%。⁹ 退化最快在兩輪之內就開始,並依循可預測的曲線:前 30 分鐘還能精準完成多檔案編輯,到第 90 分鐘就退化為單檔案的隧道視野。更長的 context window 並無法解決這個問題。同一份研究的「Concat」條件(將完整對話作為單一提示詞)以相同內容達到單輪效能的 95.1%。退化來自輪次邊界,而非 token 上限。

模型行為是機率性的,而非決定性的。告訴 Claude「編輯檔案後一律執行 Prettier」大約有 80% 的時候會成功。³ 模型可能忘記、可能優先考慮速度,或判斷該變更「太小」。對於合規、安全與團隊標準而言,80% 並不可接受。Hooks 能保證執行:每一次 Edit 或 Write 都會觸發您的 formatter,次次如此,毫無例外。決定性勝過機率性。

單一視角會遺漏多維度的問題。一個審查 API endpoint 的 agent 檢查了身份驗證、驗證了輸入清理並核對了 CORS 標頭。一切看似無恙。但第二個 agent 在獨立提示下以滲透測試者身份介入,發現該 endpoint 接受無上限的查詢參數,可能透過資料庫查詢放大觸發阻斷服務攻擊。⁷ 第一個 agent 從未檢查這點,因為其評估框架中並未把查詢複雜度視為安全面向。這個缺口是結構性的。再多的提示詞工程也無法彌補。

Agent architecture 同時解決這三者:hooks 強制執行決定性限制、subagents 管理 context 隔離,而多代理協調提供獨立視角。它們共同構成了 harness。

Harness 模式

Harness 並非框架，而是一種模式：由檔案、指令碼與慣例組成的可組合集合，將 AI 編碼代理包裹在確定性基礎設施之中。其組成元件如下：

┌──────────────────────────────────────────────────────────────┐
│                      THE HARNESS PATTERN                      │
├──────────────────────────────────────────────────────────────┤
│  ORCHESTRATION                                                │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │   Agent     │  │   Agent    │  │  Consensus │             │
│  │   Teams     │  │  Spawning  │  │  Validation│             │
│  └────────────┘  └────────────┘  └────────────┘             │
│  Multi-agent deliberation, parallel research, voting          │
├──────────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Skills   │  │  Hooks   │  │  Memory  │  │  Agents  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  Domain expertise, deterministic gates, persistent state,     │
│  specialized subagents                                        │
├──────────────────────────────────────────────────────────────┤
│  INSTRUCTION LAYER                                            │
│  ┌──────────────────────────────────────────────────────┐    │
│  │     CLAUDE.md  +  .claude/rules/  +  MEMORY.md       │    │
│  └──────────────────────────────────────────────────────┘    │
│  Project context, operational policy, cross-session memory    │
├──────────────────────────────────────────────────────────────┤
│  CORE LAYER                                                   │
│  ┌──────────────────────────────────────────────────────┐    │
│  │           Main Conversation Context (LLM)             │    │
│  └──────────────────────────────────────────────────────┘    │
│  Your primary interaction; finite context; costs money        │
└──────────────────────────────────────────────────────────────┘

指令層（Instruction Layer）： CLAUDE.md 檔案與規則資料夾定義了代理對您專案的認知。它們會在工作階段啟動時以及每次壓縮之後自動載入，是代理的長期架構記憶。

擴充層（Extension Layer）： skills 提供依情境自動啟用的領域專業知識。hooks 提供在每次符合條件的工具呼叫時觸發的確定性關卡。記憶檔案可跨工作階段持久化狀態。自訂代理則提供專屬的 subagents 設定。

編排層（Orchestration Layer）： 多代理模式協調獨立代理進行研究、審查與審議。生成預算可防止失控的遞迴，共識驗證則確保品質。

關鍵洞見：多數使用者完全在核心層（Core Layer）中運作，眼睜睜看著情境膨脹、成本攀升。進階使用者則會設定指令層與擴充層，然後僅將核心層用於編排與最終決策。²

託管式與自架 Harness 的比較（2026 年 4 月）

綜觀 2026 年初，「自行建構 harness」一直是唯一真正可行的路線。直到 2026 年 4 月，情況有了轉變。Anthropic 於 4 月 8 日推出 Claude Managed Agents 公開測試版：將 harness 迴圈、工具執行、沙箱容器與狀態持久化整合為一個 REST API，以標準 token 計費，另加每工作階段小時 $0.08。OpenAI 於 4 月 16 日發布的 Agents SDK 更新，則正式確立了同樣的分層架構——harness 與計算資源各為獨立層級，並提供原生沙箱供應商（Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel），以及用於承受容器遺失的快照/還原機制。²³²⁴

架構上的分歧已成定局：

何時選擇何種方案： 對於已具備基礎設施實力、想要完全掌控 skills/hooks，或正在深度優化特定工作流程的團隊而言，自架仍是正確選擇。若團隊沒有專屬的平台工程師、當產出時間比客製化更重要，或當代理執行需要可靠地撐過筆電關機——而又不願自行建構持久化層時，託管則較為合適。兩者並非互斥——您可以運行自架 harness，再透過其 REST API 將特定長時間任務「委派」給 Managed Agents。

Harness 在磁碟上的實際樣貌

~/.claude/
├── CLAUDE.md                    # Personal global instructions
├── settings.json                # User-level hooks and permissions
├── skills/                      # Personal skills (44+)
│   ├── code-reviewer/SKILL.md
│   ├── security-auditor/SKILL.md
│   └── api-designer/SKILL.md
├── agents/                      # Custom subagent definitions
│   ├── security-reviewer.md
│   └── code-explorer.md
├── rules/                       # Categorized rule files
│   ├── security.md
│   ├── testing.md
│   └── git-workflow.md
├── hooks/                       # Hook scripts
│   ├── validate-bash.sh
│   ├── auto-format.sh
│   └── recursion-guard.sh
├── configs/                     # JSON configuration
│   ├── recursion-limits.json
│   └── deliberation-config.json
├── state/                       # Runtime state
│   ├── recursion-depth.json
│   └── agent-lineage.json
├── handoffs/                    # Session handoff documents
│   └── deliberation-prd-7.md
└── projects/                    # Per-project memory
    └── {project}/memory/MEMORY.md

.claude/                         # Project-level (in repo)
├── CLAUDE.md                    # Project instructions
├── settings.json                # Project hooks
├── skills/                      # Team-shared skills
├── agents/                      # Team-shared agents
└── rules/                       # Project rules

此結構中的每個檔案都各有用途。~/.claude/ 樹狀結構是適用於所有專案的個人基礎設施；各個儲存庫中的 .claude/ 樹狀結構則屬於專案專屬，並透過 git 共享。兩者合一，構成完整的 harness。

Skills 系統

skills 是由模型自行調用的擴充機制。Claude 會依據情境自動發現並套用它們，無需您明確呼叫。⁴ 當您發現自己在不同工作階段中反覆說明同一組情境時，就是該建立一個 skill 的時刻。

何時該建立 skill

skills 存放的是Claude 隨時可取用的知識；斜線命令則對應您明確觸發的動作。若您在兩者之間猶豫，請自問：「這應該由 Claude 自動套用，還是由我決定何時執行？」

建立 skill

skills 可存放於四個位置，範圍由廣至窄：⁴

每個 skill 都需要一個帶有 YAML frontmatter 的 SKILL.md 檔案：

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## 安全檢查
審查程式碼時，請確認以下事項：

### 輸入驗證
- 所有使用者輸入在資料庫操作前皆已淨化
- 使用參數化查詢（SQL中不得使用字串插值）
- 對呈現的HTML內容進行輸出編碼

### 身份驗證
- 每個受保護的端點皆驗證工作階段權杖
- 資料變更前執行權限檢查
- 原始碼中不得硬編碼任何憑證或API金鑰

Frontmatter參考

Description欄位至關重要

工作階段啟動時，Claude Code會擷取每個skill的name與description，並將其注入Claude的context之中。當您傳送訊息時，Claude會運用語言模型推理來判斷是否有相關的skill可供使用。對Claude Code原始碼的獨立分析已證實此機制：skill描述會被注入系統提示的available_skills區段，模型再透過標準的語言理解能力挑選出相關的skills。¹⁰

不良的description：

description: Helps with code

有效的description：

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

有效的description包含三個要素：該skill的功能（審查程式碼的特定問題類型）、使用時機（審視變更、PR、品質分析），以及使用者自然會輸入的觸發詞彙（review、audit、check）。

Context預算

所有skill的描述共享一個動態調整的context預算，其大小為context window的2%，預設上限為16,000個字元。⁴ 若skills數量眾多，請讓每個description保持精簡。您可透過SLASH_COMMAND_TOOL_CHAR_BUDGET環境變數覆寫此預算，¹¹ 但更好的解決之道是撰寫更簡短、更精確的description。工作階段執行中可執行/context來檢查是否有skills遭到排除。

支援檔案與組織結構

Skills可引用同一目錄中的其他檔案：

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

請從SKILL.md以相對連結引用這些檔案。當skill啟用時，Claude會依需求讀取這些檔案。請將SKILL.md控制在500行以內，並將詳細的參考資料移至支援檔案。¹²

透過Git分享Skills

專案skills（儲存庫根目錄下的.claude/skills/）可透過版本控制分享：⁴

mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

當團隊成員拉取更新時，便會自動取得該skill。無需安裝，也不用設定。這是在團隊中標準化專業知識最有效的方式。

Skills作為提示詞資料庫

除了單一用途的skills之外，此目錄結構也能作為一個有系統的提示詞資料庫：

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

每個skill都編碼了您專業知識的不同面向。它們共同構成一個知識庫，Claude會根據context自動汲取運用。初階開發者無需主動詢問，便能獲得資深等級的指導。

Skills與Hooks相輔相成

Skills可在frontmatter中定義自己的hooks，這些hooks僅在skill執行期間啟用。如此一來，便能建立不會污染其他工作階段的領域專屬行為：²

---
name: deploy-checker
description: Verify deployment readiness. Use when preparing to deploy,
  release, or push to production.
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"deploy|release|publish\"; then echo \"DEPLOYMENT COMMAND DETECTED. Running pre-flight checks.\" >&2; fi'"
---

哲學類skills透過SessionStart hooks自動啟用，無需明確叫用即可將品質約束注入每個工作階段。Skill本身是知識，hook則是強制執行。兩者結合，便形成一套策略層。

常見的Skill錯誤

描述過於寬泛。 一個git-rebase-helper skill若在任何與git相關的提示下都會啟用（變基、合併、挑選提交，甚至git status），將會污染80%工作階段的context。解決之道是收緊description，或加上disable-model-invocation: true並要求明確執行/skill-name來叫用。⁴

過多skills爭奪預算。 Skills越多，就有越多descriptions爭奪那2%的context預算。若您發現skills未能啟用，請以/context檢查是否有遭排除者。寧可擁有少而精、描述清楚的skills，也不要追求數量卻含糊不清。

關鍵資訊埋沒於支援檔案。 Claude會立即讀取SKILL.md，但僅在需要時才會存取支援檔案。若關鍵資訊藏於支援檔案中，Claude可能找不到。請將必要資訊直接寫入SKILL.md。⁴

Hook 架構

Hook是由Claude Code生命週期事件觸發的shell指令。³它們以普通腳本的形式在LLM外部執行,而非由模型解讀的提示詞。模型想執行rm -rf /?只需一個10行的bash腳本,就能在shell接手之前將該指令與黑名單比對並拒絕。不論模型是否樂意,Hook都會觸發。

可用事件

Claude Code在七大類別中公開了超過26個生命週期事件(事件清單會隨版本發佈而增加——請查閱cheat sheet以取得最新完整表格):¹³

結束代碼語意

結束代碼決定Hook是否封鎖動作:³

關鍵重點:每個安全性Hook都必須使用exit 2,而非exit 1。Exit 1是非封鎖警告,危險指令仍會執行。這是各團隊最常犯的Hook錯誤。¹⁴

Hook 設定

Hook位於設定檔中。專案層級(.claude/settings.json)用於共享Hook,使用者層級(~/.claude/settings.json)則用於個人Hook:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

matcher欄位是比對工具名稱的正規表示式:Bash、Write、Edit、Read、Glob、Grep、Agent,或*代表所有工具。對於UserPromptSubmit這類不涉及工具的事件,請使用""(空字串)。

Hook 輸入/輸出協定

Hook從stdin接收JSON,附帶完整上下文:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123",
  "agent_id": "main",
  "agent_type": "main"
}

若需進階控制,PreToolUse Hook可輸出JSON以修改工具輸入、注入上下文或做出權限決策。請使用hookSpecificOutput包裝器——較舊的頂層decision/reason格式已於PreToolUse中停用:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

三種保證類型

在撰寫任何Hook之前,請先問:我需要哪種保證?¹⁴

格式化保證確保事後一致性。Write/Edit的PostToolUse Hook會在每次檔案變更後執行您的格式化工具。模型的輸出內容無關緊要,因為格式化工具會將一切正規化。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; elif [[ \"$FILE_PATH\" == *.js ]] || [[ \"$FILE_PATH\" == *.ts ]]; then npx prettier --write \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

安全性保證能在危險動作執行前加以防止。Bash的PreToolUse Hook會檢視指令,並以結束代碼2封鎖具破壞性的模式:

#!/bin/bash
# validate-bash.sh — block dangerous commands
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "rm\s+-rf\s+/|git\s+push\s+(-f|--force)\s+(origin\s+)?main|git\s+reset\s+--hard|DROP\s+TABLE"; then
    echo "BLOCKED: Dangerous command detected: $CMD" >&2
    exit 2
fi

品質保證在決策點驗證狀態。git commit指令的PreToolUse Hook會執行您的linter或測試套件,若品質檢查失敗便封鎖該次提交:

#!/bin/bash
# quality-gate.sh — lint before commit
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "^git\s+commit"; then
    if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then
        echo "LINT FAILED -- fix before committing:" >&2
        echo "$LINT_OUTPUT" >&2
        exit 2
    fi
fi

超越Shell指令的Hook類型

Claude Code支援四種Hook類型:¹³

Command Hook(type: "command")執行shell腳本。快速、決定性、無token成本。

Prompt Hook(type: "prompt")將單輪提示詞傳送給快速的Claude模型。模型回傳{ "ok": true }表示允許,或{ "ok": false, "reason": "..." }表示封鎖。適用於正規表示式無法表達的細膩判斷。

Agent Hook(type: "agent")會產生一個具備工具存取權(Read、Grep、Glob)的subagent,用於多輪驗證。當檢查需要檢視實際檔案或測試輸出時,就派上用場:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

HTTP Hook(type: "http")會將事件的JSON輸入作為POST請求傳送至URL,並接收JSON回應。適用於webhook、外部通知服務或基於API的驗證(v2.1.63+)。不支援SessionStart事件:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook.example.com/hook",
            "headers": { "Authorization": "Bearer $WEBHOOK_TOKEN" },
            "allowedEnvVars": ["WEBHOOK_TOKEN"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

非同步Hook

Hook可以在背景執行,不阻擋流程。針對通知和日誌紀錄這類非關鍵操作,請加上async: true:¹³

{
  "type": "command",
  "command": ".claude/hooks/notify-slack.sh",
  "async": true
}

非同步適用於通知、遙測和備份。切勿對格式化、驗證或任何必須在下一步動作前完成的事項使用非同步。

Dispatcher勝過獨立Hook

讓七個Hook同時在相同事件上觸發,各自獨立讀取stdin,會造成競態條件。兩個Hook同時寫入同一個JSON狀態檔,會把JSON截斷。接著每個解析該檔案的下游Hook都會失效。²

解決之道:每個事件配置一個dispatcher,從快取的stdin依序執行各Hook:

#!/bin/bash
# dispatcher.sh — run hooks sequentially with cached stdin
INPUT=$(cat)
HOOK_DIR="$HOME/.claude/hooks/pre-tool-use.d"

for hook in "$HOOK_DIR"/*.sh; do
    [ -x "$hook" ] || continue
    echo "$INPUT" | "$hook"
    EXIT_CODE=$?
    if [ "$EXIT_CODE" -eq 2 ]; then
        exit 2  # Propagate block
    fi
done

偵錯Hook

五種用於偵錯默默失敗Hook的技巧:¹⁴

1. 獨立測試腳本。傳入範例JSON:echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. 使用stderr輸出除錯訊息。結束代碼2的stderr會以錯誤訊息的形式回傳給Claude。非封鎖的stderr(exit 1、3等)僅在verbose模式下顯現(Ctrl+O)。
3. 留意jq失敗。錯誤的JSON路徑會默默回傳null。請用真實的工具輸入測試jq表達式。
4. 驗證結束代碼。使用exit 1的PreToolUse Hook看起來運作正常,實際上完全不具強制力。
5. 讓Hook保持快速。Hook是同步執行的。請將所有Hook控制在2秒以內,最好在500毫秒以內。

記憶與上下文

每次 AI 對話都在有限的上下文視窗內運作。隨著對話增長，系統會壓縮較早的輪次以騰出空間容納新內容。這種壓縮是有損的。第 3 輪記錄的架構決策可能無法保留到第 15 輪。⁹

多輪崩潰的三種機制

MSR/Salesforce 的研究識別出三種獨立的機制，每一種都需要不同的介入方式：⁹

策略 1：以檔案系統作為記憶

跨越上下文邊界最可靠的記憶儲存在檔案系統中。Claude Code 會在每次工作階段開始時，以及每次壓縮後讀取 CLAUDE.md 與記憶檔案。⁶

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

MEMORY.md 檔案會跨工作階段記錄錯誤、決策與模式。當您發現 ((VAR++)) 在 VAR 為 0 時搭配 set -e 會失敗，您便將其記錄下來。三個工作階段之後，當您在 Python 中遇到類似的整數邊界狀況時，MEMORY.md 條目便會將該模式浮現出來。¹⁵

Auto Memory（v2.1.32+）： Claude Code 會自動記錄並回憶專案上下文。當您工作時，Claude 會將觀察寫入 ~/.claude/projects/{project-path}/memory/MEMORY.md。Auto memory 會在工作階段開始時將前 200 行載入系統提示中。請保持內容精簡，並為詳細筆記連結到獨立的主題檔案。⁶

策略 2：主動壓縮

Claude Code 的 /compact 指令會摘要對話並釋放上下文空間，同時保留關鍵決策、檔案內容與任務狀態。¹⁵

何時進行壓縮： - 完成一項獨立的子任務之後（功能實作完成、bug 修復完成） - 在開始處理程式碼庫的新區域之前 - 當 Claude 開始重複或遺忘較早的上下文時 - 在密集工作階段中大約每 25 至 30 分鐘一次

在 CLAUDE.md 中自訂壓縮指令：

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

策略 3：工作階段交接

對於跨越多個工作階段的任務，建立能捕捉完整狀態的交接文件：

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

Status/Files/Decision/Blocked/Next 的結構能以極低的 token 成本，為後續工作階段提供完整的上下文。使用 claude -c（繼續）啟動新工作階段，或是讀取交接文件，都能直接進入實作階段。¹⁵

策略 4：全新上下文迭代（Ralph Loop）

對於超過 60 至 90 分鐘的工作階段，每次迭代皆啟動一個全新的 Claude 實例。狀態透過檔案系統保存，而非透過對話記憶。每次迭代都能獲得完整的上下文預算：¹⁶

Iteration 1: [200K tokens] -> writes code, creates files, updates state
Iteration 2: [200K tokens] -> reads state from disk, continues
Iteration 3: [200K tokens] -> reads updated state, continues
...
Iteration N: [200K tokens] -> reads final state, verifies criteria

與單一長時間工作階段相比：

Minute 0:   [200K tokens available] -> productive
Minute 30:  [150K tokens available] -> somewhat productive
Minute 60:  [100K tokens available] -> degraded
Minute 90:  [50K tokens available]  -> significantly degraded
Minute 120: [compressed, lossy]     -> errors accumulate

全新上下文迭代的做法以 15% 至 20% 的定向步驟成本（讀取狀態檔案、掃描 git 歷史），換取每次迭代的完整認知資源。¹⁶ 成本效益的計算方式為：對於 60 分鐘以下的工作階段，單一對話較有效率。超過 90 分鐘後，儘管有額外開銷，全新上下文仍能產生更高品質的輸出。

反模式

只需要 10 行時卻讀取整個檔案。 一次讀取 2,000 行的檔案會消耗 15,000 至 20,000 個 token。請善用行偏移：Read file.py offset=100 limit=20 能節省絕大部分的成本。¹⁵

將冗長的錯誤輸出保留在上下文中。 除錯完一個 bug 之後，您的上下文裡堆積了 40 多個失敗迭代的堆疊追蹤。在修復 bug 之後執行一次 /compact，便能釋放這些無用的負擔。

每個工作階段一開始就讀取所有檔案。 讓 Claude Code 的 glob 與 grep 工具按需尋找相關檔案，能節省超過 100,000 個不必要的預先載入 token。¹⁵

Subagent 模式

Subagent 是專門的Claude執行實例，能夠獨立處理複雜任務。它們以乾淨的上下文啟動（不會受主對話污染），使用指定工具運作，並以摘要形式回傳結果。探索過程的結果不會讓主對話膨脹，只有結論會回傳。⁵

內建 Subagent 類型

建立自訂 Subagent

在 .claude/agents/（專案）或 ~/.claude/agents/（個人）中定義 subagent：

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code
  changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Subagent 設定欄位

Worktree 隔離

Subagent 可在臨時的 git worktree 中運作，提供完整隔離的程式碼庫副本：⁵

---
name: experimental-refactor
description: Attempt risky refactoring in isolation
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

You have an isolated copy of the repository. Make changes freely.
If the refactoring succeeds, the changes can be merged back.
If it fails, the worktree is discarded with no impact on the main branch.

對於可能破壞程式碼庫的實驗性工作，worktree 隔離是不可或缺的。

平行 Subagent

Claude Code 最多支援 10 個平行 subagent。⁵ 對於獨立的研究任務，請善用平行執行：

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

每個 agent 在自己的上下文視窗中執行，找到相關程式碼並回傳摘要。主上下文保持乾淨。

遞迴防護

若沒有生成限制，agent 會委派給 agent，後者又委派給另一個 agent，每一層都會流失上下文並消耗 token。遞迴防護模式可強制執行預算上限：¹⁶

#!/bin/bash
# recursion-guard.sh — enforce spawn budget
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"

MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

# Read current depth
current_depth=$(jq -r '.depth // 0' "$STATE_FILE" 2>/dev/null)

if [[ "$current_depth" -ge "$MAX_DEPTH" ]]; then
    echo "BLOCKED: Maximum recursion depth ($MAX_DEPTH) reached" >&2
    exit 2
fi

# Increment depth using safe arithmetic (not ((VAR++)) with set -e)
new_depth=$((current_depth + 1))
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

關鍵教訓： 使用生成預算，而非僅限制深度。以深度為基礎的限制會追蹤父子鏈（在深度 3 處阻擋），卻忽略了寬度：深度 1 的 23 個 agent 仍然是「深度 1」。生成預算會追蹤每個父級所累積的活躍子代總數，並設定可調的上限。預算模型對應到實際的失敗模式（agent 總量過多），而不是代理指標（巢狀層級過深）。⁷

Agent Teams（研究預覽）

Agent Teams 可協調多個Claude Code執行實例，使其獨立工作、透過共享信箱與任務清單進行溝通，並能互相質疑彼此的發現：⁵

以下列指令啟用：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

何時使用 agent teams 而非 subagent：

多代理協作編排

單一代理 AI 系統存在結構性盲點：它們無法挑戰自身的假設。⁷ 多代理審議機制會在任何決策定案之前，強制從多個視角進行獨立評估。

跨工具協作編排（2026 年 4 月）： Google 於 4 月 7 日開源了 Scion —— 這是一款多代理 hypervisor，能將 Claude Code、Gemini CLI 及其他「deep agents」作為並行行程執行，每個代理都具備獨立的容器、git worktree 與憑證。可於本機、hub 或 Kubernetes 上運行。其明確的設計哲學為：「以隔離取代限制」—— 代理在基礎架構層所強制執行的邊界之內，以高度自主性運作，而非仰賴 prompt 層級的約束。²⁵ 這直接將 subagent 隔離的論點擴展到了不同的工具廠商之間。若您的工作流程橫跨 Claude 與 OpenAI 模型，Scion 便是首個真正具備每代理 worktree 加憑證隔離能力的跨工具 subagent 參考實作。

辯論並非萬靈丹： M3MAD-Bench 研究團隊（2026 年初）發現，多代理辯論會陷入停滯狀態，並且可能被誤導性共識所顛覆 —— 當其他代理信誓旦旦地主張錯誤答案時，有效的論點反而會落敗。²⁶ Tool-MAD 透過賦予每個代理異質化的工具存取能力，並在裁決階段採用 Faithfulness/Relevance 評分，來改善此問題。若您正在建構辯論式的協作編排，請投入心力於：（a）每個代理的工具異質性，以及（b）量化的裁決評分，而不要天真地假設代理愈多答案愈佳。

最小可行審議

從 2 個代理與 1 條規則起步：代理必須在看到彼此的成果之前先獨立評估。⁷

Decision arrives
  |
  v
Confidence check: is this risky, ambiguous, or irreversible?
  |
  +-- NO  -> Single agent decides (normal flow)
  |
  +-- YES -> Spawn 2 agents with different system prompts
             Agent A: "Argue FOR this approach"
             Agent B: "Argue AGAINST this approach"
             |
             v
             Compare findings
             |
             +-- Agreement with different reasoning -> Proceed
             +-- Genuine disagreement -> Investigate the conflict
             +-- Agreement with same reasoning -> Suspect herding

這個模式已涵蓋 80% 的價值。其餘一切都只是邊際上的改進。

信心觸發器

並非每項任務都需要審議。信心評分模組會從四個面向進行評估：¹⁷

1. 歧義性 - 該查詢是否存在多種有效的詮釋？
2. 領域複雜度 - 是否需要專業知識？
3. 賭注高低 - 該決策是否可逆？
4. 情境相依性 - 是否需要理解更廣泛的系統？

評分會對應到三個層級：

門檻會依任務類型而調整。安全性決策需達到 0.85 的共識，文件修訂則僅需 0.50。此設計可避免在簡單任務上過度設計，同時確保高風險決策能獲得充分檢視。⁷

狀態機

共七個階段，每個階段都由前一階段把關：⁷

IDLE -> RESEARCH -> DELIBERATION -> RANKING -> PRD_GENERATION -> COMPLETE
                                                                    |
                                                              (or FAILED)

RESEARCH： 獨立的代理分頭調查該主題。每個代理獲派不同的 persona（Technical Architect、Security Analyst、Performance Engineer 等）。情境隔離確保代理在研究階段無法看到彼此的發現。

DELIBERATION： 代理可檢視所有研究結果，並提出替代方案。Debate 代理負責找出衝突之處，Synthesis 代理則將不相互矛盾的發現整合起來。

RANKING： 每個代理會針對每個提案，依 5 項加權面向進行評分：

雙閘驗證架構

兩道驗證閘門會在不同階段捕捉問題：⁷

Gate 1：共識驗證（PostToolUse hook）。於每個審議代理完成後立即執行： 1. 階段必須至少達到 RANKING 2. 至少 2 個代理已完成（可設定） 3. 共識分數達到該任務的自適應門檻 4. 若有任何代理提出異議，該疑慮必須被記錄下來

Gate 2：Pride Check（Stop hook）。在工作階段關閉前執行： 1. 方法多樣性：呈現多種獨特的 personas 2. 矛盾透明化：異議須載明具體原因 3. 複雜度處理：至少產出 2 個替代方案 4. 共識信心：分類為強（0.85 以上）或中等（0.70-0.84） 5. 改善佐證：最終信心需高於初始信心

將兩個 hook 分置於生命週期的不同節點，正對應了實際發生故障的模式：有些故障是瞬間發生的（分數不佳），有些則是逐漸累積的（多樣性不足、缺少異議紀錄）。⁷

為何一致同意很危險

Charlan Nemeth 從 1986 年起研究少數異議，直至其 2018 年著作 In Defense of Troublemakers。研究指出，有異議者的群體比快速達成共識的群體能做出更好的決策。異議者不必是對的，光是「反對」這個動作本身，就足以迫使多數派檢視他們原本會略過的假設。¹⁸

Wu 等人測試 LLM 代理是否能真正進行辯論，結果發現若缺乏針對「不同意」的結構性誘因，代理就會向那個聽起來最有自信的初始回應收斂，無論該答案是否正確。¹⁹ Liang 等人將根本原因歸納為「思維退化（Degeneration-of-Thought）」：一旦 LLM 對某個立場確立了信心，自我反思便無法產生新穎的反論，這使得多代理評估在結構上成為必要。²⁰

獨立性正是關鍵的設計約束。兩個代理評估同一個部署策略，若彼此能看到對方的發現，會得出 0.45 與 0.48 的分數。同樣的代理若彼此看不見，則會得出 0.45 與 0.72。0.48 與 0.72 之間的落差，正是羊群效應所付出的代價。⁷

偵測虛假共識

共識順從偵測模組會追蹤以下幾種樣態，這些訊號顯示代理可能在沒有真正評估的情況下就彼此附和：⁷

分數群聚： 若所有代理在 10 分制上的評分都落在 0.3 分之內，這意味著共享情境受到污染，而非真正的獨立評估。當 5 個代理評估一次驗證重構時，全部將安全風險評在 7.1 至 7.4 之間；重新採用全新的情境隔離執行後，分數分散到 5.8 至 8.9。

模板化異議： 代理彼此複製對方的疑慮措辭，而非提出獨立的反對意見。

少數觀點缺席： 具有衝突優先順序的 personas 卻一致同意（Security Analyst 與 Performance Engineer 幾乎不可能事事達成一致）。

共識順從偵測器可抓出那些明顯案例（約 10-15% 的審議中代理過快收斂）。剩下的 85-90%，則由共識閘與 pride check 閘提供足夠的驗證。

審議中行不通的作法

自由形式的辯論回合。 針對資料庫索引設計進行三回合的來回辯論，產出了 7,500 個 token 的辯論內容。第一回合：真正的歧見。第二回合：重申立場。第三回合：同樣的論點換個說法。改用結構化的面向評分取代自由形式辯論後，成本下降 60%，排序品質反而提升。⁷

單一驗證閘。 最初的實作只在工作階段結束時執行一次驗證 hook。某個代理完成審議時共識分數為 0.52（低於門檻），之後繼續處理不相關的任務長達 20 分鐘，直到 session-end hook 才標記出該失敗。將其拆分為兩道閘門（一個於任務完成時、一個於工作階段結束時），便能在生命週期的不同節點捕捉到同樣的問題。⁷

審議的成本

每個研究代理大約處理 5,000 個 token 的情境，並產出 2,000-3,000 個 token 的發現。以 3 個代理計算，每次決策會額外增加 15,000-24,000 個 token；10 個代理則約為 50,000-80,000 個 token。⁷

以目前 Opus 的定價計算，3 代理審議約需花費 0.68 至 0.90 美元，10 代理審議則為 2.25 至 3.00 美元。系統僅會在約 10% 的決策上觸發審議，因此攤提到所有決策上，每個工作階段的平均成本為 0.23 至 0.30 美元。這是否值得，端看一個錯誤決策會付出多少代價。

何時應進行審議

CLAUDE.md 設計

CLAUDE.md 是 AI 代理的運作政策，而非給人類閱讀的 README。²¹代理不需要理解您為什麼使用 conventional commits，它需要知道要執行的確切指令，以及「完成」的具體樣貌。

優先順序階層

規則檔會自動載入，在不使 CLAUDE.md 臃腫的前提下提供結構化情境。⁶

哪些內容會被忽略

以下模式通常無法對代理行為產生可觀察的改變：²¹

沒有指令的散文段落。「我們重視整潔、測試完善的程式碼」是文件，而非操作指示。代理讀過之後，仍會繼續寫出沒有測試的程式碼，因為其中並無可執行的指令。

語意含糊的指示。「進行資料庫遷移時請小心」並非約束。「套用遷移前先執行 alembic check，若缺少降級路徑則中止。」才是。

互相矛盾的優先順序。「快速行動、盡快交付」加上「確保完整的測試涵蓋率」加上「將執行時間控制在 5 分鐘內」再加上「每次提交前執行完整整合測試」。代理無法同時滿足這四項，最終預設跳過驗證。²¹

沒有強制機制的風格指南。「遵循 Google Python Style Guide」若沒有搭配 ruff check --select D，代理便沒有機制可驗證是否合規。

哪些做法有效

以指令為先的指示：

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

完成定義：

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

以任務為組織原則的章節：

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`

升級處理規則：

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- Never: delete files to resolve errors, force push, or skip tests

撰寫順序

若從零開始，建議依下列優先順序新增章節：²¹

1. 建置與測試指令（代理必須先擁有這些，才能做任何有用的事）
2. 完成定義（避免虛假完成）
3. 升級規則（避免破壞性的臨時繞道）
4. 以任務為組織原則的章節（減少解析無關指示的負擔）
5. 目錄範圍界定（在 monorepo 中可讓各服務的指示彼此隔離）

在前四項尚未到位之前，先不要處理風格偏好。

檔案匯入

在 CLAUDE.md 中引用其他檔案：

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

匯入語法支援相對路徑（@docs/file.md）、絕對路徑（@/absolute/path.md）與家目錄（@~/.claude/file.md）。最大深度為 5 層匯入。⁶

跨工具指示相容性

AGENTS.md 是一項開放標準，各主流 AI 編碼工具皆予以支援。²¹若團隊同時使用多套工具，建議以 AGENTS.md 作為權威來源，再將相關章節鏡像至各工具專用檔案：

AGENTS.md 中的模式（以指令為先、定義完成條件、以任務為組織原則）在任何指示檔中皆適用，與所使用的工具無關。請勿維護多組平行的指示內容，導致彼此逐漸偏離。寫出一份權威來源，其餘鏡像即可。

測試您的指示

驗證代理是否確實讀取並遵循您的指示：

# Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
claude --print "What is your definition of done?"

關鍵考驗：請代理解釋您的建置指令。若它無法逐字重現，代表這些指示要麼過於冗長（內容被推出情境之外）、要麼過於含糊（代理無法萃取出可執行的指示）、要麼根本未被發現。GitHub 分析 2,500 個 repository 後發現，模糊不清正是多數失敗的根源。²¹

生產模式

Opus 4.7 長期任務模式（2026年4月）

Claude Opus 4.7（2026年4月16日）推出時帶有特定能力，改變了harness所需的防禦範疇：²⁹

• 工具故障韌性： Opus 4.7在工具故障時能夠繼續執行，而Opus 4.6的會話則會因此中斷。您可以減少——但無法完全消除——subagent程式碼中的防禦性重試包裝。請保留hook層級的防護措施；精簡提示內「若工具失敗則重試三次」的腳手架內容。
• xhigh強度層級（僅限Opus-4.7）： 位於high與max之間。建議作為程式設計與agentic工作負載的預設值。在長時間執行的subagent上，xhigh的表現顯著優於high，而token成本僅呈次比例增加。max仍是單次硬推理的最佳選擇；xhigh則更適合持續性任務。
• Token預算上限： 可透過output_config.task_budget（beta標頭task-budgets-2026-03-13）為每次agent執行進行設定。模型會看到持續倒數的計時器,並優雅地將工作範圍限制在預算內,而非意外耗盡。適用於希望在不犧牲短提示品質的前提下,獲得可預測token支出的agentic迴圈。
• 隱含需求感知： 首個通過「隱含需求」測試的Claude模型——能辨識出使用者字面請求未充分說明其實際需求的情況。這使得CLAUDE.md中的「釐清規則」區段變得較不必要。若您的CLAUDE.md有200行「當使用者請求Y時也請考慮X」的護欄內容,請修剪那些現已由模型原生涵蓋的部分。

品質迴圈

所有非瑣碎變更的強制審查流程：

1. 實作 - 撰寫程式碼
2. 審查 - 重新閱讀每一行。捕捉錯字、邏輯錯誤、不清楚的段落
3. 評估 - 執行evidence gate。檢查模式、邊緣案例、測試覆蓋率
4. 精煉 - 修正每一個問題。絕不推遲到「之後」
5. 放大視角 - 檢查整合點、import、相鄰程式碼是否出現回歸
6. 重複 - 若任何evidence gate標準未達標,返回步驟4
7. 報告 - 列出變更內容、如何驗證、引用具體證據

Evidence Gate

「我相信」與「它應該」不算證據。請引用檔案路徑、測試輸出或具體程式碼。

若您無法為任何一列提供證據,請返回Refine階段。²²

錯誤處理模式

原子性檔案寫入。 多個agent同時寫入同一狀態檔案會破壞JSON。請先寫入.tmp檔案,然後以mv進行原子性移動。作業系統保證同一檔案系統內的mv為原子操作。¹⁷

# Atomic state update
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

狀態損毀復原。 若狀態損毀,復原模式會從安全預設值重建,而非直接崩潰:¹⁶

if ! jq -e '.depth' "$RECURSION_STATE_FILE" &>/dev/null; then
    # Corrupted state file, recreate with safe defaults
    echo '{"depth": 0, "agent_id": "root", "parent_id": null}' > "$RECURSION_STATE_FILE"
    echo "- Recursion state recovered (was corrupted)"
fi

((VAR++)) bash陷阱。 當VAR為0時,((VAR++))會回傳exit code 1,因為0++的運算結果為0,bash將其視為false。若啟用set -e,此行為會終止腳本。請改用VAR=$((VAR + 1))。¹⁶

影響範圍分類

依影響範圍對每個agent動作分類並據此設定閘門:²

Remote Control(從任何瀏覽器或行動應用程式連接至本地Claude Code)將「外部」閘門從阻塞等待轉為非同步通知。agent可繼續處理下一項任務,您則可從手機上審查前一項。²

自主執行的任務規格

有效的自主任務包含三個要素:目標、完成標準、脈絡指標:¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

COMPLETION CRITERIA:
- All tests in tests/test_deliberation_lib.py pass (81 tests)
- post-deliberation.sh validates consensus above 70% threshold
- recursion-guard.sh enforces spawn budget (max 12 agents)
- No Python type errors (mypy clean)

CONTEXT:
- Follow patterns in lib/deliberation/state_machine.py
- Consensus thresholds in configs/deliberation-config.json
- Spawn budget model: agents inherit budget, not increment depth

標準必須可由機器驗證:測試通過/失敗、linter輸出、HTTP狀態碼、檔案存在檢查。早期一項任務要求agent「撰寫能通過的測試」,結果產出的是assert True與assert 1 == 1。技術上正確。實務上毫無價值。¹⁶

需警惕的失敗模式

具體會話軌跡

一段處理含5則故事的PRD的自主執行會話軌跡:²

1. SessionStart觸發。 dispatcher注入:當前日期、專案偵測、哲學限制、成本追蹤初始化。五個hook,共180ms。

2. agent讀取PRD,規劃第一則故事。 UserPromptSubmit觸發。dispatcher注入:活動專案脈絡、會話漂移基準。

3. agent呼叫Bash執行測試。 PreToolUse:Bash觸發。憑證檢查、沙盒驗證、專案偵測。90ms。測試執行。PostToolUse:Bash觸發:記錄活動心跳、漂移檢查。

4. agent呼叫Write建立檔案。 PreToolUse:Write觸發:檔案範圍檢查。PostToolUse:Write觸發:lint檢查、commit追蹤。

5. agent完成故事。 Stop觸發。品質閘門檢查:agent是否引用證據?是否出現模糊語句?diff中是否有TODO註解?若任何檢查失敗,exit 2而agent繼續執行。

6. 獨立驗證: 全新的agent執行測試套件,不信任前一agent的自我報告。

7. 三個code review agent並行產生。 每個agent獨立審查diff。若任何reviewer標記CRITICAL,該故事重新進入佇列。

8. 故事通過。載入下一則故事。 迴圈在全部5則故事上重複執行。

5則故事共觸發約340個hook。hook總耗時約12秒。此開銷在單一次整夜執行中防止了三次憑證外洩、一次破壞性指令、以及兩次不完整的實作。

案例研究:整夜PRD處理

一個生產harness在8次整夜會話中處理了12個PRD(47則故事)。指標比較前4個PRD(極簡harness:僅CLAUDE.md)與後8個(完整harness:hook、skill、品質閘門、多agent審查)。

兩次憑證外洩需要輪換API金鑰並稽核下游服務:約4小時的事件回應工作。防止等效情況的harness開銷則為每則故事2.4秒的bash執行時間。錯誤完成率從35%降至4%,原因是Stop hook會在允許agent回報完成之前獨立執行測試。

安全考量

可信賴代理的五大原則（Anthropic，2026年4月）

Anthropic於2026年4月9日發布了代理可信賴性的正式框架。²⁷這五項原則與本指南中的Evidence Gate思維相互呼應——並加以延伸：

Anthropic也將MCP捐贈給Linux Foundation的Agentic AI Foundation，加入AGENTS.md的行列（現由OpenAI、Google、Cursor、Factory、Sourcegraph共同維護）。代理互通標準現已獨立於特定廠商。²⁷

Skill沙箱工具：對於將skills視為攻擊面的團隊，Permiso的SandyClaw（於2026年4月2日推出）會在專屬沙箱中執行skills,並依據Sigma/YARA/Nova/Snort偵測提供有實證支持的判定結果。此為skill沙箱類別中的首款產品。²⁸

沙箱

Claude Code支援可選的沙箱模式（透過settings.json或/sandbox指令啟用），利用作業系統層級的隔離機制（macOS上的seatbelt、Linux上的bubblewrap）限制網路存取與檔案系統操作。啟用後,沙箱可防止模型發起任意網路請求或存取專案目錄外的檔案。若未啟用沙箱,Claude Code會採用以權限為基礎的模式,由您核准或拒絕個別工具呼叫。¹³

權限邊界

權限系統在多個層級對操作進行把關：

提示注入防禦

Skills與hooks提供針對提示注入的縱深防禦：

具有工具限制的Skills可防止遭入侵的提示取得寫入權限：

allowed-tools: Read, Grep, Glob

PreToolUse hooks對每個工具呼叫進行驗證,無論模型是如何被提示的：

# Block credential file access regardless of prompt
if echo "$FILE_PATH" | grep -qE "\.(env|pem|key|credentials)$"; then
    echo "BLOCKED: Sensitive file access" >&2
    exit 2
fi

Subagent隔離可限縮影響範圍。即使提示遭到入侵,設定為permissionMode: plan的subagent仍無法進行任何變更。

Hook安全性

將環境變數插入標頭的HTTP hooks必須提供明確的allowedEnvVars清單,以防止任意環境變數外洩：¹³

{
  "type": "http",
  "url": "https://api.example.com/notify",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

人類與代理的責任分工

代理架構中的安全性需要明確劃分人類與代理的責任：¹⁷

基本模式：人類擁有需要組織脈絡、倫理判斷或策略方向的決策。代理擁有需要在龐大可能性空間中進行計算搜尋的決策。Hooks則負責執行這條界線。

遞迴式Hook執行

Hooks也會為subagent的動作觸發。¹³若Claude透過Agent工具生成subagent,您的PreToolUse與PostToolUse hooks會為該subagent使用的每個工具執行。若沒有遞迴式hook執行,subagent便能繞過您的安全閘。SubagentStop事件則讓您在subagent完成時執行清理或驗證。

這不是選配項目。一個能生成subagent卻不套用您安全hooks的代理,就是一個能在您的閘門盯著主對話毫無作為時,強制推送至main、讀取憑證檔案或執行破壞性指令的代理。

成本即架構

成本是架構決策,而非營運上的事後補救。²共分三個層級：

Token層級。系統提示壓縮。移除教學用的程式碼範例（模型已熟悉APIs）、整併跨檔案的重複規則,並以約束條件取代解釋。「Reject tool calls matching sensitive paths」與長達15行解釋為何不應讀取憑證的說明,達成的效果完全相同。

代理層級。以全新生成取代長時間對話。自主運行中的每個story都會取得一個擁有乾淨脈絡的新代理。脈絡永不膨脹,因為每個代理都是從零開始。以簡報取代記憶：模型執行清晰簡報的效果,勝過在累積30步的脈絡中尋找方向。

架構層級。當操作為無狀態時,CLI優先於MCP。單次評估使用claude --print呼叫的成本較低,且不會增加連線開銷。MCP則適用於工具需要持久狀態或串流的情境。

決策框架

何時該使用哪一種機制：

Skills vs Hooks vs Subagents

常見問題

多少 hooks 算太多？

效能才是限制，而非數量。每個 hook 都同步執行，因此所有 hook 的執行時間會加總到每次配對的工具呼叫上。在使用者層級與專案層級設定中共 95 個 hooks，只要每個 hook 都能在 200ms 內完成，就不會有明顯延遲。需要留意的門檻是：若 PostToolUse hook 讓每次檔案編輯多出 500ms 以上，整個工作階段就會變得遲鈍。部署前請先用 time 分析每個 hook 的效能。¹⁴

Hooks 能阻止 Claude Code 執行指令嗎？

可以。PreToolUse hooks 以結束代碼 2 退出即可阻擋任何工具動作。Claude Code 會取消待執行的動作，並將 hook 的 stderr 輸出顯示給模型。Claude 會看到拒絕原因並建議更安全的替代方案。結束代碼 1 則是非阻擋式警告,動作仍會繼續進行。³

Hook 設定檔應該放在哪裡？

專案層級的 hook 設定（隨儲存庫提交、與團隊共享）放在 .claude/settings.json；使用者層級的 hooks（個人專屬、套用至所有專案）則放在 ~/.claude/settings.json。兩者並存時，以專案層級優先。指令檔請使用絕對路徑，以避免工作目錄相關的問題。¹⁴

每個決策都需要審議（deliberation）嗎？

不需要。信心度模組會從四個維度（模糊度、複雜度、利害關係、情境相依性）為決策評分。只有整體信心度低於 0.70 的決策才會觸發審議，大約佔全部決策的 10%。文件修正、變數更名、例行編輯完全跳過審議。安全架構、資料庫綱要變更、不可逆部署則會穩定觸發。⁷

如何測試一個刻意產生分歧的系統？

同時測試成功路徑與失敗路徑。成功：agents 產生有建設性的分歧並達成共識。失敗：agents 收斂過快、永不收斂或超出生成預算。端對端測試以確定性的 agent 回應模擬各情境，驗證兩道驗證閘門皆能捕捉每一種已記錄的失敗模式。一套正式環境的審議系統會跨三層執行 141 個測試：48 個 bash 整合測試、81 個 Python 單元測試，以及 12 個端對端管線模擬。⁷

審議帶來多少延遲？

3 個 agents 的審議會增加 30 至 60 秒的實際時間（agents 透過 Agent tool 依序執行）。10 個 agents 的審議則增加 2 至 4 分鐘。共識 hook 與 pride check hook 各自在 200ms 內完成。主要瓶頸是每個 agent 的 LLM 推論時間，而非編排本身的負擔。⁷

CLAUDE.md 檔案應該多長？

每個區段控制在 50 行以內，整份檔案不超過 150 行。過長的檔案會被上下文視窗截斷，因此請將最關鍵的指示前置：指令與完成定義要排在風格偏好之前。²¹

除了 Claude Code 以外的工具也能套用嗎？

架構原則（hooks 作為確定性閘門、skills 作為領域專業、subagents 作為隔離情境、檔案系統作為記憶）在概念上適用於任何 agentic 系統。具體實作則使用 Claude Code 的生命週期事件、matcher 模式與 Agent tool。AGENTS.md 將相同模式延伸到 Codex、Cursor、Copilot、Amp 與 Windsurf。²¹ 即使實作細節與工具相關，harness 模式本身與工具無關。

快速參考卡

Hook 設定

{
  "hooks": {
    "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "script.sh"}]}],
    "PostToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "format.sh"}]}],
    "Stop": [{"matcher": "", "hooks": [{"type": "agent", "prompt": "Verify tests pass. $ARGUMENTS"}]}],
    "SessionStart": [{"matcher": "", "hooks": [{"type": "command", "command": "setup.sh"}]}]
  }
}

Skill Frontmatter

---
name: my-skill
description: What it does and when to use it. Include trigger phrases.
allowed-tools: Read, Grep, Glob
---

Subagent 定義

---
name: my-agent
description: When to invoke. Include PROACTIVELY for auto-delegation.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

Instructions for the subagent.

結束代碼

關鍵指令

檔案位置

更新紀錄

參考資料