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

重點摘要：Claude Code 並非可存取檔案的聊天介面，而是具備30個已記載生命週期事件的可程式化執行環境。每個事件都能掛接模型無法略過的 shell 指令碼。將 hooks 組合成 dispatchers、dispatchers 組合成 skills、skills 組合成 agents、agents 組合成工作流程，即可建構自主開發 harness；它能強制執行限制、委派工作、跨工作階段保存記憶，並協調多 agent 審議。Claude Code v2.1.147 新增預設停用的 Workflow 工具（CLAUDE_CODE_WORKFLOWS=1），讓確定性的多 agent 協調從純粹的使用者空間指令碼，逐步轉向第一方執行環境原語；v2.1.149 則從安全層面再次印證相同道理，修正 PowerShell 權限繞過問題及 git-worktree 沙箱允許清單問題。正確性仍由 hooks 與 evidence gates 把關。⁵²⁵³ 本指南涵蓋此堆疊的每一層：從單一 hook 到由10個 agent 組成的共識系統。完全不需要框架，只需 bash 與 JSON。

Andrej Karpathy 創造了一個詞，用來描述環繞 LLM agent 發展而成的系統：claws。也就是讓 agent 得以掌握其上下文視窗之外世界的 hooks、指令碼與協調機制。¹ 多數開發人員將 AI 程式設計 agent 視為互動式助理：輸入提示、看著它編輯檔案，然後繼續下一件事。這種思維會將生產力上限侷限在您親自監督的範圍內。

基礎架構的思維模式截然不同：AI 程式設計 agent 是以 LLM 為核心的可程式化執行環境。模型採取的每項動作，都會通過由您掌控的 hooks。您定義的是政策，而非提示。模型在您的基礎架構中運作，就如同網頁伺服器依循 nginx 規則運作。您不會守在 nginx 前逐一輸入請求，而是完成設定、部署並加以監控。

這項差異至關重要，因為基礎架構的效益會不斷累積。能阻止 bash 指令夾帶憑證的 hook，可保護每個工作階段、每個 agent 與每次自主執行。將評估準則編碼其中的 skill，無論由您或 agent 呼叫，都能一致套用。負責安全性程式碼審查的 agent，無論您是否正在監看，都會執行相同的檢查。²

核心重點

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

如何使用本指南

每一節皆以前一節為基礎。文末的決策框架提供查詢表，協助您針對各類問題選擇合適的機制。

五分鐘黃金路徑

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

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

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

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

在 .claude/settings.json 中串接:

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

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

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

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

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

步驟 3:派出 subagent(30 秒)

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

您現在擁有什麼

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

為什麼 Agent Architecture 至關重要

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

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

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

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

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

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

Harness 模式

harness 並非框架，而是一種模式：由可組合的檔案、指令碼與慣例構成，將 AI 程式設計 agent 包覆在具確定性的基礎架構中。其元件如下：

┌──────────────────────────────────────────────────────────────┐
│                      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 檔案與 rules 目錄定義 agent 對專案的認知。它們會在工作階段開始時及每次壓縮後自動載入，構成 agent 的長期架構記憶。

擴充層：skills 提供領域專業知識，並依據情境自動啟用。hooks 則提供具確定性的關卡，在每次符合條件的工具呼叫時觸發。記憶檔案可跨工作階段保存狀態。自訂 agents 則提供專門的 subagents 設定。

協調層：多 agent 模式負責協調彼此獨立的 agents，以進行研究、審查與研議。生成配額可避免遞迴失控，共識驗證則確保品質。

關鍵洞見在於：多數使用者完全只在核心層作業，眼看著情境不斷膨脹、成本節節攀升。進階使用者則會設定指令層與擴充層，僅將核心層用於協調與最終決策。²

代管式與自行託管的 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），並透過快照與重新載入機制，在容器遺失後延續作業。²³²⁴

OpenAI 端更完整的 SDK 介面，隨 openai-agents Python v0.14.0 於2026年4月15日發布，並在4月16日正式公布：其中包含 Agent 的子類別 SandboxAgent，並具備 default_manifest、沙箱指令與功能；Manifest 用於描述全新工作區的契約（檔案、目錄、本機檔案、Git 儲存庫、環境、使用者、掛載點）；SandboxRunConfig 則負責每次執行時的沙箱用戶端連接、即時工作階段注入、manifest 覆寫、快照及實體化並行限制。內建功能涵蓋 shell 存取、檔案系統編輯、影像檢查、skills、沙箱記憶與壓縮。沙箱記憶會跨執行保存擷取出的經驗，並逐步揭露內容；工作區支援本機檔案、Git 儲存庫項目及遠端掛載（S3、R2、GCS、Azure Blob、S3 Files）；快照可跨供應商移轉。後端包括 UnixLocalSandboxClient、DockerSandboxClient，以及透過選用額外套件提供的 Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop 與 Vercel 代管用戶端。²⁴

對於希望將 Claude Code 執行環境嵌入為函式庫的 Python 專案——介於「透過 shell 呼叫 claude」與「向 Managed Agents 發送 REST API」之間——第三種選擇是 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）。³⁰ 截至2026年8月1日，PyPI 上的套件版本為 v0.2.128（隨附 Claude CLI v2.1.220，且 mcp 的最低版本現已提高至 >=1.23.0），TypeScript SDK 則為 v0.3.220；0.2.x 系列是在此處所述0.1.x 介面上的漸進式更新——下文的 include_hook_events、skills 與沙箱設定選項目前仍然適用——近期版本主要著重於子行程清理及 NDJSON 串流可靠性。⁸⁶

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

到了2026年7月，OpenAI 端的代管方案也補上了多 agent 能力：openai-agents-python v0.18.2（7月11日）與 openai-agents-js v0.13.2（7月10日）新增測試版的代管式多 agent 支援——由 OpenAI 以代管服務形式協調多個 agents，直接對應於多 Agent 協調一節所述的 Anthropic Managed Multiagent Orchestration 公開測試版。⁷³ 如今，兩家供應商在多 agent 層級提供的取捨，與下表針對單一 agent 所描述的相同：供應商負責執行委派迴圈，而您則必須放棄 hooks 介面。

架構上的分岔如今已確實成形：

該如何選擇：對於已有充足基礎架構能力、希望自行掌控 skills／hooks，或正深入最佳化特定工作流程的團隊，自行託管仍是合適選擇。若團隊沒有專職平台工程師、重視價值實現速度勝過自訂能力，或需要 agent 執行作業在筆記型電腦闔上後仍能可靠延續，且不想自行建置持久化層，則適合採用代管方案。兩者亦可相容並用——自行託管的 harness 可透過 REST API，將特定的長時間執行任務委派給 Managed Agents。

Harness 在磁碟上的結構

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

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

此結構中的每個檔案都有其用途。~/.claude/ 目錄樹是套用至所有專案的個人基礎架構；每個儲存庫中的 .claude/ 目錄樹則專屬於該專案，並透過 git 共享。兩者相輔相成，共同構成完整的 harness。

Skills 系統

Skills 是由模型呼叫的擴充功能。Claude 會根據情境自動探索並套用，無須由您明確呼叫。⁴ 當您發現自己在不同工作階段反覆說明相同背景資訊時，就該建立 skill 了。

何時該建立 Skill

Skills 用於提供Claude 隨時可用的知識。斜線命令則用於由您明確觸發的動作。若您正在兩者之間取捨，不妨問：「應由 Claude 自動套用，還是由我決定何時執行？」

建立 Skill

Skills 可存放於以下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 description 會注入系統提示詞的 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-review skills，而只會在明確呼叫時執行。這是刻意收緊由 description 驅動的啟用機制，因為這類高負載的審查 skills 若未經要求便執行，成本往往高於效益。⁷⁴

情境預算

所有 skill description 共用一筆情境預算，會依情境視窗大小動態調整為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 中使用相對連結參照這些檔案。Claude 會在 skill 啟用後按需讀取。SKILL.md 應維持在500行以內，並將詳細參考資料移至支援檔案。¹²

透過 Git 分享 Skills

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

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

團隊成員拉取變更後，便會自動取得該 skill。無須安裝，也無須設定。這是讓整個團隊採用一致專業知識最有效的方法。

將 Skills 作為提示詞程式庫

除了單一用途的 skills，此目錄結構也能作為井然有序的提示詞程式庫：

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

每個 skill 都封裝您專業知識的不同面向。這些 skills 共同構成一套知識庫，供 Claude 根據情境自動取用。即使是資淺開發人員，也能不必開口要求便獲得資深層級的指引。

Skills 與 Hooks 的組合運用

Skills 可在 frontmatter 中定義專屬 hooks，且僅在該 skill 執行期間啟用。如此便能建立特定領域的行為，同時避免干擾其他工作階段：²

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

哲學類 skills 會透過 SessionStart hooks 自動啟用，將品質限制注入每個工作階段，無須明確呼叫。Skill 本身提供知識，hook 則負責落實規範。兩者相輔相成，形成政策層。

常見的 Skill 錯誤

Description 過於寬泛。 如果 git-rebase-helper skill 遇到任何與 git 相關的提示詞都會啟用（包括 rebase、merge、cherry-pick，甚至 git status），便會干擾80%的工作階段。解決方式是縮小 description 的適用範圍，或加入 disable-model-invocation: true，要求使用者明確透過 /skill-name 呼叫。⁴

太多 skills 競爭預算。 Skills 越多，競爭1%情境預算的 description 也越多。若發現 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/ 中外掛程式與 Skill 的整合（2026年5月29日）

