在 SDK 中使用 Claude Code 功能

將專案指令、skills、hooks 和其他 Claude Code 功能載入到您的 SDK 代理中。

Agent SDK 建立在與 Claude Code 相同的基礎上，這意味著您的 SDK 代理可以存取相同的基於檔案系統的功能：專案指令（CLAUDE.md 和規則）、skills、hooks 等。

當您省略 settingSources 時，query() 會讀取與 Claude Code CLI 相同的檔案系統設定：使用者、專案和本機設定、CLAUDE.md 檔案以及 .claude/ skills、代理和命令。若要在沒有這些的情況下執行，請傳遞 settingSources: []，這會將代理限制為您以程式設計方式設定的內容。無論此選項如何，都會讀取受管原則設定和全域 ~/.claude.json 設定。請參閱 settingSources 不控制的內容。

如需每項功能的概念概述及何時使用，請參閱擴展 Claude Code。

使用 settingSources 控制檔案系統設定

設定來源選項（Python 中的 setting_sources、TypeScript 中的 settingSources）控制 SDK 載入哪些基於檔案系統的設定。傳遞明確清單以選擇加入特定來源，或傳遞空陣列以停用使用者、專案和本機設定。

此範例透過將 settingSources 設定為 ["user", "project"] 來載入使用者層級和專案層級設定：

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async for message in query(
prompt="Help me refactor the auth module",
options=ClaudeAgentOptions(
# "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
# Together they give the agent access to CLAUDE.md, skills, hooks, and
# permissions from both locations.
setting_sources=["user", "project"],
allowed_tools=["Read", "Edit", "Bash"],
),
):
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text)
if isinstance(message, ResultMessage) and message.subtype == "success":
print(f"\nResult: {message.result}")

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Help me refactor the auth module",
options: {
// "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
// Together they give the agent access to CLAUDE.md, skills, hooks, and
// permissions from both locations.
settingSources: ["user", "project"],
allowedTools: ["Read", "Edit", "Bash"]
}
})) {
if (message.type === "assistant") {
for (const block of message.message.content) {
if (block.type === "text") console.log(block.text);
}
}
if (message.type === "result" && message.subtype === "success") {
console.log(`\nResult: ${message.result}`);
}
}

每個來源都會從特定位置載入設定，其中 <cwd> 是您透過 cwd 選項傳遞的工作目錄，或如果未設定則為程序的目前目錄。如需完整的型別定義，請參閱 SettingSource（TypeScript）或 SettingSource（Python）。

來源	載入的內容	位置
`"project"`	專案 CLAUDE.md、`.claude/rules/*.md`、專案 skills、專案 hooks、專案 `settings.json`	`<cwd>/.claude/` 以及每個父目錄直到檔案系統根目錄（當找到 `.claude/` 或沒有更多父目錄時停止）
`"user"`	使用者 CLAUDE.md、`~/.claude/rules/*.md`、使用者 skills、使用者設定	`~/.claude/`
`"local"`	CLAUDE.local.md（gitignored）、`.claude/settings.local.json`	`<cwd>/`

省略 settingSources 等同於 ["user", "project", "local"]。

cwd 選項決定 SDK 在何處尋找專案設定。如果 cwd 及其任何父目錄都不包含 .claude/ 資料夾，則專案層級功能將不會載入。

settingSources 不控制的內容

settingSources 涵蓋使用者、專案和本機設定。無論其值如何，都會讀取一些輸入：

