Agent 架構：打造 AI 驅動的開發工具鏈

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

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

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

這個區別至關重要，因為基礎架構的效益會複合累積。一個在 bash 指令中攔截憑證的 hook，能保護每一次工作階段、每一個代理、每一次自主執行。一個編碼了您評估標準的 skill，無論是您手動呼叫還是代理自動觸發，都能一致地套用。一個負責程式碼安全審查的代理，不論您是否在旁監看，都會執行相同的檢查。²

核心要點

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

如何使用本指南

各章節依序遞進。最後的決策框架提供查找表，幫助您針對不同問題類型選擇合適的機制。

為何代理架構至關重要

Simon Willison 對當前時代的觀察可以歸結為一句話：寫程式碼現在很廉價。⁸ 沒錯。但其推論是：驗證才是真正昂貴的環節。缺乏驗證基礎設施的廉價程式碼，只會大規模地產生錯誤。真正值得投資的不是更好的提示詞，而是模型周圍那套能捕捉模型遺漏的系統。

三股力量使代理架構成為必要：

上下文視窗是有限且有損的。 每次讀取檔案、工具輸出和對話輪次都會消耗 token。Microsoft Research 和 Salesforce 針對 15 個 LLM 進行了超過 200,000 次模擬對話測試，發現從單輪互動到多輪互動，平均效能下降了 39%。⁹ 這種衰退最早在兩輪對話後就開始出現，並遵循可預測的曲線：前 30 分鐘精確的多檔案編輯，到第 90 分鐘就退化為單一檔案的隧道視野。更長的上下文視窗無法解決這個問題。同一研究中的「Concat」條件（將完整對話作為單一提示詞）在相同內容下達到了單輪效能的 95.1%。衰退來自輪次邊界，而非 token 限制。

模型行為是機率性的，而非確定性的。 告訴 Claude「編輯檔案後務必執行 Prettier」，大約 80% 的時間有效。³ 模型可能會遺忘、優先考慮速度，或認為改動「太小」而跳過。對於合規性、安全性和團隊標準而言，80% 是不可接受的。Hooks 保證執行：每次 Edit 或 Write 都會觸發格式化工具，每一次，毫無例外。確定性勝過機率性。

單一視角無法覆蓋多維度問題。 一個代理審查某個 API 端點時，檢查了身份驗證、驗證了輸入過濾，並確認了 CORS 標頭，給出了「一切正常」的結論。另一個代理以滲透測試者的角色獨立分析，卻發現該端點接受無界限的查詢參數，可能透過資料庫查詢放大觸發阻斷服務攻擊。⁷ 第一個代理從未檢查這一點，因為其評估框架中沒有將查詢複雜度視為安全攻擊面。這是結構性的缺陷，再多的提示詞工程也無法修補。

代理架構同時解決了這三個問題：hooks 強制執行確定性約束，subagents 管理上下文隔離，多代理協作提供獨立視角。三者共同構成了 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 提供在每次匹配的工具呼叫時觸發的確定性閘門。Memory 檔案在工作階段之間持久化狀態。自訂 agents 提供專門的 subagent 設定。

協作層： 多代理模式協調獨立的代理進行研究、審查和討論。生成預算防止遞迴失控。共識驗證確保品質。

關鍵洞察：大多數使用者僅在核心層工作，眼看著上下文膨脹和成本攀升。進階使用者會設定指令層和擴展層，然後僅將核心層用於協作和最終決策。²

Harness 在磁碟上的樣貌

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

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

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

Skills 系統

Skills 是由模型調用的擴展功能。Claude 會根據上下文自動發現並套用它們，無需您明確呼叫。⁴ 當您發現自己在不同工作階段中反覆解釋相同的上下文時，就是該建立 skill 的時機。

何時該建立 Skill

Skills 是讓 Claude 隨時具備的知識。斜線指令是 您明確觸發的操作。若難以抉擇，不妨自問：「Claude 應該自動套用這個，還是由我決定何時執行？」

建立 Skill

Skills 可存放在四個位置，從最廣到最窄的作用範圍依序為：⁴

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

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

# Code Review Expertise

## 安全檢查
審查程式碼時，請驗證以下要點：

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

### 身份驗證
- 每個受保護的端點皆驗證 session token
- 資料變更前執行權限檢查
- 原始碼中不包含寫死的憑證或 API 金鑰

