Перейти к основному содержанию
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"]:
Каждый источник загружает параметры из определённого местоположения, где <cwd> — это рабочий каталог, который вы передаёте через параметр cwd, или текущий каталог процесса, если он не установлен. Для полного определения типа см. SettingSource (TypeScript) или SettingSource (Python). Опускание settingSources эквивалентно ["user", "project", "local"]. Параметр cwd определяет, где SDK ищет входные данные уровня проекта. CLAUDE.md и rules загружаются из <cwd> и из каждого родительского каталога. Skills загружаются из <cwd> и из каждого родительского каталога вверх до корня репозитория. Project settings.json и hooks загружаются только из <cwd>/.claude/ без резервного варианта для родительского каталога.

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

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

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

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

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

Все уровни являются аддитивными: если существуют как проектные, так и пользовательские файлы CLAUDE.md, агент видит оба. Между уровнями нет жёсткого правила приоритета; если инструкции конфликтуют, результат зависит от того, как Claude их интерпретирует. Напишите неконфликтующие правила или явно укажите приоритет в более специфичном файле («Эти инструкции проекта переопределяют любые конфликтующие пользовательские значения по умолчанию»).
Вы также можете внедрить контекст непосредственно через 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.
Skills должны быть созданы как артефакты файловой системы (.claude/skills/<name>/SKILL.md). SDK не имеет программного API для регистрации skills. См. Agent Skills в SDK для полных деталей.
Дополнительную информацию о создании и использовании 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 получают входные данные инструмента и возвращают словарь решения. Возврат {} означает разрешить инструменту продолжить. Чтобы заблокировать выполнение, верните объект hookSpecificOutput с permissionDecision: "deny" и permissionDecisionReason. Причина отправляется Claude как результат инструмента. Поля верхнего уровня decision и reason устарели для PreToolUse. См. руководство hooks для полной сигнатуры обратного вызова и типов возврата.

Когда использовать какой тип hook

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

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

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