Agent 架構:建構 AI 驅動的開發框架

TL;DR： Claude Code 並非僅是具備檔案存取能力的對話框。它是一個可程式化的執行環境，內建 29 個有文件記載的生命週期事件，每一個都可透過 shell 腳本掛接，且模型無法略過。將 hooks 堆疊成 dispatchers、dispatchers 堆疊成 skills、skills 堆疊成 agents、agents 堆疊成工作流程，便能打造出自主的開發 harness，它能強制執行約束、委派工作、跨工作階段保留記憶，並協調多 agent 的審議。本指南涵蓋此堆疊的每一層：從單一 hook 到 10 個 agent 的共識系統。無需任何框架。全部以 bash 與 JSON 實作。

Andrej Karpathy 為圍繞 LLM agent 而生長的事物創造了一個詞：claws（爪）。也就是那些 hooks、腳本與協調機制，讓 agent 能夠抓住其上下文視窗之外的世界。¹ 大多數開發者把 AI 程式設計 agent 當作互動式助理使用。他們輸入提示、看著它編輯檔案，然後繼續下一件事。這樣的框架把生產力上限固定在您個人能夠監督的範圍內。

基礎設施的心智模型則截然不同：AI 程式設計 agent 是一個可程式化的執行環境，內含一個 LLM 核心。模型的每一個動作都會經過您所掌控的 hooks。您定義的是政策，而非提示。模型在您的基礎設施中運作，就如同網頁伺服器在 nginx 規則中運作一般。您不會坐在 nginx 前面打字輸入請求。您配置它、部署它、監控它。

這個區別之所以重要，是因為基礎設施會產生複利效應。一個能在 bash 命令中阻擋憑證外洩的 hook，可以保護每個工作階段、每個 agent、每次自主執行。一個編碼了您評估準則的 skill，無論是您親自呼叫，或是由 agent 呼叫，都會一致地套用。一個負責程式碼安全審查的 agent，無論您是否在旁觀看，都會執行相同的檢查。²

重點摘要

• Hooks 能保證執行；提示則不能。 對於程式碼風格檢查、格式化、安全檢查，以及任何不論模型行為如何都必須每次執行的動作，請使用 hooks。Exit code 2 會封鎖動作。Exit code 1 僅發出警告。³
• Skills 編碼會自動啟用的領域專業知識。 description 欄位決定一切。Claude 使用 LLM 推理（而非關鍵字比對）來判斷何時套用某個 skill。⁴
• Subagents 可避免上下文膨脹。 為探索與分析使用獨立的上下文視窗，讓主工作階段保持精簡。讓彼此獨立的 subagents 平行執行，當工作者之間需要持續協調時，則改用 agent 團隊。⁵
• 記憶存在於檔案系統中。 檔案會跨上下文視窗持續保留。CLAUDE.md、MEMORY.md、規則目錄與交接文件，共同構成一套結構化的外部記憶系統。⁶
• 多 agent 審議能找出盲點。 單一 agent 無法挑戰自身的假設。兩個具有不同評估優先順序的獨立 agent，能找出品質閘門無法處理的結構性缺陷。⁷
• Harness 模式即是系統本身。 CLAUDE.md、hooks、skills、agents 與記憶並非彼此獨立的功能。它們組合成一個位於您與模型之間、可隨自動化規模擴展的決定性層級。

如何使用本指南

每一節都以前一節為基礎延伸。文末的Decision Framework提供一張查詢表，協助您針對每種問題類型選擇合適的機制。

五分鐘黃金路徑

在深入探討之前,這是從零到建立可運作 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 檔案與 rules 目錄定義代理對您專案的認知。它們會在 session 啟動時以及每次壓縮後自動載入，是代理的長期架構記憶。

擴充層（Extension Layer）： skills 提供依情境自動啟用的領域專業知識。hooks 提供在每次符合條件的工具呼叫時觸發的確定性閘道。記憶檔案讓狀態跨 session 持續存在。自訂 agents 則提供專門化的 subagent 配置。

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