Frontmatter 欄位參考

Description 欄位至關重要

在工作階段啟動時，Claude Code 會擷取每個 skill 的 name 和 description，並注入 Claude 的上下文中。當您送出訊息時，Claude 透過語言模型推理來判斷是否有相關的 skill 適用。對 Claude Code 原始碼的獨立分析證實了此機制：skill 描述會被注入系統提示詞的 available_skills 區段中，模型運用標準的語言理解能力來選擇相關的 skill。¹⁰

不佳的描述：

description: Helps with code

有效的描述：

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

有效的描述包含三個要素：做什麼（針對特定問題類型審查程式碼）、何時使用（檢視變更、審查 PR、分析品質），以及使用者自然會輸入的觸發詞彙（review、audit、check）。

Context 預算

所有 skill 描述共享一個 context 預算，此預算以 context window 的 2% 動態調整，回退值為 16,000 個字元。⁴ 若您擁有大量 skill，請保持每個描述精簡扼要。可透過 SLASH_COMMAND_TOOL_CHAR_BUDGET 環境變數覆寫預算上限，¹¹ 但更根本的做法是撰寫更短、更精確的描述。在工作階段中執行 /context 即可檢查是否有 skill 被排除在外。

輔助檔案與目錄結構

Skill 可引用同一目錄下的其他檔案：

~/.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 共享 Skill

專案層級的 skill（位於版本庫根目錄的 .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，無需安裝，無需設定。這是在團隊間標準化專業知識最有效的方式。

Skill 作為提示詞庫

除了單一用途的 skill 之外，目錄結構本身就是一個有條理的提示詞庫：

~/.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 會依據上下文自動取用。即便是資淺開發者，也能在無需主動詢問的情況下獲得資深級的指引。

Skill 與 Hook 的組合應用

Skill 可在 frontmatter 中定義專屬的 hooks，這些 hooks 僅在該 skill 執行期間生效。如此便能建立特定領域的行為，而不會影響其他工作階段：²

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

Philosophy skill 透過 SessionStart hooks 自動啟用，在每次工作階段中注入品質約束，無需明確調用。Skill 本身是知識，hook 則是執行機制，兩者結合形成一個策略層。

常見的 Skill 設計錯誤

描述範圍過廣。 例如一個 git-rebase-helper skill 在任何 git 相關提示（rebase、merge、cherry-pick，甚至 git status）時都會啟用，導致 80% 的工作階段中上下文被不必要地佔用。解決方法是收窄描述範圍，或加上 disable-model-invocation: true 並要求使用者以 /skill-name 明確調用。⁴

過多 skill 爭搶預算。 Skill 越多，描述就越多，都在競爭那 2% 的 context 預算。若發現 skill 未如預期啟用，請執行 /context 檢查哪些被排除了。與其擁有大量模糊的 skill，不如精選少數描述精確的 skill。

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

Hook 架構

Hook 是由 Claude Code 生命週期事件觸發的 shell 命令。³ 它們在 LLM 之外以純腳本執行，而非由模型解讀的提示詞。模型想執行 rm -rf /？一段 10 行的 bash 腳本會將指令比對黑名單，在 shell 接觸到之前就予以攔截。無論模型是否願意，hook 都會觸發。

可用事件

Claude Code 提供橫跨六大類別共 22 個生命週期事件：¹³

結束碼語意

結束碼決定 hook 是否阻擋操作：³

關鍵： 所有安全 hook 必須使用 exit 2，而非 exit 1。Exit 1 僅是非阻擋警告，危險指令仍會執行。這是團隊間最常見的 hook 錯誤。¹⁴

Hook 設定

Hook 存放於設定檔中。專案層級（.claude/settings.json）用於共享 hook，使用者層級（~/.claude/settings.json）用於個人 hook：

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

matcher 欄位是用於比對工具名稱的正規表達式：Bash、Write、Edit、Read、Glob、Grep、Agent，或以 * 匹配所有工具。對於 UserPromptSubmit 等不涉及工具的事件，使用 ""（空字串）。

Hook 輸入/輸出協定

Hook 透過 stdin 接收 JSON，包含完整上下文：

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

進階控制方面，PreToolUse hook 可輸出 JSON 來修改工具輸入、注入上下文或做出權限決策：

