建立自訂 subagents

• 保留上下文，將探索和實現保持在主要對話之外
• 強制執行約束，限制 subagent 可以使用的工具
• 跨專案重複使用配置，使用使用者層級的 subagents
• 專門化行為，針對特定領域使用專注的系統提示
• 控制成本，將任務路由到更快、更便宜的模型，如 Haiku

​

內建 subagents

• 若要封鎖特定的內建類型，請將其新增至 permissions.deny，如停用特定 subagents 中所示。
• 若要防止 Claude 委派給任何 subagent，請使用 permissions.deny 拒絕 Agent 工具本身。
• 若要僅移除內建的 Explore 和 Plan subagents，請設定 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1。Claude 會直接讀取和探索檔案，而不是委派給它們。需要 Claude Code v2.1.198 或更新版本。
• 在非互動式模式和 Agent SDK 中，設定 CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 以移除所有內建類型，並僅提供您自己的。

​

快速入門：建立您的第一個 subagent

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Use the code-improver agent to suggest improvements in this project

​

設定子代理

​

選擇子代理範圍

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

• prompt：代理的系統提示，等同於檔案型子代理中的 markdown 主體。prompt 可能為空。如果您使用 --agent 選擇一個具有空 prompt 且沒有 memory 欄位的代理作為工作階段的代理，工作階段的系統提示保持不變。空 prompt 需要 Claude Code v2.1.281 或更新版本。
• Frontmatter 欄位：description、tools、disallowedTools、model、permissionMode、mcpServers、hooks、maxTurns、skills、initialPrompt、memory、effort、background、omitClaudeMd 和 isolation。
• 忽略的欄位：color 和 experimental 在此不被接受，被忽略而不是拒絕。

​

編寫子代理檔案

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

• 它阻止將 git 重定向到主簽出的命令。
• 當它無法從命令文字驗證命令執行的任何 git 都保留在 worktree 內時，它拒絕命令，例如當命令名稱在執行時計算時。

​

Frontmatter 參考

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

​

Claude Code 跳過的子代理檔案

• 沒有 name：Claude Code 將檔案視為保存在代理旁邊的文件。
• 不是檔案第一行的開啟 ---：Claude Code 讀取檔案為沒有 frontmatter，並將其視為文件。
• 以 - 開頭或包含 : 的 name：Claude Code 跳過檔案並將錯誤寫入偵錯日誌。請參閱上表中的 name 列。
• 有 name 但沒有 description：Claude Code 跳過檔案並將原因寫入偵錯日誌。
• 不解析的 YAML：Claude Code 不從檔案讀取任何欄位，跳過它，並將解析錯誤寫入偵錯日誌。

​

選擇模型

• 模型別名：使用可用別名之一：sonnet、opus、haiku 或 fable
• 完整模型 ID：使用完整模型 ID，例如 claude-opus-5-5 或 claude-sonnet-5。接受與 --model 旗標相同的值
• inherit：使用與主對話相同的模型

1. 每次叫用 model 參數
2. 子代理定義的 model frontmatter，其中 inherit 選擇主對話的模型
3. CLAUDE_CODE_SUBAGENT_MODEL 環境變數，當您將其設定為模型別名或模型 ID 時
4. 主對話的模型

• 主對話的模型屬於該家族：子代理在主對話的確切模型上執行，包括任何 [1m] 尾碼，因此它獲得與主對話相同的擴展上下文視窗。
• Claude Code 無法判斷主對話的模型家族，在Anthropic API 以外的提供者上：這可能發生在 Amazon Bedrock 上的應用程式推論設定檔 ARN，Claude Code 尚未解析為支援模型。此情況僅涵蓋 opus 別名，當您設定 ANTHROPIC_DEFAULT_OPUS_MODEL 時不適用，因為 opus 然後解析為您設定的模型。

• 當被阻止的值是家族別名（例如 opus）時，Claude Code 在允許清單允許的該家族的最新版本上執行子代理，遵循與 /model 相同的替換規則和提供者範圍。在 v2.1.222 之前，Claude Code 也在被阻止的家族別名的繼承模型上執行子代理。
• 對於任何其他被阻止的值，在該替換不操作的提供者上，或當允許清單允許該家族的沒有版本時，Claude Code 改為在繼承模型上執行子代理。如果您設定 CLAUDE_CODE_SUBAGENT_MODEL，Claude Code 首先嘗試該模型，在這些相同的規則下。

​

在一個模型上執行每個子代理

• 如果您設定兩個變數，子代理在 CLAUDE_CODE_SUBAGENT_MODEL 中的模型上執行。
• 如果您只設定 CLAUDE_CODE_SUBAGENT_MODEL_FORCE，subagent 會在主對話的模型上執行，但內建的 Explore subagent 例外，它會在內建 subagent 中為其列出的模型上執行。

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