關鍵洞見在於：大多數使用者完全停留在核心層工作，眼睜睜看著情境膨脹、成本攀升。進階使用者則會配置指令層與擴充層，僅在協調與最終決策時才動用核心層。²

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

整個 2026 年初，「自行打造 harness」是唯一真正可行的路徑。2026 年 4 月，情況有了轉變。Anthropic 推出 Claude Managed Agents 公開測試版（4 月 8 日）：harness loop + 工具執行 + 沙箱容器 + 狀態持久化，全部以 REST API 形式提供，依標準 tokens 計費並加收每 session 小時 $0.08 美元。OpenAI 的 Agents SDK 更新（4 月 16 日）將同樣的分層方式正式化——將 harness 與運算資源視為兩個獨立層級，並支援原生沙箱供應商（Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel）以及用於應對容器遺失的 snapshot/rehydrate 機制。²³²⁴

OpenAI 端更深入的 SDK 介面則隨 openai-agents Python v0.14.0 一同登場（2026 年 4 月 15 日發布；4 月 16 日宣布）：包含繼承自 Agent 的 SandboxAgent 子類別，具備 default_manifest、沙箱指令與能力宣告；Manifest 用於描述全新工作區的契約（檔案、目錄、本機檔案、Git 儲存庫、env、users、mounts）；SandboxRunConfig 則用於每次執行時設定沙箱用戶端、實時 session 注入、manifest 覆寫、snapshots 以及 materialization 並行限制。內建能力涵蓋 shell 存取、檔案系統編輯、影像檢視、skills、沙箱記憶與壓縮。沙箱記憶會跨執行持久保存萃取出的經驗，並逐步揭露運用；工作區支援本機檔案、Git 儲存庫項目以及遠端掛載（S3、R2、GCS、Azure Blob、S3 Files）；snapshots 可跨供應商攜帶。後端方面：UnixLocalSandboxClient、DockerSandboxClient，以及透過選用 extras 支援的 Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop 與 Vercel 託管用戶端。²⁴

對於希望以函式庫形式嵌入 Claude Code runtime 的 Python 專案而言——介於「shell 呼叫 claude」與「以 REST API 連接 Managed Agents」之間——claude-agent-sdk-python 是第三條路徑。4 月 28 至 29 日的版本系列（v0.1.69 → v0.1.71）將內建 CLI 升級至 v2.1.123，將 mcp 相依套件下限提升至 >=1.19.0（舊版會悄悄丟棄行程內 MCP tools 回傳的 CallToolResult，留給模型一個驗證錯誤的殘塊），並使 SandboxNetworkConfig 與 TypeScript SDK 的 schema 對齊（allowedDomains、deniedDomains、allowManagedDomainsOnly、allowMachLookup）。³⁰

如今，架構上的分岔已成為現實：

該如何選擇： 自架型仍適合已具備基礎設施實力、希望完全掌控 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隨時可取用的知識。Slash commands用於您明確觸發的動作。在兩者之間抉擇時，請自問：「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

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

Frontmatter參考

Description欄位至關重要

會話開始時，Claude Code會擷取每個skill的name和description，並注入Claude的上下文中。當您傳送訊息時，Claude會運用語言模型推理判斷是否有相關的skill。對Claude Code原始碼的獨立分析證實了這個機制：skill的描述會被注入系統提示的available_skills區段，模型則使用標準語言理解能力來挑選相關的skills。¹⁰

糟糕的描述：

description: Helps with code

有效的描述：

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.

有效的描述包含：功能說明（針對特定問題類型審查程式碼）、使用時機（檢視變更、PRs、品質分析），以及使用者自然會輸入的觸發詞彙（review、audit、check）。

上下文預算

所有skill的描述共用一個上下文預算，預算大小依上下文視窗的1%動態調整，預設備援值為8,000個字元。⁴若您擁有許多skills，請維持每個描述精簡，並將關鍵使用情境放在最前面。您可以透過SLASH_COMMAND_TOOL_CHAR_BUDGET環境變數覆寫預算，¹¹但更好的解決方案是撰寫更短、更精確的描述。在會話中執行/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會根據上下文自動取用。資淺工程師無需主動詢問，便能獲得資深工程師等級的指引。

