Использование функций Claude Code в SDK
Загружайте инструкции проекта, skills, hooks и другие функции Claude Code в ваши SDK-агентов.
Agent SDK построен на той же основе, что и Claude Code, что означает, что ваши SDK-агенты имеют доступ к тем же функциям на основе файловой системы: инструкции проекта (CLAUDE.md и правила), skills, hooks и многое другое.
Когда вы опускаете settingSources, query() читает те же параметры файловой системы, что и Claude Code CLI: пользовательские, проектные и локальные параметры, файлы CLAUDE.md и skills, агенты и команды в .claude/. Чтобы запустить без них, передайте settingSources: [], что ограничивает агента только тем, что вы настраиваете программно. Параметры управляемой политики и глобальная конфигурация ~/.claude.json читаются независимо от этого параметра. См. Что settingSources не контролирует.
Для концептуального обзора того, что делает каждая функция и когда её использовать, см. Расширение Claude Code.
Управление параметрами файловой системы с помощью settingSources
Параметр источников параметров (setting_sources в Python, settingSources в TypeScript) контролирует, какие параметры на основе файловой системы загружает 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" |
Project CLAUDE.md, .claude/rules/*.md, project skills, project hooks, project settings.json |
<cwd>/.claude/ и каждый родительский каталог вверх до корня файловой системы (остановка при обнаружении .claude/ или отсутствии дополнительных родителей) |
"user" |
User CLAUDE.md, ~/.claude/rules/*.md, user skills, user settings |
~/.claude/ |
"local" |
CLAUDE.local.md (gitignored), .claude/settings.local.json |
<cwd>/ |
Опускание settingSources эквивалентно ["user", "project", "local"].
Параметр cwd определяет, где SDK ищет параметры проекта. Если ни cwd, ни какой-либо из его родительских каталогов не содержит папку .claude/, функции уровня проекта не будут загружены.
Что settingSources не контролирует
settingSources охватывает пользовательские, проектные и локальные параметры. Несколько входов читаются независимо от его значения:
| Вход | Поведение | Для отключения |
|---|---|---|
| Параметры управляемой политики | Всегда загружаются при наличии на хосте | Удалите файл управляемых параметров |
~/.claude.json глобальная конфигурация |
Всегда читается | Переместите с помощью CLAUDE_CONFIG_DIR в env |
Автоматическая память в ~/.claude/projects/<project>/memory/ |
Загружается по умолчанию в системный запрос | Установите autoMemoryEnabled: false в параметрах или CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 в env |
Инструкции проекта (CLAUDE.md и правила)
Файлы CLAUDE.md и файлы .claude/rules/*.md дают вашему агенту постоянный контекст о вашем проекте: соглашения кодирования, команды сборки, архитектурные решения и инструкции. Когда settingSources включает "project" (как в примере выше), SDK загружает эти файлы в контекст при запуске сеанса. Затем агент следует вашим соглашениям проекта без необходимости повторять их в каждом запросе.
Местоположения загрузки CLAUDE.md
| Уровень | Местоположение | Когда загружается |
|---|---|---|
| Project (root) | <cwd>/CLAUDE.md или <cwd>/.claude/CLAUDE.md |
settingSources включает "project" |
| Project rules | <cwd>/.claude/rules/*.md |
settingSources включает "project" |
| Project (parent dirs) | Файлы CLAUDE.md в каталогах выше cwd |
settingSources включает "project", загружается при запуске сеанса |
| Project (child dirs) | Файлы CLAUDE.md в подкаталогах cwd |
settingSources включает "project", загружается по требованию, когда агент читает файл в этом поддереве |
| Local (gitignored) | <cwd>/CLAUDE.local.md |
settingSources включает "local" |
| User | ~/.claude/CLAUDE.md |
settingSources включает "user" |
| User rules | ~/.claude/rules/*.md |
settingSources включает "user" |
Все уровни являются аддитивными: если существуют как проектные, так и пользовательские файлы CLAUDE.md, агент видит оба. Между уровнями нет жёсткого правила приоритета; если инструкции конфликтуют, результат зависит от того, как Claude их интерпретирует. Напишите неконфликтующие правила или явно укажите приоритет в более специфичном файле («Эти инструкции проекта переопределяют любые конфликтующие пользовательские значения по умолчанию»).
О том, как структурировать и организовать содержимое CLAUDE.md, см. Управление памятью Claude.
Skills
Skills — это файлы markdown, которые дают вашему агенту специализированные знания и вызываемые рабочие процессы. В отличие от CLAUDE.md (который загружается каждый сеанс), skills загружаются по требованию. Агент получает описания skills при запуске и загружает полное содержимое при необходимости.
Skills обнаруживаются из файловой системы через settingSources. Когда параметр skills в query() опущен, обнаруженные пользовательские и проектные skills включены и инструмент Skill доступен, что соответствует поведению CLI. Для управления тем, какие skills включены, передайте skills как "all", список имён skills или [] для отключения всех. SDK автоматически включает инструмент Skill, когда skills установлен, поэтому вам не нужно добавлять его в 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 см. в разделе Agent Skills в SDK.
Hooks
SDK поддерживает два способа определения hooks, и они работают рядом:
- Filesystem hooks: команды оболочки, определённые в
settings.json, загружаются, когдаsettingSourcesвключает соответствующий источник. Это те же hooks, которые вы бы настроили для интерактивных сеансов Claude Code. - Programmatic hooks: функции обратного вызова, передаваемые непосредственно в
query(). Они выполняются в процессе вашего приложения и могут возвращать структурированные решения. См. Управление выполнением с помощью hooks.
Оба типа выполняются во время одного и того же жизненного цикла hook. Если у вас уже есть hooks в файле .claude/settings.json вашего проекта и вы установили 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 | Лучше всего для |
|---|---|
Filesystem (settings.json) |
Совместное использование hooks между сеансами CLI и SDK. Поддерживает "command" (shell-скрипты), "http" (POST на конечную точку), "mcp_tool" (вызов инструмента подключённого MCP-сервера), "prompt" (LLM оценивает запрос) и "agent" (порождает агента-верификатора). Они срабатывают в основном агенте и любых подагентах, которые он порождает. |
Programmatic (обратные вызовы в query()) |
Логика, специфичная для приложения; возврат структурированных решений; интеграция в процессе. Ограничено только основным сеансом. |
Для полных деталей о programmatic hooks см. Управление выполнением с помощью hooks. Для синтаксиса filesystem hook см. Hooks.
Выбор правильной функции
Agent SDK предоставляет вам доступ к нескольким способам расширения поведения вашего агента. Если вы не уверены, какой использовать, эта таблица отображает общие цели на правильный подход.
| Вы хотите... | Используйте | Поверхность SDK |
|---|---|---|
| Установить соглашения проекта, которые ваш агент всегда соблюдает | CLAUDE.md | settingSources: ["project"] загружает его автоматически |
| Дать агенту справочный материал, который он загружает при необходимости | Skills | settingSources + skills опция |
| Запустить повторно используемый рабочий процесс (развёртывание, проверка, выпуск) | User-invocable skills | settingSources + skills опция |
| Делегировать изолированную подзадачу свежему контексту (исследование, проверка) | Subagents | параметр agents + allowedTools: ["Agent"] |
| Координировать несколько экземпляров Claude Code с общими списками задач и прямой передачей сообщений между агентами | Agent teams | Не настраивается напрямую через параметры SDK. Agent teams — это функция CLI, где один сеанс действует как лидер команды, координируя работу независимых товарищей по команде |
| Запустить детерминированную логику на вызовах инструментов (аудит, блокировка, преобразование) | Hooks | параметр hooks с обратными вызовами или shell-скрипты, загруженные через settingSources |
| Дать Claude структурированный доступ к инструменту для внешнего сервиса | MCP | параметр mcpServers |
Каждая функция, которую вы включаете, добавляет к контекстному окну вашего агента. Для затрат на функцию и того, как эти функции слоятся вместе, см. Расширение Claude Code.
Связанные ресурсы
- Расширение Claude Code: Концептуальный обзор всех функций расширения с таблицами сравнения и анализом затрат контекста
- Skills в SDK: Полное руководство по использованию skills программно
- Subagents: Определение и вызов subagents для изолированных подзадач
- Hooks: Перехват и управление поведением агента в ключевых точках выполнения
- Permissions: Управление доступом к инструментам с помощью режимов, правил и обратных вызовов
- System prompts: Внедрение контекста без файлов CLAUDE.md