• 分叉
• 在子代理中執行的技能，具有 model: inherit

​

控制子代理功能

​

可用工具

• Agent，當子代理在深度限制時；在分叉中工具保持列出但返回錯誤而不是生成
• AskUserQuestion
• EndConversation，只能結束主對話；請參閱EndConversation 工具行為
• EnterPlanMode
• ExitPlanMode，除非子代理的 permissionMode 是 plan
• ScheduleWakeup
• WaitForMcpServers
• Workflow

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

​

限制可以生成的子代理

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

tools: Agent, Read, Bash

​

將 MCP 伺服器範圍限於子代理

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

• 不計算的信任：父資料夾的信任，以及 -p 或 SDK 工作階段為設定檔中的 hooks獲得的自動信任
• 直到那時：Claude Code 跳過該代理檔案中的每個內聯伺服器，並將 ~/.claude.json 的確切 projects["<path>"].hasTrustDialogAccepted 鍵寫入偵錯日誌
• --add-dir 目錄：您受信任工作區儲存庫外的目錄需要自己的信任條目，因為其 .claude/agents/ 檔案不繼承您工作區的信任

• 參考您已設定的伺服器的名稱
• 來自 ~/.claude/agents/ 中代理檔案的內聯伺服器，在您使用 --agents 或 SDK agents 選項傳遞的檔案中，或受管設定提供的檔案中

• --strict-mcp-config 和 --bare
• 企業受管 MCP 設定
• allowedMcpServers 和 deniedMcpServers 原則

​

權限模式

• 當主對話在 bypassPermissions、acceptEdits 或自動模式中時，子代理在該相同模式中執行，Claude Code 忽略您設定的 permissionMode。在自動模式下，分類器使用主對話的阻止和允許規則評估子代理的工具呼叫。當子代理完成時，分類器也在報告被傳遞之前檢查其工作和最終報告，如自動模式如何處理子代理所述。
• 當主對話在 default、dontAsk 或 plan 模式中時，子代理在您設定的權限模式中執行，除了 bypassPermissions。宣告 bypassPermissions 的子代理保持主對話的模式。bypassPermissions 例外需要 Claude Code v2.1.267 或更新版本。

​

將技能預載入子代理

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

​

啟用持久記憶

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

• 子代理的系統提示包括讀取和寫入記憶目錄的指示。
• 子代理的系統提示也包括記憶目錄中 MEMORY.md 的前 200 行或 25KB（以先到者為準），以及如果超過該限制則策劃 MEMORY.md 的指示。
• Read、Write 和 Edit 工具自動啟用，以便子代理可以管理其記憶檔案。

• project 是推薦的預設範圍。它使子代理知識可透過版本控制共享。
• 要求子代理在開始工作前查詢其記憶：“檢查此 PR，並檢查您的記憶以了解您之前看到的模式。”
• 要求子代理在完成任務後更新其記憶：“既然您已完成，將您學到的內容儲存到您的記憶。” 隨著時間推移，這建立了一個知識庫，使子代理更有效。
• 直接在子代理的 markdown 檔案中包括記憶指示，以便它主動維護自己的知識庫：
  Update your agent memory as you discover codepaths, patterns, library
  locations, and key architectural decisions. This builds up institutional
  knowledge across conversations. Write concise notes about what you found
  and where.
  

​

使用 hooks 的條件規則

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

chmod +x ./scripts/validate-readonly-query.sh

​

禁用特定子代理

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

claude --disallowedTools "Agent(Explore)"

​

為子代理定義 hooks

• 在子代理的 frontmatter 中：定義僅在該子代理活動時執行的 hooks
• 在 settings.json 中：定義也在子代理內觸發的工作階段範圍 hooks。工具事件（例如 PreToolUse 和 PostToolUse）對子代理的工具呼叫觸發，與它們在主對話中的方式相同，SubagentStart 和 SubagentStop 在子代理啟動或完成時觸發

​

子代理 frontmatter 中的 Hooks

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

​

子代理事件的專案級 Hooks

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

​

使用 subagents

​

理解自動委派

​

明確呼叫 subagents

• 自然語言：在提示中命名 subagent；Claude 決定是否委派
• @-mention：保證 subagent 為一個任務執行
• 工作階段範圍：整個工作階段使用該 subagent 的系統提示、工具限制和模型，透過 --agent 標誌或 agent 設定

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@"code-reviewer (agent)" look at the auth changes

claude --agent code-reviewer

claude --agent security-reviewer

claude --agent my-plugin:security-reviewer