Skills與Hooks組合運用

Skills可在frontmatter中定義專屬的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則是執行機制。兩者結合，便構成一個策略層。

Skills常見錯誤

描述過於寬泛。一個會在任何git相關提示（rebases、merges、cherry-picks，甚至git status）都啟動的git-rebase-helper skill，會在80%的會話中污染上下文。解法是收緊描述，或加入disable-model-invocation: true並要求明確以/skill-name呼叫。⁴

過多skills競爭預算。Skills越多，越多描述會競爭那1%的上下文預算。若您發現有skills未啟動，請查看/context找出被排除的項目。優先選擇少量但描述完善的skills，而非眾多含糊不清的skills。

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

SDK Skill介面（2026年5月8日）

基於claude-agent-sdk-python v0.1.77+的自託管harnesses，應使用ClaudeAgentOptions上的skills選項來宣告可用skills，而非沿用allowed_tools中的舊版"Skill"值。³⁷"Skill"簡寫已被棄用，新的專屬選項能為Claude Code提供更結構化的可用skills資訊。v0.1.77中綑綁的CLI為v2.1.133。

Hook 架構

Hook 是由 Claude Code 生命週期事件觸發的 shell 命令。³它們在 LLM 之外以純腳本形式執行，而非由模型解讀的提示詞。模型想要執行 rm -rf /？一個 10 行的 bash 腳本會根據封鎖清單檢查命令，並在 shell 看到之前就拒絕它。無論模型是否願意，hook 都會觸發。

可用事件

截至本指南更新時，Claude Code 在八個類別中公開了 29 個有文件記錄的生命週期事件。事件清單會隨著版本發行而增長，因此請將參考文件視為事實來源，並在配置正式環境的 hook 之前查閱速查表取得目前的完整列表：¹³

結束碼語意

結束碼決定 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 欄位用於過濾事件特定的值。對於工具事件，它會比對 tool_name 值，例如 Bash、Edit、Write、Read、Glob、Grep，MCP 工具名稱（如 mcp__server__tool），或使用 * 比對所有工具。簡單名稱及以 | 分隔的清單為精確比對；包含其他字元的值則為 JavaScript 正規表達式。部分事件不支援 matcher，配置後一律觸發。¹³

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 或測試套件，若品質檢查失敗則阻擋此次 commit：

#!/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 成本。

MCP 工具 hook（type: "mcp_tool"）會呼叫已連線的 MCP 伺服器上的工具。當驗證邏輯已存在於 MCP 邊界後方且無需獨立的 shell 腳本時，使用此類型。

Prompt hook（type: "prompt"）對快速的 Claude 模型發送單輪提示詞。模型回傳 { "ok": true } 表示允許，或 { "ok": false, "reason": "..." } 表示阻擋。適用於正規表達式無法表達的細膩評估。

Agent hook（type: "agent"）會啟動具有工具存取權限（Read、Grep、Glob）的 subagent 進行多輪驗證。它們屬於實驗性質；正式環境的閘道請優先使用 command hook，agent hook 則保留給確實需要檢查實際檔案或測試輸出的檢查：