輸入	行為	停用方式
受管原則設定	主機上存在時始終載入	移除受管設定檔
`~/.claude.json` 全域設定	始終讀取	在 `env` 中使用 `CLAUDE_CONFIG_DIR` 重新定位
`~/.claude/projects/<project>/memory/` 的自動記憶體	預設載入到系統提示中	在設定中設定 `autoMemoryEnabled: false`，或在 `env` 中設定 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`

專案指令（CLAUDE.md 和規則）

CLAUDE.md 檔案和 .claude/rules/*.md 檔案為您的代理提供有關您的專案的持久上下文：編碼慣例、建置命令、架構決策和指令。當 settingSources 包含 "project"（如上面的範例所示）時，SDK 在工作階段開始時將這些檔案載入到上下文中。代理隨後會遵循您的專案慣例，而無需在每個提示中重複它們。

CLAUDE.md 載入位置

層級	位置	何時載入
專案（根目錄）	`<cwd>/CLAUDE.md` 或 `<cwd>/.claude/CLAUDE.md`	`settingSources` 包含 `"project"`
專案規則	`<cwd>/.claude/rules/*.md`	`settingSources` 包含 `"project"`
專案（父目錄）	`cwd` 上方目錄中的 `CLAUDE.md` 檔案	`settingSources` 包含 `"project"`，在工作階段開始時載入
專案（子目錄）	`cwd` 子目錄中的 `CLAUDE.md` 檔案	`settingSources` 包含 `"project"`，當代理讀取該子樹中的檔案時按需載入
本機（gitignored）	`<cwd>/CLAUDE.local.md`	`settingSources` 包含 `"local"`
使用者	`~/.claude/CLAUDE.md`	`settingSources` 包含 `"user"`
使用者規則	`~/.claude/rules/*.md`	`settingSources` 包含 `"user"`

所有層級都是累加的：如果專案和使用者 CLAUDE.md 檔案都存在，代理會看到兩者。層級之間沒有硬性優先順序規則；如果指令衝突，結果取決於 Claude 如何解釋它們。編寫不衝突的規則，或在更具體的檔案中明確說明優先順序（「這些專案指令會覆蓋任何衝突的使用者層級預設值」）。

如需如何結構化和組織 CLAUDE.md 內容的資訊，請參閱管理 Claude 的記憶體。

Skills

Skills 是 markdown 檔案，為您的代理提供專門知識和可呼叫的工作流程。與 CLAUDE.md（每個工作階段都載入）不同，skills 按需載入。代理在啟動時接收 skill 描述，並在相關時載入完整內容。

Skills 透過 settingSources 從檔案系統中發現。當 query() 上的 skills 選項被省略時，已發現的使用者和專案 skills 會被啟用，且 Skill 工具可用，符合 CLI 行為。若要控制啟用哪些 skills，請將 skills 傳遞為 "all"、skill 名稱清單或 [] 以停用全部。SDK 在設定 skills 時會自動啟用 Skill 工具，因此您不需要將其新增至 allowedTools。

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

# Skills in .claude/skills/ are discovered automatically
# when settingSources includes "project"
async for message in query(
prompt="Review this PR using our code review checklist",
options=ClaudeAgentOptions(
setting_sources=["user", "project"],
skills="all",
allowed_tools=["Read", "Grep", "Glob"],
),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)

import { query } from "@anthropic-ai/claude-agent-sdk";

// Skills in .claude/skills/ are discovered automatically
// when settingSources includes "project"
for await (const message of query({
prompt: "Review this PR using our code review checklist",
options: {
settingSources: ["user", "project"],
skills: "all",
allowedTools: ["Read", "Grep", "Glob"]
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

如需建立和使用 skills 的詳細資訊，請參閱 SDK 中的代理 Skills。

Hooks

SDK 支援兩種定義 hooks 的方式，它們並行執行：

檔案系統 hooks： 在 settings.json 中定義的 shell 命令，當 settingSources 包含相關來源時載入。這些是您為互動式 Claude Code 工作階段設定的相同 hooks。
程式設計 hooks： 直接傳遞給 query() 的回呼函式。這些在您的應用程式程序中執行，可以返回結構化決策。請參閱使用 hooks 控制執行。

兩種類型都在相同的 hook 生命週期中執行。如果您已經在專案的 .claude/settings.json 中有 hooks，並且您設定 settingSources: ["project"]，那些 hooks 會在 SDK 中自動執行，無需額外設定。

Hook 回呼接收工具輸入並返回決策字典。返回 {}（空字典）表示允許工具繼續。返回 {"decision": "block", "reason": "..."} 會阻止執行，原因會作為工具結果發送給 Claude。請參閱 hooks 指南以取得完整的回呼簽名和返回型別。

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage


# PreToolUse hook callback. Positional args:
#   input_data: HookInput dict with tool_name, tool_input, hook_event_name
#   tool_use_id: str | None, the ID of the tool call being intercepted
#   context: HookContext, carries session metadata
async def audit_bash(input_data, tool_use_id, context):
command = input_data.get("tool_input", {}).get("command", "")
if "rm -rf" in command:
return {"decision": "block", "reason": "Destructive command blocked"}
return {}  # Empty dict: allow the tool to proceed


# Filesystem hooks from .claude/settings.json run automatically
# when settingSources loads them. You can also add programmatic hooks:
async for message in query(
prompt="Refactor the auth module",
options=ClaudeAgentOptions(
setting_sources=["project"],  # Loads hooks from .claude/settings.json
hooks={
"PreToolUse": [
HookMatcher(matcher="Bash", hooks=[audit_bash]),
]
},
),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)

import { query, type HookInput, type HookJSONOutput } from "@anthropic-ai/claude-agent-sdk";

// PreToolUse hook callback. HookInput is a discriminated union on
// hook_event_name, so narrowing on it gives TypeScript the right
// tool_input shape for this event.
const auditBash = async (input: HookInput): Promise<HookJSONOutput> => {
if (input.hook_event_name !== "PreToolUse") return {};
const toolInput = input.tool_input as { command?: string };
if (toolInput.command?.includes("rm -rf")) {
return { decision: "block", reason: "Destructive command blocked" };
}
return {}; // Empty object: allow the tool to proceed
};

// Filesystem hooks from .claude/settings.json run automatically
// when settingSources loads them. You can also add programmatic hooks:
for await (const message of query({
prompt: "Refactor the auth module",
options: {
settingSources: ["project"], // Loads hooks from .claude/settings.json
hooks: {
PreToolUse: [{ matcher: "Bash", hooks: [auditBash] }]
}
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}

何時使用哪種 hook 類型

Hook 類型	最適合
檔案系統（`settings.json`）	在 CLI 和 SDK 工作階段之間共享 hooks。支援 `"command"`（shell 指令碼）、`"http"`（POST 到端點）、`"mcp_tool"`（呼叫連接的 MCP 伺服器的工具）、`"prompt"`（LLM 評估提示）和 `"agent"`（生成驗證器代理）。這些在主代理和它生成的任何子代理中執行。
程式設計（`query()` 中的回呼）	應用程式特定邏輯；返回結構化決策；進程內整合。限制於主工作階段。

如需程式設計 hooks 的完整詳細資訊，請參閱使用 hooks 控制執行。如需檔案系統 hook 語法，請參閱 Hooks。

選擇正確的功能

Agent SDK 為您提供了多種方式來擴展代理的行為。如果您不確定要使用哪一種，此表將常見目標對應到正確的方法。

您想要...	使用	SDK 表面
設定代理始終遵循的專案慣例	CLAUDE.md	`settingSources: ["project"]` 會自動載入它
為代理提供它在相關時載入的參考資料	Skills	`settingSources` + `skills` 選項
執行可重複使用的工作流程（部署、審查、發佈）	使用者可呼叫的 skills	`settingSources` + `skills` 選項
將隔離的子任務委派給新的上下文（研究、審查）	子代理	`agents` 參數 + `allowedTools: ["Agent"]`
協調多個 Claude Code 實例，具有共享任務清單和直接的代理間訊息傳遞	代理團隊	不直接透過 SDK 選項設定。代理團隊是一個 CLI 功能，其中一個工作階段充當團隊主管，協調獨立隊友之間的工作
在工具呼叫上執行確定性邏輯（審計、阻止、轉換）	Hooks	`hooks` 參數與回呼，或透過 `settingSources` 載入的 shell 指令碼
為 Claude 提供對外部服務的結構化工具存取	MCP	`mcpServers` 參數

您啟用的每項功能都會增加代理的上下文視窗。如需每項功能的成本以及這些功能如何分層組合，請參閱擴展 Claude Code。

agent-sdk/claude-code-features.md +9 −7

14 14

15## 使用 settingSources 控制檔案系統設定15## 使用 settingSources 控制檔案系統設定

16 16

17設定來源選項（Python 中的 [`setting_sources`](/zh-TW/agent-sdk/python#claude-agent-options)、TypeScript 中的 [`settingSources`](/zh-TW/agent-sdk/typescript#setting-source)）控制 SDK 載入哪些基於檔案系統的設定。傳遞明確清單以選擇加入特定來源，或傳遞空陣列以停用使用者、專案和本機設定。17設定來源選項（Python 中的 [`setting_sources`](/zh-TW/agent-sdk/python#claudeagentoptions)、TypeScript 中的 [`settingSources`](/zh-TW/agent-sdk/typescript#settingsource)）控制 SDK 載入哪些基於檔案系統的設定。傳遞明確清單以選擇加入特定來源，或傳遞空陣列以停用使用者、專案和本機設定。

18 18

19此範例透過將 `settingSources` 設定為 `["user", "project"]` 來載入使用者層級和專案層級設定：19此範例透過將 `settingSources` 設定為 `["user", "project"]` 來載入使用者層級和專案層級設定：

20 20

65 ```65 ```

66</CodeGroup>66</CodeGroup>

67 67

68每個來源都會從特定位置載入設定，其中 `<cwd>` 是您透過 `cwd` 選項傳遞的工作目錄（如果未設定，則為程序的目前目錄）。如需完整的型別定義，請參閱 [`SettingSource`](/zh-TW/agent-sdk/typescript#setting-source)（TypeScript）或 [`SettingSource`](/zh-TW/agent-sdk/python#setting-source)（Python）。68每個來源都會從特定位置載入設定，其中 `<cwd>` 是您透過 `cwd` 選項傳遞的工作目錄，或如果未設定則為程序的目前目錄。如需完整的型別定義，請參閱 [`SettingSource`](/zh-TW/agent-sdk/typescript#settingsource)（TypeScript）或 [`SettingSource`](/zh-TW/agent-sdk/python#settingsource)（Python）。

69 69

70| 來源 | 載入的內容 | 位置 |70| 來源 | 載入的內容 | 位置 |

71| :---------- | :---------------------------------------------------------------------- | :------------------------------------------------------------ |71| :---------- | :---------------------------------------------------------------------- | :------------------------------------------------------------ |

119 119

120Skills 是 markdown 檔案，為您的代理提供專門知識和可呼叫的工作流程。與 `CLAUDE.md`（每個工作階段都載入）不同，skills 按需載入。代理在啟動時接收 skill 描述，並在相關時載入完整內容。120Skills 是 markdown 檔案，為您的代理提供專門知識和可呼叫的工作流程。與 `CLAUDE.md`（每個工作階段都載入）不同，skills 按需載入。代理在啟動時接收 skill 描述，並在相關時載入完整內容。

121 121

122Skills 透過 `settingSources` 從檔案系統中發現。使用預設選項，使用者和專案 skills 會自動載入。當您未指定 `allowedTools` 時，`Skill` 工具預設啟用。如果您使用 `allowedTools` 允許清單，請明確包含 `"Skill"`。122Skills 透過 `settingSources` 從檔案系統中發現。當 `query()` 上的 `skills` 選項被省略時，已發現的使用者和專案 skills 會被啟用，且 Skill 工具可用，符合 CLI 行為。若要控制啟用哪些 skills，請將 `skills` 傳遞為 `"all"`、skill 名稱清單或 `[]` 以停用全部。SDK 在設定 `skills` 時會自動啟用 Skill 工具，因此您不需要將其新增至 `allowedTools`。

123 123

124<CodeGroup>124<CodeGroup>

125 ```python Python theme={null}125 ```python Python theme={null}

131 prompt="Review this PR using our code review checklist",131 prompt="Review this PR using our code review checklist",

132 options=ClaudeAgentOptions(132 options=ClaudeAgentOptions(

133 setting_sources=["user", "project"],133 setting_sources=["user", "project"],

134 allowed_tools=["Skill", "Read", "Grep", "Glob"],134 skills="all",

135 allowed_tools=["Read", "Grep", "Glob"],

135 ),136 ),

136 ):137 ):

137 if isinstance(message, ResultMessage) and message.subtype == "success":138 if isinstance(message, ResultMessage) and message.subtype == "success":

147 prompt: "Review this PR using our code review checklist",148 prompt: "Review this PR using our code review checklist",

148 options: {149 options: {

149 settingSources: ["user", "project"],150 settingSources: ["user", "project"],

150 allowedTools: ["Skill", "Read", "Grep", "Glob"]151 skills: "all",

152 allowedTools: ["Read", "Grep", "Glob"]

151 }153 }

152 })) {154 })) {

153 if (message.type === "result" && message.subtype === "success") {155 if (message.type === "result" && message.subtype === "success") {

260| 您想要... | 使用 | SDK 表面 |262| 您想要... | 使用 | SDK 表面 |

261| :-------------------------------------- | :---------------------------------------- | :------------------------------------------------------- |263| :-------------------------------------- | :---------------------------------------- | :------------------------------------------------------- |

agent-sdk/claude-code-features.md 2026-05-07 22:59 UTC to 2026-05-08 22:00 UTC

在 SDK 中使用 Claude Code 功能

使用 settingSources 控制檔案系統設定

settingSources 不控制的內容

專案指令（CLAUDE.md 和規則）

CLAUDE.md 載入位置

Skills

Hooks

何時使用哪種 hook 類型

選擇正確的功能

相關資源

agent-sdk/claude-code-features.md +9 −7