代理架構：打造 AI 驅動的開發框架

TL;DR： Claude Code不是具有檔案存取權的聊天視窗，而是具備31個已記錄生命週期事件的可程式化執行環境；每個事件都可掛接模型無法略過的Shell指令碼。將hooks堆疊為dispatchers、dispatchers堆疊為skills、skills堆疊為agents、agents堆疊為workflows，您便能建立一套自主開發harness：強制遵循約束、委派工作、跨工作階段保留記憶，並協調多代理人審議。Claude Code的動態workflows（v2.1.154+）讓確定性的多代理人協調成為第一方原生機制——透過/workflows執行數十到數百個背景agents——而平台現在預設會在背景執行subagents（20個並行、深度3層巢狀），讓您的工作階段能以對等身分彼此傳訊（v2.1.224），並可在自架runners上執行雲端工作階段。正確性仍由hooks與evidence gates掌握。⁵²⁵³⁸⁷本指南涵蓋該堆疊的每一層：從單一hook到10-agent共識系統。無須任何framework。全部以Bash與JSON完成。

Andrej Karpathy為圍繞LLMagent成長出的事物創造了一個詞：claws。也就是讓agent能夠抓住其context window之外世界的hooks、指令碼與協調機制。¹多數開發者將AI程式設計agents視為互動式助理：輸入prompt、看著它編輯檔案，然後繼續下一件事。這種框架會將生產力上限鎖定在您親自能監督的範圍內。

基礎設施的心智模型則不同：AI程式設計agent是具有LLMkernel的可程式化執行環境。模型採取的每項動作都會經過您所控制的hooks。您定義的是政策，而非prompts。模型在您的基礎設施內運作，就如同web伺服器在nginx規則中運作一般。您不會坐在nginx前手動輸入requests；您會設定、部署並監控它。

這個差異至關重要，因為基礎設施能產生複利效應。一個會攔截Bash指令中憑證的hook，能保護每個工作階段、每個agent及每次自主執行。一項編碼您評估準則的skill，無論由您或agent呼叫，都能一致套用。一個進行程式碼安全審查的agent，無論您是否在旁監看，都會執行相同的檢查。²

重點摘要

• Hooks能保證執行；prompts則不能。 對於linting、formatting、安全檢查，以及無論模型行為為何都必須每次執行的事項，請使用hooks。結束代碼2會阻擋動作；結束代碼1僅會提出警告。³
• Skills會編碼可自動啟用的領域專業知識。 description欄位決定一切。Claude使用LLM推理（而非關鍵字比對）來判斷何時應套用skill。⁴
• Subagents可避免context膨脹。 供探索與分析使用的隔離context windows，能讓主要工作階段保持精簡。讓彼此獨立的subagents平行執行；當workers需要持續協調時，則使用agent teams。⁵
• Memory存在檔案系統中。 檔案可跨context windows保留。CLAUDE.md、MEMORY.md、rules directories與handoff文件共同形成結構化的外部記憶系統。⁶
• 多代理人審議能發現盲點。 單一agents無法挑戰自身假設。兩個具備不同評估優先順序的獨立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        │
└──────────────────────────────────────────────────────────────┘

指令層：CLAUDE.md檔案與規則目錄定義代理對您專案的理解。它們會在工作階段啟動及每次壓縮後自動載入。這是代理的長期架構記憶。

擴充層：skills依據內容自動啟用，提供領域專業知識。hooks則在每次符合條件的工具呼叫時提供具確定性的關卡。記憶檔案會跨工作階段保留狀態。自訂代理提供專門的subagent設定。

協調層：多代理模式協調彼此獨立的代理進行研究、審查與研議。產生預算可防止遞迴失控。共識驗證確保品質。

關鍵洞見是：大多數使用者完全在核心層工作，看著內容膨脹、成本攀升。進階使用者會設定指令與擴充層，然後只使用核心層進行協調與最終決策。²

受管理與自建harness（2026年4月）

在2026年初的大部分時間裡，「自行建立harness」是唯一真正可行的途徑。2026年4月，情況改變了。Anthropic於4月8日以公開Beta版推出Claude Managed Agents：harness迴圈＋工具執行＋sandbox容器＋狀態持久化，透過REST API提供，按標準token費用加上每工作階段小時0.08美元計費。OpenAI於4月16日推出的Agents SDK更新，正式確立相同的區分方式——harness與運算為獨立層，並提供原生sandbox供應商（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、sandbox指令與capabilities；Manifest用於描述全新工作區合約（檔案、目錄、本機檔案、Git儲存庫、env、使用者、mount）；SandboxRunConfig則用於每次執行時設定sandbox client、即時工作階段注入、manifest覆寫、snapshots及materialization並行限制。內建capabilities涵蓋shell存取、檔案系統編輯、影像檢視、skills、sandbox memory與compaction。Sandbox memory會跨執行保存擷取出的經驗，並逐步揭露；工作區支援本機檔案、Git儲存庫項目及遠端mount（S3、R2、GCS、Azure Blob、S3 Files）；snapshots可跨供應商攜帶。後端包括UnixLocalSandboxClient、DockerSandboxClient，以及透過可選extras提供的Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop與Vercel託管client。²⁴

對於希望將Claude Code執行階段作為程式庫嵌入的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工具的CallToolResult回傳值，導致模型只收到驗證錯誤blob），並讓SandboxNetworkConfig與TypeScript SDK達成schema對等（allowedDomains、deniedDomains、allowManagedDomainsOnly、allowMachLookup）。³⁰截至2026-08-12，該套件在PyPI上的版本為v0.2.137，TypeScript SDK則為v0.3.229（兩者皆已根據即時registry驗證）；相較於本文所述的0.1.x介面，0.2.x系列屬於漸進式更新——下方的include_hook_events、skills與sandbox設定選項仍然適用——近期版本主要著重於subprocess清理與NDJSON串流可靠性。⁹⁰⁸⁶

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

2026年7月，OpenAI端的受管理選項也新增多代理方案：openai-agents-python v0.18.2（7月11日）與openai-agents-js v0.13.2（7月10日）在Beta版中新增hosted multi-agent support——由OpenAI託管、協調多個代理作為一項服務，直接對應Anthropic的Managed Multiagent Orchestration公開Beta版，詳見多代理協調章節。⁷³兩家供應商如今在多代理層提供與下表單一代理相同的取捨：供應商負責執行委派迴圈，而您放棄hook介面。

架構上的分岔如今已真實存在：

何時該選哪一種：對於已有基礎設施能力、想控制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可存放於4個位置，作用範圍由廣至窄如下：⁴

每個skill都需要一個含有YAMLfrontmatter的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會被注入系統提示中的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包含：它的功能（針對特定問題類型審查程式碼）、使用時機（檢視變更、PR、品質分析），以及使用者自然會輸入的觸發詞（review、audit、check）。

請注意，自動啟用是可調整的刻度，而非鐵則：自v2.1.215起，Claude不再自行呼叫內建的/verify與/code-reviewskills——它們僅會在明確呼叫時執行。這是刻意收回description驅動啟用的做法，因為未經提示就執行的重量級審查skills，成本高於其帶來的效益。⁷⁴

脈絡預算

所有skill descriptions共用一份脈絡預算，會依脈絡視窗的1%動態調整，並有8,000個字元的備援值。⁴若有許多skills，請保持每個description精簡，並將關鍵使用情境放在最前面。雖然可透過SLASH_COMMAND_TOOL_CHAR_BUDGET環境變數覆寫預算，¹¹但更好的解法是讓description更短、更精確。在工作階段中執行/context，確認是否有skills遭到排除。

支援檔案與組織方式

Skills可以參照同一資料夾中的額外檔案：

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

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

透過Git分享Skills

專案skills（儲存在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作為提示詞庫

除了單一用途的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會透過SessionStarthooks自動啟用，將品質限制注入每個工作階段，無須明確呼叫。skill本身是知識；hook則負責落實。兩者結合，即形成一層政策。

常見Skill錯誤

Description過於寬泛。若git-rebase-helperskill會在任何與git相關的提示上啟用（rebase、merge、cherry-pick，甚至git status），便會污染80%的工作階段。解法是收緊description，或加入disable-model-invocation: true並要求明確透過/skill-name呼叫。⁴

太多skills競爭預算。更多skills意味著更多descriptions要競爭1%的脈絡預算。若發現skills沒有啟用，請透過/context查看遭排除的項目。與其建立許多模糊的skills，不如優先保留較少但description寫得完善的skills。

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

SDKSkill介面（2026年5月8日）

使用claude-agent-sdk-pythonv0.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 Codev2.1.157將該資料夾延伸支援plugins：放置於.claude/skills/的plugin現在會自動載入，無須marketplace註冊；claude plugin init <name>也會在該處建立新的scaffold，並預先串接manifest與SKILL.md。⁵⁸這填補了兩種原本位於不同位置的專案工具型態之間的落差——直接提交至repo的裸skill，以及將skill、hooks與MCPserver打包在一起、但過去需透過marketplace安裝的plugin。對harness設計的實際影響是：專案範圍的工具不再需要繞經registry才能交付——寫好、提交後，團隊成員只要執行git pull就能取得相同介面。Plugins仍負責可打包安裝的使用情境（在單一ZIP中包含hooks、skills、MCPservers與agents）；改變的是，專案不必只為了從自身目錄樹載入plugin而建置marketplace。這項匯流如今也有跨供應商的基礎：Agent Plugins 1.0.0（於2026年8月6日發布）將相同套件結構標準化——plugin.jsonmanifest、包含SKILL.md資料夾的skills/目錄，以及可選的mcp.json——並稱其為「AI agents的可攜式套件格式」。發表時即獲VS Code、Cursor、GitHubCopilot、ChatGPT & Codex與Kiro採用。它明確是Agent Skills與MCP的封裝層，而非替代品；請注意，Agent Skills spec的作者Anthropic尚未加入聯盟——因此，應將Claude-Code向外的可攜性視為格式層級的相容性，而非官方雙向契約。⁸⁹

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

Skills代表能力，而能力就是攻擊面。Claude Codev2.1.169新增disableBundledSkills設定（以及對應的CLAUDE_CODE_DISABLE_BUNDLED_SKILLS環境變數），可將內建skills、workflows與內建slash commands完全從模型視野中隱藏。⁶⁰對於強化或受監管的harness而言，這是刻意縮減攻擊面的措施：已稽核並核准一組特定專案與個人skills的操作者，可以抑制Anthropic隨附的一切內容，使模型只會針對操作者審核過的介面進行推理。請以對待工具allowlist的方式看待它——預設提供廣泛能力，而關閉預設值是一項治理決策，不是便利性的切換鈕。

巢狀.claude/skills與最近者優先解析（2026年6月16日）

Claude Codev2.1.178讓專案工具具備位置感知能力。現在，當您處理該資料夾下的檔案時，巢狀.claude/skills資料夾中的skills也會載入，不再僅限repo根目錄；若名稱衝突，巢狀skill會顯示為<dir>:<name>，使兩者都能存取。⁶³同一版本也讓其餘專案介面依據最接近工作目錄的位置解析：當agent、workflow或output-style名稱在巢狀.claude/資料夾間衝突時，最接近工作目錄的項目優先；而儲存專案範圍workflow時，會寫入最近的既有.claude/workflows/，不再一律寫入根目錄。⁶³對monorepo或repo-of-repos而言，這讓原本單一扁平的全域介面，轉變為會隨情境啟用的每個package工具——services/api/.claude/skills/可承載僅在該目錄樹工作時出現的API專屬skills，而不會與同名的services/web/skill衝突。

Hook 架構

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

可用事件

截至本指南更新時，Claude Code在 8 個類別中提供 31 個已記錄的生命週期事件。事件清單會隨版本更新而增加，因此應以參考文件為準，並在串接正式環境 hooks前查看速查表，取得目前完整表格：¹³