{
  "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 毫秒以下。

SDK 端 Hook 事件串流

建構於 claude-agent-sdk-python（v0.1.74+，2026 年 5 月 6 日）的自託管 harness 可直接從訊息串流訂閱 hook 事件，無需透過 shell 腳本回呼。³⁶在 ClaudeAgentOptions 上設定 include_hook_events=True，HookEventMessage 物件（PreToolUse、PostToolUse、Stop 等）便會與助理訊息和工具結果一同從同一迭代器中產出。這對應於 TypeScript SDK 的 includeHookEvents 選項；同一版本中內附的 CLI 也升級至 v2.1.129。

當您的 harness 已使用 Python 撰寫，且希望 hook 訊號與模型輸出共用同一控制流程時，事件串流模式最為合適。對於組合多個工具、在 Claude Code 與 Codex 之間共享 hook，或需要結束碼語意進行阻擋的 harness，shell 腳本 hook 合約（結束碼、stdin JSON、dispatcher）仍是正確答案。

Effort 與 Session 來源（2026 年 5 月 7-8 日）

Claude Code v2.1.132 與 v2.1.133 兩項新增功能讓 hook 與子程序對其執行上下文獲得更佳訊號：³⁸³⁹

• Hook 輸入中的 effort.level。 Hook 現在會在承載 tool_input 與 session_id 的同一輸入上收到 effort.level JSON 欄位。同樣的值也會匯出為 $CLAUDE_EFFORT 環境變數，因此 Bash 命令無需解析 JSON 即可讀取。可利用此機制依 effort 等級調整 hook 成本：在 low 時略過昂貴的驗證，在 xhigh 或 max 時執行完整的安全閘道。
• Bash 子程序上的 CLAUDE_CODE_SESSION_ID 環境變數。 Bash 工具子程序現在能看到與 hook 相同的 session_id 值，以 CLAUDE_CODE_SESSION_ID 形式公開。這彌補了那些記錄 per-session 狀態、過去無法將子程序事件與 hook 事件對應起來的工具的來源缺口。

兩項訊號均無需修改程式碼即可使用；忽略新欄位的既有 hook 仍可正常運作。

記憶與情境

每一次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++))在bash中於VAR為0時搭配set -e會失敗,您就把它記錄下來。三個工作階段之後,當您在Python中遇到類似的整數邊緣案例時,MEMORY.md的條目就會浮現出該模式。¹⁵

自動記憶(v2.1.32+):Claude Code會自動記錄並回憶專案情境。當您工作時,Claude會將觀察寫入~/.claude/projects/{project-path}/memory/MEMORY.md。自動記憶會在工作階段開始時將前200行載入您的系統提示中。請保持簡潔,並連結至個別主題檔案以記錄詳細筆記。⁶

策略2:主動壓縮

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

何時應該壓縮: - 在完成一個明確的子任務之後(功能實作完成、錯誤修復完畢) - 在開始程式碼庫的新區域之前 - 當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(continue)開啟新工作階段或閱讀交接文件,可直接進入實作階段。¹⁵

策略4:全新情境迭代(Ralph迴圈)

對於超過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分鐘之後,儘管有額外開銷,全新情境仍能產生更高品質的輸出。

策略5:託管記憶策展(Dreaming)

Anthropic的Claude Managed Agents於2026年5月6日將Dreaming新增為研究預覽功能。³⁵ 根據Anthropic所述:「Dreaming是一個排程程序,會檢視您的代理工作階段與記憶儲存區、擷取模式並策展記憶,讓您的代理隨著時間持續改善。」³⁵

Dreaming在工作階段之間於背景執行,並不在關鍵路徑上。它與「檔案系統作為記憶」的模式互補,而非取代:您的MEMORY.md檔案仍是承載重量的主要介面;Dreaming則將經過策展的記憶條目寫入Managed Agents的記憶儲存區,代理會在工作階段開始時讀取它。對於混合自託管檔案系統狀態與託管端策展的harness,這兩種模式可以並存。

Dreaming目前處於研究預覽階段,因此行為可能會有所變動。上述記載的工作階段交接與CLAUDE.md模式,對於自託管的harness而言,仍是權威的記憶機制。

反模式

只需要10行卻讀取整個檔案。讀取單一2,000行的檔案會消耗15,000至20,000個token。請使用行偏移量:Read file.py offset=100 limit=20可省下絕大部分的成本。¹⁵

將冗長的錯誤輸出保留在情境中。在除錯之後,您的情境裡可能堆積了40多個來自失敗迭代的堆疊追蹤。修復錯誤後執行一次/compact即可釋放這些累贅。

每次工作階段一開始就讀取每一個檔案。請讓Claude Code的glob與grep工具按需尋找相關檔案,如此可省下100,000個以上不必要的預先載入token。¹⁵

子代理模式

子代理是專門的Claude實例，能夠獨立處理複雜任務。它們從乾淨的脈絡開始（不受主對話的污染），使用指定的工具運作，並以摘要形式回傳結果。探索結果不會讓主對話膨脹；只有結論會回傳。⁵