{
  "hookSpecificOutput": {
    "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 之前，先問自己：需要哪種保障？¹⁴

格式保障確保事後的一致性。PostToolUse hook 在 Write/Edit 後執行格式化工具。模型的輸出內容無關緊要，因為格式化工具會統一處理一切。

{
  "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'"
          }
        ]
      }
    ]
  }
}

安全保障在危險操作執行前予以阻止。PreToolUse hook 針對 Bash 檢查指令，並以結束碼 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

品質保障在決策點驗證狀態。PreToolUse hook 針對 git commit 指令執行 linter 或測試套件，品質檢查未通過則阻擋提交：

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

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

Shell 指令以外的 Hook 類型

Claude Code 支援三種 hook 類型：¹³

指令 hook（type: "command"）執行 shell 腳本。快速、確定性高、無 token 成本。

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

代理 hook（type: "agent"）啟動具備工具存取權限（Read、Grep、Glob）的 subagent，進行多輪驗證。適用於需要檢查實際檔案或測試輸出的場景：

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

非同步 Hook

Hook 可在背景執行而不阻擋主流程。為通知和記錄等非關鍵操作加上 async: true：¹³

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

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

使用 Dispatcher 取代獨立 Hook

七個 hook 同時對同一事件觸發、各自獨立讀取 stdin，會產生競爭條件。兩個 hook 同時寫入同一個 JSON 狀態檔會導致 JSON 被截斷，所有下游解析該檔案的 hook 都會失敗。²

解法：每個事件使用一個 dispatcher，從快取的 stdin 依序執行 hook：

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

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

除錯 Hook

五種針對靜默失敗 hook 的除錯技巧：¹⁴

1. 獨立測試腳本。 傳入範例 JSON：echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. 使用 stderr 輸出除錯資訊。 寫入 stderr 的內容會出現在 Claude 的上下文中。
3. 留意 jq 失敗。 錯誤的 JSON 路徑會靜默回傳 null。務必用真實的工具輸入測試 jq 表達式。
4. 驗證結束碼。 PreToolUse hook 若使用 exit 1，看似正常運作實則毫無阻擋效果。
5. 保持 hook 快速。 Hook 以同步方式執行。所有 hook 應控制在 2 秒內，理想值為 500 毫秒以下。

記憶與上下文

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

多輪崩潰的三大機制

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

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

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

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

MEMORY.md 檔案用於跨工作階段記錄錯誤、決策和模式。當您發現 ((VAR++)) 在 bash 中搭配 set -e 且 VAR 為 0 時會失敗，便將其記錄下來。三次工作階段後，當遇到 Python 中類似的整數邊界案例時，MEMORY.md 的記錄便會浮現這個模式。¹⁵

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

策略 2：主動壓縮

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

何時進行壓縮： - 完成一個獨立子任務後（功能實作完成、錯誤修正完畢） - 開始處理程式碼庫的新區塊前 - 當 Claude 開始重複或遺忘先前的上下文時 - 密集工作階段中大約每 25-30 分鐘一次

可在 CLAUDE.md 中自訂壓縮指示：

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

策略 3：工作階段交接

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

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

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

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

當工作階段超過 60-90 分鐘，建議為每次迭代啟動全新的 Claude 實例。狀態透過檔案系統而非對話記憶來持久化，每次迭代都能獲得完整的上下文額度：¹⁶

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

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

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

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

反模式

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

將冗長的錯誤輸出留在上下文中。 除錯完畢後，上下文中可能殘留 40 筆以上失敗迭代的堆疊追蹤。修正錯誤後執行一次 /compact 即可釋放這些無用負擔。

每次開始工作階段都讀取所有檔案。 善用 Claude Code 的 glob 和 grep 工具按需搜尋相關檔案，可省下超過 100,000 個 token 的不必要預載。¹⁵

Subagent 模式

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

內建 Subagent 類型

建立自訂 Subagent

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

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

You are a senior security engineer reviewing code for vulnerabilities.

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

Focus on actionable security findings, not style issues.

Subagent 設定欄位

Worktree 隔離

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

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

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

Worktree 隔離對於可能破壞程式碼庫的實驗性工作至關重要。

平行 Subagent

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

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

每個 agent 在各自的上下文視窗中運行，找到相關程式碼後回傳摘要。主上下文維持乾淨不受影響。