{
  "agent": "code-reviewer"
}

​

在前景或背景中執行 subagents

• 前景 subagents 阻止主要對話直到完成。權限提示會在出現時傳遞給您。
• 背景 subagents 在您繼續工作時並行執行。當背景 subagent 到達需要權限的工具呼叫時，Claude Code 會在您的主要工作階段中出現提示，並命名要求的 subagent。批准以讓 subagent 繼續，或按 Esc 拒絕該單一工具呼叫而不停止 subagent。

• 如果進行中的 agent team 隊友產生了 subagent，Claude Code 會在前景中執行它。Claude Code 會拒絕並出現錯誤以產生隊友的 subagent，當隊友的定義設定 background: true 時。當 fork 模式 關閉且您未 關閉背景任務 時，Claude Code 也會在隊友設定 run_in_background: true 時拒絕並出現錯誤。
• 如果您將 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 設定為 1，Claude Code 會在前景中執行 subagent，在每種工作階段中以及無論 fork 模式是否開啟。
• 當 fork 模式 開啟時（在互動式工作階段中預設開啟），Claude Code 會在背景中執行 subagent，fork 和非 fork subagents 都是如此，Claude 無法要求前景。
• 當 fork 模式關閉時，Claude 預設在背景中執行 subagent，在需要結果才能繼續時在前景中執行。Fork 模式在 非互動模式 中使用 -p 和在 Agent SDK 中關閉，除非您開啟它。若要在 Claude 需要結果時將特定 subagent 保持在背景中，請將其 frontmatter background 欄位設定為 true。

• 當 fork 模式關閉時，要求 Claude 在背景或前景中執行任務
• 按 Ctrl+B 將執行中的任務放在背景中

• 當 subagent 成功完成時，Claude Code 會立即移除其列，除了在 螢幕閱讀器模式 中，在頁腳中顯示 /tasks to see subagents 30 秒。在這 30 秒內，執行 /tasks 並在 subagent 上按 Enter 以開啟其文字。在 v2.1.232 之前，Claude Code 在 subagent 完成後保持列 30 秒，與失敗的相同，並顯示無頁腳提示。
• 當 subagent 失敗或您停止它時，Claude Code 會保持其列 30 秒。若要更快清除列，請選擇它並按 x。

​

Subagent 名稱

​

Subagents 中的 API 錯誤

• 前景：如果速率限制、過載或伺服器錯誤切斷已經產生文字輸出的 subagent，Agent 工具會返回該部分輸出，並附註 subagent 被切斷且未完成其任務。未產生任何內容或其唯一輸出為工具呼叫的 subagent 會失敗，並顯示 Agent terminated early due to an API error，後跟錯誤詳細資訊。在 v2.1.199 中，切斷工具呼叫專用形狀的速率限制、過載或伺服器錯誤返回了只包含切斷注記的空部分結果。
• 背景：subagent 被標記為失敗，Claude 在其結束時接收的訊息命名 API 錯誤並包括 subagent 的最後輸出，所以部分工作不會丟失。

​

Subagent 輸出掃描