內建子代理類型

建立自訂子代理

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

---
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.

子代理設定欄位

Worktree 隔離

子代理可在臨時的 git worktrees 中運作，提供完整的隔離儲存庫副本：⁵

---
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 隔離至關重要。

平行子代理

對於不需要彼此協調的獨立研究任務，請使用平行子代理：⁵

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

每個代理在自己的脈絡視窗中執行、找出相關程式碼，並回傳摘要。主脈絡保持乾淨。

遞迴防護機制

若無生成限制，代理會委派給代理，再委派給代理，每一層都流失脈絡並耗費 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 個代理，仍然只是「深度 1」。生成預算追蹤每個父代理底下的活躍子代理總數，以可設定的上限為準。預算模型對應到實際的失敗模式（代理總數過多），而非代理指標（巢狀層級過多）。⁷

代理團隊（研究預覽）

代理團隊協調多個獨立工作的Claude Code實例，透過共用信箱與任務清單溝通，並可挑戰彼此的結論：⁵

啟用方式：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

何時使用代理團隊或子代理：

多代理人協作

單一代理人 AI 系統存在結構性盲點：無法質疑自身的假設。⁷ 多代理人協商在任何決策定案前，強制從多個角度進行獨立評估。

跨工具協作（2026年4月）： Google 於 4 月 7 日開源 Scion — 這是一個多代理人 hypervisor，可將 Claude Code、Gemini CLI 及其他「深度代理人」作為並行行程執行，每個代理人都擁有獨立的容器、git worktree 與憑證。可在本機、hub 或 Kubernetes 上執行。其明確的設計理念是「以隔離取代約束」— 代理人在基礎架構層強制的邊界內以高度自主性運作，而非依賴提示中的限制。²⁵ 這直接將 subagent 隔離的論述延伸至不同工具廠商之間。若您的工作流程橫跨 Claude 與 OpenAI 模型，Scion 是首個真正可作為跨工具 subagent 參考實作的方案，提供每個代理人專屬的 worktree 與憑證隔離。

辯論並非萬靈丹： M3MAD-Bench 研究群組（2026 年初）發現，多代理人辯論會出現停滯，且可能被誤導性共識顛覆 — 當其他代理人自信地堅持錯誤答案時，正確的論點反而會落敗。²⁶ Tool-MAD 透過讓每個代理人擁有異質的工具存取權限，並在裁判階段使用 Faithfulness/Relevance 分數來改善此問題。若您正在建構辯論式協作架構，應投資於（a）每個代理人的工具異質性，以及（b）量化的裁判評分，而非假設代理人愈多答案就愈好。

託管多代理人協作與成果（公開測試版）

如果您不想自行建構下方所述的協商基礎架構，Multiagent Orchestration 已於 2026 年 5 月 6 日進入 Claude Managed Agents 的公開測試階段。³⁵ 根據 Anthropic 的說法：「當工作量過大、單一代理人難以勝任時，多代理人協作可讓主導代理人將任務拆解成多個部分，並委派給各自擁有專屬模型、提示與工具的專家代理人。」³⁵ 專家代理人「在共享檔案系統上並行工作，並貢獻於主導代理人的整體脈絡。」³⁵

追蹤功能也內建其中。根據 Anthropic：「您也可以在 Claude Console 中追蹤每一個步驟：哪個代理人做了什麼、按什麼順序、為何如此，讓您完全掌握任務如何被委派與執行的全貌。」³⁵

搭配的公開測試版功能是 Outcomes。根據 Anthropic：「您撰寫一份描述成功樣貌的評分標準（rubric），代理人即會朝該目標努力。獨立的評分器在自己的脈絡視窗中依您的標準評估輸出，因此不會受到代理人推理過程的影響。」³⁵ 這是本節後續所述雙閘驗證模式的託管服務版本：rubric 取代了手寫的閘門，獨立評分器則取代了共識驗證器。