Skills 一向會從專案的 .claude/skills/ 目錄載入。Claude Code v2.1.157 將此目錄擴及外掛程式：現在只要將外掛程式放入 .claude/skills/，無須向市集註冊即可自動載入；而 claude plugin init <name> 會在該處建立新的外掛程式骨架，manifest 與 SKILL.md 也已完成串接。⁵⁸ 這項變更消除了兩種原本分處不同位置的專案工具形式之間的隔閡：一種是直接提交至儲存庫的獨立 skill；另一種是將 skill、hooks 與 MCP server 封裝在一起，過去卻必須透過市集安裝的外掛程式。對 harness 設計的實際影響是：專案範圍的工具不必再繞道登錄系統才能交付。撰寫、提交後，團隊成員執行 git pull 即可取得相同介面。外掛程式仍適合可整包安裝的使用情境（將 hooks + skills + MCP servers + agents 整合於單一 ZIP）；改變之處在於，專案不再需要僅為了從自己的目錄樹載入外掛程式而架設市集。

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

Skills 代表能力，而能力也代表攻擊面。Claude Code v2.1.169 新增 disableBundledSkills 設定（以及相對應的 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS 環境變數），可向模型完全隱藏內建 skills、workflows 與內建斜線命令。⁶⁰ 對強化或受監管的 harness 而言，這是一項刻意縮減攻擊面的措施：操作人員在稽核並核准一組特定的專案及個人 skills 後，可停用 Anthropic 隨附的所有功能，確保模型只會針對經過審核的介面進行推理。請以對待工具允許清單的方式看待此設定——預設提供廣泛能力，而關閉預設能力是一項治理決策，並非便利性切換選項。

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

Claude Code v2.1.178 讓專案工具具備位置感知能力。現在處理某個目錄下的檔案時，也會載入該目錄內巢狀 .claude/skills 目錄中的 skills，不再侷限於儲存庫根目錄；若名稱衝突，巢狀 skill 會顯示為 <dir>:<name>，讓兩者皆可存取。⁶³ 同一版本也讓專案其餘介面採用最接近工作目錄者優先的解析方式：當巢狀 .claude/ 目錄中的 agent、workflow 或 output-style 名稱衝突時，以最接近工作目錄者為準；儲存專案範圍的 workflow 時，也會以最近的既有 .claude/workflows/ 為目標，而非一律存至根目錄。⁶³ 對 monorepo 或儲存庫內含儲存庫的架構而言，這正是單一扁平全域介面與依套件劃分、隨情境啟用的工具之間的關鍵差異——services/api/.claude/skills/ 可收納僅在該目錄樹中工作時才會顯示的 API 專屬 skills，且不會與 services/web/ 中同名的 skill 衝突。

Hook Architecture

Hooks 是由 Claude Code 生命週期事件觸發的 shell 命令。³它們以一般指令碼的形式在 LLM 外部執行，而非由模型解讀的提示。模型想執行 rm -rf /？只需一段 10 行的 bash 指令碼，即可依封鎖清單檢查命令，並在 shell 看到命令之前拒絕執行。無論模型是否願意，hook 都會觸發。

可用事件

截至本指南更新時，Claude Code 提供橫跨 8 個類別、共 30 個已有文件記載的生命週期事件。事件清單會隨版本發布而增加，因此請以參考文件為準；在為正式環境配置 hooks 前，請先查閱速查表，確認目前完整的事件表：¹³

DirectoryAdded（v2.1.219）補上了工作階段中途加入工作區的缺口。自 v2.1.152 加入 MessageDisplay 後，事件清單便一直維持穩定；DirectoryAdded 是此後首個新增的生命週期事件。當 /add-dir 或 SDK 的 register_repo_root 控制要求在工作階段中途註冊新的工作目錄後，便會觸發此事件。⁸⁴它所填補的缺口確實存在：過去，harness 即使在 SessionStart 時徹底驗證工作區，仍可能在完全沒有 hook 觸發的情況下，看著第 2 個儲存庫被接入。凡是在啟動時對工作區做出的任何判定，包括信任檢查、機密資訊掃描、依目錄樹建立的路徑範圍規則，以及各儲存庫的原則載入，都必須在此重新執行，因為工作階段的目錄集合不再於啟動時固定不變。此事件僅供提供資訊，無法封鎖操作。因此，應將它視為重新推導狀態與記錄來源的觸發條件，而非 evidence gate；若某個目錄絕不能被加入，請在設定中禁止，而不要試圖透過 hook 否決。SDK 端也在同一版本完成支援（TypeScript v0.3.219 將 DirectoryAdded 加入控制協定的生命週期事件），因此由 SDK 託管的 harness 能以與 CLI 託管者相同的方式接收此事件。⁸⁵

結束狀態碼語意