遞迴防護機制

若缺乏產生限制，agent 會不斷委派給其他 agent，層層遞迴，逐步失去上下文並消耗大量 token。遞迴防護模式透過預算機制加以約束：¹⁶

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

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

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

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

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

關鍵教訓： 應使用產生預算，而非僅靠深度限制。深度限制追蹤的是父子鏈（在深度 3 時被阻擋），卻忽略了廣度問題：在深度 1 有 23 個 agent 仍然算是「深度 1」。產生預算追蹤的是每個父 agent 的活躍子 agent 總數，上限可自行設定。預算模型直接對應實際的失敗模式（活躍 agent 總數過多），而非間接的代理指標（巢狀層級過深）。⁷

Agent Teams（研究預覽）

Agent Teams 協調多個 Claude Code 實例，各自獨立運作，透過共享信箱與任務清單溝通，並能互相質疑彼此的發現：⁵

啟用方式：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

何時使用 Agent Teams 與 Subagent：

多代理協調

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

最小可行審議

從 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： 獨立代理各自調查主題。每個代理被賦予不同角色（技術架構師、安全分析師、效能工程師等）。脈絡隔離確保代理在研究階段無法看到彼此的發現。

DELIBERATION： 代理查看所有研究發現並提出替代方案。辯論代理識別衝突點，綜合代理整合不矛盾的發現。

RANKING： 每個代理依據 5 個加權維度為每個提案方案評分：

雙閘門驗證架構

兩道驗證閘門在不同階段攔截問題：⁷

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

閘門 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。

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

缺少少數觀點： 利益衝突的角色（安全分析師與效能工程師鮮少在所有事項上意見一致）卻一致通過審核。

一致性偵測器能捕捉到明顯的案例（約 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 代理的操作策略，而非給人類閱讀的 README。²¹ 代理不需要理解為何使用 conventional commits，它需要知道確切要執行的指令，以及「完成」的定義是什麼。

優先順序層級

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

會被忽略的內容

以下模式幾乎不會對代理行為產生可觀察的影響：²¹

不含指令的散文段落。「我們重視乾淨、經過良好測試的程式碼」只是文件，不是操作指示。代理讀完後依然會寫出沒有測試的程式碼，因為缺乏可執行的指令。

模糊的指示。「處理資料庫遷移時要小心」不是約束條件。「在套用遷移前執行 alembic check，若缺少降級路徑則中止。」才是。

矛盾的優先順序。「快速推進並盡早交付」加上「確保全面的測試覆蓋」加上「執行時間控制在 5 分鐘內」加上「每次提交前執行完整的整合測試」。代理無法同時滿足這四項要求，最終會預設跳過驗證。²¹

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

有效的做法

指令優先的說明：

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

完成條件的定義：

## 完成定義
當以下所有條件皆通過時，任務才算完成：
1. `ruff check .` 回傳 0
2. `pytest -v` 回傳 0 且無失敗
3. `mypy app/ --strict` 回傳 0
4. 已變更的檔案已暫存並提交
5. 提交訊息遵循慣例格式：`type(scope): description`

依任務組織的區段：

## 撰寫程式碼時
- 每次修改檔案後執行 `ruff check .`
- 為所有新函式添加型別提示

## 審查程式碼時
- 檢查安全性問題：`bandit -r app/`
- 驗證測試覆蓋率：`pytest --cov=app --cov-fail-under=80`

## 發佈時
- 更新 `pyproject.toml` 中的版本號
- 執行完整測試套件：`pytest -v && ruff check . && mypy app/`

升級處理規則：

## 遇到阻礙時
- 若測試連續失敗 3 次：停止並回報失敗的測試及完整輸出
- 若缺少相依套件：先檢查 `requirements.txt`，再提出詢問
- 絕對禁止：刪除檔案來解決錯誤、強制推送、或跳過測試

撰寫順序

若從零開始，依以下優先順序新增區段：²¹

1. 建置與測試指令（代理在能做任何有用的事之前，需要這些指令）
2. 完成定義（防止虛假的完成判定）
3. 升級處理規則（防止破壞性的變通做法）
4. 依任務組織的區段（減少不相關的指令解析）
5. 目錄範圍界定（monorepo：將服務指令隔離）

在前四項運作正常之前，先略過風格偏好設定。

檔案匯入

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

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

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