當驗證需要與您自己的 hook 介面整合（PreToolUse 阻擋、退出碼語意、自訂 dispatcher），或當 harness 必須在沒有外部相依性的情況下執行時，自託管協商仍是正確答案。當標準委派加上 rubric 評分就是您實際需要的契約時，託管 Multiagent 才是正確答案。

最小可行協商

從 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： 獨立代理人各自調查主題。每個代理人都會獲得不同的角色設定（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. 方法多元：呈現多個獨特角色 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 分以內，這暗示共享脈絡受到污染，而非獨立評估。當五個代理人評估身分驗證重構時，安全風險全都評在 7.1 至 7.4 之間，以新的脈絡隔離重新執行後，分數則散佈於 5.8 至 8.9 之間。

樣板式反對意見： 代理人複製彼此的疑慮用語，而非產生獨立的反對意見。

少數派觀點缺席： 來自具有衝突優先順序的角色卻全數同意（Security Analyst 與 Performance Engineer 鮮少在所有事情上達成一致）。

從眾偵測器能捕捉明顯的案例（約 10-15% 的協商中代理人收斂得太快）。剩餘的 85-90%，則由共識與 pride check 閘門提供充分的驗證。

協商中無效的做法

自由形式的辯論回合。 在資料庫索引討論中進行三輪來回文字辯論，產生了 7,500 token 的辯論內容。第一輪：真實的意見分歧。第二輪：重述立場。第三輪：以不同字眼重複相同論點。結構化的面向評分取代了自由形式辯論，將成本降低 60%，同時提升了排序品質。⁷

單一驗證閘門。 第一版實作只在工作階段結束時執行一個驗證 hook。某代理人完成協商時共識分數為 0.52（低於門檻），接著繼續處理無關任務 20 分鐘，直到工作階段結束的 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 agent的操作政策,而非給人類閱讀的README。²¹ Agent不需要理解您為何使用慣例式提交格式,只需要知道確切的執行指令以及「完成」的標準是什麼。

優先順序階層

規則檔案會自動載入,提供結構化脈絡,而不會讓CLAUDE.md變得雜亂。⁶

哪些內容會被忽略

下列模式無法可靠地讓agent行為產生可觀察的變化:²¹

沒有指令的散文段落。「我們重視乾淨、經過良好測試的程式碼」是文件,不是操作指示。Agent讀完後仍會撰寫沒有測試的程式碼,因為缺乏可執行的具體指示。

模糊的指令。「資料庫遷移時請小心」並非約束。「套用遷移前執行alembic check。若缺少降版路徑則中止。」才是。

互相矛盾的優先順序。「快速行動、迅速出貨」加上「確保完整測試覆蓋率」加上「執行時間維持在5分鐘以內」加上「每次提交前執行完整整合測試」。Agent無法同時滿足全部四項,於是預設略過驗證。²¹

沒有強制機制的風格指南。「請遵循Google Python Style Guide」若沒有搭配ruff check --select D,agent就沒有任何機制驗證是否符合規範。

哪些做法有效

指令優先的指示:

## 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. 建構與測試指令(agent必須先有這些,才能執行任何有用的工作)
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中的模式(指令優先、定義收尾、依任務組織)在任何指示檔案中都通用,不分工具。請勿維護多份平行而逐漸偏離的指示集。撰寫一份權威來源,並進行鏡射。

Codex對等說明

Codex如今對主要的harness層級都已具備一級對應,但遷移是模式轉譯,而非檔案複製。Codex在開始工作前會讀取AGENTS.md,並將~/.codex的全域指引與專案及巢狀儲存庫的指示分層疊加。³¹ Codex skills採用相同的SKILL.md心智模型並支援漸進式揭露:Codex先取得skill名稱、描述與檔案路徑,只有在決定使用時才載入完整skill。³² Codex同樣具備原生hooks、plugin綁定的hooks、託管型hooks、MCP支援,以及明確的subagent工作流程。³³³⁴

實務對應如下:

關鍵差異在於:Claude subagents可依描述自動被選用,而Codex目前的subagent工作流程是明確指定的。因此在Codex中,skills與hooks是常駐harness行為的合理預設;subagents則用於刻意的平行工作、審查與探索。

