代理架構：建構AI驅動的開發工作框架

TL;DR：Claude Code不是具備檔案存取能力的聊天框，而是一個可程式化 runtime，擁有29個已記錄的生命週期事件，每個事件都可透過模型無法略過的 shell scripts 掛上 hook。將 hooks 疊成 dispatchers，dispatchers 疊成 skills，skills 疊成 agents，agents 疊成 workflows，就能得到一套自主開發 harness：它會強制執行限制、委派工作、跨 sessions 保留 memory，並協調多 agent deliberation。Claude Code v2.1.147 新增預設關閉的 Workflow tool（CLAUDE_CODE_WORKFLOWS=1），讓確定性的 multi-agent orchestration 從純 userland scripts 逐步走向 first-party runtime primitive；v2.1.149 則從安全面強化同一個教訓，修正 PowerShell permission-bypass 與 git-worktree sandbox allowlist 問題。Hooks 與 evidence gates 仍然掌握正確性。⁵²⁵³ 本指南涵蓋這套堆疊的每一層：從單一 hook 到10-agent consensus system。無需任何 frameworks。全部使用 bash 與 JSON。

Andrej Karpathy 為圍繞 LLM agent 成長出的東西取了一個詞：claws。也就是讓 agent 能在 context window 之外抓住現實世界的 hooks、scripts 與 orchestration。¹ 多數開發者把 AI coding agents 視為互動式助理。他們輸入 prompt，看它編輯檔案，然後繼續下一步。這種框架會把生產力限制在您能親自監督的範圍內。

基礎架構的心智模型不同：AI coding agent 是一個具備 LLM kernel 的可程式化 runtime。模型採取的每個動作，都會通過您控制的 hooks。您定義的是 policies，而不是 prompts。模型在您的基礎架構中運作，就像 web server 在 nginx rules 中運作。您不會坐在 nginx 前面逐一輸入 requests。您會設定它、部署它，並監控它。

這個差異很重要，因為基礎架構會複利成長。一個能阻擋 bash commands 中憑證的 hook，會保護每個 session、每個 agent、每次自主執行。一個編碼了評估 rubric 的 skill，不論由您呼叫或由 agent 呼叫，都會一致套用。一個負責安全 code review 的 agent，不論您是否正在觀看，都會執行同樣的檢查。²

重點摘要

• Hooks 保證執行；prompts 不會。 對 linting、formatting、安全檢查，以及任何無論模型行為如何都必須每次執行的事項使用 hooks。Exit code 2 會阻擋動作。Exit code 1 只會警告。³
• Skills 編碼會自動啟用的領域專業知識。 description 欄位決定一切。Claude 使用 LLM reasoning（不是關鍵字比對）來判斷何時套用 skill。⁴
• Subagents 防止 context bloat。 用於探索與分析的隔離 context windows，可讓主要 session 保持精簡。並行執行獨立 subagents；當 workers 需要持續協調時，則使用 agent teams。⁵
• Memory 存在於檔案系統。 檔案會跨 context windows 持續保留。CLAUDE.md、MEMORY.md、rules directories 與 handoff documents 形成結構化外部 memory system。⁶
• Multi-agent deliberation 能捕捉盲點。 單一 agent 無法挑戰自己的假設。兩個具備不同評估優先順序的獨立 agents，能抓出 quality gates 無法處理的結構性失敗。⁷
• Harness pattern 就是整個系統。 CLAUDE.md、hooks、skills、agents 與 memory 不是彼此獨立的功能。它們會組合成一個位於您與模型之間的確定性層，並能隨自動化規模擴展。

如何使用本指南

每個章節都建立在前一節之上。最後的 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 檔案與規則目錄定義代理對您專案的認知。它們會在工作階段啟動以及每次壓縮（compaction）後自動載入，是代理的長期架構記憶。

擴充層（Extension Layer）： skills 提供根據情境自動啟用的領域專業知識。hooks 提供在每次符合條件的工具呼叫時觸發的確定性閘道。記憶檔案則跨工作階段保存狀態。自訂代理（agents）提供專門的 subagents 設定。

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

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

託管式與自架式 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），以及在容器遺失時透過快照與還原（snapshot/rehydrate）保留狀態的機制。²³²⁴

OpenAI 端更深層的 SDK 表面則隨著 openai-agents Python v0.14.0 推出（2026 年 4 月 15 日發布、4 月 16 日公告）：Agent 的 SandboxAgent 子類別具備 default_manifest、沙盒指令與 capabilities；Manifest 描述全新工作區契約（檔案、目錄、本機檔案、Git 儲存庫、env、users、mounts）；SandboxRunConfig 用於針對每次執行配置沙盒用戶端、即時 session 注入、manifest 覆寫、快照與具現化（materialization）並行限制。內建 capabilities 涵蓋 shell 存取、檔案系統編輯、影像檢查、skills、沙盒記憶與壓縮。沙盒記憶會跨執行保存擷取出的經驗教訓，並逐步揭露；工作區支援本機檔案、Git 儲存庫項目以及遠端掛載（S3、R2、GCS、Azure Blob、S3 Files）；快照可在不同供應商之間移植。後端：UnixLocalSandboxClient、DockerSandboxClient，以及透過選用 extras 連接 Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop 與 Vercel 的託管用戶端。²⁴

對於希望將 Claude Code runtime 以函式庫形式嵌入 Python 專案的情境——介於「shell out 呼叫 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 工具回傳的 CallToolResult，使模型只看到一個驗證錯誤的二進位資料），並讓 SandboxNetworkConfig 與 TypeScript SDK 的綱要對齊（allowedDomains、deniedDomains、allowManagedDomainsOnly、allowMachLookup）。³⁰

若您的 harness 包含語音或即時（realtime）層，openai-agents-python v0.17.0（2026 年 5 月 8 日）將 RealtimeAgent 的預設值更新為 gpt-realtime-2。⁴¹ 既有的即時工作階段會自動採用新的預設值；如需在評估期間維持舊行為，請明確固定先前的模型版本。

架構上的分岔已然成形：

何時選擇何者： 自架式仍適合已具備基礎設施實力、希望掌控自家 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 System

Skills是由模型叫用的擴充功能。Claude會根據脈絡自動探索並套用它們，不需要您明確呼叫。⁴只要發現自己在不同工作階段反覆重新說明同一段脈絡，就是該建立skill的時候。

何時建立Skill

Skills適合放置Claude永遠可用的知識。Slash commands則適合您明確觸發的動作。如果正在兩者之間取捨，請問自己：「Claude應該自動套用這項內容，還是應該由我決定何時執行？」

建立Skill

Skills可以放在4種位置，範圍由廣到窄如下：⁴

每個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 descriptions會被注入系統prompt的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會包含：它做什麼（針對特定問題類型review code）、何時使用（檢查變更、PR、品質分析），以及使用者自然會輸入的觸發片語（review、audit、check）。

脈絡預算

所有skill descriptions共用一個脈絡預算，會以脈絡視窗的1%動態調整，並以8,000個字元作為後備值。⁴如果skills很多，請讓每個description保持精簡，並把關鍵使用情境放在最前面。您可以透過SLASH_COMMAND_TOOL_CHAR_BUDGET環境變數覆寫預算，¹¹但更好的修正方式是寫出更短、更精準的descriptions。工作階段中執行/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中使用相對連結參照它們。Claude會在skill啟用時按需讀取這些檔案。請將SKILL.md控制在500行以內，並把詳細參考資料移到支援檔案中。¹²

透過Git分享Skills

Project skills（repo根目錄中的.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

隊友pull之後，就會自動取得skill。不需要安裝，也不需要設定。這是讓團隊共享專業知識最有效的方式。

Skills作為Prompt Library

除了單一用途skills之外，目錄結構也可作為井然有序的prompt library：

~/.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'"
---

Philosophy skills會透過SessionStart hooks自動啟用，將品質約束注入每個工作階段，而不需明確叫用。Skill本身是知識。Hook則是執行約束。兩者合在一起，形成一層政策。

常見Skill錯誤

