Использование функций 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 не контролирует.

Управление параметрами файловой системы с помощью settingSources

Параметр источников параметров (setting_sources в Python, settingSources в TypeScript) контролирует, какие параметры на основе файловой системы загружает SDK. Передайте явный список для включения определённых источников или передайте пустой массив для отключения пользовательских, проектных и локальных параметров.

Этот пример загружает как пользовательские, так и проектные параметры, устанавливая settingSources на ["user", "project"]:

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
import asyncio


async def main():
    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}")


asyncio.run(main())

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}`);
  }
}

Когда это выполняется, ответ ассистента выводится в stdout, а затем выводится финальная строка результата после завершения запуска.

Каждый источник загружает параметры из определённого местоположения, где <cwd> — это рабочий каталог, который вы передаёте через параметр cwd, или текущий каталог процесса, если он не установлен. Для полного определения типа см. SettingSource (TypeScript) или SettingSource (Python).

Опускание settingSources эквивалентно ["user", "project", "local"].

Параметр cwd определяет, где SDK ищет входные данные уровня проекта. Project settings.json и hooks загружаются только из <cwd>/.claude/ без резервного варианта для родительского каталога.

Что settingSources не контролирует

settingSources охватывает пользовательские, проектные и локальные параметры. Несколько входов читаются независимо от его значения:

[!WARNING]

Не полагайтесь на параметры query() по умолчанию для изоляции в многопользовательской среде. Поскольку входы выше читаются независимо от settingSources, процесс SDK может подхватить конфигурацию уровня хоста и память для каждого каталога. Для развёртываний в многопользовательской среде запустите каждого пользователя в собственной файловой системе и установите settingSources: [] плюс CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 в env. Параметры, управляемые сервером, загружаются при аутентификации процесса с помощью учётных данных организации; изоляция файловой системы их не удаляет. См. Безопасное развёртывание.

Инструкции проекта (CLAUDE.md и правила)

Файлы CLAUDE.md и файлы .claude/rules/*.md дают вашему агенту постоянный контекст о вашем проекте: соглашения кодирования, команды сборки, архитектурные решения и инструкции. Когда settingSources включает "project", как в примере settingSources, SDK загружает эти файлы в контекст при запуске сессии. Затем агент следует вашим соглашениям проекта без необходимости повторять их в каждом промпте.

Местоположения загрузки CLAUDE.md

Все уровни являются аддитивными: если существуют как проектные, так и пользовательские файлы CLAUDE.md, агент видит оба. Между уровнями нет жёсткого правила приоритета; если инструкции конфликтуют, результат зависит от того, как Claude их интерпретирует. Напишите неконфликтующие правила или явно укажите приоритет в более специфичном файле («Эти инструкции проекта переопределяют любые конфликтующие пользовательские значения по умолчанию»).

[!TIP]

Вы также можете внедрить контекст непосредственно через systemPrompt без использования файлов CLAUDE.md. См. Изменение системных промптов. Используйте CLAUDE.md, когда вы хотите, чтобы один и тот же контекст был общим между интерактивными сессиями Claude Code и вашими SDK-агентами.

О том, как структурировать и организовать содержимое CLAUDE.md, см. Управление памятью Claude.

Skills

Skills — это файлы markdown, которые дают вашему агенту специализированные знания и вызываемые рабочие процессы. В отличие от CLAUDE.md (который загружается каждый сеанс), skills загружаются по требованию. Агент получает описания skills при запуске и загружает полное содержимое при необходимости.

Skills обнаруживаются из файловой системы через settingSources. Когда параметр skills в query() опущен, обнаруженные пользовательские и проектные skills включены и инструмент Skill доступен, что соответствует поведению CLI. Для управления тем, какие skills включены, передайте skills как "all", список имён skills или [] для отключения всех. Когда skills установлен, SDK автоматически добавляет инструмент Skill в allowedTools. Если вы также передаёте явный список tools, включите "Skill" в этот список, чтобы Claude мог вызывать skills.

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage
import asyncio


# Skills in .claude/skills/ are discovered automatically
# when settingSources includes "project"
async def main():
    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)


asyncio.run(main())

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);
  }
}

[!NOTE]

Skills должны быть созданы как артефакты файловой системы (.claude/skills/<name>/SKILL.md). SDK не имеет программного API для регистрации skills. См. Agent Skills в SDK для полных деталей.

Hooks

SDK поддерживает два способа определения hooks, и они работают рядом:

• Filesystem hooks: команды оболочки, определённые в settings.json, загружаются, когда settingSources включает соответствующий источник. Это те же hooks, которые вы бы настроили для интерактивных сеансов Claude Code.
• Programmatic hooks: функции обратного вызова, передаваемые непосредственно в query(). Они выполняются в процессе вашего приложения и могут возвращать структурированные решения. См. Управление выполнением с помощью hooks.

Обратные вызовы Hook получают входные данные инструмента и возвращают словарь решения. Возврат {} означает разрешить инструменту продолжить. Чтобы заблокировать выполнение, верните объект hookSpecificOutput с permissionDecision: "deny" и permissionDecisionReason. Причина отправляется Claude как результат инструмента. См. руководство hooks для полной сигнатуры обратного вызова и типов возврата.

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage
import asyncio


# 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, reserved for future abort-signal support
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 def main():
    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)


asyncio.run(main())

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

[!NOTE]

TypeScript SDK поддерживает дополнительные события hook помимо Python, включая SessionStart, SessionEnd, TeammateIdle и TaskCompleted. См. руководство hooks для полной таблицы совместимости событий.

Для полных деталей о programmatic hooks см. Управление выполнением с помощью hooks. Для синтаксиса filesystem hook см. Hooks.

Выбор правильной функции

Agent SDK предоставляет вам доступ к нескольким способам расширения поведения вашего агента. Если вы не уверены, какой использовать, эта таблица отображает общие цели на правильный подход.

Каждая функция, которую вы включаете, добавляет к контекстному окну вашего агента. Для затрат на функцию и того, как эти функции слоятся вместе, см. Расширение Claude Code.

Связанные ресурсы

• Расширение Claude Code: Концептуальный обзор всех функций расширения с таблицами сравнения и анализом затрат контекста
• Skills в SDK: Полное руководство по использованию skills программно
• Subagents: Определение и вызов subagents для изолированных подзадач
• Hooks: Перехват и управление поведением агента в ключевых точках выполнения
• Permissions: Управление доступом к инструментам с помощью режимов, правил и обратных вызовов
• System prompts: Внедрение контекста без файлов CLAUDE.md