測試您的指示

驗證agent是否真的讀取並遵循您的指示:

# 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?"

酸性測試:請agent複述您的建構指令。若無法逐字重現,代表指示要不是過於冗長(內容被擠出脈絡視窗)、過於模糊(agent無法萃取出可執行的指示),就是根本沒被發現。GitHub針對2,500個儲存庫的分析發現,模糊性是大多數失敗的根因。²¹

生產模式

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 之間。建議作為程式撰寫與代理工作負載的預設值。在長時間執行的 subagent 上,xhigh 顯著優於 high,且 token 成本呈次比例增長。max 仍是單次困難推理的正確選擇;xhigh 則更適合持續性任務。
• Token 預算上限:可透過 output_config.task_budget(beta header task-budgets-2026-03-13)針對每次代理執行進行設定。模型會看到倒數計時,並優雅地將工作範圍縮減至預算內,而非意外耗盡。適用於需要可預測 token 花費而又不犧牲短提示品質的代理迴圈。
• 隱含需求覺察:首個通過「隱含需求」測試的 Claude 模型 — 能辨識使用者的字面請求何時未充分指明其實際需要。這讓 CLAUDE.md 中的「澄清規則」段落變得較不必要。若您的 CLAUDE.md 有 200 行「當使用者要求 Y 時也請考慮 X」之類的護欄,請刪減那些現在已由原生支援涵蓋的部分。

Worktree 基底、沙箱路徑與管理員設定(2026年5月7日)

Claude Code v2.1.133 新增四項管理員層級設定,值得在生產 harness 中了解:³⁹

worktree.baseRef 還原是需要對使用者標示的重點:仰賴 v2.1.128-v2.1.132 行為(worktree 從本機 HEAD 分支)的代理,除非主動選擇還原舊行為,否則將失去在新 worktree 中存取未推送工作的能力。

品質迴圈

所有非瑣碎變更皆須遵循的強制性審查流程:

1. 實作 - 編寫程式碼
2. 審查 - 重新閱讀每一行。捕捉錯字、邏輯錯誤、不清晰的段落
3. 評估 - 執行證據關卡。檢查模式、邊緣情況、測試覆蓋率
4. 修正 - 修復每個問題。絕不延後到「之後」
5. 拉遠視角 - 檢查整合點、匯入、相鄰程式碼是否有迴歸
6. 重複 - 若任一證據關卡標準失敗,回到步驟 4
7. 報告 - 列出變更內容、如何驗證、引用具體證據

證據關卡

「我認為」與「應該會」不是證據。請引用檔案路徑、測試輸出或具體程式碼。

若您無法為任何一列提供證據,請回到「修正」階段。²²

錯誤處理模式

原子性檔案寫入。多個代理同時寫入同一狀態檔案會損毀 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++)) 會回傳結束碼 1,因為 0++ 求值為 0,而 bash 將其視為 false。在啟用 set -e 的情況下,這會終止指令稿。請改用 VAR=$((VAR + 1))。¹⁶

影響範圍分類

依影響範圍對每項代理動作分類,並據此設置關卡:²

遠端控制(從任何瀏覽器或行動應用程式連接到本機 Claude Code)將「外部」關卡從阻塞性等待轉為非同步通知。代理可繼續處理下一個任務,而您從手機上審查上一個任務。²

自主執行的任務規格

有效的自主任務包含三項要素:目標、完成標準與情境指引:¹⁶

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 狀態碼、檔案存在性檢查。早期某項任務要求代理「撰寫通過的測試」,結果產出 assert True 和 assert 1 == 1。技術上正確。實務上毫無價值。¹⁶

須留意的失敗模式

具體的工作階段軌跡

一段自主執行處理含 5 個 story 的 PRD 的工作階段軌跡:²

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

2. 代理閱讀 PRD,規劃第一個 story。UserPromptSubmit 觸發。Dispatcher 注入:活躍專案情境、工作階段漂移基準。

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

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

5. 代理完成該 story。Stop 觸發。品質關卡檢查:代理是否引用了證據?是否有模糊措辭?diff 中是否有 TODO 註解?若任一檢查失敗,exit 2,代理繼續工作。

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