Descriptions過於寬泛。如果git-rebase-helper skill會在任何git相關prompt中啟用（rebase、merge、cherry-pick，甚至git status），就會污染80%的工作階段脈絡。修正方式是收緊description，或加入disable-model-invocation: true並要求明確透過/skill-name叫用。⁴

太多skills競爭預算。Skills越多，代表越多descriptions會競爭1%的脈絡預算。如果注意到skills沒有啟用，請用/context檢查被排除的項目。比起大量模糊的skills，應優先保留少量、描述清楚的skills。

關鍵資訊埋在支援檔案中。Claude會立即讀取SKILL.md，但只會在需要時存取支援檔案。如果關鍵資訊在支援檔案中，Claude可能找不到。請把必要資訊直接放在SKILL.md裡。⁴

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

基於claude-agent-sdk-python v0.1.77+的自架harness，應使用ClaudeAgentOptions上的skills選項宣告可用skills，而不是在allowed_tools中使用舊版"Skill"值。³⁷"Skill"簡寫已被棄用，專用選項能讓Claude Code取得更結構化的資訊，了解哪些skills可用。v0.1.77中內建的CLI是v2.1.133。

.claude/skills/中的Plugin與Skill匯流（2026年5月29日）

Skills一直都會從專案的.claude/skills/目錄載入。Claude Code v2.1.157將該目錄延伸到plugins：放在.claude/skills/中的plugin現在無需marketplace註冊即可自動載入，而claude plugin init <name>會在該處搭建新的plugin骨架，並預先串好manifest與SKILL.md。⁵⁸這彌合了過去分處不同位置的兩種專案工具形態：一種是直接commit到repo的裸skill，另一種是綁定skill、hooks與MCP server的plugin，但後者以往需要透過marketplace安裝。對harness設計的實際影響是：專案範圍工具不再需要繞道registry才能發布。寫好、commit，隊友在git pull後就會取得同一套介面。Plugins仍然負責可打包安裝的使用情境（hooks + skills + MCP servers + agents放在同一個ZIP）；改變之處在於，專案不再需要只為了從自己的樹狀結構載入一個plugin，就架設marketplace。

將內建介面隱藏作為治理（2026年6月8日）

Skills是能力，而能力也是攻擊面。Claude Code v2.1.169加入disableBundledSkills設定（以及對應的CLAUDE_CODE_DISABLE_BUNDLED_SKILLS環境變數），可讓模型完全看不到內建skills、workflows與內建slash commands。⁶⁰對經過強化或受監管的harness而言，這是刻意縮減攻擊面：已稽核並核准特定project與personal skills集合的operator，可以壓下Anthropic隨附的所有內容，讓模型只會針對operator審核過的介面進行推理。請把它視為tool allowlist。預設值代表廣泛能力，而關閉預設值是一項治理決策，不是便利性切換。

巢狀.claude/skills與Closest-Wins解析（2026年6月16日）

Claude Code v2.1.178讓專案工具具備位置感知能力。巢狀.claude/skills目錄中的skills現在會在您處理該目錄底下的檔案時載入，而不只從repo根目錄載入；如果名稱衝突，巢狀skill會顯示為<dir>:<name>，因此兩者都仍可存取。⁶³同一版也讓其餘專案介面以最接近工作目錄的方式解析：當agent、workflow或output-style名稱在巢狀.claude/目錄之間衝突時，離工作目錄最近者勝出；而儲存project-scope workflow時，目標會是最接近的既有.claude/workflows/，不再一律是根目錄。⁶³對monorepo或repo-of-repos而言，這就是單一扁平全域介面與按套件脈絡啟用的工具之間的差別。services/api/.claude/skills/可以承載API專屬skills，只有在該樹狀結構中工作時才會浮現，且不會與同名的services/web/ skill衝突。

Hook 架構

Hooks 是由 Claude Code 生命週期事件觸發的 shell commands。³它們以一般 scripts 形式在 LLM 外部執行，不是由模型解讀的 prompts。模型想執行 rm -rf /？一段 10 行的 bash script 會先對照 blocklist 檢查該 command，並在 shell 看到之前拒絕它。無論模型是否願意，hook 都會觸發。

可用事件

截至本指南更新時，Claude Code 在 8 個類別中公開了 29 個已記載的生命週期事件。事件清單會隨版本發布而增加，因此請把參考文件視為唯一可信來源；在接上 production hooks 前，請先查看 cheat sheet 的目前完整表格：¹³

Exit Code 語意

Exit codes 決定 hooks 是否封鎖動作：³

關鍵：每個 security hook 都必須使用 exit 2，不是 exit 1。Exit 1 是 non-blocking warning。危險 command 仍會執行。這是各團隊最常見的 hook 錯誤。¹⁴

Hook 設定

Hooks 放在 settings files 中。Project-level（.claude/settings.json）用於 shared hooks。User-level（~/.claude/settings.json）用於 personal hooks：

{
  "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 events 而言，它會比對 tool_name 值，例如 Bash、Edit、Write、Read、Glob、Grep、像 mcp__server__tool 這類 MCP tool names，或用 * 表示所有 tools。Simple names 和以 | 分隔的 lists 是 exact matches；含有其他字元的值則是 JavaScript regular expressions。有些 events 不支援 matchers，只要設定就一定會觸發。¹³

Hook Input/Output Protocol

Hooks 會從 stdin 收到含完整 context 的 JSON：

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

若需要進階控制，PreToolUse hooks 可以輸出 JSON 來修改 tool input、注入 context，或做出 permission decisions。請使用 hookSpecificOutput wrapper；較舊的 top-level 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."
  }
}

3 種保證

撰寫任何 hook 前，先問：我需要哪一種保證？¹⁴

格式保證會在事後確保一致性。Write/Edit 上的 PostToolUse hooks 會在每次檔案變更後執行 formatter。模型輸出並不重要，因為 formatter 會將一切正規化。