• 反斜線插入：掃描會在模仿 Claude Code 自己輸出的文字中插入反斜線，例如 <system-reminder> 標籤或以 Human: 或 Assistant: 開頭的行，以便模仿讀作普通文字而不是被誤認為是對話的一部分。
• 標記行：當報告模仿 <system-reminder> 之類的標籤或提及 bypassPermissions 或 --dangerously-skip-permissions 之類的權限設定時，掃描會前置以 [harness: subagent output matched instruction-shaped pattern(s): 開頭的行。權限設定提及會獲得標記行，但文字本身保持原樣。

​

常見模式

​

隔離高容量操作

Use a subagent to run the test suite and report only the failing tests with their error messages

​

執行並行研究

Research the authentication, database, and API modules in parallel using separate subagents

​

鏈接 subagents

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

​

在 subagents 和主要對話之間選擇

• 任務需要頻繁的來回或反覆改進
• 多個階段共享重要上下文，例如規劃、實現和測試
• 您正在進行快速、有針對性的更改
• 延遲很重要。不是 fork 的 subagent 從頭開始，可能需要時間收集上下文

• 任務產生您不需要在主要上下文中的詳細輸出
• 您想強制執行特定的工具限制或權限
• 工作是自包含的，可以返回摘要

​

讓 subagents 產生自己的 subagents

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

​

並行 subagent 限制

• 您使用 /subtask 啟動的進行中 fork 在執行時佔用一個插槽，永遠不會被限制阻止。
• 恢復已完成的 subagent 會佔用一個新插槽而不檢查限制，所以恢復可以將執行計數推過限制。

​

管理 subagent 上下文

​

啟動時載入的內容

• 系統提示：代理自己的提示加上 Claude Code 附加的環境詳細資訊，而不是 Claude Code 系統提示。自訂 subagents 在 markdown 正文 或 prompt 欄位中定義它們。內建代理有預定義的提示。
• 任務訊息：Claude 在交接工作時編寫的委派提示。
• CLAUDE.md 檔案：主要對話載入的 CLAUDE.md 層級 的每個級別，包括 ~/.claude/CLAUDE.md、專案規則、CLAUDE.local.md、受管理的政策檔案和任何 AGENTS.md 檔案 作為專案指令載入。內建的 Explore 和 Plan 代理跳過這個。subagent 的定義設定 omitClaudeMd 時，只載入受管理的政策檔案，或當定義來自 受管理設定 時完全不載入。
• Git 狀態：在 subagent 啟動時拍攝的快照。當工作目錄不是 Git 儲存庫或當 includeGitInstructions 為 false 時不存在。Explore 和 Plan 無論如何都跳過它。
• 預載入的技能：代理的 skills 欄位 中命名的任何技能的完整內容。內建代理不預載入技能。
• 同級名單：系統提醒，列出 main 和工作階段中的每個其他命名代理，每個都是 SendMessage 的有效 to 值。需要 Claude Code v2.1.206 或更新版本。名單僅在 subagent 的工具包括 SendMessage 且至少有一個其他代理有名稱時出現，無論 Claude 在產生時命名它還是它作為 agent teams 隊友執行。它是在 subagent 啟動時拍攝的快照，所以稍後命名的代理不會出現。

• 輸出風格：subagent 執行自己的系統提示，所以您的 輸出風格 不會塑造其回應，除了在 fork 中。
• 自動記憶：主要對話的 自動記憶 不會被載入。若要給 subagent 自己的持久記憶，請使用 memory 欄位。
• 上下文視窗大小：subagent 的上下文視窗由其自己的模型調整大小，而不是父級的。委派給具有較小視窗的模型會給該 subagent 較小的視窗。

​

恢復 subagents

• 當 subagent 完成時，Claude 接收其代理 ID。
• 內建的 Explore 和 Plan 代理是一次性的，不返回代理 ID，所以 Claude 無法恢復它們。當您需要繼續工作時，請使用 general-purpose 或自訂 subagent。
• 當 subagent 在其 maxTurns 限制處停止時，Claude Code 會將返回的輸出標記為部分。對於返回代理 ID 的 subagents，Claude Code 也會在結果中注意 Claude 可以訊息 subagent 以從停止的地方繼續。

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

• 主要對話壓縮：當主要對話壓縮時，subagent 文字不受影響。它們儲存在單獨的檔案中。
• 工作階段持續性：Subagent 文字在其工作階段內持續存在。您可以透過恢復相同工作階段在重新啟動 Claude Code 後 恢復 subagent。
• 自動清理：Claude Code 在 cleanupPeriodDays 保留期後刪除 subagent 文字，預設為 30 天，遵循 保留掃描規則。

​

自動壓縮

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

​

Fork 目前的對話

/subtask draft unit tests for the parser changes so far

​

觀察和引導執行中的 forks

• /compact、/clear 和 /rewind 會作用於主要對話，因此從此檢視執行其中任一命令之前，Claude Code 會要求您確認。
• /model 和 /fast 會設定主要對話的模型和快速模式，而不是所檢視 agent 的，因此無法從此檢視執行。系統會顯示通知說明原因。

​

Forks 與其他 subagents 的區別

​

開啟或關閉 fork 模式

• Claude 可以透過要求 fork subagent 類型來產生 fork。當 Claude 不要求類型時，如果工作階段仍有該類型，它會取得通用 subagent。從定義產生的 subagents，例如 Explore，照常工作。
• Claude Code 在背景中執行 Claude 產生的 subagents，forks 和非 fork subagents 都是如此，除了保持在前景的情況。Claude Code 也會移除 Agent 工具的 run_in_background 參數，因此 Claude 無法要求前景。

• 1 在非互動模式和 Agent SDK 中也開啟 fork 模式
• 0 在每種工作階段中關閉 fork 模式

​

範例 subagents

​

程式碼審查者

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

​

除錯器

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

​

資料科學家

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

​

資料庫查詢驗證器

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

chmod +x ./scripts/validate-readonly-query.sh

​

後續步驟

• 使用外掛程式分發 subagents 以跨團隊或專案共享 subagents
• 以程式方式執行 Claude Code 使用 Agent SDK 進行 CI/CD 和自動化
• 使用 MCP 伺服器 為 subagents 提供對外部工具和資料的存取