DirectoryAdded（v2.1.219）補上工作階段中途工作區的缺口。自v2.1.152加入MessageDisplay以來，事件清單一直保持穩定；DirectoryAdded是自此之後首個新的生命週期事件，會在/add-dir——或SDK的register_repo_root控制請求——於工作階段中途註冊新工作目錄後觸發。⁸⁴它補上的確實是個缺口：在此之前，harness可以在SessionStart時完整驗證工作區，卻只能眼睜睜看著第二個儲存庫被接上，而完全沒有 hook觸發。任何在啟動時針對工作區所做的斷言——信任檢查、祕密掃描、由樹狀結構推導的路徑範圍規則、各儲存庫政策載入——都需要在此重新執行，因為工作階段的目錄集合不再於啟動時固定。此事件僅供資訊使用，無法阻擋；因此應將其視為重新推導狀態及記錄來源的觸發點，而非閘門。若某個目錄絕不能新增，應在設定中拒絕它，而非嘗試透過 hook否決。SDK端也在同一版本推出（TypeScript v0.3.219將DirectoryAdded加入控制協定生命週期事件），因此由SDK託管的 harness與CLI的 harness同樣能取得此事件。⁸⁵

結束代碼語意

結束代碼決定 hooks是否阻擋動作：³

Hook設定

