在 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/` 用于 `settings.json` 和 hooks；`<cwd>` 和每个父目录用于 CLAUDE.md 和规则；`<cwd>` 和每个父目录直到存储库根目录用于 skills
`"user"`	用户 CLAUDE.md、`~/.claude/rules/*.md`、用户 skills、用户设置	`~/.claude/`
`"local"`	CLAUDE.local.md、`.claude/settings.local.json`	`<cwd>/.claude/` 用于 `settings.local.json`；`<cwd>` 和每个父目录用于 CLAUDE.local.md

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

cwd 选项确定 SDK 查找项目级输入的位置。CLAUDE.md 和规则从 <cwd> 和每个父目录加载。Skills 从 <cwd> 和每个父目录直到存储库根目录加载。项目 settings.json 和 hooks 仅从 <cwd>/.claude/ 加载，没有父目录回退。

settingSources 不控制的内容

settingSources 涵盖用户、项目和本地设置。无论其值如何，都会读取一些输入：

输入	行为	禁用方式
托管策略设置	端点管理的策略（无论是 MDM plist、注册表策略还是托管设置文件）从主机加载；服务器管理的设置在会话使用组织 OAuth 登录或直接配置的 API 密钥进行身份验证时获取，在符合条件的配置上	端点策略：从主机中删除托管设置文件、plist 或注册表策略。服务器管理的设置：由您的组织管理员控制；无法从 SDK 禁用
`~/.claude.json` 全局配置	始终读取	使用 `env` 中的 `CLAUDE_CONFIG_DIR` 重新定位
`~/.claude/projects/<project>/memory/` 处的自动内存	默认加载到系统提示中	在设置中设置 `autoMemoryEnabled: false`，或在 `env` 中设置 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`
claude.ai MCP 连接器	当活跃身份验证方法是 claude.ai 订阅时加载。传递 `mcpServers: {}` 不会抑制它们	设置 `strictMcpConfig: true`、`disableClaudeAiConnectors: true` 在设置中，或在 `env` 中设置 `ENABLE_CLAUDEAI_MCP_SERVERS=false`

项目说明（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` 和 `.claude/rules/.md` 在每个父目录中	`settingSources` 包含 `"project"`
项目（父目录）	`cwd` 上方目录中的 `CLAUDE.md` 文件	`settingSources` 包含 `"project"`，在会话开始时加载
项目（子目录）	`cwd` 子目录中的 `CLAUDE.md` 文件	`settingSources` 包含 `"project"`，当代理读取该子树中的文件时按需加载
本地	`<cwd>/CLAUDE.local.md` 和 `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 名称列表或 [] 传递以禁用所有。当设置 skills 时，SDK 会自动将 Skill 工具添加到 allowedTools。如果您还传递了显式的 tools 列表，请在该列表中包含 "Skill"，以便 Claude 可以调用 skills。

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 中的 Agent 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 回调接收工具输入并返回决策字典。返回 {} 意味着允许工具继续。要阻止执行，返回一个 hookSpecificOutput 对象，其中包含 permissionDecision: "deny" 和 permissionDecisionReason。原因会作为工具结果发送给 Claude。顶级 decision 和 reason 字段对于 PreToolUse 已弃用。有关完整的回调签名和返回类型，请参阅 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 {
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "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 {
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "deny",
permissionDecisionReason: "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()` 中的回调）	应用程序特定的逻辑、结构化决策和进程内集成。这些也在子代理内触发。回调接收 `agent_id` 和 `agent_type` 来区分。

有关编程 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。

扩展 Claude Code：所有扩展功能的概念概述，包含比较表和上下文成本分析
SDK 中的 Skills：使用 skills 的完整指南
子代理：为隔离的子任务定义和调用子代理
Hooks：在关键执行点拦截和控制代理行为
权限：使用模式、规则和回调控制工具访问
系统提示：在不使用 CLAUDE.md 文件的情况下注入上下文

agent-sdk/claude-code-features.md 2026-06-23 22:00 UTC to 2026-06-24 22:02 UTC

在 SDK 中使用 Claude Code 功能

使用 settingSources 控制文件系统设置

settingSources 不控制的内容

项目说明（CLAUDE.md 和规则）

CLAUDE.md 加载位置

Skills

Hooks

何时使用哪种 hook 类型

选择正确的功能

agent-sdk/claude-code-features.md +3 −3

agent-sdk/claude-code-features.md 2026-06-23 22:00 UTC to 2026-06-24 22:02 UTC

在 SDK 中使用 Claude Code 功能

使用 settingSources 控制文件系统设置

settingSources 不控制的内容

项目说明（CLAUDE.md 和规则）

CLAUDE.md 加载位置

Skills

Hooks

何时使用哪种 hook 类型

选择正确的功能

相关资源