結束狀態碼決定 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 正規表示式。部分事件不支援 matchers，只要完成設定就一律會觸發。¹³自 Claude Code v2.1.195 起，含有連字號識別碼（code-reviewer、mcp__brave-search）的 matchers 會進行完全比對，不再意外比對子字串。因此，針對特定代理或伺服器的 hook，不會再對名稱中僅含該字串的所有項目觸發；若要涵蓋含連字號之 MCP 伺服器的所有工具，請明確撰寫模式 mcp__brave-search__.*。⁶⁶v2.1.214 對路徑模式採用了同樣嚴謹的規則：hook 的 if: 條件若使用單一區段的 dir/** 模式，現在只會比對 <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 包裝器；對 PreToolUse 而言，舊版頂層 decision／reason 格式已遭棄用：

{
  "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 會在每次變更檔案後執行格式化工具。模型產生何種輸出並不重要，因為格式化工具會將所有內容標準化。

{
  "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 會執行程式碼檢查工具或測試套件；若品質檢查失敗，便會封鎖提交：

#!/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": "..." }予以阻擋。適合用於正規表示式無法表達的細緻評估。

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
}

非同步模式適合用於通知、遙測與備份。格式化、驗證或任何必須在下一個動作前完成的工作，絕對不可使用非同步模式。

以Dispatchers取代獨立Hooks

若7個hooks全都由同一事件觸發，並各自獨立讀取stdin，就會產生競爭條件。當2個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. 確認結束代碼。 PreToolUse hook若使用exit 1，看似正常運作，實際上卻毫無強制效果。
5. 維持hooks迅速執行。 Hooks採同步執行。所有hooks都應在2秒內完成，最好不超過500ms。

SDK端Hook事件串流

以claude-agent-sdk-python建置的自託管harness（v0.1.74+，2026年5月6日）可以直接從訊息串流訂閱hook事件，不必透過shell指令碼callback。³⁶ 在ClaudeAgentOptions上設定include_hook_events=True後，HookEventMessage物件（PreToolUse、PostToolUse、Stop及其他事件）便會與助理訊息及工具結果一起從同一個iterator產生。這與TypeScript SDK的includeHookEvents選項相呼應；同一版本也將內附的CLI升級至v2.1.129。

若harness本就以Python執行，並希望hook訊號與模型輸出位於同一控制流程中，事件串流模式便最為合適。若harness需要組合多種工具、讓Claude Code與Codex共用hooks，或仰賴結束代碼語意進行阻擋，shell指令碼hook合約（結束代碼、stdin JSON、dispatchers）仍是正確選擇。

TypeScript SDK於2026年7月推出的系列版本（v0.3.205–v0.3.208），讓串流協定本身成為更明確的合約。⁷⁰ 中斷現在會回傳具型別的收據：中斷收據會透過still_queued UUID確認哪些佇列訊息仍在等待處理；工作階段也會在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等待期間發出abort，卻被轉換為hook成功的問題——這表示由PreToolUse hook管控的工具，可能會在呼叫端中止後仍繼續執行。⁷⁰ 若harness以SDK端hooks作為權限閘門，並仰賴abort取消執行中的工作，請將v0.3.208視為最低版本；低於此版本時，「已中止」並不必然代表「已阻擋」。Python v0.2.127（2026年7月24日）是1個月內第2個同類型的繞過問題——query()在收到第一個result frame時便關閉stdin，即使背景subagents仍在執行亦然，導致其SDK-MCP工具呼叫因"Stream closed"而失敗，並且完全繞過PreToolUse hooks。⁸⁵ 請明確認識並持續監控此模式：SDK端hook的強制機制會在生命週期邊界——abort、teardown、stream close——失效放行。傳輸層在取得hook判定前就已終止，而且失敗悄無聲息，因為遭繞過的hook看起來與核准操作的hook毫無二致。請鎖定兩個SDK的最低版本，並保留可確實驗證其強制效果的shell-hook層。

Effort與工作階段來源（2026年5月7日至8日）

Claude Code v2.1.132與v2.1.133新增了2項功能，讓hooks與子程序能更清楚掌握執行環境：³⁸³⁹

• hook輸入中的effort.level。 Hooks現在會在承載tool_input與session_id的同一份輸入中，收到effort.level JSON欄位。同一值也會匯出為$CLAUDE_EFFORT環境變數，因此Bash命令無須解析JSON即可讀取。可用此值依effort層級調整hook成本：在low時略過昂貴的驗證，在xhigh或max時執行完整安全閘門。
• Bash子程序中的CLAUDE_CODE_SESSION_ID環境變數。 Bash工具子程序現在可取得hooks所見的同一個session_id值，並以CLAUDE_CODE_SESSION_ID提供。這補足了來源追蹤的缺口；先前，記錄各工作階段狀態的工具無法將子程序事件與hook事件相互關聯。

這2項訊號無須修改程式碼即可使用；忽略新欄位的現有hooks仍可繼續運作。

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

Claude Code v2.1.136為auto mode新增hard-deny層級，並修正一系列會影響長時間執行harness的plugin與MCP問題：⁴⁰ - settings.autoMode.hard_deny。 Auto mode 分類器規則會無條件封鎖操作，不受使用者意圖或允許例外影響。此設定位於現有的允許／拒絕比對器之上，是不可協商的治理手段。即使操作者已在個人設定中核准較廣泛的類別，仍可用它設定絕不容許覆寫的規則（例如強制推送至 main、存有密鑰的檔案、存取正式環境資料庫）。 - autoMode.classifyAllShell（v2.1.193）。 Auto mode 分類器預設只會審查符合任意程式碼執行模式的 shell 指令。此設定會將每一條 Bash／PowerShell 指令都交由分類器處理，為受治理的 harness 提供涵蓋範圍最完整的防護態勢。同一版本也會在文字記錄、快顯通知及 /permissions 中顯示拒絕原因，將原本悄無聲息的封鎖轉化為可稽核的決策。Codex 在 v0.142.2 中也收緊了對應機制：若 PowerShell 指令含有安全分類器無法檢查的可執行 AST 區域，現在必須取得核准，不再默默放行。⁶⁶ - Hook ask 為分類器設定下限（v2.1.211）。 Hook 與 auto mode 之間的優先順序如今已有定論：若 PreToolUse hook 傳回 ask 權限決策，最終結果至少必須提示使用者確認；對於未受沙箱隔離的 Bash 指令，auto mode 無法再將其提升為允許。⁶⁹ 對受治理的 harness 而言，這補上了缺失的保證層級：即使採用全自動權限態勢，hook 的 ask 仍是確定且無法略過的人工介入關卡。若某項操作需要由人員決定，而非直接拒絕，請使用 ask（而不只是以結束碼2封鎖）。 - 分類器模型會在每個工作階段固定（v2.1.210）。 Auto mode 分類器預設採用 Sonnet 5，並在工作階段期間固定不變，因此工作階段進行中的模型切換不再改變負責權限分類的模型。分類一致性是治理的重要特性；此變更消除了一項不易察覺的偏移來源。 - MCP 伺服器不再於 /clear 後消失。 在 VS Code 擴充功能、JetBrains 外掛程式及 Agent SDK 中執行 /clear 後，於 .mcp.json、外掛程式及 claude.ai 連接器中設定的伺服器，過去會悄悄從作用中集合消失。此問題已於 v2.1.136 修正。若您曾遇到「MCP 伺服器 X 在工作階段進行中消失」，原因就在此。 - 並行重新整理導致 MCP OAuth refresh token 遺失。 使用多個遠端 MCP 伺服器的使用者，現在應不再需要每日重新驗證。先前並行重新整理時的寫入操作會彼此覆寫。 - Plan mode 現在能正確封鎖檔案寫入。 符合條件的 Edit(...) 允許規則過去會繞過 plan mode 的寫入保護。如今無論允許規則為何，皆會強制執行 plan mode。 - 外掛程式的 Stop 與 UserPromptSubmit hooks 不再於工作階段進行中失效。 快取清理程序過去會刪除執行中工作階段仍在使用的外掛程式版本檔案，導致這兩個 hook 事件失效。修正後，使用中的版本會維持固定。 - plugin.json 中的 skills 項目。 設定 skills 過去會隱藏外掛程式預設的 skills/ 目錄。現在兩者能正確組合；若將該項目指向檔案路徑，也會明確回報錯誤，不再無聲失敗。 - CLAUDE_ENV_FILE SessionStart hook 的環境變數失效。 SessionStart hooks 透過 CLAUDE_ENV_FILE 匯出的變數，過去會在 /resume 或 /clear 後失效。此問題已於 v2.1.136 修正。工作階段現在會在這些事件發生時重新載入環境檔案。

對治理型 harness 而言，實務上最值得關注的是 autoMode.hard_deny（新的治理手段），以及 MCP 消失問題的修正（這項無聲失敗會破壞長時間工作階段）。其餘項目主要是改善使用體驗。

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

Claude Code v2.1.139 新增了兩項對正式環境 harness 至關重要的 hook 細節：command hooks 可採用 args: string[] exec 形式，以及 PostToolUse hooks 可使用 continueOnBlock。⁴²⁴⁴ 若 hook 需要動態值或路徑預留位置，建議優先使用 args。它不經 shell，直接產生指令程序，從根本上避免一整類引號處理與注入錯誤。

如果 PostToolUse hook 應將拒絕原因回傳給 Claude 並繼續目前回合，而非終止流程，請使用 continueOnBlock。應將其視為改善操作者體驗的功能，而非繞過安全機制的途徑。負責封鎖的關卡仍須阻止不安全的結果。

同一版本也會將 CLAUDE_PROJECT_DIR 傳給 MCP stdio 伺服器，並允許外掛程式設定在指令中參照 ${CLAUDE_PROJECT_DIR}。⁴² MCP 工具應依據此值解析專案相對路徑，而非仰賴啟動伺服器時碰巧採用的程序工作目錄。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 輸出中新增 terminalSequence 欄位，可在沒有控制終端機的情況下發出桌面通知、設定視窗標題及響鈴。⁵⁰ 請將此功能視為操作者訊號，而非強制執行機制。安全與品質關卡仍應透過一般封鎖契約傳達失敗：使用結構化 hook 輸出，並配合能阻止不安全操作的結束行為。同一版本也新增 claude agents --cwd <path>，可將 Agent View 的範圍限定於單一目錄；新增 CLAUDE_CODE_PLUGIN_PREFER_HTTPS，供缺少 GitHub SSH 金鑰的環境安裝外掛程式；另新增 ANTHROPIC_WORKSPACE_ID，讓工作負載身分同盟規則可涵蓋多個工作區。⁵⁰ 對團隊 harness 而言，這些都是架構層面的細節：縮小作業檢視範圍、減少安裝外掛程式時的前提假設，並明確限定企業權杖的適用範圍。

相較於 hook 語意，Claude Code v2.1.142 對背景工作階段協調更為重要。⁵¹ claude agents 現在能以明確的目錄、設定、MCP、外掛程式、權限、模型及 effort 旗標分派背景工作階段，不再依賴包裝程式狀態。該版本的 fast mode 預設採用 Opus 4.7；若 harness 經量測後確實依賴 Opus 4.6 的行為，可使用 CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 將其固定。到了 v2.1.219，Opus 4.7 已完全退出 fast mode，而 /fast 適用於 Opus 5 與 Opus 4.8。⁸⁴ 探索外掛程式根層級的 SKILL.md，以及顯示外掛程式提供的 LSP，減少了封裝上的模糊空間。針對 MCP_TOOL_TIMEOUT、既有背景工作階段 worktrees、daemon 睡眠／喚醒與升級後清理，以及外掛程式快取清理的修正，也補上了原本容易被誤認為協調錯誤的可靠性缺口。

Stop-hook 引導、跨工作階段權限與多代理程式 v2（2026年6月）

6月上旬有4項變更對 harness 與多代理程式設計至關重要。⁵⁹

Stop／SubagentStop hooks 新增了引導通道。 自 Claude Code v2.1.163 起，Stop 或 SubagentStop hook 可傳回 hookSpecificOutput.additionalContext，將意見回饋交給 Claude 並讓目前回合繼續，且不會將回應標示為 hook 錯誤。在此之前，Stop hook 唯一實質可用的手段是以結束碼2封鎖，但這會顯示為錯誤，並計入連續封鎖上限。對品質關卡 harness 而言，這是更簡潔合宜的基本機制：如果 Stop hook 偵測到「您說已完成，但測試仍未通過」，現在可以注入「以下項目仍然失敗，請繼續處理」，而不必強制封鎖。真正必須停止的情況請使用封鎖；若是「尚未完成，原因如下」，則使用 additionalContext。

跨工作階段訊息不再附帶借用的權限。 v2.1.166 強化了多工作階段情境：經由 SendMessage 從另一個 Claude 工作階段轉送的訊息，不再附帶原使用者的權限。因此，接收端工作階段會拒絕轉送而來的權限要求，auto mode 也會予以封鎖。若您的協調架構會讓代理程式彼此傳訊，應將傳入訊息視為不受信任的資料，而非經過驗證的指令。這與安全性章節套用於工具輸出的原則相同，只是進一步延伸至代理程式間的訊息傳遞。自 v2.1.199 起，若兩個代理程式同名而導致 SendMessage 傳送至錯誤對象，Claude Code 也會偵測並發出警告。這項可靠性改善與權限邊界相輔相成，因為訊息送達錯誤的同名代理程式，本身就是另一類協調錯誤。 模型韌性已成為一級設定。 fallbackModel 設定現在最多可串接3個備援模型；主要模型過載或無法使用時，會依序嘗試這些模型。若發生非預期且不可重試的API錯誤，每個回合還會自動使用備援模型重試1次。對於長時間執行的自主 harness 而言，這能將主要模型的短暫中斷轉化為平順的降級服務，而非直接中止執行。claude agents --json 也新增了 waitingFor 欄位（v2.1.162），用來顯示受阻的背景工作階段正在等待什麼，例如權限提示。對任何輪詢 agent 叢集的協調器而言，這都是可觀測性上的一大進展。

適用於潔淨室治理與疑難排解的安全模式。 Claude Code v2.1.169 新增 --safe-mode 旗標（以及對應的 CLAUDE_CODE_SAFE_MODE 環境變數），啟動工作階段時可一次停用所有自訂項目：CLAUDE.md、外掛程式、skills、hooks 與MCP伺服器。⁶⁰ 這是 harness 的反面——刻意建立的潔淨室。每位維運人員終究都會問：「這個行為來自模型，還是來自我的某項設定？」此模式正可用來釐清答案。當 hook 誤觸發、skill 在不該啟用時啟用，或MCP伺服器汙染了上下文，--safe-mode 會提供一個已知為空的基準，供您比對差異。它也是一項治理基元：讓您能以純粹模型執行，不帶 harness 平時授予的任何持續性權限。若需重現結果，且不希望受到任何維運人員定義的鷹架影響，這點至關重要。

關於模型層級的說明。 自Claude Code v2.1.197（2026年6月30日）起，Claude Sonnet 5 已成為新工作階段隨附的預設模型——原生支援1M上下文，並於8月31日前提供每百萬 token 2美元／10美元的促銷價格，取代 Opus 4.8 成為開箱即用的選擇。本指南將 Opus 5（claude-opus-5）視為建議的 agentic 預設模型：除非刻意另作選擇，否則自主 harness 應使用此模型執行，因為長時間跨度、高風險的 agent 迴圈，正是 Opus 深度推理足以回報其成本的場景。Opus 5 於2026年7月24日隨Claude Code v2.1.219 推出，成為新的預設 Opus——支援1M上下文，每 MTok 5美元／25美元（與其取代的 Opus 4.8 同價），另有每 MTok 10美元／50美元的快速模式，速度約為預設模式的2.5倍。Anthropic 報告指出，它在 Frontier-Bench v0.1 的成績超過 Opus 4.8 的兩倍，CursorBench 3.2 分數則與 Fable 5 相差不到0.5%，成本卻只有一半。⁸⁴⁸⁷ 價格不變、能力更強，而且Anthropic 將此模型形容為「更擅長驗證自身工作並審慎反覆改進」；對 harness 工作而言，這種難得的升級無須再從成本角度辯護，從4.8遷移僅需變更模型 ID。若工作重視成本或高吞吐量，且 Sonnet 5 的速度與智慧比更占優勢，則可降至 Sonnet 5。Opus 之上還有 Claude Fable 5（claude-fable-5），於2026年6月9日推出。Anthropic 將這個新層級描述為其最強大的模型，是一套已達到可安全供大眾使用程度的「Mythos-class」系統；自Claude Code v2.1.170 起，可透過 /model claude-fable-5 選用。⁶⁰ 應審慎選用更高層級，僅在原始推理深度足以證明其成本合理的決策上使用，而非將其一概套用至整個叢集。Opus 5 切換另帶來兩項例行調整：Opus 4.7 已移出快速模式（/fast 現在適用於 Opus 5 與 Opus 4.8）；而自 v2.1.176 起，auto-mode 分類器的 Fable-5 備援選項——「目前可用的最佳 Opus 模型」——現在會解析為 Opus 5。⁸⁴

Codex 推出 multi-agent v2。 Codex CLI v0.137.0 讓每個 thread 自行保有 runtime 選擇，為衍生的 agent 提供更簡潔的後續操作與中繼資料預設值（hide_spawn_agent_metadata 現已預設為 true），並將原始父層事件傳播給子層監聽器。其 subagent 模型仍採明確定義：內建 default／worker／explorer agent 類型、以 TOML 定義的自訂 agent，以及並行控制（agents.max_threads 預設為6，agents.max_depth 預設為1）。同一版本也加入 v1 skills 擴充功能，包括每回合解析 skill 目錄，以及新的 thread-start／turn-error 生命週期 contributor 事件；這在維持 kernel-sandbox 態勢作為預設邊界的同時，也縮小了與Claude Code hook／skill 介面之間的差距。接著，Codex v0.138.0–v0.139.0 強化 multi-agent v2，使其適用於正式環境：agent 之間的訊息 payload 現已加密；v2 agent 設定目錄搭配 agent-residency LRU，負責管理哪些 agent 保持常駐；並行數則改以執行中的活動計算，而非已衍生的 thread 數量，因此閒置 agent 不再占用名額。⁶¹ 生命週期API也更加成熟——close_agent 在 v0.139.0 中更名為 interrupt_agent，以反映其實際作用是中斷執行中的 agent，而非只是關閉控制代碼；此外，由 subagent 觸發的MCP啟動警告，現在會侷限於所屬 thread，不再向上複製至父層的逐字記錄。⁶¹ 對任何建置 Codex 端協調機制的人而言，這些正是展示原型與正式叢集之間的分水嶺：加密的訊息傳輸、設有上限的常駐機制、按執行活動計算的並行數，以及不會跨越 thread 邊界洩漏的警告。隨後，Codex v0.140.0 開啟了一道跨工具的接合面：/import 可選擇性地將設定、專案設定與近期聊天記錄從Claude Code匯入 Codex；工作階段也可永久刪除（codex delete／/delete，並設有確認防護措施）。⁶⁴ /import 首度正式承認維運人員會在不同 harness 之間移動——您為其中一個建立的設定，不再受困於該處。

記憶與上下文

每段 AI 對話都在有限的上下文視窗內運作。隨著對話內容增加，系統會壓縮較早的對話輪次，為新內容騰出空間。這種壓縮會造成資訊損失。第 3 輪記錄的架構決策，到了第 15 輪時可能已不復存在。⁹

多輪對話崩解的 3 種機制

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

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

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

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

MEMORY.md 檔案會記錄跨工作階段的錯誤、決策與模式。當您發現 VAR 為 0 時，((VAR++)) 在啟用 set -e 的 bash 中會失敗，便將此事記錄下來。3 個工作階段後，當您在 Python 遇到類似的整數邊界情況時，MEMORY.md 中的項目便會帶出這個模式。¹⁵

Auto Memory（v2.1.32+）：Claude Code 會自動記錄並回想專案上下文。工作期間，Claude 會將觀察結果寫入 ~/.claude/projects/{project-path}/memory/MEMORY.md。工作階段開始時，Auto memory 會將前 200 行載入系統提示詞。內容應保持精簡，詳細筆記則連結至個別主題檔案。⁶ 自 v2.1.210 起，若寫入 MEMORY.md 的內容超過大小限制，系統會回報錯誤，而非無聲截斷⁶⁹——問題會在寫入時浮現，不再讓記憶項目悄然消失。若您的 harness 會自動寫入記憶，請妥善處理此錯誤；這是平台在告知您該檔案需要整理，而不是要求重試。

重視記憶整理，而非記憶數量（2026年5月）：近期一篇探討 LLM-agent 協作的 arXiv 預印本指出，擴大回想範圍可能反而導致失敗：在作者的實驗中，較長的可見歷史記錄使 28 種模型博弈設定中的 18 種協作品質下降。⁴⁸ 應將此視為設計警訊，而非定論。實務上的原則已相當明確：保持 MEMORY.md 精簡、以連結導向詳細內容，並在交接文件中提供可直接用於決策的摘要。原始逐字稿、工具記錄與冗長的回想資料應存放於可搜尋的儲存空間，而不是自動放入當前提示詞。

策略 2：主動壓縮

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

適合執行壓縮的時機： - 完成一項獨立子任務後（功能已實作、錯誤已修正） - 開始處理程式碼庫的新區域之前 - Claude 開始重複內容或忘記先前上下文時 - 密集工作期間約每 25 至 30 分鐘一次

CLAUDE.md 中的自訂壓縮指示：

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

壓縮可保護對話；而 /cd 命令（Claude Code v2.1.169）則可保護提示詞快取。它能在不中斷目前流程的情況下，將工作階段移至新的工作目錄，同時保留該輪對話中已累積的快取。⁶⁰ 在此之前，變更目錄意味著必須建立新的工作階段，且快取需從零開始。若長時間執行的工作階段需要從某個儲存庫轉至同層的另一個儲存庫——這在 monorepo 與多服務工作中很常見——/cd 可保留成本高昂的已快取前置內容，同時將檔案系統上下文重新指向新位置。

策略 3：工作階段交接

對於橫跨多個工作階段的任務，請建立交接文件，完整記錄目前狀態：

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

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

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

若工作階段超過 60 至 90 分鐘，請為每次迭代啟動新的 Claude 執行個體。狀態透過檔案系統保存，而非仰賴對話記憶。每次迭代都能取得完整的上下文預算：¹⁶

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

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

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

每次迭代採用全新上下文的方法，會因準備步驟（讀取狀態檔案、掃描 git 歷史記錄）增加 15% 至 20% 的額外成本，但每次迭代都能運用完整的認知資源。¹⁶ 成本效益的衡量方式如下：工作階段若短於 60 分鐘，使用單一對話較有效率；超過 90 分鐘後，儘管存在額外成本，全新上下文仍能產出品質更高的結果。

策略 5：受管理的記憶整理（Dreaming）

Anthropic 的 Claude Managed Agents 已於 2026年5月6日新增 Dreaming Research Preview。³⁵ 根據 Anthropic 的說明：「Dreaming 是一項排程程序，會檢視您的 agent 工作階段與記憶儲存空間、擷取模式並整理記憶，讓您的 agents 能隨時間逐步改善。」³⁵

Dreaming 會在工作階段之間於背景執行，不會位於關鍵路徑上。它是檔案系統記憶模式的補充，而非替代方案：MEMORY.md 檔案仍是承載核心資訊的介面；Dreaming 則會將整理後的記憶項目寫入 Managed Agents 記憶儲存空間，agent 會在工作階段開始時讀取這些內容。對於同時採用自行託管檔案系統狀態與受管理端整理機制的 harness，這兩種模式可並行運作。

Dreaming 目前仍處於 Research Preview，行為可能有所變動。對於自行託管的 harness，上述工作階段交接與 CLAUDE.md 模式仍是權威的記憶機制。

反模式

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

在上下文中保留冗長的錯誤輸出。錯誤除錯完成後，上下文中可能仍保留 40 多份失敗迭代的堆疊追蹤。修正錯誤後執行一次 /compact，即可卸下這些無用負擔。

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

Subagents 模式

Subagents 是專門處理複雜任務的 Claude 執行個體，能夠獨立作業。它們會從乾淨的脈絡開始（不受主對話內容干擾），使用指定工具執行工作，並以摘要形式回傳結果。探索結果不會讓主對話變得臃腫；只有結論會回傳。⁵

內建 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 中作業，取得完整且隔離的儲存庫副本：⁵

---
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——而這正是此機制原本要防止的問題。⁶⁹ 若您將 isolation: worktree 視為安全邊界，而不只是便利功能，應以 v2.1.210 為最低版本。隨附的權限變更則朝另一個方向發展：自 v2.1.211 起，「always allow」規則會跨 worktrees 持續保存在儲存庫根目錄，因此在某個 worktree 中接受的規則，也會套用至同一儲存庫的其他 worktrees。⁶⁹ 這對平行運作的 worktree agents 而言確實更符合操作需求，但也代表在拋棄式實驗期間授予的允許會比實驗本身存續更久——授權時應考量整個儲存庫，而不只是眼前的 worktree。

v2.1.216 完成了最後一塊拼圖，讓 worktree 隔離從錯誤修正提升至可強制落實的等級。⁷⁴ v2.1.210 的修正可防止 worktree subagents 透過一般 git 呼叫修改主要 checkout，但 git 本身提供明確的重新導向方式——git -C <path>、--git-dir，以及 GIT_DIR/GIT_WORK_TREE 環境變數——採用 worktree 隔離的 subagent 仍可利用其中任一方式指向共用 checkout。如今，這些逃逸途徑已全數封鎖。同一版本也修正了 worktree sessions 偶爾進入「其他專案」殘留 worktree 的問題；防止 workflow 與排程任務的寫入操作跟隨置於 .claude 的符號連結，前往專案外部目標；並讓 /rewind 拒絕穿越符號連結與硬式連結。這四項修正一脈相承：隔離邊界必須能抵禦刻意的重新導向——例如 git 環境覆寫與植入符號連結——而不只是防範預設行為。若 isolation: worktree 在您的 harness 中是安全邊界，而非便利功能，v2.1.216 就是新的最低版本。

平行 Subagents

針對彼此無須協調的獨立研究任務，可使用平行 subagents：⁵

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

每個 agent 都會在自己的 context window 中執行、尋找相關程式碼，並回傳摘要。主脈絡得以保持乾淨。

遞迴防護

若未限制產生數量，agents 會委派給其他 agents，而後者又繼續委派給更多 agents；每一層都會流失脈絡並消耗 tokens。遞迴防護模式會強制執行預算：¹⁶

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

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

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

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

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

關鍵教訓：請使用產生預算，不要只靠深度限制。以深度為準的限制會追蹤父子鏈（在第 3 層封鎖），卻無法掌握寬度：深度 1 有 23 個 agents，仍然只是「深度 1」。產生預算會追蹤每個父項目前啟用的子項總數，並以可設定的上限加以約束。預算模型直接對應實際失敗模式（agents 總數過多），而不是替代指標（巢狀層級過多）。⁷

巢狀深度的預設值已變更 3 次；請勿以此為基礎建構系統。 Claude Code v2.1.172（2026年6月10日）允許 sub-agents 產生自己的 sub-agents，巢狀深度最多可達 5 層——此前的委派實際上僅有 1 層。⁶² 此設定從 v2.1.172 維持至 v2.1.216。v2.1.217（2026年7月21日）將其下調至 1，預設關閉巢狀產生。接著，v2.1.219（2026年7月24日）取折衷值：「Subagents 現在預設最多可產生深度 3 的巢狀 subagents（原為 1）；設定 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 即可停用巢狀結構。」⁸⁴ 先是 5，再降為 1，接著改成 3——後兩次變更僅相隔 3 天。

真正值得注意的不是其中任何一個數字是否正確，而是平台仍在摸索合適的預設值。因此，讓 harness 繼承「目前隨附的值」並非明智之舉。請將巢狀深度視為明確的預算項目：依架構的實際需求設定 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH——大多數協調架構只需 1 或 2——如此升級就不會悄然改變 agent 群的委派深度。無論預設值如何頻繁變動，核心論點始終不變：agents 委派給 agents 的鏈結，消耗脈絡與 tokens 的速度往往快過產出結果；深度是必須編列預算加以防範的風險，而不是應刻意追求的能力。無論預設值下一步如何漂移，上述遞迴防護都能避免深層樹狀結構擴散成數百個啟用中的 agents。唯有自行設定的限制，才能在下次版本發布後，仍維持您所理解的深度意義。

Auto mode 現在會在啟動前審查產生作業。 Claude Code v2.1.178 補上了對應的治理缺口：在 auto mode 中，subagent 產生作業會在 subagent 啟動「之前」由權限分類器評估，而不是等到它開始執行動作後才評估。⁶³ 過去可能產生一個 subagent，要求執行父 session 原本會遭封鎖的動作——產生作業本身就是繞過途徑。在產生階段進行審查，代表遞迴防護與權限模型終於接軌：子項無法再充當政策禁止動作的洗白步驟。

平台現在內建原生產生預算。 Claude Code v2.1.212（2026年7月）加入第一方失控迴圈防護：sessions 預設最多可產生 200 個 subagents（使用 CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 調整，/clear 會重設計數器），而 WebSearch 每個 session 最多可呼叫 200 次（CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION）。⁶⁹ 自 v1.0 起，本節一直將產生預算模式記錄為使用者空間指令碼，如今平台已原生提供——這也驗證了預算模型優於深度模型。但請留意其校準方式：200 次產生比上述設定中的 12-agent 預算高出一個數量級。原生上限是防止迴圈徹底失控的保險絲，而不是針對您的架構量身調校的預算。請保留使用者空間防護，以管理每個父項的預算、追蹤深度，並設定符合實際協調需求的限制；平台上限則負責攔截任何漏網之魚。

第一方防護現已涵蓋 4 個軸向。 其中 3 個正好為本節使用者空間防護所追蹤的項目提供後盾：每個 session 的產生總數（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）。⁷⁸⁸⁴ v2.1.219 新增第 4 個通常不存在於使用者空間防護中的軸向：協調寬度，也就是單一規劃 workflow 可包含的 agents 數量；其預設指引為「目標應少於 15 個 agents」，並可透過任何設定檔中的 workflowSizeGuideline 設定（詳見下方 Workflow Tool 一節）。產生預算模式現在於原先設計涵蓋的每個軸向都有後盾，還多了一個原先未涵蓋的軸向。

校準方面的提醒依然適用，但各軸向程度不一。200 次產生與 20 個並行 agents 都是保險絲——比上述設定中的 12-agent deliberation 預算高出一個數量級，其規模是為了攔截失控迴圈，而非塑造架構。寬度指引則是第一個與實際預算處於相同量級的原生數字：每個 workflow 15 個 agents，與本指南的 12 個相當接近。採用平台預設值幾乎無須付出代價；若選擇不同數字，理當具備充分理由。請將 3 個保險絲設為您能合理辯護的值，並讓寬度指引符合原本預期建構的協調形態。

Agent Teams（研究預覽）

Agent Teams 會協調多個獨立運作的 Claude Code 執行個體。它們透過共用信箱與任務清單溝通，並能彼此質疑對方的發現：⁵

啟用方式：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

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

Agent View 與目標迴圈（2026年5月）

Claude Code v2.1.139 新增 Agent View。這是一項研究預覽介面，可透過 claude agents 啟動，並在單一畫面中顯示執行中、受阻與已完成的 Claude Code sessions。⁴²⁴³ 官方文件將其定位為一種派送與管理多個 sessions 的方式，可查看每個 session 正在執行的工作，並找出哪些需要操作者介入。⁴³ 這讓多 agent 工作具備最終摘要無法提供的營運視圖。

將 subagent 或 team 模式推向實務運作時，請使用 Agent View 檢查哪些 sessions 受阻、哪些仍在執行，以及工作分配是否符合預期架構。切勿將它視為品質證明。它提供的是可觀測性；工作是否可靠，仍應由測試、審查閘門與 evidence reports 決定。

同一版本也新增 /goal，可設定完成條件，讓 Claude 跨 turns 持續執行，直到條件達成；互動式、-p 與 Remote Control 用法皆受支援。⁴² 請將 /goal 視為 session 範圍的完成迴圈，而非確定性閘門的替代品。它有助於讓 agent 專注於目標，但在失敗必須阻擋流程的情境中，測試、引用檢查、部署檢查與安全 hooks 仍應由命令或指令碼提供可靠後盾。

Workflow Tool（v2.1.147+）

Claude Code v2.1.147 新增預設關閉的 Workflow tool，用於確定性的多 agent 協調。設定 CLAUDE_CODE_WORKFLOWS=1 即可啟用。⁵² 從架構角度來看，此功能至關重要，因為它為 Claude Code 提供第一方協調原語，可處理過去必須依賴自訂派送指令碼、信箱狀態與 subagent 協調慣例的流程。

請勿因此刪除周邊 harness。Workflow 可以組織執行流程，卻無法取代您的安全模型。請保留 PreToolUse 與 PostToolUse hooks 作為阻擋層，保留產生預算或 workflow 步驟預算以防止寬度失控，確保檔案系統狀態可供稽核，並讓最終 evidence reports 獨立於模型的自我評估。實務上：使用 Workflow 塑造協調結構；使用 hooks、測試與審查閘門判定事實。

Dynamic workflows 現在對寬度提出明確主張（v2.1.219）。 Dynamic workflows 預設採用中型規模指引——「目標應少於 15 個 agents」——在 /config 的 Dynamic workflow size 中，另有其他規模與不受限制的選項；執行中的 workflow 狀態列也會顯示目前指引。⁸⁴ 此數字僅供建議，並不強制執行；它會引導 planner，而不是封鎖寬廣的計畫。真正值得設定的是其交付機制：新的 workflowSizeGuideline 設定鍵可在任何設定檔中設定——包括受管理設定與專案設定；自 v0.3.219 起，它也已納入 TypeScript SDK 設定類型——因此，協調寬度可由團隊或組織統一規範，不必讓每位操作者各自摸索。⁸⁵ 請在專案層級設定，以反映程式碼庫工作實際可拆解的方式。另有 2 點操作提醒：當設定檔正在提供此值時，/config 對應列會自行隱藏；這是正確行為，但若不清楚原因，可能會誤以為設定遺失。其次，由於此指引只會引導 planner 而不會阻擋執行，因此它屬於「結構」欄，而不是「安全」欄。寬度失控仍應由產生上限負責。

值得保留的觀點是：這是第 4 個第一方防護軸向——協調寬度，與產生數量、巢狀深度及並行執行並列——也是 Anthropic 第一個依合理工作規模校準，而非當作失控保險絲的軸向。每個 workflow 15 個 agents，與本指南自 v1.0 起使用的 12-agent deliberation 預算處於相同數量級。當平台預設值與您自己的預算從不同方向殊途同歸時，這幾乎就是此類數字所能獲得的最佳獨立佐證。

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

Claude Code v2.1.212 重塑了 2 個協調原語。⁶⁹ /fork 現在會從目前對話狀態建立一個新的背景 session——分支出的工作線會獨立執行，原始工作線則繼續運作——先前的 session 內行為已重新命名為 /subtask。這項區別對協調設計至關重要：/subtask 是單一 session 生命週期內範圍受限的支線；/fork 則能以低成本建立繼承完整脈絡的平行背景 session，更接近 Ralph-loop spawn，而非 subagent。若您的 harness 指令碼原本假設 /fork 會留在 session 內，現在它們將會派送背景工作。

同一版本也會自動將緩慢的 MCP 呼叫移至背景：若 MCP tool 呼叫執行超過 2 分鐘，就會自動轉為背景執行（可使用 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 調整門檻）。⁶⁹ 緩慢的 MCP 伺服器不再阻塞 agentic loop——但這也代表「工具回傳」與「turn 繼續」不再是同一事件。因此，原本假設 MCP 會同步完成的 hooks 或指令碼，應以工具結果為觸發依據，而非 turn 邊界。

針對 headless 協調，v2.1.211 新增 --forward-subagent-text（環境變數：CLAUDE_CODE_FORWARD_SUBAGENT_TEXT），可將 subagent assistant 文字轉送至 stream-json 輸出。⁶⁹ 消費父項 stream 的 coordinator process 現在可直接觀察 subagent 進度，無須輪詢 transcripts 或等待最終摘要——這正好補足預設在背景執行之 subagents 的可觀測性。v2.1.219 將此功能延伸至第一層之外：深度 2 或更深處產生的 subagents，現在也會出現在轉送的 stream 中，並以產生它們的 Agent tool_use id 作為索引鍵。⁸⁴ 這個索引鍵才是應當據以建構系統的部分。巢狀產生重新預設啟用後，扁平的 subagent 文字 stream 會產生歧義——該 id 可讓 coordinator 判斷哪個父項產生了哪個子項，進而從 stream 重建委派樹，而不必自行推斷。若您的 stream consumer 是依單層 subagents 編寫，現在會看到來自過去根本不知道存在之 agents 的文字；請依產生端的 tool_use id 分組，不要假設每一行轉送內容都屬於直接子項。

多代理人協作

單一代理人 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 讀完後仍會繼續撰寫未經測試的程式碼，因為其中沒有可執行的指示。

模稜兩可的指示。「處理資料庫遷移時務必謹慎」並不構成限制。「套用遷移前執行 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）：介於 high 與 max 之間。建議將其作為程式開發及代理式工作負載的預設值。對長時間執行的 subagents 而言，xhigh 的表現明顯優於 high，而 token 成本增加幅度相對較低。max 仍適合單次高難度推理；xhigh 則更適合持續性任務。
• Token 預算上限：可透過 output_config.task_budget 為每次 agent 執行進行設定（beta 標頭為 task-budgets-2026-03-13）。模型會看到持續倒數的預算，並依預算從容調整工作範圍，而不會意外耗盡。適合用於需要可預測 token 支出、同時又不希望犧牲短提示詞品質的代理式迴圈。
• 隱含需求感知：首個通過「隱含需求」測試的 Claude 模型，能辨識使用者的字面要求何時未能完整說明其實際需求。這降低了 CLAUDE.md 中「釐清規則」章節的必要性。若您的 CLAUDE.md 有 200 行「當使用者要求 Y 時，也要考慮 X」之類的防護規則，請刪除模型現已能原生處理的部分。

Worktree 基準、Sandbox 路徑與管理員設定（2026年5月7日）

Claude Code v2.1.133 新增 4 項值得生產環境 harness 留意的管理員層級設定：³⁹

worktree.baseRef 的回復是最需要提醒使用者的變更：若 agent 仰賴 v2.1.128 至 v2.1.132 的行為（worktree 從本機 HEAD 建立分支），除非明確選擇恢復該行為，否則在全新 worktree 中將無法存取尚未推送的工作。

適用於企業可觀測性的 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 程序，作為端點 agent、啟動時政策檢查，以及所有程序都必須在指定監督程式下執行之環境的整合點。若企業過去以 shell 別名或分支修改的啟動器指令稿勉強實現此功能，現在已有正式支援的介接點。

同一版本也降低了 harness 最有感的執行階段負擔：在 MCP 工具數量龐大的工作階段中，工具使用回合最快提升 7 倍，工作階段逐字記錄則縮小至多 79 倍。⁶⁸ 這在一定程度上緩和了以成本作為架構考量的指引，但並未將其推翻：對無狀態的單次操作而言，CLI 優先仍是最佳選擇；不過，搭載數十項 MCP 工具的 harness，不再承受春季版本中每回合的高額效能代價，逐字記錄儲存也不再是長時間自主執行的隱藏成本。

quality loop

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

1. 實作－撰寫程式碼
2. 審查－重新閱讀每一行，找出錯字、邏輯錯誤與語意不清之處
3. 評估－執行 evidence gate，檢查模式、邊界情況與測試涵蓋率
4. 精煉－修正所有問題，絕不推延至「稍後」處理
5. 綜觀全局－檢查整合點、匯入項目及相鄰程式碼是否出現迴歸
6. 重複－若任何 evidence gate 準則未通過，返回步驟 4
7. 報告－列出變更內容、驗證方式，並引用具體證據

evidence gate

「我相信」和「應該可以」都不算證據。請引用檔案路徑、測試輸出或特定程式碼。

若任一列無法提出證據，請返回「精煉」步驟。²²

人工合併權限

2026年5月一項針對 29,585 個 AI agent pull request 生命週期的 arXiv 研究，將作業執行權與合併治理區分開來。⁴⁷ 其架構啟示十分明確：agent 可以開始工作、延續分支、建立 PR、審查工作並摘要風險，而合併權限則維持為獨立的治理邊界。

請在 harness 中明確劃定此邊界。允許 agent 準備 PR 並蒐集證據；除非組織另有經過稽核的自動化政策，否則合併、發布及破壞性儲存庫操作都必須取得人工核准。若由自動化系統執行合併，請保留能區分實際執行者與授權該操作之人員或政策的記錄。

錯誤處理模式

不可分割的檔案寫入。多個 agent 同時寫入同一個狀態檔案會破壞 JSON。先寫入 .tmp 檔案，再以 mv 執行不可分割的移動操作。作業系統保證在同一檔案系統內，mv 是不可分割的操作。¹⁷

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

狀態毀損復原。若狀態毀損，復原模式會從安全預設值重新建立狀態，而非直接當機：¹⁶

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

((VAR++)) bash 陷阱。當 VAR 為 0 時，((VAR++)) 會傳回結束代碼 1，因為 0++ 的計算結果為 0，而 bash 將 0 視為 false。啟用 set -e 後，這會使指令稿終止。請改用 VAR=$((VAR + 1))。¹⁶

影響範圍分類

依影響範圍為每項 agent 操作分類，並設定相應的管控關卡：²

Remote Control（從任何瀏覽器或行動應用程式連線至本機 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 個 story 的 PRD 時所產生的工作階段追蹤記錄：²

1. SessionStart 觸發。dispatcher 注入：目前日期、專案偵測、理念限制條件、成本追蹤初始化。共 5 個 hooks，總計 180ms。

2. Agent 讀取 PRD，規劃第一個 story。UserPromptSubmit 觸發。dispatcher 注入：作用中專案背景資訊、工作階段偏移基準線。

3. Agent 呼叫 Bash 執行測試。PreToolUse:Bash 觸發。執行認證資訊檢查、sandbox 驗證、專案偵測，耗時 90ms。測試隨後執行。PostToolUse:Bash 觸發：記錄活動心跳並檢查偏移。

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

5. Agent 完成 story。Stop 觸發。quality gate 檢查：agent 是否引用證據？是否使用模稜兩可的措辭？diff 中是否有 TODO 註解？若任何檢查失敗，便以結束代碼 2 結束，agent 則繼續處理。

6. 獨立驗證：由全新的 agent 執行測試套件，不採信先前 agent 的自行報告。

7. 3 個程式碼審查 agent 平行產生。各自獨立審查 diff。若任何審查者標記 CRITICAL，該 story 就會返回佇列。

8. Story 通過，載入下一個 story。對全部 5 個 story 重複此循環。

處理 5 個 story 期間觸發的 hooks 總數：約 340 次。hooks 總耗時：約 12 秒。這些額外負擔在單次夜間執行中，防止了 3 次認證資訊外洩、1 次破壞性命令，以及 2 項未完成的實作。

案例研究：夜間 PRD 處理

某個生產環境 harness 在 8 個夜間工作階段中處理了 12 個 PRD（47 個 story）。下列指標比較前 4 個 PRD（最精簡的 harness：僅有 CLAUDE.md）與後 8 個（完整 harness：hooks、skills、quality gates、多 agent 審查）。

這 2 次認證資訊外洩導致必須輪替 API 金鑰並稽核下游服務，事件應變約耗費 4 小時。能防止同等事件的 harness 額外負擔，僅為每個 story 執行 2.4 秒的 bash。錯誤完成率從 35% 降至 4%，原因在於 Stop hook 會先獨立執行測試，再允許 agent 回報完成。

安全性考量

可信賴 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 互通性標準如今已不受特定供應商限制。²⁷

MCP 的無狀態回合與自行聲明的身分（2026年7月）。MCP 規格正處於轉向無狀態核心（SEP-2575）的過渡期，將移除過去用來傳遞伺服器身分的有狀態初始化交握。7月16日合併的一項規格草案變更（PR #3002）將身分恢復為一個選用介面：伺服器可在回應的 _meta 中加入 io.modelcontextprotocol/serverInfo 物件，而請求中的 clientInfo 則改為選用。⁷¹與安全性最相關的是規格對信任的說明：此身分是自行聲明且未經驗證，僅供顯示與記錄使用，不應作為安全決策的依據。如果您的 harness 根據 MCP 伺服器宣告的名稱來套用允許清單、權限規則或以記錄為基礎的稽核，請切記該名稱只是宣稱，而非憑證。信任應固定於傳輸與設定之上（也就是您在何種端點設定了哪一部伺服器），絕不可取決於伺服器如何自稱。最終版無狀態規格預定於2026年7月28日修訂完成，本節的通訊協定細節預計會在下次更新時更加明確。

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

沙箱

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

2026年5月的安全基準。Claude Code v2.1.149 修正了 PowerShell 工作目錄權限繞過問題、數個 PowerShell 允許規則及過期變數的權限分析缺口，以及一項 git worktree 沙箱寫入允許清單錯誤。該錯誤原先涵蓋整個主要儲存庫根目錄，而非僅限於共用的 git 內部資料。⁵³如果您的 harness 允許 PowerShell 或採用 worktree 隔離的 Agent，請將 v2.1.149 以上版本視為最低基準，並嚴格限縮 shell 規則。寬泛的 PowerShell(*) 與整個儲存庫的寫入例外只是編排捷徑，並非安全邊界。

OpenAI Agents SDK 沙箱封鎖強化（v0.17.0，2026年5月8日）。在 OpenAI 方面，openai-agents-python v0.17.0 收緊了另一項平行邊界：LocalFile.src 與 LocalDir.src 現在必須位於具體化作業的 base_dir 之內（套用資訊清單時 SDK 程序的目前工作目錄），除非來源已透過 Manifest.extra_path_grants 搭配 SandboxPathGrant 明確授權。⁴¹相對本機來源會以 base_dir 為基準解析；絕對路徑則必須已位於其中，或持有授權。這項修正封閉了本機成品邊界的問題：舊版允許資訊清單將主機上的任意路徑拉入沙箱工作區。遷移方式：若要唯讀掛載，請在資訊清單層級使用 SandboxPathGrant(path=..., read_only=True) 宣告受信任的主機根目錄。應將 extra_path_grants 視為受信任的應用程式設定；絕不可根據模型輸出或不受信任的資訊清單輸入來填入授權。

OpenAI Agents SDK 後續最低基準（v0.17.3）。0.17.1 至0.17.3系列進一步強化沙箱與工作階段，包括封存檔解壓縮限制、GitRepo 子路徑驗證、更明確的沙箱供應商錯誤、避免掛載點憑證出現在沙箱命令中、拒絕相對沙箱工作區根目錄，以及處理 Vercel 沙箱的終止狀態。⁵⁴如果您使用 OpenAI 託管或供應商支援的沙箱，而不只依賴 Claude Code hooks，請將0.17.3視為本節模式目前的最低基準。

各產品採用的三種圍堵模式（Anthropic，2026年5月）

Anthropic 的工程文章〈How we contain Claude across products〉（2026年5月25日）是供應商對本節各處所述原則的正式闡釋，包括上述設定層級沙箱、worktree 隔離基準，以及將一切視為不受信任的立場。⁸¹其核心做法，是依產品介面調整圍堵強度；而這項對應關係本身就是關鍵：不存在唯一正確的隔離設計，只能根據誰在監督，以及可能發生哪些問題來選擇相稱的隔離措施。

• 暫時性 gVisor 容器（claude.ai）。伺服器端執行作業會在隔離基礎設施上的 gVisor 容器中進行，並為每個工作階段提供暫時性檔案系統。其威脅模型著重於基礎設施與租戶隔離。由於完全無法觸及使用者的電腦，因此不需防護任何本機內容。
• 人類參與決策的作業系統沙箱（Claude Code）。這是上述沙箱段落所述模式的政策化表述：macOS 使用 Seatbelt，Linux 使用 bubblewrap；允許讀取、將寫入限制在工作區內，並預設拒絕網路存取。邊界未涵蓋的部分則交由人類核准。Anthropic 已將執行階段開放原始碼（sandbox-runtime），讓邊界可供稽核。該文章坦率指出其中的薄弱環節：約93%的權限提示都會獲得核准。Auto Mode 分類器則會在執行前攔截約83%的過度積極行為，同時將核准提示減少84%。這項機制之所以存在，正是因為核准疲勞屬於安全性問題，而非使用者體驗方面的抱怨。這正是本指南自 v2.1.193 起持續追蹤的檢查層立場。
• 密封式 VM（Claude Cowork）。完整的虛擬機器會在平台 Hypervisor 上執行——macOS 採用 Apple Virtualization framework，Windows 採用 HCS——且僅掛載所選工作區與 .claude 資料夾；主機上的其他內容一概不可見。憑證絕不會進入 VM，而是保留在主機鑰匙圈中；每個工作階段只會取得範圍受限、可獨立撤銷的權杖。VM 內的防禦性 MITM Proxy 會強制執行此機制，只允許帶有該 VM 自行佈建之工作階段權杖的請求通過。攻擊者嵌入的金鑰會在邊界遭到拒絕，因為只有 VM 知道其來源。

這套分類法背後的設計原則才是可以觸類旁通的部分。先在環境層圍堵，再於模型層引導：任何機率式防禦都有非零的漏判率，因此確定性邊界必須攔住提示詞層級引導所遺漏的情況。這也就是本指南所述「hooks 保證執行」的論點，由供應商換一種方式重申。讓隔離強度符合使用者的監督能力：開發人員能在核准前評估 bash 命令；知識工作者則未必能做到。因此 Code 採用權限對話框，而 Cowork 使用密封式 VM。優先採用久經考驗的基本機制，而非自行撰寫隔離程式碼：Hypervisor、seccomp 與容器執行階段所承受的對抗性檢驗，比 Anthropic 自行開發的允許清單 Proxy 與設定解析器更嚴苛。將專案本機設定與工具輸出視為不受信任：文章指示，應像處理任何來自網際網路的傳入請求一樣看待開啟專案與載入設定；即使工具本身受信任，其輸出仍是攻擊面。這與本指南對 Agent 間訊息、subagent 讀取的內容，以及自行聲明的 MCP 身分所採取的立場相同。將憑證留在沙箱之外：應使用範圍受限、可撤銷且每個工作階段獨立的權杖，而非 Agent 可能洩漏的環境常駐金鑰。

設定介面正逐步跟上第一項原則（v2.1.219）。「先在環境層圍堵」看似理所當然，實際設定卻一直不太順手。因為 Claude Code 沙箱對規則未涵蓋的情況會以提問解決；正如上述93%的核准率所顯示，權限提示只是披著確定性外衣的機率式防禦。sandbox.network.strictAllowlist 消除了對輸出流量的提問：啟用後，沙箱命令對不在允許清單中的主機提出請求時，系統會直接拒絕，而不會顯示提示。⁸⁴將其與 v2.1.216 的 sandbox.filesystem.disabled 搭配使用，兩項設定便能組成完整的安全態勢，而非雜亂無章的開關集合。檔案系統與網路圍堵可各自獨立選擇，而網路圍堵如今也能以確定性方式執行。對無人值守的 harness 而言，後者更為重要，因為注入指令正是透過輸出流量演變成資料外洩。核准疲勞的終極情況，就是鍵盤前根本無人可感到疲勞。其代價與所有確定性邊界相同：允許清單必須正確無誤，遺漏的主機將收到不透明的拒絕，而非詢問。請列出 Agent 合法需要存取的主機，然後移除提示機制。

上述措施都不能取代 hook 層，而是位於其下方。圍堵模式構成確定性的最低防線。本指南所記錄的 worktree 強制執行歷程，也以縮影形式傳達相同教訓：唯有在蓄意重新導向之下仍能守住，才稱得上邊界；最有可能守住的基本機制，往往不是為了眼前情境臨時打造的方案。

權限邊界

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

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

Claude Code v2.1.178 將權限規則從工具層級延伸到參數層級：Tool(param:value) 會比對工具的輸入參數，並以 * 作為萬用字元。標準範例是 Agent(model:opus)，此規則會阻止 subagents 使用特定模型層級產生。⁶³從架構角度來看，這項機制補足了上述四層表格無法表達的缺口：過去只能全面允許或拒絕某項工具，卻無法約束工具的呼叫方式。如今，治理政策可以透過確定性規則指出「subagents 可以產生，但不得使用 Fable 5 層級」，或「允許 Bash，但不得搭配這個旗標」，不再只是提示詞層級的要求。

配套的受管理設定 enforceAvailableModels（v2.1.175）會由上而下限制模型選擇：固定 Default 模型，並防止使用者或專案範圍的設定擴大受管理的 availableModels 允許清單。⁶³兩者可以相互配合：允許清單定義工作階段中可以使用哪些層級，參數層級規則則限制 subagents 如何從中選用。自 v2.1.196 起，管理員也能從組織主控台設定全組織預設模型，並在 /model 中顯示為「Org default」。如此一來，整個機群都能繼承受治理的預設值，不必由每位操作人員分別固定模型，形成與允許清單上限相輔相成的最低基準。

路徑範圍的允許規則會錨定於工作目錄（2026年7月）

Claude Code v2.1.214 修正了路徑範圍權限規則中一項不易察覺的過度比對問題：採用單一區段 dir/** 模式的允許規則（例如 Edit(src/**)），原先會自動核准對任意深度中任何名為 src 之目錄的編輯，包括 vendor/some-package/src/，以及規則作者從未打算授權的其他巢狀 src/ 目錄。如今，此類規則只會錨定於 <cwd>/dir；如果確實需要任意深度比對，請使用 **/dir/** 明確宣告。⁷⁴拒絕與詢問規則則刻意保留舊有的任意深度比對方式。這種不對稱正是正確的失效安全設計：允許規則比對範圍過窄時會安全失效（您會收到提示），拒絕規則比對過窄卻會開放失效（應封鎖的路徑會漏網）。因此，允許規則變得更嚴格，而拒絕規則維持寬泛。如果您的設定依賴單一區段的允許模式涵蓋巢狀路徑，升級至 v2.1.214 後便不再適用。這正是修正按預期運作的結果，但仍值得檢查允許清單，重新明確宣告實際需要的涵蓋範圍。

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）；並非由 Agent 在本工作階段建立之 commit 的 git commit --amend；以及基礎設施拆除操作（terraform destroy、pulumi destroy、cdk destroy），除非您指定了特定 stack。⁶⁵從架構角度來看，這是上述產生審查與參數層級規則的互補措施：它不管控使用哪一個工具，也不管控工具如何產生，而是依意圖管控一小組特定且不可逆的命令。Agent 仍可執行這些命令，但僅限於接獲明確指示時，不能擅自行動。對自主式 harness 而言，也應將相同原則編入自己的 PreToolUse hooks：會摧毀狀態的命令，理應預設拒絕，且只能由操作人員的明確訊號解除。

2026年7月：Auto Mode 進入企業環境，且有一項提示不可豁免。Auto Mode 在 v2.1.207 中正式於 Amazon Bedrock、Google Vertex AI 與 Microsoft Foundry 全面推出，並以受管理設定 disableAutoMode 作為企業停用選項。分類器作為檢查層的安全態勢，如今已可在每個第一方企業平台上使用；停用它是明確的治理決策，不再是平台能力的缺口。⁶⁸接著，v2.1.208 將災難性移除防護設為絕對規則：災難性移除的確認提示，現在會凌駕於 --dangerously-skip-permissions 與 Auto Mode 兩者。⁶⁸這是一項值得注意的先例，也是 Claude Code 中第一個無法由任何權限態勢豁免的確認提示，即使是明確的略過旗標亦然。若自主式 harness 的設計原先假設 --dangerously-skip-permissions 代表完全不會出現提示，就應將這項例外納入考量；它正好會在無人值守迴圈可能造成最嚴重且無法復原之損害的情況下觸發。

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

v2.1.203 至 v2.1.206 版本封閉了 Agent 捏造自身稽核軌跡的兩條路徑。⁶⁸首先，新增的 Auto Mode 規則會阻止竄改逐字稿檔案；工作階段紀錄不再能由該工作階段本身的工具呼叫改寫。其次，背景工作通知現在會明確指出，工作執行期間未發生任何人類輸入。第二項修正針對的是一種細微的失敗情況：模型彙整背景工作時，過去可能會在逐字稿中呈現（甚至捏造）一項從未發生的「核准」，而通知中沒有任何內容可加以反駁。現在，通知本身就是反證。

這項架構教訓也適用於 Evidence Gate：逐字稿、通知與記錄都是稽核介面，而稽核介面不得由其所稽核的對象寫入。平台如今已對自身逐字稿強制執行此原則；您的 harness 也應採用相同規則——證據報告、測試輸出與審議紀錄，均應置於模型可寫入路徑之外。

提示詞注入防禦

Skills 與 hooks 可提供多層次的提示詞注入防禦：

透過工具限制的 skills 可防止遭入侵的提示詞取得寫入權限：

allowed-tools: Read, Grep, Glob

無論模型收到何種提示，PreToolUse hooks 都會驗證每次工具呼叫：

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

Subagent 隔離可限制影響範圍。使用 permissionMode: plan 的 subagent 即使提示詞遭到入侵，也無法進行變更。

平台的安全基準於2026年7月提高。Claude Code v2.1.210 強化了 Agent tool，使其更能抵禦透過 subagent 所讀內容間接傳入的提示詞注入。無論是遭下毒的檔案、網頁，或由 subagent 取得的工具結果，都更難藉此操控委派介面本身。⁶⁹v2.1.211 則強化了鏈結中的人類環節：權限預覽現在會消除雙向文字覆寫、零寬度及外觀相似的 Unicode 字元所造成的影響，因此命令無法再被刻意製作成於核准對話框中看似無害，實際執行時卻另有所圖。⁶⁹第二項修正對於需要人類在時間壓力下核准轉譯預覽的 harness 尤為重要，因為顯示內容本身也是注入介面。這兩項變更都不能取代上述 hook 層級的防禦，而是提高其下方的最低安全基準。

Agent 記錄與防護規則也是安全介面

2026年5月的兩份安全公告進一步印證一項模式：Agent 基礎設施會創造新的位置，讓敏感內容與可執行政策發生洩漏或逸出。GitHub 公告 GHSA-f3jg-756w-gm35 涉及 Gryph Agents 的 payload 篩選問題；在預設記錄行為下，敏感的工具 payload 內容可能留存在本機 SQLite 記錄中。⁴⁵OSV GHSA-wxxx-gvqv-xp7p 則涉及 LiteLLM 的自訂程式碼 guardrail，可能從受管理員保護的 Proxy 端點逃逸沙箱。⁴⁶

正式環境的準則是：將 Agent 逐字稿、工具 payload、SQLite 記錄與 guardrail 執行視為敏感基礎設施。應在持久儲存前遮蔽敏感內容、套用保留期限，並確保自訂 guardrail 程式碼在沙箱中執行且可供審查。只在提示詞層級規定「不要記錄機密」並不足夠；記錄與 guardrail 路徑都需要確定性測試。

Hook 安全性

將環境變數插入標頭的 HTTP hooks，必須明確列出 allowedEnvVars 清單，以防止任意環境變數遭到外洩：¹³

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

人類與 Agent 的責任分工

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

其模式是：需要組織脈絡、倫理判斷或策略方向的決策由人類負責；需要在龐大可能性空間中進行運算搜尋的決策則由 Agent 負責。Hooks 會強制執行這項邊界。

遞迴式 Hook 強制執行

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

這不是選用功能。若 Agent 產生的 subagent 未套用您的安全 hooks，該 Agent 便能在閘門眼睜睜看著主要對話毫無動靜時，強制推送至 main、讀取憑證檔案或執行破壞性命令。

將成本視為架構

成本是一項架構決策，而非事後才考慮的營運問題。²可分為三個層級：

Token 層級。壓縮系統提示詞。移除教學式程式碼範例（模型已了解 APIs），合併分散於各檔案的重複規則，並以約束取代解釋。「拒絕符合敏感路徑的工具呼叫」與一段15行、解釋為何不應讀取憑證的文字，能達成相同效果。

Agent 層級。優先使用全新產生的 Agent，而非冗長對話。自主執行中的每個 story 都交由擁有乾淨脈絡的新 Agent 處理。由於每個 Agent 都從頭開始，脈絡不會無止境膨脹。應提供簡報而非記憶：相較於梳理累積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 會取消待執行的動作，並將 hook 的 stderr output 顯示給 model。Claude 會看到拒絕原因，並建議更安全的替代方案。Exit 1 則是非阻塞警告，動作仍會繼續執行。³

hook configuration files 應該放在哪裡？

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

每個決策都需要 deliberation 嗎？

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

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

成功路徑與失敗路徑都要測試。成功：agents 能有建設性地分歧，並達成共識。失敗：agents 太快收斂、始終無法收斂，或超出 spawn budgets。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 對 latency 的影響是什麼？

3-agent deliberation 會增加 30-60 秒的 wall-clock time（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 截斷，因此請把最關鍵的 instructions 放在前面：commands 與 closure definitions 應先於 style preferences。²¹

這能搭配 Claude Code 以外的工具使用嗎？

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

快速參考卡

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

關鍵指令

檔案位置

變更記錄

參考資料