Hooks位於設定檔中。專案層級（.claude/settings.json）用於共用 hooks。使用者層級（~/.claude/settings.json）用於個人 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_name值，例如Bash、Edit、Write、Read、Glob、Grep、像mcp__server__tool這類MCP工具名稱，或使用*涵蓋所有工具。單純名稱與以|分隔的清單會進行完全比對；含有其他字元的值則是JavaScript正規表示式。部分事件不支援 matcher，設定後一律觸發。¹³自Claude Code v2.1.195起，包含連字號識別碼（code-reviewer、mcp__brave-search）的 matcher會進行完全比對，不再意外進行子字串比對——指定給單一代理或伺服器的 hook不會再對所有僅包含該字串的名稱觸發；若要涵蓋來自帶連字號MCP伺服器的所有工具，請明確寫成模式mcp__brave-search__.*。⁶⁶v2.1.214也將相同原則套用至路徑模式：使用單一區段dir/**模式的 hook if:條件，現在只會比對<cwd>/dir，不會比對樹狀結構中任何名為dir的目錄——若確實要涵蓋任意深度，請寫成**/dir/**。⁷⁴如同v2.1.195的變更，這項修正以明確宣告的意圖取代意外擴大的範圍；請稽核任何曾悄悄依賴舊有任意深度行為的 hook條件。

Hook輸入／輸出協定

Hooks會透過 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 hooks可以輸出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 hooks會在每次檔案變更後執行格式化工具。模型輸出並不重要，因為格式化工具會將一切正規化。

{
  "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會檢查指令，並以結束代碼 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 hooks會執行 linter或測試套件，並在品質檢查失敗時阻擋提交：

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

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

Shell指令以外的 Hook類型

Claude Code支援 5 種 hook類型：¹³ 命令 hooks（type: "command"）會執行 shell 指令碼。速度快、具決定性，且不耗用 token。

MCP tool hooks（type: "mcp_tool"）會呼叫已連線 MCP 伺服器上的工具。當驗證邏輯已存在於 MCP 邊界之後，且不需要另行撰寫 shell 指令碼時，適合使用此類 hooks。

Prompt hooks（type: "prompt"）會向快速的 Claude 模型傳送單回合提示。模型會回傳 { "ok": true } 以允許，或回傳 { "ok": false, "reason": "..." } 以阻擋。適合用於 regex 無法表達的細緻評估。

Agent hooks（type: "agent"）會啟動可存取工具（Read、Grep、Glob）的 subagent，進行多回合驗證。這項功能仍屬實驗性；生產環境的閘門應優先使用 command hooks，僅在確實需要檢查實際檔案或測試輸出時才使用 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 輸入包含 subagent_type，讓共用 hook 能區分 security-reviewer 執行、explorer 或一般 worker，而無須從提示文字猜測。⁴⁹

HTTP hooks（type: "http"）會將事件的 JSON 輸入以 POST 請求傳送至 URL，並接收 JSON 回應。適用於 webhooks、外部通知服務或以 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
          }
        ]
      }
    ]
  }
}

非同步 Hooks

Hooks 可在背景執行，不會阻擋作業。針對通知與記錄等非關鍵操作，加入 async: true：¹³

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

通知、telemetry 與備份可使用 async。切勿將 async 用於格式化、驗證，或任何必須在下一項動作前完成的工作。

Dispatcher 優於獨立 Hooks

在同一事件上同時執行 7 個 hooks，並讓每個 hook 各自讀取 stdin，會造成競態條件。兩個 hooks 若同時寫入同一個 JSON 狀態檔，就可能截斷 JSON。所有解析該檔案的下游 hook 都會失效。²

解法是：每個事件設置一個 dispatcher，從快取的 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

偵錯 Hooks

以下 5 種技巧可用於偵錯無聲失敗的 hooks：¹⁴

1. 獨立測試指令碼。 透過範例 JSON 管線輸入：echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. 使用 stderr 輸出偵錯資訊。 結束碼 2 的 stderr 會作為錯誤訊息回傳給 Claude。非阻擋的 stderr（結束碼 1、3 等）只會在詳細模式（Ctrl+O）中顯示。
3. 留意 jq 失敗。 錯誤的 JSON 路徑會無聲回傳 null。請以真實工具輸入測試 jq 運算式。
4. 確認結束碼。 使用 exit 1 的 PreToolUse hook 看似正常運作，實際上完全沒有強制效果。
5. 保持 hooks 快速。 Hooks 會同步執行。所有 hooks 應控制在 2 秒內，理想情況是低於 500ms。

SDK 端 Hook 事件串流

基於 claude-agent-sdk-python（v0.1.74+，2026年5月6日）的自行託管 harness，現在可直接從訊息串流訂閱 hook 事件，而不必透過 shell 指令碼回呼。³⁶ 在 ClaudeAgentOptions 上設定 include_hook_events=True 後，HookEventMessage 物件（PreToolUse、PostToolUse、Stop 等）會與 assistant 訊息及工具結果從同一個 iterator 產生。這與 TypeScript SDK 的 includeHookEvents 選項相呼應；同次發布中，內建 CLI 也升級至 v2.1.129。

若您的 harness 已在 Python 中運作，並希望 hook 訊號與模型輸出處於相同控制流程，事件串流模式是合適選擇。對於組合多個工具、在 Claude Code 與 Codex 之間共用 hooks，或需要以結束碼語意進行阻擋的 harness，shell 指令碼 hook 合約（結束碼、stdin JSON、dispatchers）仍是正確的做法。

TypeScript SDK 在 2026年7月推出的系列版本（v0.3.205–v0.3.208），讓串流協定本身更具合約性。⁷⁰ 中斷現在會回傳具型別的收據：中斷會透過 still_queued UUID 確認哪些佇列訊息仍在等待，且 sessions 會在 system/init 中宣告 interrupt_receipt_v1 功能，讓協調器可區分「中斷已送達」與「中斷在已傳輸的訊息之後才發生」。command_lifecycle frames會針對每則訊息回報 queued／started／completed／cancelled／discarded——這是第一方首次解答「我送出的訊息後來怎麼了」，不再需要從 transcript 推論。另有較小的介面更新：用於 subagent 完成 payload 的 AgentToolCompletedOutput 型別，以及 canUseTool callbacks 現在可在沒有 updatedInput 欄位時回傳 {behavior: 'allow'}。

該系列中有一項是安全性底線，而非功能：v0.3.208 修正了呼叫端在 hook 等待期間中止，卻被轉換為 hook 成功的問題——這代表受 PreToolUse hook 閘控的工具，可能會在呼叫端中止後仍然執行。⁷⁰ 若您的 harness 將 SDK 端 hooks 作為權限閘門，並依賴中止來取消進行中的工作，請將 v0.3.208 視為最低版本；在此版本以下，「已中止」並不可靠地等同於「已阻擋」。Python v0.2.127（2026年7月24日）是當月第二個同類型的繞過問題——query() 在第一個 result frame 出現時便關閉 stdin，但背景 subagents 仍在執行，因此其 SDK-MCP 工具呼叫不僅因 "Stream closed" 失敗，還完全繞過了 PreToolUse hooks。⁸⁵ 請辨識並留意這種模式：SDK 端 hook 強制機制會在生命週期邊緣失效開放——中止、拆除、串流關閉——此時傳輸會在取得 hook 判定前終止；而且會無聲失敗，因為被繞過的 hook 看起來與核准操作的 hook 完全相同。請固定兩項 SDK 版本底線，並保留 shell-hook 層作為可證明的強制機制。

Effort 與 Session 來源資訊（2026年5月7日至8日）

Claude Code v2.1.132 與 v2.1.133 新增了兩項功能，讓 hooks 與 subprocesses 更能掌握其執行內容：³⁸³⁹

• hook 輸入中的 effort.level。 Hooks 現在可在同時含有 tool_input 與 session_id 的輸入中取得 effort.level JSON 欄位。同一數值也會匯出為 $CLAUDE_EFFORT 環境變數，因此 Bash 命令無須解析 JSON 即可讀取。可依 effort 層級調整 hook 成本：在 low 時略過昂貴驗證，在 xhigh 或 max 時執行完整安全性閘門。
• Bash subprocesses 的 CLAUDE_CODE_SESSION_ID 環境變數。 Bash 工具 subprocesses 現在可取得 hooks 所見的相同 session_id 值，並以 CLAUDE_CODE_SESSION_ID 公開。這補足了依 session 記錄狀態的工具之來源資訊缺口；過去這些工具無法將 subprocess 事件與 hook 事件建立關聯。

兩項訊號皆無須變更程式碼即可使用；忽略新欄位的既有 hooks 仍可正常運作。

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

Claude Code v2.1.136 為 auto mode 新增硬性拒絕層級，並修正了一組會影響長時間運行 harness 的 plugin 與 MCP 問題：⁴⁰ - settings.autoMode.hard_deny。無論使用者意圖或允許例外為何，Auto mode 分類器規則都會無條件封鎖。它位於既有的允許／拒絕比對器之上，是不可協商的治理槓桿。即使操作人員已在個人設定中核准較廣泛的類別，也應將絕不可覆寫的規則用於此處（強制推送至 main、含有祕密資訊的檔案、正式環境資料庫存取）。 - autoMode.classifyAllShell（v2.1.193）。預設情況下，auto-mode 分類器只會審查符合任意程式碼執行模式的 shell 指令。此設定會讓每一個 Bash／PowerShell 指令都通過分類器——這是受治理 harness 的最大涵蓋範圍立場——同一版本也會在逐字稿、toast 和 /permissions 中顯示拒絕原因，讓無聲封鎖成為可稽核的決策。Codex 在 v0.142.2 收緊了對應範圍：其安全分類器無法檢查的可執行 AST 區域，如出現在 PowerShell 指令中，現在需要核准，而不再悄然放行。⁶⁶ - Hook ask為分類器設定下限（v2.1.211）。hook 與 auto mode 的優先順序問題如今已有定論：回傳 ask 權限決策的 PreToolUse hook，會將最終結果限制在提示層級——auto mode 無法再將未沙箱化的 Bash 指令升級為允許。⁶⁹對受治理 harness 而言，這是缺失的保證層：hook 的 ask 是確定的人在迴路停止點，即使採取完全自動的權限立場仍然有效。對於希望由人員決策而非直接拒絕的作業，請使用 ask（不只是 exit-2 封鎖）。 - 分類器模型會在每個工作階段固定（v2.1.210）。auto-mode 分類器預設使用 Sonnet 5，並在整個工作階段內固定，因此在工作階段中途切換模型，不再改變進行權限分類的模型。⁶⁹分類一致性是一項治理特性；這消除了隱性的漂移來源。 - MCP伺服器不再於/clear後消失。設定於 .mcp.json、plugins 與 claude.ai connectors 的伺服器，過去在 VS Code extension、JetBrains plugin 與 Agent SDK 中執行 /clear 後，會悄然從作用中的集合移除。修正已於 v2.1.136 推出。若您遇過「MCP server X 在工作階段中途消失」，原因就在此。 - 並行重新整理時遺失MCP OAuth refresh token。使用多個遠端 MCP 伺服器的使用者不再需要每天重新驗證。先前並行的重新整理寫入會彼此覆寫。 - Plan mode 現在會正確封鎖檔案寫入。相符的 Edit(...) 允許規則曾繞過 plan-mode 寫入保護。如今無論允許規則為何，都會強制執行 Plan mode。 - Plugin Stop和UserPromptSubmit hooks 不再於工作階段中途失敗。快取清理會刪除執行中工作階段仍在使用的 plugin 版本檔案，尤其會使這兩個 hook event 失效。修正後會固定仍在使用的版本。 - plugin.json中的skills項目。設定 skills 曾隱藏 plugin 預設的 skills/ 資料夾。現在該項目能正確組合，而將其指向檔案路徑時會明確報錯，不再悄然失敗。 - CLAUDE_ENV_FILE SessionStart hook 環境變數過期。SessionStart hooks 透過 CLAUDE_ENV_FILE 匯出的變數，曾在 /resume 或 /clear 後過期。已在 v2.1.136 修正。工作階段現在會在這些事件時重新載入 env 檔案。

對治理 harness 而言，營運上值得關注的項目是 autoMode.hard_deny（新的槓桿）及 MCP 消失的修正（會破壞長時間工作階段的無聲失敗）。其餘皆屬改善使用體驗的清理工作。

結構化 Hook 引數與封鎖後繼續執行（2026年5月11日）

Claude Code v2.1.139 新增兩項對正式環境 harness 至關重要的 hook 細節：供指令 hooks 使用的 args: string[] exec 形式，以及供 PostToolUse hooks 使用的 continueOnBlock。⁴²⁴⁴當 hook 需要動態值或路徑預留位置時，建議使用 args。它會直接啟動指令而不經過 shell，避免一整類引號與注入錯誤。

當 PostToolUse hook 應將拒絕原因回饋給 Claude，並繼續當前回合而非結束流程時，請使用 continueOnBlock。應將其視為操作人員體驗功能，而非安全性繞過機制。封鎖閘門仍應阻止不安全的結果。

同一版本會將 CLAUDE_PROJECT_DIR 傳遞給 MCP stdio 伺服器，並允許 plugin 設定在指令中參照 ${CLAUDE_PROJECT_DIR}。⁴²MCP tools 應從該值解析相對於專案的路徑，而非依賴恰巧啟動伺服器的程序工作目錄。2026年7月初的版本（v2.1.203–v2.1.206）將相同原則延伸至通訊協定層：MCP roots/list 現在會包含工作階段的額外工作目錄，並在變更時發出 roots/list_changed 通知——因此遵守 MCP roots 的伺服器會追蹤實際的多目錄工作區形狀，而非假設只有單一專案目錄。⁶⁸

Claude Code v2.1.140 主要是為 harness 操作人員提供的可靠性版本：它修正 ConfigChange hooks 未在設定變更時觸發的問題，處理 disableAllHooks 與 allowManagedHooksOnly 在不同設定層級無法正確組合的邊界情況，並防止權限對話方塊曝露 hook 結果回傳的非預期環境變數。⁴⁹這讓本節既有的治理模式更加可靠；不需要新的 hook 架構。

Claude Code v2.1.141 新增 hook-output terminalSequence 欄位，可在沒有控制終端機時提供桌面通知、視窗標題與鈴聲。⁵⁰應將其視為操作人員訊號，而非強制執行機制。安全與品質閘門仍應透過正常的封鎖契約傳達失敗：結構化 hook output 加上可阻止不安全動作的 exit 行為。同一版本新增 claude agents --cwd <path>，用於將 Agent View 限定在單一目錄；也新增 CLAUDE_CODE_PLUGIN_PREFER_HTTPS，供缺少 GitHub SSH keys 的環境安裝 plugin，以及 ANTHROPIC_WORKSPACE_ID，供涵蓋多個 workspace 的 workload-identity federation 規則使用。⁵⁰這些是團隊 harness 的架構細節：更聚焦的操作檢視、更少 plugin 安裝假設，以及明確的企業 token 範圍。

Claude Code v2.1.142 對背景工作階段編排的重要性高於 hook 語意。⁵¹claude agents 現在可透過明確的目錄、設定、MCP、plugin、權限、模型與 effort flags 派送背景工作階段，而不必依賴 wrapper 狀態。該版本中，Fast mode 預設使用 Opus 4.7；對於經測量後依賴 Opus 4.6 行為的 harness，則可使用 CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 固定版本——截至 v2.1.219，Opus 4.7 已完全退出 fast mode，而 /fast 適用於 Opus 5 與 Opus 4.8。⁸⁴根層級 plugin SKILL.md 探索與 plugin 提供的 LSP 可見性，降低了封裝上的模糊性。針對 MCP_TOOL_TIMEOUT、既有背景工作階段 worktrees、daemon 睡眠／喚醒與升級後清理，以及 plugin 快取清理的修正，補齊了原本看似編排 bug 的可靠性缺口。

Stop-hook 引導、跨工作階段權限與 multi-agent v2（2026年6月）

6月初的4項變更，對 harness 與 multi-agent 設計至關重要。⁵⁹

Stop/SubagentStop hooks 新增引導通道。自 Claude Code v2.1.163 起，Stop 或 SubagentStop hook 可回傳 hookSpecificOutput.additionalContext，向 Claude 提供回饋並讓回合持續進行，而不會將回應標示為 hook error。在此之前，Stop hook 唯一真正的槓桿是 exit-2 封鎖；這看起來像錯誤，且會計入連續封鎖上限。對品質閘門 harness 而言，這是更乾淨的原語：偵測到「您說已完成，但測試仍失敗」的 Stop hook，現在可以注入「以下項目仍在失敗，請繼續」，而不是硬性封鎖。真正需要停止的情況請使用封鎖；「尚未完成，原因如下」則使用 additionalContext。

跨工作階段訊息不再攜帶借用的權限。v2.1.166 強化了多工作階段情境：透過另一個 Claude 工作階段的 SendMessage 轉送的訊息，不再攜帶來源使用者的權限，因此接收工作階段會拒絕轉送的權限請求，auto mode 也會封鎖這些請求。若您的編排讓 agents 彼此傳訊，應將傳入訊息視為不受信任的資料，而非已驗證的指令。這與安全性章節套用於 tool output 的原則相同，只是延伸至 inter-agent messaging。截至 v2.1.199，Claude Code 也會在兩個 agents 共用相同名稱而導致 SendMessage 路由錯誤時偵測並發出警告——這是對此權限邊界的可靠性補強，因為訊息送達錯誤的同名 agent，本身就是另一類編排 bug。 Sessions現在是同級的一等公民（v2.1.224+）。跨 session 訊息傳遞已從 relay 強化邁向完整功能面：SendMessage/ListAgents讓各個 session 能在您的 macOS/Linux 機器之間探索並互傳訊息；接收端則提供crossSessionInbound接受／保留／拒絕控制。而self-hosted runners讓Claude Code網頁與行動 session 能在您掌控的硬體上執行。就 harness 架構而言，這讓「一個 session」成為可定址節點：探索、傳入政策，以及前述權限邊界，如今都是平台原生機制，而非 mailbox scripts（Claude Code guide記錄了完整契約）。⁸⁷另有一項政策變化：auto mode將於2026年8月14日成為 Pro、Max 與 Team 方案的預設權限模式——若 harness 將 Manual mode 提示視為 human-in-the-loop 的最後防線，應明確釘選defaultMode，而非想當然耳。⁸⁷

模型韌性成為一等設定。fallbackModel設定現在可串接最多 3 個備援模型；當主要模型過載或無法使用時，會依序嘗試。遇到非預期、不可重試的API錯誤時，該 turn 也會使用備援模型自動重試一次。對長時間執行的自主 harness 而言，這能將短暫的主要模型中斷轉為平順降級，而非直接遺失一次執行。claude agents --json也新增了waitingFor欄位（v2.1.162），可顯示受阻背景 session 正在等待什麼，例如權限提示——對輪詢 agent 群的任何協調器而言，這是可觀測性的一大提升。

適用於 clean-room 治理與疑難排解的 safe mode。Claude Code v2.1.169 新增--safe-mode旗標（以及對應的CLAUDE_CODE_SAFE_MODE環境變數），可在停用所有自訂項目的狀態下一次啟動 session：CLAUDE.md、plugins、skills、hooks 及MCP servers。⁶⁰這正是 harness 的反面——刻意建立的 clean-room。它可用來回答每位操作人員終將面對的問題：「這個行為來自模型，還是來自我設定的某些東西？」當 hook 誤觸發、skill 在不該啟用時啟用，或MCP server 汙染 context 時，--safe-mode可提供一個已知為空的基準，供您進行差異比對。它也是一種治理原語：讓您在 harness 通常授予的持續權限一概不存在時執行裸模型；當您需要重現結果，且不希望任何操作人員定義的 scaffolding 影響它時，這點格外重要。

關於模型 tier 的說明。截至Claude Code v2.1.197（2026年6月30日），Claude Sonnet 5 已是新 session 隨附的預設模型——原生 1M context、促銷期間每 MTok $2/$10 的定價至 8 月 31 日——取代 Opus 4.8 成為開箱即用的選擇。本指南將Opus 5（claude-opus-5）視為建議的 agentic 預設模型：除非您有意選擇其他模型，否則應以它執行自主 harness；因為長期、高風險的 agent loop，正是 Opus 的推理深度值得其成本的場景。Opus 5 於2026年7月24日隨Claude Code v2.1.219 推出，成為新的預設 Opus——1M context、每 MTok $5/$25（與其取代的 Opus 4.8 價格相同），fast mode 為 $10/$50，速度約為預設速度的 2.5 倍——而Anthropic指出，它在 Frontier-Bench v0.1 的表現超過 Opus 4.8 的兩倍，且以一半成本達到與 Fable 5 的 CursorBench 3.2 分數相差 0.5% 以內的成績。⁸⁴⁹¹同樣價格、更強能力，而且Anthropic形容該模型「在驗證自身工作與謹慎迭代方面強得多」；對 harness 工作而言，這是難得不需要成本論證的升級，從 4.8 遷移只需變更 id。若工作對成本敏感或吞吐量需求高，而其速度與智慧的比例更具優勢，則可降用 Sonnet 5。Opus 之上還有Claude Fable 5（claude-fable-5），於2026年6月9日推出——這是一個新 tier，被描述為Anthropic最強大的模型；它是已安全化、可供一般用途的「Mythos-class」系統，且可透過Claude Code v2.1.170 的/model claude-fable-5選用。⁶⁰應審慎使用更高 tier，只在原始推理深度足以合理化其成本的決策上採用，而不是將它設為整個 agent 群的通用設定。Opus 5 切換還有兩項例行影響：Opus 4.7 已退出 fast mode（/fast現在適用於 Opus 5 與 Opus 4.8），而 auto-mode classifier 的 Fable-5 fallback——自 v2.1.176 起為「可用的最佳 Opus 模型」——現在會解析為 Opus 5。⁸⁴

Codex 推出了 multi-agent v2。Codex CLI v0.137.0 將 runtime 選擇保留在各個 thread 中，為 spawned agents 提供更乾淨的 follow-up 與 metadata 預設值（hide_spawn_agent_metadata現在預設為 true），並將原始 parent events 傳遞給 child listeners。其 subagent 模型維持明確設計：內建 default/worker/explorer agent types、以 TOML 定義的 custom agents，以及並行控制（agents.max_threads預設為 6，agents.max_depth預設為 1）。同一版本還新增 v1 skills extension，支援每 turn 的 skill-catalog 解析，以及新的 thread-start/turn-error lifecycle contributor events；在維持 kernel-sandbox 姿態作為預設邊界的同時，縮小了與Claude Code hook/skill 功能面的差距。接著 Codex v0.138.0–v0.139.0 針對 production 強化 multi-agent v2：agent 間的訊息 payload 現已加密；v2 agent config catalog 與 agent-residency LRU 用於管理哪些 agents 保持常駐；並行數則依active execution而非 spawned threads 計算，因此閒置 agents 不再占用 slot。⁶¹lifecycle API也更趨成熟——close_agent更名為interrupt_agent（v0.139.0），以反映它中斷的是執行中的 agent，而不只是關閉 handle——且由 subagent 觸發的MCP startup warnings，現在會維持在所屬 thread 範圍內，不再重複出現在 parent 的 transcript。⁶¹對任何建置 Codex 端 orchestration 的人而言，這些正是 demo 與 fleet 的分水嶺：加密的訊息傳輸、受限的常駐管理、按執行數計算的並行控制，以及不會越過 thread 邊界洩漏的 warnings。Codex v0.140.0 接著開啟跨tool的接點：/import可選擇性地從Claude Code匯入 setup、project config 與近期 chats 至 Codex，而 sessions 也變得可永久刪除（codex delete／/delete，並提供確認防護）。⁶⁴/import是官方首次承認操作人員會在 harness 之間移動——您為其中一個建立的設定，不再被困在那裡。

記憶與上下文

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

多回合崩解的三種機制

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

策略1：以 Filesystem 作為記憶

跨越上下文邊界時，最可靠的記憶存在於 filesystem 中。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 檔案會跨 sessions 記錄錯誤、決策與模式。當您發現 VAR 為0時，((VAR++)) 在 bash 搭配 set -e 會失敗，便將此情況記錄下來。3個 sessions 後，當您在 Python 遇到類似的整數邊界情況時，MEMORY.md 的項目便會帶出這個模式。¹⁵

Auto Memory（v2.1.32+）： Claude Code 會自動記錄並回想專案上下文。工作期間，Claude 會將觀察結果寫入 ~/.claude/projects/{project-path}/memory/MEMORY.md。Auto memory 會在 session 開始時，將前200行載入 system prompt。請維持精簡，並將詳細筆記連結至個別主題檔案。⁶ 自 v2.1.210 起，超過大小限制的 MEMORY.md 寫入會直接報錯，而非悄悄截斷⁶⁹——失敗會在寫入時顯現，而不是讓記憶項目無聲消失。若您的 harness 會自動寫入記憶，請處理該錯誤；這是平台告訴您檔案需要整理，而不是要您重試。

記憶整理優先於記憶容量（2026年5月）： 一篇近期探討 LLM-agent 協作的 arXiv preprint，將擴大的 recall 視為可能的失敗模式：在作者的實驗中，較長的可見歷史紀錄使28種模型遊戲設定中的18種協作表現下降。⁴⁸ 請將此視為設計警訊，而非已定論的法則。實務規則已足夠清楚：讓 MEMORY.md 保持精簡、連結至詳細資料，並在 handoffs 中放入可立即據以決策的摘要。原始逐字稿傾印、tool logs 與冗長 recall feeds 應放在可搜尋的儲存空間，而非自動置入目前的 prompt。

策略2：主動 Compaction

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

適合進行 compaction 的時機： - 完成明確的子任務後（功能完成、bug 修正） - 開始處理程式碼庫的新區域之前 - 當 Claude 開始重複或遺忘先前上下文時 - 密集 session 期間約每25至30分鐘

CLAUDE.md 中的自訂 compaction 指示：

# 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 切換至新的工作目錄。⁶⁰ 在此之前，變更目錄意味著必須開啟全新 session，並使用冷 cache。對於從一個 repository 轉向相鄰 repository 的長時間 session——這在 monorepo 與多服務工作中很常見——/cd 可在重新指向 filesystem context 的同時，保留昂貴的 cached prefix。

策略3：Session Handoffs

對於跨越多個 sessions 的任務，請建立能完整記錄狀態的 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：全新上下文迭代（Ralph Loop）

對於超過60至90分鐘的 sessions，請每次迭代啟動一個全新的 Claude instance。狀態透過 filesystem 持續保存，而非依賴對話記憶。每次迭代都可取得完整的 context budget：¹⁶

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

與單一長時間 session 比較：

Minute 0:   [fresh context]        -> productive
Minute 30:  [context filling]      -> somewhat productive
Minute 60:  [mostly consumed]      -> degraded
Minute 90:  [compaction pending]   -> significantly degraded
Minute 120: [compressed, lossy]    -> errors accumulate

每次迭代使用全新上下文的方法，會以15%至20%的 orient step 額外成本（讀取狀態檔案、掃描 git history），換取每次迭代完整的認知資源。¹⁶ 成本效益的判斷如下：少於60分鐘的 sessions 中，單一對話較有效率。超過90分鐘後，儘管存在額外成本，全新上下文仍可產生品質更高的輸出。

策略5：受管理的記憶整理（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 會將整理過的 memory entries 寫入 Managed Agents memory store，agent 會在 session 開始時讀取該記憶。對於混合自架 filesystem state 與 managed-side curation 的 harnesses，這兩種模式可以並存。

Dreaming 目前仍是 Research Preview，行為可能變動。上述記錄的 session-handoffs 與 CLAUDE.md 模式，仍是 self-hosted harnesses 的權威記憶機制。

反模式

只需要10行，卻讀取整份檔案。 讀取單一2,000行檔案會消耗15,000至20,000 tokens。使用行位移：Read file.py offset=100 limit=20 可節省絕大多數成本。¹⁵

在上下文中保留冗長的錯誤輸出。 完成 bug 除錯後，您的 context 中可能保留40多份失敗迭代的 stack traces。修正 bug 後執行一次 /compact，即可釋放這些無用負擔。

每次 session 開始時都讀取所有檔案。 讓 Claude Code 的 glob 與 grep tools 依需求找出相關檔案，可省下超過100,000 tokens 的不必要預先載入。¹⁵

Subagents 模式

Subagents 是專門化的 Claude 執行個體，可獨立處理複雜任務。多數 subagents 會從乾淨的 context 開始（不受主要對話干擾）；下文的 fork 類型則是例外，會刻意繼承所有內容。它們使用指定工具執行作業，並以摘要形式回傳結果。探索結果不會讓主要對話變得臃腫，只有結論會回傳。[⁠^5]

內建 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 中運作，取得完整且隔離的儲存庫副本：[⁠^5]

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

唯有邊界確實成立，隔離才稱得上隔離。 Claude Code v2.1.210 修正了一項錯誤：使用 worktree 隔離的 subagents 仍可能修改主要 checkout，而這正是此機制原本要防止的問題。[⁠^97] 若您將 isolation: worktree 視為安全邊界，而不只是便利功能，請將 v2.1.210 視為最低版本。另一方面，配套的權限變更則朝相反方向發展：自 v2.1.211 起，「always allow」規則會持續保留在儲存庫根目錄，並且跨越各個 worktrees，因此在某個 worktree 中接受的規則，也會套用到同一儲存庫的其他 worktrees。[⁠^97] 這對並行 worktree agents 而言相當便利，但也表示在拋棄式實驗中授予的允許權限，不會隨實驗結束而消失。授權時應著眼於整個儲存庫，而非只考慮眼前的 worktree。

v2.1.216 完成了最後一塊拼圖，讓 worktree 隔離從單純修正錯誤，提升至足以強制執行的等級。[⁠^102] v2.1.210 的修正可防止 worktree subagents 透過一般 git 呼叫修改主要 checkout，但 git 本身提供明確的重新導向方式，例如 git -C <path>、--git-dir，以及 GIT_DIR/GIT_WORK_TREE 環境變數；使用 worktree 隔離的 subagent 仍能藉此指向共用 checkout。如今，這些逃逸途徑已全數封閉。同一版本還修正了 worktree 工作階段偶爾進入其他專案殘留 worktree 的問題；阻止 workflow 與 scheduled-task 寫入作業跟隨置於 .claude、指向專案外部目標的 symlink；並讓 /rewind 拒絕跨越 symlinks 與 hard links。這 4 項修正的共通原則如出一轍：隔離邊界不僅要能防範預設行為，還必須能抵禦蓄意重新導向，例如覆寫 git 環境設定或植入 symlink。若 isolation: worktree 在您的 harness 中是安全邊界，而不只是便利功能，v2.1.216 才是新的最低版本。

並行 Subagents

對於不需要彼此協調的獨立研究任務，請使用並行 subagents：[⁠^5]

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

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

遞迴防護

若未限制 spawn，agents 會委派給其他 agents，而後者又繼續委派；每一層都會流失 context 並消耗 tokens。遞迴防護模式會強制落實預算：[⁠^16]

#!/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，仍然只是「深度 1」。spawn budget 會追蹤每個父項的活躍子項總數，並將其限制在可設定的上限內。預算模型對應真正的失敗模式（agents 總數過多），而不是替代指標（巢狀層級過多）。[⁠^7]

預設巢狀深度已變動 3 次；請勿以此作為設計基礎。 Claude Code v2.1.172（2026年6月10日）允許 sub-agents 產生自己的 sub-agents，最多可巢狀至 5 層；在此之前，委派實際上僅有 1 層。[⁠^90] 此設定從 v2.1.172 維持到 v2.1.216。v2.1.217（2026年7月21日）將其降至 1，預設關閉巢狀 spawn。接著，v2.1.219（2026年7月24日）取其中道：「Subagents 現在預設最多可產生深度 3 的巢狀 subagents（原為 1）；設定 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 可停用巢狀功能。」[⁠^112] 從 5 降至 1，再升至 3；後兩次變更更在短短 3 天內發生。

重點並不是其中任何一個數字才正確，而是平台仍在摸索合適的預設值。因此，讓 harness 照單全收「目前版本附帶的預設值」並非明智之舉。請將巢狀深度視為明確的預算項目：把 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 設為架構實際所需的深度；對多數 orchestration 而言，通常是 1 或 2。如此一來，升級就不會悄然改變 agent fleet 的委派深度。無論預設值如何反覆變動，核心論點始終不變：agents 委派給 agents 的鏈狀結構，消耗 context 與 tokens 的速度往往快於產生成果的速度。深度是一項必須編列預算因應的風險，而非值得追求的能力。無論下一次預設值如何漂移，上述遞迴防護都能避免深層樹狀結構擴散成數百個活躍 agents；唯有自行設定限制，才能確保下一版發布後，深度數字仍符合您的原意。

Auto mode 現在會在啟動前審查 spawn。 Claude Code v2.1.178 補上了相應的治理缺口：在 auto mode 中，subagent spawn 會在 subagent 啟動之前接受 permission classifier 評估，而非等到開始採取動作後才評估。[⁠^91] 過去可以產生 subagent，讓它要求執行父工作階段原本會遭封鎖的動作；spawn 本身因而成為繞過限制的手段。在 spawn 階段進行審查，表示遞迴防護與權限模型終於相互銜接：不能再將子項當成漂白步驟，用來執行政策禁止的動作。

平台現在內建原生 spawn budget。 Claude Code v2.1.212（2026年7月）新增第一方失控迴圈防護：每個工作階段預設最多可 spawn 200 個 subagents（使用 CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 調整，/clear 會重設計數器），WebSearch 每個工作階段也以 200 次呼叫為上限（CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION）。[⁠^97] 本節自 v1.0 起以 userland scripting 記錄的 spawn-budget 模式，如今已由平台原生提供，證明預算模型比深度模型更切合實際。然而，請留意其尺度：200 次 spawn 比上述設定中的 12-agent 預算高出一個數量級。原生上限是防止迴圈徹底失控的保險絲，而不是依照您的架構調校的預算。請保留 userland guard，用於實施每個父項的預算、追蹤深度，以及設定符合 orchestration 實際需求的限制；平台上限則負責攔下漏網之魚。

第一方 guardrail 現已涵蓋 4 個軸向。 其中 3 個正好支援本節 userland guard 所追蹤的項目：每個工作階段的 spawn 總數（v2.1.212，上限 200，CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION）、巢狀深度（CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH，目前預設為 3，且已證明並不穩定），以及同時執行數量（v2.1.217，預設 20，CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS；單一訊息再也無法無限制地擴散出背景 agents）。[⁠^106][⁠^112] v2.1.219 新增了 userland guards 通常不具備的第 4 個軸向：orchestration width，也就是單一已規劃 workflow 可包含的 agents 數量。預設指引為「以少於 15 個 agents 為目標」，並可透過任何 settings 檔案中的 workflowSizeGuideline 設定（詳見下方 Workflow Tool 一節）。spawn-budget 模式的每個原始設計軸向，如今都有平台機制支援，還多了一項原先未涵蓋的軸向。

尺度方面的提醒依然適用，但各項程度不一。200 次 spawn 與 20 個並行 agents 都屬於保險絲，其數量比上述設定中的 12-agent deliberation 預算高出一個數量級，目的是攔截失控迴圈，而非塑造架構。width guideline 則是第一個與實際預算位於同一尺度的原生數字：每個 workflow 15 個 agents，與本指南的 12 個相差無幾；採用平台預設幾乎不需付出代價，若不採用，也應有充分理由。請將 3 個保險絲設為您能合理辯護的值，並依照預期的 orchestration 結構設定 width guideline。

Agent Teams（Research Preview）

Agent Teams 會協調多個獨立運作的 Claude Code 執行個體。它們可透過共用 mailbox 與 task list 溝通，也能互相質疑彼此的發現：[⁠^5]

啟用方式：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

何時應使用 agent teams，何時應使用 subagents：

Agent View 與 Goal Loops（2026年5月）

Claude Code v2.1.139 新增了 Agent View。這項 research-preview 介面可透過 claude agents 啟動，並在單一畫面中顯示執行中、受阻及已完成的 Claude Code 工作階段。[⁠^70][⁠^71] 官方文件將其定位為可用來分派及管理多個工作階段、查看各工作階段的執行內容，並辨識哪些工作階段需要操作人員介入的工具。[⁠^71] 它為多 agent 工作提供了最終摘要無法取代的作業檢視能力。

推展 subagent 或 team 模式時，請使用 Agent View 檢查哪些工作階段受阻、哪些仍在執行，以及工作分配是否符合預期架構。但別把它當作品質證明。它提供的是 observability；工作是否可靠，仍須由測試、review gates 與 evidence reports 判定。

同一版本也新增了 /goal，可設定完成條件，並讓 Claude 跨越多個 turns 持續執行，直到條件達成；互動模式、-p 與 Remote Control 皆支援此功能。[⁠^70] 請將 /goal 視為工作階段層級的 completion loop，而非 deterministic gates 的替代品。它有助於讓 agent 專注於目標，但凡是失敗時必須阻擋流程的測試、citation checks、deploy checks 與 security hooks，仍應由命令或指令碼支援。

Workflow Tool（v2.1.147+）

Claude Code 的 dynamic workflows 已正式推出，且預設可用：自 v2.1.154 起，它可在背景協調數十至數百個 agents，並透過 /workflows 監控；v2.1.202 加入了「Dynamic workflow size」的 /config 控制項；v2.1.219 則加入 workflowSizeGuideline settings key，預設指引為 medium，也就是除非另有指示，否則以少於 15 個 agents 為目標。此功能早一版在 v2.1.147 首度登場，當時是預設關閉、須透過 CLAUDE_CODE_WORKFLOWS=1 啟用的 Workflow tool；如今該 flag 時代已成歷史，但它揭示的架構意義依然成立。[⁠^80] 對於過去必須仰賴自訂 dispatch scripts、mailbox state 與 subagent 協調慣例的流程，它為 Claude Code 提供了第一方 orchestration primitive。

請勿移除其周邊的 harness。Workflow 能組織執行流程，卻無法取代安全模型。應繼續以 PreToolUse 和 PostToolUse hooks 作為封鎖層，保留 spawn budgets 或 workflow step budgets 以避免寬度失控，讓 filesystem state 保持可稽核，並將最終 evidence reports 置於模型的自我評估之外。實務上，請使用 Workflow 定義 orchestration shape，並以 hooks、測試與 review gates 判定真實結果。

Dynamic workflows 現在對寬度提出了明確主張（v2.1.219）。 Dynamic workflows 的預設 size guideline 為 medium，也就是「以少於 15 個 agents 為目標」；Dynamic workflow size 的 /config 中另有其他大小及不設限選項，執行中的 workflow 狀態列也會顯示目前指引。[⁠^112] 此數字屬於建議而非強制限制；它會引導 planner，而不會封鎖過寬的計畫。值得設定的關鍵在於其傳遞機制：新的 workflowSizeGuideline settings key 可在任何 settings 檔案中設定，包括 managed settings 與 project settings；自 v0.3.219 起，它也已納入 TypeScript SDK settings types。因此，orchestration width 可以由團隊或組織統一規範，而不必讓每位操作人員各自重新摸索。[⁠^113] 請在專案層級設定此值，以反映程式碼庫實際的工作拆分方式。另有 2 項操作注意事項：當 settings 檔案正在控制該值時，/config 中的對應列會自動隱藏；此行為雖然正確，但若不明就裡，看起來會像設定項目遺失。此外，由於這項指引只會引導 planner，而不會阻止執行，因此它屬於形態欄，而非安全欄。寬度失控仍應由 spawn cap 負責防範。

值得保留的觀點是：這是第 4 個第一方 guardrail 軸向，也就是 orchestration width；另外 3 個則是 spawn count、nesting depth 與 concurrent execution。這也是 Anthropic 第一個按照合理工作規模校準，而非當作失控保險絲的軸向。每個 workflow 15 個 agents，與本指南自 v1.0 起採用的 12-agent deliberation 預算位於同一數量級。當平台預設與自訂預算從不同方向殊途同歸時，這幾乎已是此類數字所能得到最接近獨立驗證的結果。

Session Forking 與自動背景化的 MCP（2026年7月）

Claude Code v2.1.212 重塑了 2 項 orchestration primitives。[⁠^97] /fork 現在會依據目前的對話狀態建立新的背景工作階段；分叉後的執行線會獨立運作，原始工作階段則繼續處理其他工作。先前在同一工作階段內的行為已重新命名為 /subtask。這項區別對 orchestration 設計相當重要：/subtask 是單一工作階段生命週期內、範圍受限的支線任務；/fork 則能以低成本建立繼承完整 context 的並行背景工作階段，其性質更接近 Ralph-loop spawn，而非 subagent。若您的 harness scripts 原本假設 /fork 會留在同一工作階段內，如今它們將改為分派背景工作。

同一版本也會自動將緩慢的 MCP 呼叫轉入背景：執行超過 2 分鐘的 MCP tool call，會自動移至背景執行（可使用 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 調整門檻）。[⁠^97] 緩慢的 MCP 伺服器不再阻塞 agentic loop；然而，這也表示「工具已回傳」與「turn 已繼續」不再是同一事件。因此，原本假設 MCP 會同步完成的 hooks 或 scripts，應以工具結果為準，而不是 turn boundary。

針對 headless orchestration，v2.1.211 新增了 --forward-subagent-text（環境變數：CLAUDE_CODE_FORWARD_SUBAGENT_TEXT），可將 subagent assistant 文字轉送至 stream-json 輸出。[⁠^97] 讀取消費父項 stream 的 coordinator process，現在可直接觀察 subagent 進度，不必輪詢 transcripts 或等待最終摘要；這正好補足預設在背景執行的 subagents 所需的 observability。v2.1.219 更將支援範圍延伸至第 1 層之後：在深度 2 或更深處產生的 subagents，如今也會出現在轉送的 stream 中，並以產生它們的 Agent tool_use id 作為索引鍵。[⁠^112] 這個索引鍵才是值得作為設計基礎的部分。如今巢狀功能重新預設啟用，扁平的 subagent 文字 stream 會語意不明；該 id 能讓 coordinator 辨識哪個父項產生了哪個子項，從 stream 重建 delegation tree，而不必依賴推測。若您的 stream consumer 是依照單層 subagents 設計，現在將收到它從未預期存在的 agents 所輸出的文字；請依產生它們的 tool_use id 分組，而不要假設每一行轉送內容都來自直接子項。

多代理協作編排

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

跨工具編排（2026年4月）：Google於4月7日開源了Scion——一個多代理 hypervisor，可將Claude Code、Gemini CLI及其他「deep agents」作為並行程序執行；每個程序都有隔離的 container、git worktree與憑證。可在本機、hub或Kubernetes執行。其明確理念是：「isolation over constraints」——代理可在基礎設施層級強制執行的邊界內維持高度自主，而非受限於prompt。²⁵ 這直接將 subagent isolation 的論點延伸到不同工具供應商之間。若您的工作流程涵蓋Claude與OpenAI模型，Scion是首個具備每代理 worktree與憑證隔離的跨工具 subagents實際參考實作。

辯論並非萬靈丹：M3MAD-Bench研究群集（2026年初）發現，多代理辯論會停滯，且可能遭誤導性共識顛覆——當其他代理自信地斷言錯誤答案時，合理論點反而會落敗。²⁶ Tool-MAD透過為每個代理提供異質工具存取權，並在評審階段採用 Faithfulness/Relevance分數來改善此問題。若您正在建置辯論式編排，應投入於（a）每個代理的工具異質性，以及（b）量化的評審計分，而不是假設更多代理＝更好的答案。

受管多代理編排與Outcomes（公開測試版）

若不想自行建置下文所述的審議基礎設施，Multiagent Orchestration已於2026年5月6日在Claude Managed Agents進入公開測試版。³⁵ 根據Anthropic：「當單一代理無法妥善完成過多工作時，多代理編排讓主導代理可將工作拆分，並將每一部分委派給具備自身模型、prompt與工具的專家。」³⁵ 專家「會在共用檔案系統中並行工作，並為主導代理的整體 context作出貢獻。」³⁵

Tracing隨附提供。根據Anthropic：「您也可以在Claude Console中追蹤每一步：哪個代理做了什麼、依何順序、為什麼做，完整掌握工作如何被委派與執行。」³⁵

配套的公開測試功能是Outcomes。根據Anthropic：「您撰寫一份描述成功樣貌的 rubric，代理便會朝此目標努力。獨立的 grader會在自己的 context window中，依據您的標準評估輸出，因此不會受到代理推理影響。」³⁵ 這是本節後續記錄之雙閘門驗證模式的受管服務版本：rubric取代手寫 gate，獨立 grader取代共識驗證器。

當驗證必須整合自身 hook surface（PreToolUse阻擋、exit-code語意、自訂 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%的價值。其餘作法都只是漸進式改善。

信心觸發條件

並非每項工作都需要審議。信心計分模組會評估4個面向：¹⁷

1. 模糊性－查詢是否存在多種合理解讀？
2. 領域複雜度－是否需要專業知識？
3. 風險程度－決策是否可逆？
4. context相依性－是否需要理解更廣泛的系統？

分數對應至3個等級：

閾值會依工作類型調整。安全性決策需要0.85的共識；文件變更僅需0.50。這可避免為簡單工作過度設計，同時確保高風險決策受到審慎檢視。⁷

狀態機

共有7個階段，每個階段均以前一階段為閘門：⁷

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

RESEARCH：獨立代理研究主題。每個代理會獲得不同 persona（Technical Architect、Security Analyst、Performance Engineer等）。context isolation可確保代理在研究期間無法看見彼此的發現。

DELIBERATION：代理可看見所有研究發現，並提出替代方案。Debate代理辨識衝突；Synthesis代理整合不互相矛盾的發現。

RANKING：每個代理依5個加權面向，為每種建議方法計分：

雙閘門驗證架構

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

Gate 1：共識驗證（PostToolUse hook）。每個審議代理完成後立即執行： 1. 階段至少必須達到RANKING 2. 至少完成2個代理（可設定） 3. 共識分數須達到因應工作調整的閾值 4. 若有任何代理持異議，必須記錄其疑慮

Gate 2：Pride Check（Stop hook）。在 session可結束前執行： 1. 方法多元：必須涵蓋多個不同 persona 2. 衝突透明：異議必須記錄理由 3. 複雜度處理：至少產生2個替代方案 4. 共識信心：歸類為強（高於0.85）或中等（0.70-0.84） 5. 改善證據：最終信心高於初始信心

在不同生命週期節點使用兩個 hooks，符合失敗實際發生的方式：有些問題立即顯現（分數不佳），有些則逐漸累積（多樣性不足、缺少異議文件）。⁷

為何一致意見很危險

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分以內，表示可能是共用 context遭污染，而非獨立評估。當5個代理評估驗證重構時，全部將安全風險評為7.1至7.4；以全新的 context isolation重新執行後，分數分布擴展至5.8-8.9。

制式異議：代理複製彼此的疑慮措辭，而非產生獨立反對意見。

缺少少數觀點：具有衝突優先事項的 persona一致核准（Security Analyst與Performance Engineer很少會在所有事情上意見相同）。

一致性偵測器能抓到明顯案例（約10-15%的審議中，代理過快趨於一致）。其餘85-90%的情況，則由共識與pride check閘門提供足夠驗證。

審議中未奏效的作法

自由形式的辯論回合。針對資料庫索引討論進行3輪來回文字辯論，產生了7,500個 Token的辯論。第1輪：真正的歧見。第2輪：重述立場。第3輪：用不同文字重複相同論點。結構化面向計分取代自由辯論後，成本降低60%，排名品質也隨之提升。⁷

單一驗證閘門。第一個實作僅在 session結束時執行一個驗證 hook。某代理以0.52共識分數（低於閾值）完成審議後，仍持續處理不相關工作20分鐘，直到 session-end hook才標示該失敗。拆分為兩個閘門（工作完成時一個、session結束時一個）後，可在不同生命週期節點捕捉相同問題。⁷

審議成本

每個研究代理約處理5,000個 Token的 context，並產生2,000-3,000個 Token的發現。使用3個代理時，每個決策會增加15,000-24,000個 Token；使用10個代理時，約為50,000-80,000個 Token。⁷

以目前Opus 5定價（每MTok $5/$25）計算，3代理審議約需$0.23-0.30；10代理審議約需$0.75-1.00。系統僅會在約10%的決策上觸發審議，因此平均分攤至所有決策的成本為每個 session $0.08-0.10。（較早版本引用的數字為此處3倍，係以舊版$15/$75 Opus 4.x定價計算。）這是否值得，取決於錯誤決策的代價。

何時應進行審議

CLAUDE.md 設計

CLAUDE.md 是 AI agent 的操作政策，而非供人閱讀的 README。²¹ Agent 不需要理解您為何採用 conventional commits，只需要知道該執行的確切命令，以及何謂「完成」。

優先順序層級

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

哪些內容會被忽略

下列模式確實不會對 agent 行為產生可觀察的改變：²¹

沒有命令的敘述段落。「我們重視簡潔且經過充分測試的程式碼」只是說明文件，不是操作指令。Agent 讀完後仍會繼續撰寫未經測試的程式碼，因為其中沒有可執行的指示。

模稜兩可的指示。「處理資料庫遷移時務必謹慎」並不構成限制。「套用遷移前執行 alembic check。若缺少降版路徑，立即中止。」才算明確。

彼此矛盾的優先事項。「快速推進並儘速發布」加上「確保全面的測試涵蓋率」、加上「將執行時間控制在 5 分鐘內」、再加上「每次 commit 前執行完整整合測試」。Agent 無法同時滿足這 4 項要求，最後通常會直接略過驗證。²¹

缺乏強制機制的風格指南。只要求「遵循 Google Python 風格指南」，卻沒有 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。自 2026年7月初發布的版本（v2.1.203–v2.1.206）起，/doctor 會分析 CLAUDE.md，並建議刪減模型可自行從程式碼庫推導的內容，例如重述的目錄配置、程式碼已呈現的框架慣例，以及與套件指令碼重複的命令清單。⁶⁸ 這是第一方對本節主張的印證：只有記錄 agent 無法自行推斷的資訊（政策、門檻、完成條件定義），指示所占用的 token 才有價值，而非重複它能從磁碟讀取的內容。CLAUDE.md 大幅擴充後，請執行 /doctor，並將其刪減建議視為起點；但若它將關鍵操作規則標示為「可推導」，仍應予以保留，因為這些是不可或缺的限制，而非單純描述。

檔案匯入

在 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 工作流程。³³³⁴

Codex v0.138.0–v0.139.0 強化了非簡單工作區中的 AGENTS.md 探索機制：現在會透過環境的檔案系統抽象層載入，並在探索走訪期間保留邏輯路徑。因此，即使工作區位於遠端檔案系統或採用符號連結目錄樹，也能選取正確的檔案。⁶¹ 當規範來源 AGENTS.md 具備最高權威，而 agent 又是在掛載、由容器具現化或使用符號連結的 checkout 上運作時，這項改進至關重要。若只是單純走訪路徑，這些情況可能會悄然選錯指示檔案，甚至完全找不到檔案。若您在多項服務之間同步單一權威 AGENTS.md，至少應採用此版本，才能信任 agent 實際載入的檔案正是您撰寫的那一份。

隨後，Codex v0.141.0 進一步強化遠端執行路徑：遠端執行器現在會透過經過驗證、端對端加密的 Noise-relay 通道連線（控制平面與執行器不再需要信任兩者之間的 relay）；跨平台遠端執行會保留執行器的原生工作目錄與 shell；TLS 也接受企業 Proxy 的 P-521 憑證簽章。⁶⁵ 若您的 orchestration 會驅動 Codex 執行器跨越網路邊界，這代表架構已從「必須信任 relay」轉變為「端對端加密」。任何遠端執行器拓撲都應以此版本作為基準。

2026年7月的版本脈絡顯示，兩套 runtime 正從不同方向逐步匯聚至相同的基礎機制。⁷² Codex v0.143.0 預設讓 MCP 工具透過 tool search 載入：工具 schema 不再預先塞入 context，而是延後至有需要時才擷取。這與 Claude Code 透過 ToolSearch 介面提供的延遲工具載入模式相同；當 MCP 工具數量龐大、造成 context 膨脹時，這也是兩套 runtime 的正確解法。Codex v0.144.0 新增 writes 應用程式核准模式：唯讀操作不經提示即可執行，寫入操作則必須取得核准。這是在唯讀與自動核准之間真正新增的權限模式基礎機制，而 Claude Code 的模式清單並無直接對應項目（最接近的是 plan 模式，但它會完全封鎖寫入，而非逐次提示核准）。同一版本也讓 MCP 互動式驗證正式進入 GA。v0.144.5 則擴大了危險命令偵測範圍，呼應 Claude Code 在 v2.1.183 與 v2.1.208 推出的破壞性命令防護機制。對跨 runtime 的 harness 設計而言，匯聚才是重點：延遲工具載入、分級寫入核准，以及意圖層級的危險命令攔截，正逐漸成為基本配備，而非供應商之間的差異化功能。

Codex v0.145.0 在兩方面進一步推動這項匯聚。⁷⁶ 選用的 multi-agent V2 介面已趨於穩定：現在可設定 sub-agent 模型、推理層級與並行數量，先前移除的 agent 角色也已恢復。這是 Codex 對 .claude/agents/ frontmatter 中逐一設定 subagent 模型與工作強度的回應。此外，/import 已發展為完整的跨 harness 遷移功能：除了 v0.140.0 推出的 Claude Code 設定匯入，現在還能遷移 Claude Code 與 Cursor 的設定，包括 MCP 伺服器、plugins、sessions、commands，以及專案範圍的 memories。對同時使用兩套 runtime 的團隊而言，兩者之間單向遷移的成本持續下降；您在 Claude Code 建立的 harness 層（伺服器、作為 commands 的 skills、memory）日益成為可攜式狀態，而非供應商綁定。

實務對應關係如下：

重要差異在於：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 說明您的建置命令。若無法逐字重現，表示指示不是過於冗長（內容被擠出 context）、過於含糊（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 effort 層級：與 Opus 4.7 一同推出，現在由目前的 Opus 模型支援（Opus 4.8 在 v2.1.154 中以 /effort xhigh 推出；Opus 5 亦沿用）。介於 high 與 max 之間。建議作為程式開發與 agentic 工作負載的預設值。對長時間執行的 subagents 而言，xhigh 的表現明顯優於 high，而 token 成本增幅低於比例。max 仍適合一次性的高難度推理；持續性任務則以 xhigh 更佳。
• Token 預算上限：可透過 output_config.task_budget（beta header task-budgets-2026-03-13）為每次 agent 執行設定。模型會看見持續倒數的計時，並依預算妥善縮限工作範圍，而非意外耗盡資源。適用於希望 token 支出可預期、又不犧牲短提示品質的 agentic 迴圈。
• 隱含需求辨識：首個通過「implicit-need」測試的 Claude 模型——能辨識使用者字面要求未充分描述其實際需求的情況。這讓 CLAUDE.md 的「澄清規則」章節不再那麼必要。若您的 CLAUDE.md 有 200 行「使用者要求 Y 時，也要考量 X」這類防護規則，請刪減目前已由原生能力涵蓋的部分。

Worktree Base、Sandbox Paths 與管理員設定（2026年5月7日）

Claude Code v2.1.133 新增了 4 項值得在正式環境 harness 中留意的管理員層級設定：³⁹

worktree.baseRef 的回復是應提醒使用者的一點：仰賴 v2.1.128-v2.1.132 行為（worktree 從本機 HEAD 建立分支）的 agents，除非重新選擇加入，否則會在新的 worktree 中失去未 push 工作的存取權。

企業可觀測性的 OTel 回饋問卷（2026年5月8日）

Claude Code v2.1.136 新增 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL，讓企業可重新啟用工作階段內的品質問卷，並透過 OpenTelemetry 擷取回覆。⁴⁰若組織將 OTel 事件匯入中央可觀測性平台，這個環境變數會讓問卷重新進入資料路徑，使品質訊號透過與延遲及錯誤指標相同的管線流動。應將其視為選用功能：預設會維持抑制問卷，這對未部署 OTel 的環境是正確做法。

企業啟動器與 MCP 規模效能（2026年7月）

v2.1.207 有兩項變更對正式環境部署很重要。⁶⁸CLAUDE_CODE_PROCESS_WRAPPER 讓受管理環境透過企業包裝二進位檔啟動 Claude Code 程序——這是端點 agents、啟動時政策檢查，以及每個程序都必須在指定監督程式下執行之環境的整合點。若企業先前以 shell aliases 或分支出的啟動器指令碼模擬此做法，現在已有受支援的銜接點。

同一版本也降低了 harness 最有感的執行階段額外負擔：在 MCP 工具數量很高的工作階段中，工具使用回合最高可快 7 倍，而工作階段逐字記錄可縮小 79 倍。⁶⁸這緩和了——但未推翻——將成本視為架構的指引：CLI-first 對無狀態的一次性作業仍然最具優勢，但攜帶數十個 MCP 工具的 harness，不再承受春季時每回合的代價，逐字記錄儲存也不再是長時間自主執行的隱性成本。

品質迴圈

所有非瑣碎變更都必須遵循的審查流程：

1. 實作 - 撰寫程式碼
2. 審查 - 重新閱讀每一行。找出拼字錯誤、邏輯錯誤與不清楚的段落
3. 評估 - 執行 evidence gate。檢查模式、邊界情況與測試涵蓋率
4. 精修 - 修正每一個問題。絕不延後到「之後」
5. 拉高視角 - 檢查整合點、import 與相鄰程式碼是否發生回歸
6. 重複 - 若任何 evidence gate 準則失敗，回到步驟 4
7. 報告 - 列出變更內容、驗證方式，並引用具體證據

Evidence Gate

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

若無法為任一列提出證據，請回到精修。²²

人類合併授權

一項於 2026年5月發布、分析 29,585 個 AI-agent pull-request 生命週期的 arXiv 研究，將作業自主性與合併治理區分開來。⁴⁷有用的架構啟示很簡單：agents 可以開始工作、持續推進分支、開啟 PR、審查工作並彙整風險，而合併授權仍是另一道治理邊界。

請在 harness 中明確劃定這道邊界。讓 agents 準備 PR 並蒐集證據；除非組織另有經稽核的自動化政策，否則合併、發行與破壞性 repository 操作都必須取得人類核准。自動化執行合併時，應保留能區分執行者與授權該行為之人員或政策的記錄。

錯誤處理模式

原子檔案寫入。多個 agents 同時寫入同一個狀態檔會損毀 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))。¹⁶

影響範圍分類

依影響範圍分類每個 agent 動作，並據此設置關卡：²

Remote Control（從任何瀏覽器或行動 app 連線至本機 Claude Code）會將「外部」關卡從阻塞式等待轉為非同步通知。您可從手機審查前一項工作時，agent 會繼續處理下一項工作。²

自主執行的任務規格

有效的自主任務包含 3 個要素：目標、完成準則與內容指標：¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

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

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

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

需要留意的失敗模式

具體工作階段追蹤

來自一個處理含有 5 個故事之 PRD 的自主執行工作階段追蹤：²

1. SessionStart 觸發。Dispatcher 注入：目前日期、專案偵測、哲學限制、成本追蹤初始化。5 個 hooks，合計 180ms。

2. Agent 讀取 PRD，規劃第一個故事。UserPromptSubmit 觸發。Dispatcher 注入：作用中的專案內容、工作階段漂移基準線。

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

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

5. Agent 完成故事。Stop 觸發。品質關卡檢查：agent 是否引用證據？是否使用模稜兩可的語言？diff 中是否有 TODO 註解？任一檢查失敗時，結束碼為 2，agent 繼續執行。

6. 獨立驗證：新的 agent 在不信任前一個 agent 自我報告的情況下執行測試套件。

7. 3 個程式碼審查 agents 平行啟動。各自獨立審查 diff。只要任一審查者標記為 CRITICAL，該故事就會回到佇列。

8. 故事通過。載入下一個故事。此循環會重複處理全部 5 個故事。

5 個故事共觸發約 340 個 hooks。hooks 總耗時約 12 秒。這些額外負擔在單次隔夜執行中，防止了 3 次憑證洩漏、1 個破壞性指令，以及 2 項未完成的實作。

案例研究：隔夜 PRD 處理

一個正式環境 harness 在 8 次隔夜工作階段中處理了 12 個 PRD（47 個故事）。指標將前 4 個 PRD（最小 harness：僅 CLAUDE.md）與後 8 個（完整 harness：hooks、skills、品質關卡、多 agent 審查）進行比較。

這 2 次憑證洩漏需要輪替 API keys 並稽核下游服務：約需 4 小時的事件應變。防止同等事件的 harness 額外負擔，則是每個故事 2.4 秒的 bash。錯誤完成率從 35% 降至 4%，因為 Stop hook 會在允許 agent 回報完成前獨立執行測試。

安全性考量

值得信賴的 Agents 五項原則（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 互通性標準如今已不再受單一供應商限制。²⁷

MCP的無狀態 turn 與自我回報身分。 MCP規格在2026年7月28日修訂版（現為 Current spec）完成向無狀態核心（SEP-2575）的轉型，移除了過去會攜帶伺服器身分的有狀態 initialize handshake。7月16日合併的 draft-spec 變更（PR #3002）將身分恢復為可選介面：伺服器可在回應 _meta 中加入 io.modelcontextprotocol/serverInfo 物件，而請求中的 clientInfo 則改為可選。⁷¹與安全性相關的重點在於規格對信任的說法：此身分為自我回報且未經驗證——僅供顯示與記錄——並且 SHOULD NOT 用於驅動安全性決策。如果您的 harness 依據MCP伺服器宣告的名稱建立 allowlist、權限規則或以記錄為基礎的稽核，該名稱只是一項聲稱，而非認證憑證；信任應固定在傳輸與設定上（您在何處設定了哪一部伺服器），絕不可建立在伺服器自稱的身分上。無狀態修訂版已於2026年7月28日如期推出（強制 server/discover、透過 _meta 進行 protocol-version 協商、Streamable HTTP header）；上述信任指引描述的是已推出的行為。

Skill sandbox 工具： 對將 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 可防止模型任意發出網路請求，或存取專案目錄以外的檔案。未使用 sandboxing 時，Claude Code採用以權限為基礎的模型，由您核准或拒絕個別工具呼叫。¹³

2026年5月安全性底線。 Claude Code v2.1.149 修正了 PowerShell 工作目錄權限繞過、數個 PowerShell allow-rule 與過期變數的權限分析缺口，以及 git-worktree sandbox 寫入 allowlist 錯誤；後者原本涵蓋整個主要儲存庫根目錄，而非僅限共用的 git 內部結構。⁵³若您的 harness 允許 PowerShell 或 worktree 隔離的 Agents，應將 v2.1.149+ 視為最低版本，並維持狹窄的 shell 規則。寬鬆的 PowerShell(*) 與全儲存庫寫入例外是編排上的捷徑，不是安全邊界。

OpenAI Agents SDK sandbox 鎖定（v0.17.0，2026年5月8日）。 在 OpenAI 方面，openai-agents-python v0.17.0 收緊了一條平行邊界：LocalFile.src 與 LocalDir.src 現在必須位於 materialization base_dir 範圍內（套用 manifest 時SDK程序的目前工作目錄），除非透過 SandboxPathGrant 明確在 Manifest.extra_path_grants 中授予來源存取權。⁴¹相對本機來源會從 base_dir 解析；絕對路徑必須已位於其中，或具備授權。這修正了本機 artifact 邊界問題：先前版本允許 manifests 將任意主機路徑帶入 sandbox workspace。遷移方式：對唯讀掛載，使用 SandboxPathGrant(path=..., read_only=True) 在 manifest 層級宣告可信任的主機根目錄。請將 extra_path_grants 視為可信任的應用程式設定；絕不可依據模型輸出或不受信任的 manifest 輸入填入授權。

OpenAI Agents SDK後續版本底線（v0.17.3）。 0.17.1-0.17.3 版本線加入更多 sandbox 與工作階段強化：封存檔解壓縮限制、GitRepo 子路徑驗證、更清楚的 sandbox-provider 錯誤、避免將 mountpoint 認證資訊放入 sandbox 指令、拒絕相對 sandbox workspace 根目錄，以及 Vercel-sandbox 終止狀態處理。⁵⁴若您使用的是 OpenAI 託管或 provider-backed sandboxes，而非僅使用Claude Code hooks，請將 0.17.3 視為本節模式的目前最低版本。

跨產品的三種隔離模式（Anthropic，2026年5月）

Anthropic的工程文章「How we contain Claude across products」（2026年5月25日）是供應商對本節零星教授原則的完整闡述——上述設定層級 sandbox、worktree-isolation 底線，以及將所有事物視為不受信任的立場。⁸¹其核心做法是將隔離強度對應到產品介面，而這項對應本身就是教訓：不存在唯一正確的隔離設計，只有符合監督能力與潛在風險的隔離方式。

• 短暫的 gVisor containers（claude.ai）。 伺服器端執行在隔離基礎架構上的 gVisor containers 中進行，並使用每個工作階段短暫存在的檔案系統。威脅模型針對基礎架構與租戶隔離——使用者的機器永遠無法存取，因此沒有任何本機資源需要防護。
• Human-in-the-loop OS sandboxing（Claude Code）。 上述 sandbox 段落所描述的模式，從政策角度來看是：macOS 使用 Seatbelt、Linux 使用 bubblewrap，允許讀取、將寫入限制於 workspace，且預設拒絕網路——人類負責核准邊界未涵蓋的事項。Anthropic已將執行階段開源（sandbox-runtime），讓該邊界可供稽核。該文章坦率指出薄弱環節：大約 93% 的權限提示都會被核准，而 auto-mode 分類器——在執行前攔截約 83% 的過度積極行為，同時減少 84% 的核准提示——正是因為核准疲勞是安全性特性，而不是 UX 抱怨。這正是本指南自 v2.1.193 以來持續追蹤的 check-layer 姿態。
• 密封 VMs（Claude Cowork）。 在平台 hypervisors 上執行的完整 virtual machines——macOS 使用 Apple Virtualization framework，Windows 使用 HCS——僅掛載選取的 workspace 與 .claude 資料夾；主機上的其他內容一概不可見。認證資訊永不進入 VM：它們保留在主機 keychain，每個工作階段則取得範圍受限、可獨立撤銷的 token。VM 內的防禦性 MITM proxy 會執行此規則，只傳遞攜帶 VM 自身佈建 session token 的請求——嵌入攻擊者的 key 會在邊界遭拒，因為只有 VM 知道其來源。

此分類法底層的設計原則才是可移植的部分。先在環境層級隔離，再在模型層級引導：任何機率性防禦都有非零的漏失率，因此確定性的邊界必須攔截 prompt-level 引導遺漏的項目——這正是本指南的 hooks-guarantee-execution 論點，也是供應商重新表述的結論。讓隔離強度符合使用者的監督能力：開發者可以在核准前評估 bash 指令；知識工作者無法如此——這就是為什麼 Code 使用權限對話方塊，而 Cowork 使用密封 VM。優先使用久經考驗的 primitives，而非自訂隔離程式碼：hypervisors、seccomp 與 container runtimes 經受的對抗性審視，比Anthropic自行撰寫的 allowlist proxies 與設定解析器更嚴苛。將專案本機設定與工具輸出視為不受信任：文章指示應將開啟專案與載入設定，如同處理網際網路上的任何傳入請求；即使工具可信任，工具輸出也應視為攻擊面——這與本指南套用於 inter-agent 訊息、subagent 所讀內容及自我回報MCP身分的立場一致。將認證資訊保留在 sandbox 外：採用範圍受限、可撤銷、每個工作階段各自使用的 tokens，而非 Agent 可能洩漏的環境 keys。

設定介面正逐漸追上第一項原則（v2.1.219）。「先在環境層級隔離」很容易認同，卻一直難以實際設定，因為Claude Code的 sandbox 對規則未涵蓋的事項會透過提問處理——而權限提示正如上述 93% 核准率所承認，是披著確定性外衣的機率性防禦。sandbox.network.strictAllowlist 取消了對外連線的提問：啟用後，sandboxed 指令對不在 allowlist 中主機提出的請求會直接遭拒，而非顯示提示。⁸⁴將它與 v2.1.216 的 sandbox.filesystem.disabled 搭配，這兩項設定便構成一種安全姿態，而非一堆切換開關——檔案系統與網路隔離可各自選擇，且網路隔離如今可設為確定性。對無人監督的 harness 而言，兩者中這項更為重要，因為對外輸出正是注入指令轉化為資料外洩之處，而核准疲勞的極端情況是鍵盤前根本沒有人可以疲勞。代價就是確定性邊界一貫的代價：allowlist 必須正確，遺漏的主機會以不透明的拒絕失敗，而不是提出問題。請列舉您的 Agents 合理需要的主機，然後移除提示。

這些措施都無法取代 hook 層；它們位於其下。隔離模式構成確定性的底線，而本指南中 worktree-enforcement 的歷史也是同一教訓的縮影：邊界只有在面對蓄意重新導向時仍能守住才算數，而最可能守住的 primitives，往往不是為當下情境臨時寫成的。

權限邊界

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

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

Claude Code v2.1.178 將權限規則從工具層級延伸至參數層級：Tool(param:value) 會比對工具的輸入參數，並以 * 作為 wildcard。標準範例為 Agent(model:opus)——此規則可封鎖以特定模型層級啟動 subagents。⁶³從架構上看，這填補了上述四層表格無法表達的缺口：先前只能整體允許或拒絕工具，無法限制其呼叫方式。治理政策現在可以規定「可啟動 subagents，但不可使用 Fable 5 層級」或「允許 Bash，但不可使用此 flag」，並作為確定性規則而非 prompt-level 請求。

配套的受管理設定 enforceAvailableModels（v2.1.175）從上而下限制模型選擇：它會固定 Default model，並防止使用者或專案範圍的設定擴大受管理的 availableModels allowlist。⁶³兩者可相互配合——allowlist 定義工作階段中可用的層級，而參數層級規則則限制 subagents 如何取用它們。自 v2.1.196 起，管理員也能從 org console 設定全組織預設模型，並在 /model 顯示為「Org default」，讓整個 fleet 繼承受治理的預設值，而無須每位操作員個別固定——這是補足 allowlist 上限的底線。

路徑範圍 Allow 規則錨定於工作目錄（2026年7月）

Claude Code v2.1.214 修正了路徑範圍權限規則中一項隱微的過度比對：含單一區段 dir/** 模式的 allow 規則——例如 Edit(src/**)——會自動核准對任意深度、任何名為 src 目錄的編輯，包括 vendor/some-package/src/ 與規則作者從未打算允許的所有巢狀 src/。這類規則現在僅錨定於 <cwd>/dir；若您確實希望在任意深度比對，請明確宣告 **/dir/**。⁷⁴Deny 與 ask 規則則刻意保留舊有的任意深度比對。這種不對稱是正確的 fail-safe 設計：比對過窄的 allow 規則會安全失敗（您會收到提示），比對過窄的 deny 規則則會開放失敗（原應封鎖的路徑會漏過）——因此 allows 變得更嚴格，而 denies 維持寬鬆。若您的設定仰賴單一區段 allow patterns 涵蓋巢狀路徑，它們在 v2.1.214 已悄然停止如此運作；這正是修正預期的效果，但仍值得檢查一次您的 allowlists，重新宣告您真正需要的範圍。

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

Claude Code v2.1.183 縮小了 auto mode 對會悄然遺失工作或拆除環境之操作的影響範圍。除非您在工作階段中明確要求，auto mode 現在會強制封鎖：破壞性的 git 操作（git reset --hard、git checkout -- .、git clean -fd、git stash drop）；若該 commit 並非本工作階段由 Agent 建立時的 git commit --amend；以及未指定特定 stack 時的基礎架構拆除（terraform destroy、pulumi destroy、cdk destroy）。⁶⁵從架構上看，這補足了前述 spawn-vetting 與參數層級規則：它並非管控哪一種工具或如何啟動，而是依據意圖管控少數特定不可逆指令——Agent 仍可執行它們，但必須有明確指示，不能自行決定。對自主 harness，請在自己的 PreToolUse hooks 中編碼相同原則：會摧毀狀態的指令應採用預設拒絕規則，僅在操作員發出明確訊號時解除。

2026年7月：auto mode 進入企業版，且有一則提示無法豁免。 Auto mode 在 v2.1.207 於 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 達到 GA，並提供 disableAutoMode 受管理設定作為企業退出機制——分類器作為 check-layer 的姿態現已適用於所有第一方企業平台，停用它是明確的治理決策，不再是平台缺口。⁶⁸接著 v2.1.208 讓災難性移除的護欄成為絕對規則：災難性移除的確認提示如今會穿透兩者 --dangerously-skip-permissions 與 auto mode。⁶⁸這是值得注意的先例——Claude Code中第一個無論何種權限姿態（包括明確略過的 flag）皆無法豁免的確認。假設 --dangerously-skip-permissions 意味著完全零提示的自主 harness 設計，應將此例外納入考量；它恰恰在無人監督迴圈最可能造成無法挽回損害之處觸發。

防止捏造的護欄（2026年7月）

v2.1.203–v2.1.206 版本封閉了 Agent 可自行捏造稽核軌跡的兩條途徑。⁶⁸首先，auto-mode 規則現會封鎖對 transcript 檔案的竄改——工作階段紀錄不再能由該工作階段自己的工具呼叫改寫。其次，background-task 通知現在會明確指出，任務執行期間沒有任何人類輸入。第二項針對一種微妙的失敗：模型過去在摘要 background task 時，可能呈現（或捏造）逐字稿中從未發生的「核准」，而通知中沒有任何內容與之矛盾。如今，通知本身就是反證。

這項架構教訓可推廣至 Evidence Gate：transcripts、通知與記錄都是稽核介面，稽核介面不能由受稽核的事物寫入。平台現在已對自身 transcript 強制執行此規則；請將相同規則套用到您的 harness——證據報告、測試輸出與審議紀錄都應置於模型不可寫入的路徑之外。

Prompt Injection 防禦

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

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

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 即使其 prompt 遭入侵，也無法進行變更。

平台底線在2026年7月提高。 Claude Code v2.1.210 強化了 Agent tool，以防禦由 subagent 所讀內容攜帶的間接 prompt injection——遭污染的檔案、網頁或由 subagent 取得的工具結果，較難操控委派介面本身。⁶⁹而 v2.1.211 強化了鏈條中的人類環節：權限預覽現在會中和 bidirectional-override、zero-width 與 look-alike Unicode 字元，因此指令再也無法被設計成在核准對話方塊中顯示為無害，實際卻執行其他內容。⁶⁹第二項修正對於人類在時間壓力下核准呈現預覽的 harness 特別重要——顯示介面本身也是 injection surface。兩項變更都無法取代上述 hook-level 防禦；它們只是提高其下方的底線。

Agent Logs 與 Guardrails 是安全性介面

兩則2026年5月的 advisory 強化了一種模式：Agent 基礎架構創造了新的位置，敏感內容與可執行政策可能在這些位置洩漏或逃逸。GitHub Advisory GHSA-f3jg-756w-gm35 涵蓋 Gryph Agents 的 payload-filter 問題；敏感工具 payload 內容可能在預設記錄行為下保留於本機 SQLite logs。⁴⁵OSV GHSA-wxxx-gvqv-xp7p 涵蓋 LiteLLM於 admin-protected proxy endpoint 的 custom-code guardrail sandbox escape。⁴⁶

生產環境規則是：將 Agent transcripts、工具 payloads、SQLite logs 與 guardrail 執行視為敏感基礎架構。在持久化前進行遮罩、套用保留期限限制，並確保 custom guardrail code 置於 sandbox 且可供檢視。僅有 prompt-level 的「不要記錄 secrets」規則並不足夠；記錄與 guardrail 路徑需要確定性測試。

Hook 安全性

將環境變數插入 headers 的 HTTP hooks，需要明確的 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 actions 觸發。¹³若Claude透過 Agent tool 啟動 subagent，您的 PreToolUse 與 PostToolUse hooks 會針對該 subagent 使用的每項工具執行。若沒有遞迴 hook enforcement，subagent 便可能繞過您的安全閘門。SubagentStop event 可讓您在 subagent 完成時執行清理或驗證。

這不是可選項目。能啟動 subagent、卻未套用您的 security hooks 的 Agent，能在您的閘門只監看主對話而毫無作為時，force-push 到 main、讀取 credential 檔案，或執行破壞性指令。

成本即架構

成本是架構決策，不是營運上的事後考量。²共有三個層級：

Token 層級。System prompt 壓縮。移除教學程式碼範例（模型知道APIs）、合併跨檔案的重複規則，並以約束取代說明。「Reject tool calls matching sensitive paths」與以 15 行說明為何不應讀取認證資訊，達成相同效果。

Agent 層級。相較於長對話，採用 fresh spawns。自主執行中的每個 story 都使用具備乾淨 context 的新 Agent。由於每個 Agent 都重新開始，context 永遠不會膨脹。以 briefing 取代 memory：模型執行清楚 briefing 的效果，優於在累積 30 個步驟的 context 中摸索。

架構層級。當操作是無狀態時，CLI優先於MCP。用於一次性評估的 claude --print 呼叫成本更低，也不會增加連線負擔。當工具需要持久狀態或串流時，MCP才有意義。

決策框架

各機制的適用時機：

Skills、Hooks 與 Subagents

常見問題

多少 hooks 算太多？

限制因素是效能，而非數量。每個 hook 都會同步執行，因此所有 hook 的總執行時間會累加到每次符合條件的工具呼叫中。使用者層級與專案層級設定合計95個 hooks，只要每個 hook 都在200ms內完成，便不會有明顯延遲。需要留意的門檻是：若 PostToolUse hook 為每次檔案編輯增加超過500ms，session 便會顯得遲緩。部署前請用 time 分析 hooks 的效能。¹⁴

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

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

應將 hook 設定檔放在哪裡？

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

每個決策都需要 deliberation 嗎？

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

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

同時測試成功路徑與失敗路徑。成功路徑：agents 進行有建設性的分歧，並達成共識。失敗路徑：agents 過快收斂、永遠無法收斂，或超出 spawn 預算。端對端測試會以確定性的 agent 回應模擬各種情境，驗證兩個驗證閘門能捕捉所有已記錄的失敗模式。一套正式環境的 deliberation 系統會跨3個層次執行141項測試：48項 Bash 整合測試、81項 Python 單元測試，以及12項端對端 pipeline 模擬。⁷

deliberation 對延遲有何影響？

3-agent deliberation 會增加30至60秒的實際經過時間（此 deliberation 設計會透過 Agent tool 依序執行 agents；自v2.1.198起，平台本身會在背景並行執行 subagents）。10-agent deliberation 則會增加2至4分鐘。共識與 pride check hooks 各自都能在200ms內執行完畢。主要瓶頸是每個 agent 的 LLM 推論時間，而非編排額外負擔。⁷

CLAUDE.md 檔案應有多長？

每個段落應控制在50行內，整個檔案則不超過150行。過長的檔案會遭 context windows 截斷，因此應將最關鍵的指示置於前方：先放指令與完成定義，再放風格偏好。²¹

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

架構原則（hooks 作為確定性閘門、skills 作為領域專業知識、subagents 作為獨立 contexts、檔案系統作為記憶）在概念上適用於任何 agentic system。具體實作則使用 Claude Code 的生命週期事件、matcher patterns 與 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.

結束代碼

重要指令

檔案位置

變更記錄

參考資料