跨工具指令相容性

AGENTS.md 是一個開放標準，已被超過 60,000 個專案採用，且受到所有主流 AI 程式碼工具的支援。²¹ 若您的團隊使用多種工具，請以 AGENTS.md 作為權威來源，再將相關區段同步至各工具專屬的檔案：

AGENTS.md 中的模式（指令優先、閉包定義、依任務組織）適用於任何指令檔案，不限特定工具。切勿維護多套各自偏移的平行指令集——撰寫一份權威來源，再進行同步即可。

測試您的指令

驗證代理確實讀取並遵循您的指令：

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

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

最終驗證： 請代理解釋您的建置指令。若它無法逐字重現，表示指令不是太冗長（內容被推出上下文之外）、就是太模糊（代理無法擷取可執行的指令），或是根本未被發現。GitHub 對 2,500 個儲存庫的分析發現，模糊性是導致大多數失敗的主因。²¹

正式環境模式

Quality Loop

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

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

Evidence Gate

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

若任一列無法提供證據，回到精煉步驟。²²

錯誤處理模式

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

影響範圍分級

依影響範圍對每個代理動作進行分級，並據此設置關卡：²

Remote Control（從任何瀏覽器或行動應用程式連接到本機 Claude Code）將「外部」關卡從阻塞等待轉為非同步通知。代理在您透過手機審核前一項任務時，可繼續處理下一項任務。²

自主執行的任務規格

有效的自主任務包含三個要素：目標、完成條件與上下文指引：¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

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

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

條件必須可由機器驗證：測試通過/失敗、檢查工具輸出、HTTP 狀態碼、檔案存在性檢查。早期有一項任務要求代理「撰寫能通過的測試」，結果產出了 assert True 和 assert 1 == 1——技術上正確，實務上毫無價值。¹⁶

應注意的失敗模式

具體的工作階段追蹤

以下是一個自主執行的工作階段追蹤紀錄，處理包含 5 個 story 的 PRD：²

1. SessionStart 觸發。 Dispatcher 注入：當前日期、專案偵測、設計哲學約束、成本追蹤初始化。五個 hooks，共 180 毫秒。

2. 代理讀取 PRD，規劃第一個 story。 UserPromptSubmit 觸發。Dispatcher 注入：活躍專案上下文、工作階段偏移基準線。

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

4. 代理呼叫 Write 建立檔案。 PreToolUse:Write 觸發：檔案範圍檢查。PostToolUse:Write 觸發：程式碼檢查、提交追蹤。

5. 代理完成該 story。 Stop 觸發。品質關卡檢查：代理是否引用了證據？是否有模稜兩可的用語？差異中是否有 TODO 註解？若任一檢查未通過，回傳退出碼 2，代理繼續作業。

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

7. 三個程式碼審查代理平行啟動。 各自獨立審查差異。若任一審查者標記為 CRITICAL，該 story 將重新排入佇列。

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

5 個 story 中觸發的 hooks 總數：約 340 次。Hooks 總耗時：約 12 秒。這些開銷在單次通宵執行中，阻止了三次憑證洩漏、一次破壞性指令，以及兩次不完整的實作。

安全考量

沙箱機制

Claude Code 在沙箱環境中運行，限制網路存取與檔案系統操作。沙箱可防止模型發出任意網路請求，或存取專案目錄以外的檔案。¹³

權限邊界

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

提示注入防禦

Skills 與 hooks 提供縱深防禦，抵禦提示注入攻擊：

附帶工具限制的 skills 能防止遭入侵的提示取得寫入權限：

allowed-tools: Read, Grep, Glob

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

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

Subagent 隔離 限縮影響範圍。即使提示遭到入侵，設定為 permissionMode: plan 的 subagent 也無法進行任何修改。

Hook 安全性

將環境變數內插至標頭的 HTTP hooks，需要明確指定 allowedEnvVars 清單，以防止任意環境變數外洩：¹³

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

人類與代理的責任劃分

代理架構中的安全性，需要人類與代理之間有清晰的責任分工：¹⁷

其核心模式為：人類負責需要組織脈絡、倫理判斷或策略方向的決策；代理負責需要在龐大可能性空間中進行運算搜尋的決策。Hooks 則負責執行兩者之間的界線。

遞迴 Hook 執行