7. 三個程式碼審查代理並行啟動。每個獨立審查 diff。若任一審查者標記 CRITICAL,該 story 回到佇列。

8. Story 通過。下一個 story 載入。該循環為所有 5 個 story 重複進行。

5 個 story 共觸發約 340 個 hook。在 hook 中的總時間:約 12 秒。在單次過夜執行中,該額外開銷防止了三次憑證洩漏、一個破壞性指令以及兩個不完整的實作。

案例研究:過夜 PRD 處理

某生產 harness 在 8 個過夜工作階段中處理了 12 個 PRD(47 個 story)。指標比較前 4 個 PRD(極簡 harness:僅 CLAUDE.md)與後 8 個(完整 harness:hooks、skills、品質關卡、多代理審查)。

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

安全考量

可信代理的五項原則（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指令啟用),使用OS層級的隔離(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層級。 系統提示壓縮。移除教學程式碼範例(模型已知API),整併跨檔案的重複規則,並以約束取代解釋。「拒絕符合敏感路徑的工具呼叫」與15行解釋為何不應讀取認證的說明,效果相同。

代理層級。 以全新產生取代長對話。自主執行中的每個故事都會獲得一個全新代理與乾淨脈絡。脈絡不會膨脹,因為每個代理都是從頭開始。以簡報取代記憶:模型執行清晰簡報的效果,優於導覽30個累積脈絡步驟。

架構層級。 當操作為無狀態時,優先採用CLI而非MCP。一次性評估的claude --print呼叫成本較低,且不增加連線開銷。當工具需要持久狀態或串流時,MCP才有意義。

決策框架

何時使用各機制:

Skills vs Hooks vs Subagents

常見問題

多少個 hooks 才算太多？

限制取決於效能而非數量。每個 hook 都是同步執行，因此所有 hook 的執行時間會累加到每次符合條件的 tool 呼叫上。當每個 hook 都能在 200 毫秒內完成時，跨使用者層級與專案層級設定的 95 個 hooks 執行起來不會有明顯延遲。需要留意的門檻是：若 PostToolUse hook 為每次檔案編輯增加超過 500 毫秒，整個工作階段就會感覺遲鈍。部署前請使用 time 對 hooks 進行效能分析。¹⁴

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

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

Hook 設定檔該放在哪裡？

Hook 設定可放入 .claude/settings.json（專案層級 hooks，會提交到您的儲存庫並與團隊共用），或放入 ~/.claude/settings.json（使用者層級 hooks，個人專屬，套用到每個專案）。當兩者同時存在時，專案層級 hooks 優先生效。請使用絕對路徑指定指令檔，以避免工作目錄問題。¹⁴

每個決策都需要 deliberation 嗎？

不需要。信心模組會從四個維度（模糊性、複雜性、影響範圍、情境依賴）對決策評分。只有整體信心分數低於 0.70 的決策才會觸發 deliberation，約佔總決策的 10%。文件修正、變數重新命名與例行性編輯完全跳過 deliberation。安全性架構、資料庫結構變更與不可逆的部署則會穩定觸發 deliberation。⁷

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

成功路徑與失敗路徑都要測。成功：agents 富有成效地產生分歧並達成共識。失敗：agents 過早收斂、永遠無法收斂，或超出 spawn 預算。端對端測試以確定性的 agent 回應模擬每種情境，驗證兩道驗證閘門能攔截每一種已記錄的失敗模式。一個生產級的 deliberation 系統會在三個層級執行 141 個測試：48 個 bash 整合測試、81 個 Python 單元測試，以及 12 個端對端管線模擬。⁷

Deliberation 對延遲有何影響？

3 個 agent 的 deliberation 會增加 30 至 60 秒的實際時間（agents 透過 Agent tool 依序執行）。10 個 agent 的 deliberation 則增加 2 至 4 分鐘。共識與 pride check hooks 各自能在 200 毫秒內執行完成。主要瓶頸來自每個 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.

退出代碼

主要指令

檔案位置

變更日誌

參考資料