{
  "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 hooks 會檢查 commands，並以 exit code 2 封鎖 destructive patterns：

#!/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 commands 上的 PreToolUse hooks 會執行 linter 或 test suite，若 quality checks 失敗就封鎖 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 Commands 以外的 Hook 類型

Claude Code 支援 5 種 hook types：¹³

Command hooks（type: "command"）會執行 shell scripts。快速、可預測，而且沒有 token cost。

MCP tool hooks（type: "mcp_tool"）會呼叫已連線 MCP server 上的 tool。當 validation logic 已經位於 MCP 邊界後方，且不需要另外寫 shell script 時，適合使用它們。

Prompt hooks（type: "prompt"）會把 single-turn prompt 傳給快速的 Claude model。模型回傳 { "ok": true } 表示允許，或 { "ok": false, "reason": "..." } 表示封鎖。適合用於 regex 無法表達的細緻評估。

Agent hooks（type: "agent"）會產生具備 tool access（Read、Grep、Glob）的 subagent 來進行 multi-turn verification。它們仍屬實驗性；production gates 請優先使用 command hooks，只有在檢查確實需要檢視實際檔案或 test output 時，才保留 agent hooks：

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

截至 Claude Code v2.1.140，agent hook input 包含 subagent_type，可讓 shared hook 區分 security-reviewer run、explorer 或 generic worker，而不必從 prompt text 猜測。⁴⁹

HTTP hooks（type: "http"）會把 event 的 JSON input 以 POST request 傳送到 URL，並接收 JSON 回來。適用於 webhooks、external notification services，或以 API 為基礎的 validation（v2.1.63+）。不支援 SessionStart events：

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

Async Hooks

Hooks 可以在背景執行而不封鎖 execution。對 notifications 和 logging 這類非關鍵操作，加入 async: true：¹³

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

Async 適合 notifications、telemetry 和 backups。絕不要將 async 用於 formatting、validation，或任何必須在下一個動作前完成的事項。

Dispatchers 優於獨立 Hooks

若同一個 event 觸發 7 個 hooks，且每個 hook 都各自讀取 stdin，會產生 race conditions。兩個 hooks 同時寫入同一個 JSON state file，會截斷該 JSON。所有後續解析該檔案的 hooks 都會壞掉。²

解法是：每個 event 使用一個 dispatcher，從 cached stdin 依序執行 hooks：

#!/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

Debugging Hooks

以下是 debugging hooks 靜默失敗的 5 個技巧：¹⁴

1. 獨立測試 scripts。Pipe sample JSON：echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. 使用 stderr 輸出 debug 資訊。Exit code 2 的 stderr 會作為錯誤訊息回饋給 Claude。Non-blocking stderr（exit 1、3 等）只會在 verbose mode（Ctrl+O）中出現。
3. 留意 jq failures。錯誤的 JSON paths 會靜默回傳 null。請用真實 tool input 測試 jq expressions。
4. 確認 exit codes。使用 exit 1 的 PreToolUse hook 看似有效，實際上沒有任何強制力。
5. 保持 hooks 快速。Hooks 會同步執行。所有 hooks 都應低於 2 秒，最好低於 500ms。

SDK 端 Hook Event Streaming

以 claude-agent-sdk-python（v0.1.74+，2026年5月6日）建置的 self-hosted harnesses，可以直接從 message stream 訂閱 hook events，而不必透過 shell-script callbacks。³⁶在 ClaudeAgentOptions 設定 include_hook_events=True 後，HookEventMessage objects（PreToolUse、PostToolUse、Stop 等）會從與 assistant messages 和 tool results 相同的 iterator 產出。這呼應了 TypeScript SDK 的 includeHookEvents option；同一版也將 bundled CLI 升到 v2.1.129。

當 harness 本身已經位於 Python 中，而且您希望 hook signals 與 model output 位在同一段 control flow 裡，event-stream pattern 就很合適。對於會組合多個 tools、跨 Claude Code 與 Codex 共享 hooks，或需要 exit-code semantics 來封鎖的 harnesses，shell-script hook contract（exit codes、stdin JSON、dispatchers）仍然是正解。

Effort 和 Session Provenance（2026年5月7-8日）

Claude Code v2.1.132 和 v2.1.133 的兩項新增功能，讓 hooks 和 subprocesses 更清楚掌握其 execution context：³⁸³⁹

• hook input 中的 effort.level。Hooks 現在會在同一份帶有 tool_input 和 session_id 的 input 中，收到 effort.level JSON 欄位。同一個值也會匯出為 $CLAUDE_EFFORT env var，因此 Bash commands 不必解析 JSON 就能讀取。可用它依 effort tier 調整 hook cost：在 low 跳過昂貴 validation，在 xhigh 或 max 執行完整 security gate。
• Bash subprocesses 上的 CLAUDE_CODE_SESSION_ID env var。Bash tool subprocesses 現在會看到與 hooks 相同的 session_id 值，並以 CLAUDE_CODE_SESSION_ID 暴露。這補上了 provenance gap；過去記錄 per-session state 的 tools 無法將 subprocess events 與 hook events 關聯起來。

這兩個 signals 不需要修改程式碼即可使用；既有 hooks 若忽略新欄位，仍會繼續運作。

autoMode.hard_deny 和 v2.1.136 Hook/Plugin 修正（2026年5月8日）

Claude Code v2.1.136 為 auto mode 新增 hard-deny tier，並修正一批影響 long-running harnesses 的 plugin 和 MCP 問題：⁴⁰

• settings.autoMode.hard_deny。Auto mode classifier rules 會無條件封鎖，不受 user intent 或 allow exceptions 影響。它位於既有 allow/deny matchers 之上，是不可協商的 governance lever。請將它用於絕不能被覆寫的規則（force-push to main、含有 secrets 的檔案、production database access），即使 operator 已在個人設定中核准更廣泛類別也一樣。
• MCP servers 不再於 /clear 後消失。在 VS Code extension、JetBrains plugin 和 Agent SDK 中，設定於 .mcp.json、plugins 和 claude.ai connectors 的 servers 曾在 /clear 後靜默從 active set 掉出。修正在 v2.1.136 落地。如果您看過「MCP server X went missing mid-session」，原因就是這個。
• MCP OAuth refresh-token 在 concurrent refresh 時遺失。擁有多個 remote MCP servers 的使用者，應該不再需要每天重新驗證。Concurrent refresh writes 之前會彼此覆寫。
• Plan mode 現在會正確封鎖 file writes。相符的 Edit(...) allow rule 之前會繞過 plan-mode write protection。現在無論 allow rules 如何，Plan mode 都會被強制執行。
• Plugin Stop 和 UserPromptSubmit hooks 不再於 mid-session 失敗。Cache cleanup 之前會刪除仍被 running session 使用的 plugin-version files，特別導致這兩個 hook events 壞掉。修正後會將 in-use versions 固定保留。
• plugin.json 中的 skills entry。設定 skills 之前會隱藏 plugin 的預設 skills/ 目錄。現在該 entry 會正確組合；若指向 file path，會明確報錯，而不是靜默失敗。
• CLAUDE_ENV_FILE SessionStart hook env vars 過期。SessionStart hooks 透過 CLAUDE_ENV_FILE 匯出的 vars，之前會在 /resume 或 /clear 後過期。v2.1.136 已修正。Sessions 現在會在這些 events 重新 source env file。

對 governance harnesses 而言，操作上最值得注意的是 autoMode.hard_deny（新的 lever）和 MCP 消失問題的修正（會破壞 long sessions 的 silent failure）。其他都是 quality-of-life cleanup。

Structured Hook Arguments 和 Block Continuation（2026年5月11日）

Claude Code v2.1.139 新增兩個對 production harnesses 重要的 hook 細節：command hooks 的 args: string[] exec form，以及 PostToolUse hooks 的 continueOnBlock。⁴²⁴⁴當 hook 需要 dynamic values 或 path placeholders 時，請優先使用 args。它會直接 spawn command，不經 shell，因此排除一整類 quoting 和 injection 錯誤。

當 PostToolUse hook 應將 rejection reason 回饋給 Claude 並繼續該 turn，而不是結束流程時，使用 continueOnBlock。請把它視為 operator-experience 功能，不是 security bypass。Blocking gate 仍應封鎖 unsafe outcome。

同一版本會把 CLAUDE_PROJECT_DIR 傳給 MCP stdio servers，並讓 plugin configs 在 commands 中引用 ${CLAUDE_PROJECT_DIR}。⁴²MCP tools 應從該值解析 project-relative paths，而不是依賴剛好啟動 server 的 process working directory。

Claude Code v2.1.140 主要是給 harness operators 的 reliability release：它修正 settings changes 時 ConfigChange hooks 不觸發的問題，補上 disableAllHooks 和 allowManagedHooksOnly 在不同 settings levels 間無法正確組合的 edge cases，並避免 permission dialogs 暴露由 hook results 回傳的非預期 environment variables。⁴⁹這讓本節既有 governance patterns 更可靠；不需要新的 hook architecture。

Claude Code v2.1.141 新增 hook-output terminalSequence 欄位，可在沒有 controlling terminal 的情況下用於 desktop notifications、window titles 和 bells。⁵⁰請把它視為 operator signaling，而非 enforcement。Security 和 quality gates 仍應透過一般 blocking contract 溝通失敗：structured hook output 加上阻止 unsafe action 的 exit behavior。同一版本也新增 claude agents --cwd <path>，用於將 Agent View 限定到單一目錄；新增 CLAUDE_CODE_PLUGIN_PREFER_HTTPS，供沒有 GitHub SSH keys 的環境安裝 plugins；並新增 ANTHROPIC_WORKSPACE_ID，用於涵蓋多個 workspace 的 workload-identity federation rules。⁵⁰這些都是 team harnesses 的 architecture details：更窄的 operational views、更少的 plugin-install assumptions，以及明確的 enterprise token scoping。

Claude Code v2.1.142 對 background-session orchestration 的重要性高於 hook semantics。⁵¹claude agents 現在可以使用明確的 directory、settings、MCP、plugin、permission、model 和 effort flags dispatch background sessions，而不必依賴 wrapper state。Fast mode 現在預設使用 Opus 4.7；只有在 harness 已量測出對 Opus 4.6 行為有依賴時，才 pin CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1。Root-level plugin SKILL.md discovery 和 plugin-provided LSP visibility 可降低 packaging ambiguity。針對 MCP_TOOL_TIMEOUT、pre-existing background-session worktrees、daemon sleep/wake 和 post-upgrade cleanup，以及 plugin cache cleanup 的修正，補上了否則看起來像 orchestration bugs 的 reliability gaps。

Stop-hook steering、cross-session authority 和 multi-agent v2（2026年6月）

6 月初的 4 項變更，對 harness 和 multi-agent design 很重要。⁵⁹

Stop/SubagentStop hooks 取得 steering channel。自 Claude Code v2.1.163 起，Stop 或 SubagentStop hook 可以回傳 hookSpecificOutput.additionalContext，將 feedback 交給 Claude 並讓 turn 繼續，而不會把 response 標示為 hook error。在此之前，Stop hook 真正可用的 lever 只有 exit-2 block；它會顯示成 error，且計入 consecutive-block cap。對 quality-gate harness 來說，這是更乾淨的 primitive：偵測到「你說完成但 tests 還是紅的」的 Stop hook，現在可以注入「以下仍在失敗，請繼續」，而不是 hard-block。真正的停止條件才使用 block；「尚未完成，原因如下」則使用 additionalContext。

Cross-session messaging 不再攜帶借來的 authority。v2.1.166 強化了 multi-session 情境：透過 SendMessage 從另一個 Claude session 轉送的 messages，不再帶有 originating user 的 authority，因此 receiving session 會拒絕 relayed permission requests，auto mode 也會封鎖它們。如果您的 orchestration 讓 agents 彼此傳訊，請把 inbound message 視為 untrusted data，而不是 authenticated instruction。這與 security section 套用到 tool output 的原則相同，只是延伸到 inter-agent messaging。

Model resilience 成為一等設定。fallbackModel setting 現在最多可串接 3 個 backup models，當 primary overloaded 或 unavailable 時依序嘗試；若遇到 unexpected non-retryable API errors，該 turn 也會在 fallback 上自動重試一次。對 long-running autonomous harness 來說，這會把短暫的 primary-model outage 轉化為 graceful degradation，而不是 dropped run。claude agents --json 也新增 waitingFor 欄位（v2.1.162），可揭露 blocked background session 正在等待什麼，例如 permission prompt；對任何輪詢 agent fleet 的 coordinator 都是 observability 上的提升。

用於 clean-room governance 和 troubleshooting 的 Safe mode。Claude Code v2.1.169 新增 --safe-mode flag（以及對應的 CLAUDE_CODE_SAFE_MODE environment variable），可在啟動 session 時一次停用所有 customization：CLAUDE.md、plugins、skills、hooks 和 MCP servers。⁶⁰這是 harness 的反向操作：刻意的 clean-room。用它回答每位 operator 終究會問的問題：「這個行為來自模型，還是來自我設定的東西？」當 hook 誤觸、skill 在不該啟動時啟動，或 MCP server 汙染 context，--safe-mode 會提供已知為空的 baseline 供您比對。它也是 governance primitive：一種在沒有 harness 平常授予之 persistent authority 的情況下執行裸模型的方法。當您需要重現結果，且不讓任何 operator-defined scaffolding 影響它時，這點很重要。

關於 model tiers 的說明。本指南將 Opus 4.8 視為 Claude Code 的 agentic default，也就是除非另行選擇，否則用於執行 autonomous harnesses 的模型。截至 2026年6月9日，Anthropic 推出 Claude Fable 5（claude-fable-5），這是位於 Opus 之上的新 tier，被描述為其最強大的模型，也就是可供一般使用且經安全化的「Mythos-class」系統，可在 Claude Code v2.1.170 透過 /model claude-fable-5 選用。⁶⁰Opus 4.8 仍是 agentic default；請在 raw reasoning depth 足以合理化成本的決策上，刻意選用更高 tier，而不是把它當作整個 fleet 的 blanket setting。

Codex 發布 multi-agent v2。Codex CLI v0.137.0 讓 runtime choice 留在每個 thread 上，為 spawned agents 提供更乾淨的 follow-up 和 metadata defaults（hide_spawn_agent_metadata 現在預設為 true），並將 raw parent events 傳播給 child listeners。它的 subagent model 維持明確：built-in default/worker/explorer agent types、以 TOML 定義的 custom agents，以及 concurrency controls（agents.max_threads 預設 6，agents.max_depth 預設 1）。同一版本新增 v1 skills extension，具備 per-turn skill-catalog resolution 和新的 thread-start/turn-error lifecycle contributor events，在保留 kernel-sandbox posture 作為預設邊界的同時，縮小與 Claude Code hook/skill surface 的差距。接著 Codex v0.138.0–v0.139.0 將 multi-agent v2 強化到可用於 production：inter-agent message payloads 現在已加密，v2 agent config catalog 加上 agent-residency LRU 會管理哪些 agents 保持 resident，而 concurrency 依 active execution 計算，不再依 spawned threads 計算，所以 idle agents 不再占用 slot。⁶¹lifecycle API 也更成熟；close_agent 更名為 interrupt_agent（v0.139.0），以反映它是 interrupt running agent，而不只是關閉 handle；由 subagent 引發的 MCP startup warnings 現在會限定在 owning thread，不會重複冒到 parent transcript。⁶¹對任何建置 Codex-side orchestration 的人而言，這些就是 demo 和 fleet 的差別：encrypted message transport、bounded residency、execution-counted concurrency，以及不會跨 thread boundary 洩漏的 warnings。Codex v0.140.0 接著開啟跨 tool seam：/import 可從 Claude Code 選擇性拉取 setup、project config 和 recent chats 到 Codex，而 sessions 也變成可永久刪除（codex delete / /delete，含 confirmation safeguards）。⁶⁴/import 是官方第一次承認 operators 會在 harnesses 之間移動；您為其中一個建立的 configuration，不再被困在原地。

記憶與脈絡

每一段 AI 對話都在有限的 context window 內運作。隨著對話變長，系統會壓縮較早的回合，為新內容騰出空間。這種壓縮會造成資訊流失。第 3 輪記錄的架構決策，到了第 15 輪可能已不復存在。⁹

多輪崩解的 3 種機制

MSR/Salesforce 研究指出 3 種彼此獨立的機制，每一種都需要不同的介入方式：⁹

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

跨越 context 邊界時，最可靠的記憶存在於檔案系統中。Claude Code 會在每個 session 開始時，以及每次 compaction 後，讀取 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 檔案會跨 session 記錄錯誤、決策與模式。當您發現 bash 中 VAR 為 0 時，set -e 會讓 ((VAR++)) 失敗，就應該記錄下來。3 個 session 之後，當您在 Python 遇到類似的整數邊界案例時，MEMORY.md 條目就會浮現這個模式。¹⁵

Auto Memory（v2.1.32+）： Claude Code 會自動記錄並回想專案脈絡。工作期間，Claude 會將觀察寫入 ~/.claude/projects/{project-path}/memory/MEMORY.md。Auto memory 會在 session 開始時，將前 200 行載入 system prompt。請保持精簡，並連結到獨立的主題檔案以存放詳細筆記。⁶

記憶整理優先於記憶量（2026 年 5 月）： 一篇近期關於 LLM-agent cooperation 的 arXiv 預印本，將擴大 recall 視為可能的失敗模式：在作者的實驗中，更長的可見歷史在 28 組 model-game 設定中的 18 組降低了合作表現。⁴⁸ 請把這視為設計警訊，而不是已成定律。production 規則已經足夠清楚：保持 MEMORY.md 簡短、連結到詳細資料，並在 handoffs 中放入可供決策的摘要。原始逐字稿傾印、tool logs 和冗長 recall feeds 應放在可搜尋的儲存空間，而不是自動進入 active prompt。

策略 2：主動 Compaction

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

何時 compact： - 完成一個明確子任務後（功能已實作、bug 已修復） - 開始處理 codebase 的新區域前 - 當 Claude 開始重複或遺忘先前脈絡時 - 在高強度 session 中，大約每 25-30 分鐘一次

CLAUDE.md 中的自訂 compaction instructions：

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

Compaction 保護對話；/cd command（Claude Code v2.1.169）保護 prompt cache。它能在不中斷該回合已累積 cache 的情況下，將 session 在中途移到新的 working directory。⁶⁰ 在此之前，變更目錄代表必須開啟新的 session，cache 也會變冷。對於長時間執行、需要從一個 repository 轉向 sibling repository 的 session，這在 monorepo 和多服務工作中很常見，/cd 能保留昂貴的 cached prefix，同時重新指向檔案系統脈絡。

策略 3：Session Handoffs

對於橫跨多個 session 的任務，請建立 handoff documents 來捕捉完整狀態：

## 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 成本，為後續 session 提供完整脈絡。使用 claude -c（continue）開始新的 session，或讀取 handoff document，都能直接進入實作。¹⁵

策略 4：Fresh-Context Iteration（Ralph Loop）

對於超過 60-90 分鐘的 sessions，每次 iteration 都啟動一個新的 Claude instance。狀態透過檔案系統延續，而不是透過對話記憶延續。每個 iteration 都能取得完整的 context budget：¹⁶

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

與單一長 session 相比：

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

每個 iteration 使用 fresh context 的做法，會以 15-20% 的額外成本換取 orient step（讀取狀態檔案、掃描 git history），但每次 iteration 都能保有完整的認知資源。¹⁶ 成本效益計算如下：60 分鐘以內的 sessions，單一對話效率較高。超過 90 分鐘後，即使有額外成本，fresh-context 仍會產生品質更高的輸出。

策略 5：Managed Memory Curation（Dreaming）

Anthropic 的 Claude Managed Agents 於 2026 年 5 月 6 日將 Dreaming 加入為 Research Preview。³⁵ 根據 Anthropic：「Dreaming 是一個排程程序，會檢閱您的 agent sessions 和 memory stores，擷取模式並整理記憶，讓您的 agents 隨時間改進。」³⁵

Dreaming 在 sessions 之間於背景執行，不位於 critical path。它是對 filesystem-as-memory 模式的補充，而非取代：您的 MEMORY.md 檔案仍是承重面；Dreaming 會將整理過的記憶條目寫入 Managed Agents memory store，agent 會在 session 開始時讀取。對於同時混用自架檔案系統狀態與 managed-side curation 的 harnesses，這兩種模式可以並存。

Dreaming 仍處於 Research Preview，因此行為可能改變。上文記錄的 session-handoffs 和 CLAUDE.md patterns，仍是 self-hosted harnesses 的權威記憶機制。

反模式

只需要 10 行，卻讀取整個檔案。 單次讀取 2,000 行檔案會消耗 15,000-20,000 tokens。請使用行偏移：Read file.py offset=100 limit=20 能省下絕大多數成本。¹⁵

將冗長錯誤輸出留在 context 中。 除錯完成後，您的 context 可能仍保留 40 多個失敗 iteration 的 stack traces。修好 bug 後執行一次 /compact，就能釋放這些多餘負擔。

每個 session 一開始就讀取所有檔案。 讓 Claude Code 的 glob 和 grep tools 依需求尋找相關檔案，避免預先載入 100,000+ tokens 的不必要內容。¹⁵

Subagent 模式

Subagents 是專門化的 Claude 實例，能獨立處理複雜任務。它們會以乾淨的 context 啟動（不受主對話污染），使用指定 tools 執行作業，並以摘要形式回傳結果。探索結果不會膨脹您的主對話；只有結論會回傳。⁵

內建 Subagent 類型

建立自訂 Subagents

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

---
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 隔離

Subagents 可以在暫時性的 git worktrees 中運作，提供完整且隔離的 repository 副本：⁵

---
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 隔離對可能破壞 codebase 的實驗性工作至關重要。

平行 Subagents

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

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

每個 agent 都在自己的 context window 中執行，找出相關程式碼，並回傳摘要。主 context 保持乾淨。

Recursion Guard

如果沒有 spawn 限制，agents 會委派給 agents，而後者再委派給其他 agents；每一層都會遺失 context 並消耗 tokens。recursion guard 模式會強制執行預算：¹⁶

#!/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"

關鍵教訓： 使用 spawn budgets，而不只是 depth limits。以深度為基礎的限制會追蹤父子鏈（例如深度 3 時封鎖），但會漏掉寬度問題：深度 1 有 23 個 agents，仍然只是「depth 1」。spawn budget 會追蹤每個 parent 的 active children 總數，並以可設定的最大值封頂。budget model 對應的是實際失敗模式（agents 總數過多），而不是替代指標（巢狀層級過多）。⁷

遞迴委派現在是一級支援的深度能力。 自 Claude Code v2.1.172（2026年6月10日）起，sub-agents 可以生成自己的 sub-agents，最多巢狀 5 層；過去委派實際上只能到 1 層。⁶² 這讓上方的 recursion guard 更加重要，而不是更不重要：平台現在允許的，正是 agents 委派給 agents、並燃燒 context 與 tokens 的鏈條。因此 spawn budget 與 depth cap 才是避免 5 層樹狀結構擴散成數百個 active agents 的關鍵。請將 5 層視為平台允許的上限，而不是預設應追求的目標。

Auto mode 現在會在 spawns 啟動前進行審核。 Claude Code v2.1.178 補上了 matching governance 的缺口：在 auto mode 中，subagent spawns 會在 subagent 啟動前，由 permission classifier 評估，而不是等它開始採取行動後才評估。⁶³ 過去，subagent 可能被生成來請求 parent session 原本會被阻擋的動作，而 spawn 本身就是繞過點。在 spawn time 進行審核，意味著 recursion guard 與 permission model 終於接上：child 不能被用來漂白 policy 禁止的動作。

Agent Teams（Research Preview）

Agent Teams 會協調多個 Claude Code 實例；它們各自獨立工作，透過共用 mailbox 與 task list 溝通，也能挑戰彼此的發現：⁵

啟用方式：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

何時使用 agent teams，而非 subagents：

Agent View 與 Goal Loops（2026年5月）

Claude Code v2.1.139 加入了 Agent View，這是一個以 claude agents 啟動的 research-preview 介面，可在同一個畫面查看執行中、遭封鎖與已完成的 Claude Code sessions。⁴²⁴³ 官方文件將它描述為一種 dispatch 並管理多個 sessions、查看每個 session 正在做什麼，以及辨識哪些 session 需要操作員輸入的方式。⁴³ 這讓 multi-agent 工作擁有最終摘要無法提供的 operations view。

在推廣 subagent 或 team 模式時使用 Agent View：檢查哪些 sessions 遭封鎖、哪些仍在執行，以及工作分配是否符合預期架構。不要把它當作品質證明。它是 observability；tests、review gates 與 evidence reports 仍然決定工作是否健全。

同一版本也加入了 /goal，可設定 completion condition，並讓 Claude 跨 turns 持續執行直到條件達成；支援 interactive、-p 與 Remote Control 使用。⁴² 請將 /goal 視為 session-scoped completion loop，而不是 deterministic gates 的替代品。它有助於讓 agent 專注在目標上，但凡是失敗必須阻擋流程的地方，tests、citation checks、deploy checks 與 security hooks 仍應由 command 或 script 支撐。

Workflow Tool（v2.1.147+）

Claude Code v2.1.147 加入了預設關閉的 Workflow tool，用於 deterministic multi-agent orchestration。使用 CLAUDE_CODE_WORKFLOWS=1 啟用。⁵² 從架構上看，這一點很重要，因為它為 Claude Code 提供第一方 orchestration primitive，可處理過去需要自訂 dispatch scripts、mailbox state 與 subagent coordination conventions 的流程。

不要刪除其周邊 harness。Workflow 可以結構化執行，但不會取代您的 safety model。保留 PreToolUse 與 PostToolUse hooks 作為阻擋層；保留 spawn budgets 或 workflow step budgets，以防止寬度失控；讓 filesystem state 可稽核；並讓最終 evidence reports 位於 model 自我評估之外。實務上：用 Workflow 定義 orchestration shape；用 hooks、tests 與 review gates 判定真相。

多代理人協作

單一代理人 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不需要理解您為什麼使用conventional commits。它需要知道要執行的確切命令，以及「完成」是什麼樣子。

優先順序層級

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

會被忽略的內容

這些模式通常不會對agent行為產生可觀察的變化：²¹

沒有命令的散文段落。「我們重視乾淨且經過良好測試的程式碼」是文件，不是作業指令。agent會讀取它，然後繼續撰寫沒有測試的程式碼，因為其中沒有可執行的指示。

模糊的指令。「小心處理資料庫migration」不是限制。「套用migration前先執行alembic check。如果缺少downgrade路徑就中止。」才是。

互相矛盾的優先事項。「快速前進並迅速出貨」加上「確保完整測試覆蓋率」加上「將執行時間維持在5分鐘內」再加上「每次commit前執行完整整合測試。」agent無法同時滿足這4項要求，預設會略過驗證。²¹

沒有強制機制的風格指南。「遵循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：讓服務指示彼此隔離）

在前4項可正常運作前，先略過風格偏好。

檔案匯入

在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 coding tool都能辨識的開放標準。²¹如果您的團隊使用多種工具，請將AGENTS.md作為標準來源，並把相關區段鏡像到工具專屬檔案：

AGENTS.md中的模式（命令優先、收尾明確、依任務組織）可用於任何工具的指示檔。不要維護會彼此偏移的平行指示集。撰寫一份權威來源，並進行鏡像。

Codex對等注意事項

Codex現在已為主要harness層提供一級等價功能，但遷移是模式轉譯，不是檔案複製。Codex會在工作開始前讀取AGENTS.md，將來自~/.codex的全域指引，與專案及巢狀repository指示分層套用。³¹Codex skills使用相同的SKILL.md心智模型，並採用漸進式揭露：Codex一開始只看到skill名稱、描述與檔案路徑，只有在決定使用時才載入完整skill。³²Codex也有原生hooks、plugin-bundled hooks、managed hooks、MCP支援，以及明確的subagent工作流程。³³³⁴

Codex v0.138.0–v0.139.0強化了AGENTS.md在非平凡工作區中的探索機制：載入現在會經由環境的檔案系統抽象層，並在探索走訪期間保留邏輯路徑，因此即使工作區是遠端檔案系統或符號連結樹，也能選到正確檔案。⁶¹只要您的標準AGENTS.md是權威來源，而agent正在掛載、容器實體化或符號連結的checkout上作業，這點就很重要；這些情境中，天真的路徑走訪可能會悄悄選到錯誤的指示檔，甚至完全找不到。若您在多個服務間鏡像一份權威AGENTS.md，請將此版本視為信任agent實際載入檔案就是您所寫檔案的最低基準。

接著，Codex v0.141.0強化了遠端執行路徑本身：remote executors現在會透過已驗證且端對端加密的Noise-relay channels連線（控制平面與executor不再信任兩者之間的relay），跨平台遠端執行會保留executor原生的工作目錄與shell，而TLS也接受企業proxy使用的P-521憑證簽章。⁶⁵如果您的orchestration會跨網路邊界驅動Codex executors，這就是信任relay假設與端對端加密假設之間的差別。請把它視為任何remote-executor拓撲的基準。

實務對應如下：

重要差異在於：Claude subagents可依描述自動選取，而Codex目前將subagent工作流程記載為明確啟用。因此，在Codex中，skills與hooks才是always-on harness行為的合理預設；subagents則適合用於刻意安排的平行工作、review與探索。

測試您的指示

驗證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個repository的分析發現，模糊性造成了大多數失敗。²¹

生產環境模式

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

Claude Opus 4.7（2026年4月16日）推出了幾項特定能力，會改變 harness 需要防範的事項：²⁹

• 工具失敗韌性： Opus 4.7 會在工具失敗後繼續執行，而這類失敗過去會中斷 Opus 4.6 session。您可以減少 subagent 程式碼中的防禦性重試 wrapper，但不能完全移除。保留 hook 層級的防護；刪減 prompt 內「如果工具失敗，就再試三次」這類 scaffolding。
• xhigh effort tier（僅 Opus-4.7）： 介於 high 與 max 之間。建議作為 coding 與 agentic workload 的預設值。對長時間執行的 subagents 而言，xhigh 明顯優於 high，且 token 成本增幅低於效能增幅。max 仍適合單次高難度推理；xhigh 則更適合持續性任務。
• Token 預算上限： 可透過 output_config.task_budget 為每次 agent 執行設定（beta header task-budgets-2026-03-13）。模型會看到持續倒數的預算，並優雅地將工作範圍收斂在預算內，而不是意外耗盡。適合用於 agentic loops，讓 token 支出可預測，同時不犧牲短 prompt 的品質。
• 隱含需求感知： 第一個通過「implicit-need」測試的 Claude model，能辨識使用者字面請求低估實際需求的情況。這會降低 CLAUDE.md 中「clarifying rules」區段的必要性。如果您的 CLAUDE.md 有 200 行「使用者要求 Y 時也要考慮 X」這類 guardrails，請修剪已由模型原生涵蓋的部分。

Worktree Base、Sandbox Paths 與 Admin Settings（2026年5月7日）

Claude Code v2.1.133 新增了 4 個值得 production harness 了解的 admin-tier settings：³⁹

worktree.baseRef revert 是需要提醒使用者的重點：若 agents 仰賴 v2.1.128-v2.1.132 的行為（worktrees 從本機 HEAD 建立分支），fresh worktrees 將無法存取未 push 的工作，除非重新選擇加入。

Enterprise Observability 的 OTel Feedback Survey（2026年5月8日）

Claude Code v2.1.136 新增 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL，讓透過 OpenTelemetry 擷取回應的企業可重新啟用 session 內品質問卷。⁴⁰ 如果您的組織將 OTel events 匯入中央 observability stack，這個 env var 會把問卷放回 data path，讓品質訊號能和 latency、error metrics 走同一條 pipeline。請將其視為 opt-in：預設會抑制問卷，這對非 OTel 部署是正確選擇。

Quality Loop

所有非平凡變更都必須採用的強制 review 流程：

1. Implement - 撰寫程式碼
2. Review - 重新閱讀每一行。抓出錯字、邏輯錯誤、不清楚的區段
3. Evaluate - 執行 evidence gate。檢查 patterns、edge cases、test coverage
4. Refine - 修正每個問題。絕不推給「之後」
5. Zoom Out - 檢查 integration points、imports、相鄰程式碼是否有 regressions
6. Repeat - 若任何 evidence gate criterion 失敗，回到第 4 步
7. Report - 列出變更內容、驗證方式，並引用具體 evidence

Evidence Gate

「我相信」和「應該可以」不是 evidence。請引用 file paths、test output，或具體程式碼。

如果無法為任何一列提出 evidence，請回到 Refine。²²

Human Merge Authority

一篇 2026年5月的 arXiv 研究分析了 29,585 個 AI-agent pull-request lifecycle，將 operational agency 與 merge governance 區分開來。⁴⁷ 有用的架構教訓很簡單：agents 可以開始工作、推進 branches、開 PRs、review 工作並摘要風險，但 merge authority 仍應是獨立的 governance boundary。

請在 harness 中明確建立這條界線。讓 agents 準備 PRs 並蒐集 evidence；除非組織有另行稽核過的 automation policy，否則 merges、releases 與 destructive repository operations 都必須要求 human approval。當 automation 執行 merge 時，請保留 logs，用來區分執行者，以及授權該行為的人或 policy。

Error Handling Patterns

Atomic file writes。 多個 agents 同時寫入同一個 state file 會毀損 JSON。請先寫入 .tmp 檔案，再以 mv 原子性搬移。OS 保證同一 filesystem 上的 mv 具備 atomic 特性。¹⁷

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

State corruption recovery。 如果 state 損毀，recovery pattern 會從安全預設值重建，而不是直接 crash：¹⁶

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 trap。 ((VAR++)) 在 VAR 為 0 時會回傳 exit code 1，因為 0++ 會求值為 0，而 bash 會將其視為 false。啟用 set -e 時，這會讓 script 終止。請改用 VAR=$((VAR + 1))。¹⁶

Blast Radius Classification

依 blast radius 為每個 agent action 分類，並據此 gate：²

Remote Control（從任何 browser 或 mobile app 連線到本機 Claude Code）會把「External」gate 從阻塞等待變成 async notification。當您用手機 review 前一項任務時，agent 仍會繼續處理下一項任務。²

Autonomous Runs 的 Task Specification

有效的 autonomous tasks 包含三個元素：objective、completion criteria 與 context pointers：¹⁶

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

Criteria 必須可由機器驗證：test pass/fail、linter output、HTTP status codes、file existence checks。早期有個任務要求 agent「write tests that pass」，結果產生了 assert True 和 assert 1 == 1。技術上正確。實務上毫無價值。¹⁶

需要留意的 Failure Modes

一段具體的 Session Trace

以下是一段 autonomous run 的 session trace，該執行處理一個含 5 個 stories 的 PRD：²

1. SessionStart 觸發。 Dispatcher 注入：current date、project detection、philosophy constraints、cost tracking initialization。共 5 個 hooks，總計 180ms。

2. Agent 讀取 PRD，規劃第一個 story。 UserPromptSubmit 觸發。Dispatcher 注入：active project context、session drift baseline。

3. Agent 呼叫 Bash 執行 tests。 PreToolUse:Bash 觸發。Credentials check、sandbox validation、project detection。90ms。Tests 執行。PostToolUse:Bash 觸發：activity heartbeat logged、drift check。

4. Agent 呼叫 Write 建立檔案。 PreToolUse:Write 觸發：file scope check。PostToolUse:Write 觸發：lint check、commit tracking。

5. Agent 完成 story。 Stop 觸發。Quality gate 檢查：agent 是否引用 evidence？是否有 hedging language？diff 中是否有 TODO comments？若任何檢查失敗，exit 2，agent 會繼續。

6. Independent verification： 一個 fresh agent 執行 test suite，不信任前一個 agent 的 self-report。

7. 3 個 code review agents 平行 spawn。 各自獨立 review diff。若任何 reviewer 標記 CRITICAL，該 story 會回到 queue。

8. Story 通過。下一個 story 載入。 這個 cycle 會為全部 5 個 stories 重複執行。

5 個 stories 總共觸發約 340 個 hooks。Hooks 總耗時約 12 秒。這些 overhead 在單次 overnight run 中阻止了 3 次 credential leaks、1 個 destructive command，以及 2 個 incomplete implementations。

Case Study：Overnight PRD Processing

一個 production harness 在 8 次 overnight sessions 中處理了 12 個 PRDs（47 個 stories）。Metrics 比較前 4 個 PRDs（minimal harness：僅 CLAUDE.md）與後 8 個（full harness：hooks、skills、quality gates、multi-agent review）。

兩次 credential leaks 需要輪替 API keys 並稽核 downstream services：約 4 小時的 incident response。防止同等事件所需的 harness overhead，是每個 story 2.4 秒的 bash。False completion rate 從 35% 降到 4%，原因是 Stop hook 會在允許 agent 回報完成前，獨立執行 tests。

安全性考量

可信任 Agent 的五大原則（Anthropic，2026年4月）

Anthropic 於2026年4月9日發布了 Agent 可信任性的正式框架。²⁷這五項原則與本指南中的 Evidence Gate 思維相呼應，並進一步延伸：

Anthropic 也將 MCP 捐贈給 Linux Foundation 的 Agentic AI Foundation，並加入 AGENTS.md（目前由 OpenAI、Google、Cursor、Factory、Sourcegraph 共同維護）。Agent 互通性標準如今已成為供應商中立。²⁷

Skill sandbox tooling：對於將 skills 視為攻擊面的團隊，Permiso 的 SandyClaw（2026年4月2日推出）會在專用 sandbox 中執行 skills，並提供由 Sigma/YARA/Nova/Snort 偵測支援、有證據依據的判定。這是 skill-sandbox 類別中的首款產品。²⁸

Sandbox

Claude Code 支援選用的 sandbox 模式（透過 settings.json 或 /sandbox 指令啟用），使用作業系統層級隔離（macOS 上的 seatbelt、Linux 上的 bubblewrap）限制網路存取與檔案系統操作。啟用後，sandbox 會防止模型任意發出網路請求，或存取專案目錄外的檔案。若未使用 sandbox，Claude Code 則採用權限式模型，由您核准或拒絕個別 tool calls。¹³

2026年5月安全底線。Claude Code v2.1.149 修復了 PowerShell 工作目錄權限繞過、多個 PowerShell allow-rule 與 stale-variable 權限分析缺口，以及 git-worktree sandbox 寫入 allowlist 錯誤；該錯誤涵蓋整個主要 repository root，而不只是共用的 git internals。⁵³如果您的 harness 允許 PowerShell 或 worktree-isolated agents，請將 v2.1.149+ 視為底線，並保持 shell rules 嚴格。寬泛的 PowerShell(*) 與整個 repo 的寫入例外，是 orchestration 捷徑，不是安全邊界。

OpenAI Agents SDK sandbox lockdown（v0.17.0，2026年5月8日）。在 OpenAI 端，openai-agents-python v0.17.0 收緊了一個平行邊界：LocalFile.src 與 LocalDir.src 現在被限制在 materialization base_dir 內（套用 manifest 時 SDK process 的目前工作目錄），除非來源透過 Manifest.extra_path_grants 搭配 SandboxPathGrant 明確授權。⁴¹相對本機來源會從 base_dir 解析；絕對路徑必須已位於其中，或附帶 grant。這關閉了一個本機 artifact 邊界問題：舊版本允許 manifests 將任意 host paths 拉入 sandbox workspace。遷移方式：在 manifest 層級使用 SandboxPathGrant(path=..., read_only=True) 宣告可信任 host roots，以供唯讀掛載。請將 extra_path_grants 視為可信任的應用程式設定；切勿從模型輸出或不可信任的 manifest input 填入 grants。

OpenAI Agents SDK 後續底線（v0.17.3）。0.17.1-0.17.3 系列加入更多 sandbox 與 session 強化：archive extraction limits、GitRepo subpath validation、更清楚的 sandbox-provider errors、mountpoint credentials 不進入 sandbox commands、拒絕相對 sandbox workspace roots，以及 Vercel-sandbox terminal-state handling。⁵⁴如果您使用的是 OpenAI-hosted 或 provider-backed sandboxes，而不只是 Claude Code hooks，請將 0.17.3 視為本節模式的目前底線。

權限邊界

權限系統會在多個層級管控操作：

參數層級權限規則（2026年6月）

Claude Code v2.1.178 將權限規則從工具層級延伸到參數層級：Tool(param:value) 會比對工具的輸入參數，並以 * 作為萬用字元。標準範例是 Agent(model:opus)，這條規則會阻擋 subagents 在特定 model tier 上產生。⁶³從架構上看，這補上了上方四層表格無法表達的缺口：過去您只能整體允許或拒絕某個工具，卻無法約束它被如何呼叫。如今治理政策可以用確定性規則表達「subagents 可以產生，但不可使用 Fable 5 tier」或「允許 Bash，但不可帶此 flag」，而不必仰賴 prompt 層級請求。

配套的 managed setting enforceAvailableModels（v2.1.175）則由上而下限制模型選擇：它會固定 Default model，並防止使用者或專案範圍設定擴大 managed availableModels allowlist。⁶³兩者相輔相成：allowlist 定義 session 中實際存在的 tiers，而參數層級規則則限制 subagents 如何從中取用。

Auto-Mode 破壞性指令防護欄（2026年6月）

Claude Code v2.1.183 收窄了 auto mode 對於會悄悄遺失工作或拆除環境的操作所造成的爆炸半徑。除非您在 session 中明確要求，auto mode 現在會硬性阻擋：破壞性 git 操作（git reset --hard、git checkout -- .、git clean -fd、git stash drop）；在該 commit 不是 agent 於本 session 建立時執行 git commit --amend；以及基礎設施拆除（terraform destroy、pulumi destroy、cdk destroy），除非您指定了特定 stack。⁶⁵從架構上看，這是上述 spawn-vetting 與參數層級規則的補足：它管控的不是哪個工具或它如何產生，而是依據意圖管控一小組特定不可逆指令。agent 仍可執行它們，但只能在明確指示下執行，不能自行發起。對於自主式 harness，請在自己的 PreToolUse hooks 中編碼相同原則：會摧毀狀態的指令應採 deny-by-default 規則，只有明確的操作者訊號才能解除。

Prompt Injection 防禦

Skills 與 hooks 針對 prompt injection 提供縱深防禦：

帶有工具限制的 skills可防止遭入侵的 prompt 取得寫入權限：

allowed-tools: Read, Grep, Glob

PreToolUse hooks會驗證每個 tool call，不受模型如何被提示影響：

# 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 即使 prompt 遭入侵，也無法做出變更。

Agent Logs 與 Guardrails 都是安全面

2026年5月的兩則公告強化了一個模式：agent infrastructure 會創造敏感內容與可執行政策外洩或逃逸的新位置。GitHub Advisory GHSA-f3jg-756w-gm35 涵蓋 Gryph Agents 的 payload-filter 問題，在預設記錄行為下，敏感的 tool-payload content 可能留存在本機 SQLite logs 中。⁴⁵OSV GHSA-wxxx-gvqv-xp7p 則涵蓋 LiteLLM custom-code guardrail 在受管理員保護的 proxy endpoint 中發生 sandbox escape。⁴⁶

正式環境規則是：將 agent transcripts、tool payloads、SQLite logs 與 guardrail execution 視為敏感基礎設施。持久化前先遮蔽、套用保留期限，並確保 custom guardrail code 受到 sandbox 保護且可審查。prompt 層級的「不要記錄 secrets」規則並不足夠；logging 與 guardrail path 需要確定性測試。

Hook 安全性

若 HTTP hooks 會將環境變數插入 headers，必須有明確的 allowedEnvVars 清單，避免任意環境變數遭外洩：¹³

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

人類與 Agent 的責任分工

Agent 架構中的安全性需要清楚劃分人類與 agent 的責任：¹⁷

模式是：需要組織脈絡、倫理判斷或策略方向的決策，由人類負責。需要在大型可能性空間中進行計算搜尋的決策，由 agents 負責。Hooks 負責強制維持這條邊界。

遞迴 Hook 強制執行

Hooks 也會在 subagent 動作時觸發。¹³如果 Claude 透過 Agent tool 產生 subagent，您的 PreToolUse 與 PostToolUse hooks 會針對 subagent 使用的每個工具執行。若沒有遞迴 hook 強制執行，subagent 就可能繞過您的安全閘門。SubagentStop 事件讓您能在 subagent 完成時執行清理或驗證。

這不是選配。若 agent 產生的 subagent 沒有套用您的 security hooks，那個 agent 就能在您的閘門只看著主對話無所作為時，force-push 到 main、讀取 credential files，或執行破壞性指令。

成本即架構

成本是一項架構決策，不是營運上的事後補救。²分為三個層級：

Token 層級。System prompt compression。移除教學式程式碼範例（模型知道 APIs）、合併跨檔案的重複規則，並以約束取代解釋。「拒絕符合敏感路徑的 tool calls」與一段 15 行說明為何不應讀取 credentials 的文字，能完成同樣工作。

Agent 層級。以 fresh spawns 取代長對話。自主執行中的每個 story 都會取得一個具備乾淨脈絡的新 agent。由於每個 agent 都從頭開始，脈絡不會膨脹。以 briefing 取代 memory：模型執行清楚 briefing 的效果，勝過在累積 30 步的脈絡中摸索。

架構層級。當操作是無狀態時，優先採用 CLI，而不是 MCP。針對一次性評估呼叫 claude --print 成本較低，且不增加連線開銷。當工具需要持久狀態或串流時，MCP 才合理。

決策框架

何時使用各機制：

Skills vs Hooks vs Subagents

FAQ

hooks 到底多少才算太多？

限制在於效能，而不是數量。每個 hook 都會同步執行，因此 hook 總執行時間會加到每次相符的 tool call 上。若每個 hook 都能在 200ms 內完成，即使 user-level 與 project-level settings 合計有 95 個 hooks，也不會有明顯延遲。需要留意的門檻是：如果某個 PostToolUse hook 讓每次檔案編輯多出超過 500ms，session 就會開始顯得遲鈍。部署前，請先用 time profile 您的 hooks。¹⁴

hooks 可以阻止 Claude Code 執行命令嗎？

可以。PreToolUse hooks 只要以 code 2 結束，就能封鎖任何 tool action。Claude Code 會取消待處理的 action，並把 hook 的 stderr output 顯示給模型。Claude 會看到拒絕原因，並建議更安全的替代方案。Exit 1 則是非阻塞警告，action 仍會繼續執行。³

hook 設定檔應該放在哪裡？

hook 設定放在 .claude/settings.json 可作為 project-level hooks（commit 到 repository，與團隊共享），或放在 ~/.claude/settings.json 作為 user-level hooks（個人使用，套用到每個專案）。兩者同時存在時，project-level hooks 優先。script 檔案請使用絕對路徑，避免 working directory 造成問題。¹⁴

每個決策都需要 deliberation 嗎？

不需要。confidence module 會從 4 個維度為決策評分（歧義度、複雜度、風險、context dependency）。只有整體信心分數低於 0.70 的決策才會觸發 deliberation，約占總決策的 10%。文件修正、變數重新命名與例行編輯會完全略過 deliberation。安全性架構、資料庫 schema 變更，以及不可逆部署則會穩定觸發。⁷

如何測試一個設計來產生分歧的系統？

成功路徑與失敗路徑都要測。成功：agents 有建設性地分歧，並達成共識。失敗：agents 太快收斂、永遠無法收斂，或超過 spawn 預算。End-to-end tests 會用確定性的 agent responses 模擬每種情境，驗證兩道 validation gates 都能捕捉每個已記錄的 failure mode。production deliberation system 會在 3 層執行 141 項 tests：48 個 bash integration tests、81 個 Python unit tests，以及 12 個 end-to-end pipeline simulations。⁷

deliberation 對延遲有什麼影響？

3-agent deliberation 會增加 30-60 秒的實際等待時間（agents 會透過 Agent tool 依序執行）。10-agent deliberation 會增加 2-4 分鐘。consensus 與 pride check hooks 各自在 200ms 內完成。主要瓶頸是每個 agent 的 LLM inference time，而不是 orchestration overhead。⁷

CLAUDE.md 檔案應該多長？

每個 section 保持在 50 行以內，整份檔案控制在 150 行內。太長的檔案會被 context windows 截斷，因此請把最關鍵的指示放在前面：命令與 closure definitions 應該早於風格偏好。²¹

這套方法能與 Claude Code 以外的工具搭配嗎？

這些架構原則（hooks 作為確定性 gates、skills 作為領域專業、subagents 作為隔離 contexts、檔案系統作為 memory）在概念上適用於任何 agentic system。具體實作使用 Claude Code 的 lifecycle events、matcher patterns 與 Agent tool。AGENTS.md 會把相同模式帶到 Codex、Cursor、Copilot、Amp 與 Windsurf。²¹ 即使實作細節取決於特定工具，harness pattern 本身仍是 tool-agnostic。

快速參考卡

Hook Configuration

{
  "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 Definition

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

Exit Codes

關鍵命令

檔案位置

變更記錄

參考資料