Hooks 也會對 subagent 的操作觸發。¹³ 若 Claude 透過 Agent tool 產生 subagent，您的 PreToolUse 和 PostToolUse hooks 會針對 subagent 使用的每一個工具執行。若缺少遞迴 hook 執行機制，subagent 便可能繞過安全關卡。SubagentStop 事件則讓您在 subagent 完成時執行清理或驗證。

這並非可有可無。一個在不受安全 hooks 監管的情況下產生 subagent 的代理，等同於一個可以強制推送到 main、讀取憑證檔案、或執行破壞性指令的代理——而您的安全關卡只能眼睜睜看著主對話毫無作為。

成本即架構

成本是架構決策，而非事後的營運考量。² 分為三個層級：

Token 層級。 壓縮系統提示。移除教學用的程式碼範例（模型已熟悉相關 API），合併跨檔案的重複規則，並以簡潔的約束取代冗長的說明。「拒絕匹配敏感路徑的工具呼叫」與 15 行解釋為何不應讀取憑證的效果相同。

代理層級。 以全新產生取代漫長對話。自主運行中的每個 story 都由一個全新代理在乾淨的上下文中執行，上下文不會因此膨脹。簡報優於記憶：模型執行一份清晰的簡報，遠勝於在累積 30 步的上下文中摸索前行。

架構層級。 當操作為無狀態時，優先選擇 CLI 而非 MCP。一次性評估使用 claude --print 呼叫，成本更低且無連線開銷。MCP 則適用於需要持久狀態或串流的場景。

決策框架

何時使用何種機制：

Skills vs Hooks vs Subagents

常見問題

多少 hooks 才算太多？

效能才是限制，而非數量。每個 hook 同步執行，因此 hook 總執行時間會加到每次匹配的工具呼叫上。95 個 hooks 分布於使用者層級與專案層級設定中，只要每個 hook 在 200ms 內完成，就不會有明顯延遲。需要留意的閾值是：若 PostToolUse hook 對每次檔案編輯增加超過 500ms，session 就會明顯遲鈍。部署前請用 time 對 hooks 進行效能分析。¹⁴

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

可以。PreToolUse hooks 以 exit code 2 退出即可阻擋任何工具操作。Claude Code 會取消待執行的操作，並將 hook 的 stderr 輸出呈現給模型。Claude 看到拒絕原因後會建議更安全的替代方案。Exit 1 則為非阻擋性警告，操作仍會繼續執行。³

Hook 設定檔應該放在哪裡？

Hook 設定放在 .claude/settings.json 為專案層級 hooks（提交至版本庫，與團隊共享），或放在 ~/.claude/settings.json 為使用者層級 hooks（個人使用，套用於所有專案）。兩者同時存在時，專案層級 hooks 優先。腳本檔案請使用絕對路徑，以避免工作目錄問題。¹⁴

每個決策都需要審議嗎？

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

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

需要測試成功路徑與失敗路徑。成功：代理之間產生建設性分歧並達成共識。失敗：代理過早趨同、始終無法收斂、或超出產生預算。端對端測試以確定性代理回應模擬每種情境，驗證兩個驗證關卡能捕捉所有已記錄的失敗模式。一個正式環境的審議系統會執行 141 個測試，橫跨三個層級：48 個 bash 整合測試、81 個 Python 單元測試，以及 12 個端對端流程模擬。⁷

審議的延遲影響為何？

3 個代理的審議會增加 30-60 秒的實際時間（代理透過 Agent tool 依序執行）。10 個代理的審議則增加 2-4 分鐘。共識檢查與 pride check hooks 各在 200ms 內完成。主要瓶頸在於每個代理的 LLM 推理時間，而非編排開銷。⁷

CLAUDE.md 檔案應該多長？

每個區段控制在 50 行以內，整個檔案不超過 150 行。過長的檔案會被上下文窗口截斷，因此請將最關鍵的指示放在最前面：指令與閉包定義優先於風格偏好。²¹

這套方法適用於 Claude Code 以外的工具嗎？

架構原則（hooks 作為確定性關卡、skills 作為領域專業知識、subagents 作為隔離上下文、檔案系統作為記憶）在概念上適用於任何代理系統。具體實作使用了 Claude Code 的生命週期事件、匹配模式與 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 前置資訊

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

結束代碼

常用指令

檔案位置

變更日誌

參考資料