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).
| Источник | Что он загружает | Местоположение |
|---|---|---|
"project" | Project CLAUDE.md, .claude/rules/*.md, project skills, project hooks, project settings.json | <cwd>/.claude/ для settings.json и hooks; <cwd> и каждый родительский каталог для CLAUDE.md и rules; <cwd> и каждый родительский каталог вверх до корня репозитория для skills |
"user" | User CLAUDE.md, ~/.claude/rules/*.md, user skills, user settings | ~/.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 и rules загружаются из <cwd> и из каждого родительского каталога. Skills загружаются из <cwd> и из каждого родительского каталога вверх до корня репозитория. Project settings.json и hooks загружаются только из <cwd>/.claude/ без резервного варианта для родительского каталога.
Что settingSources не контролирует
settingSources охватывает пользовательские, проектные и локальные параметры. Несколько входов читаются независимо от его значения:
| Вход | Поведение | Для отключения |
|---|---|---|
| Параметры управляемой политики | Всегда загружаются при наличии на хосте | Удалите файл управляемых параметров |
~/.claude.json глобальная конфигурация | Всегда читается | Переместите с помощью CLAUDE_CONFIG_DIR в env |
Автоматическая память в ~/.claude/projects/<project>/memory/ | Загружается по умолчанию в системный запрос | Установите autoMemoryEnabled: false в параметрах или CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 в env |
| claude.ai MCP connectors | Загружаются, когда активный метод аутентификации — это подписка claude.ai. Передача mcpServers: {} их не подавляет | Установите strictMcpConfig: true или ENABLE_CLAUDEAI_MCP_SERVERS=false в 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 и .claude/rules/*.md в каждом родительском каталоге | settingSources включает "project" |
| Project (parent dirs) | Файлы CLAUDE.md в каталогах выше cwd | settingSources включает "project", загружается при запуске сеанса |
| Project (child dirs) | Файлы CLAUDE.md в подкаталогах cwd | settingSources включает "project", загружается по требованию, когда агент читает файл в этом поддереве |
| Local | <cwd>/CLAUDE.local.md и 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 или [] для отключения всех. Когда skills установлен, SDK автоматически добавляет инструмент Skill в allowedTools. Если вы также передаёте явный список tools, включите "Skill" в этот список, чтобы Claude мог вызывать skills.
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.
.claude/settings.json вашего проекта и вы установили settingSources: ["project"], эти hooks автоматически запускаются в SDK без дополнительной конфигурации.
Обратные вызовы Hook получают входные данные инструмента и возвращают словарь решения. Возврат {} означает разрешить инструменту продолжить. Чтобы заблокировать выполнение, верните объект hookSpecificOutput с permissionDecision: "deny" и permissionDecisionReason. Причина отправляется Claude как результат инструмента. Поля верхнего уровня decision и reason устарели для PreToolUse. См. руководство hooks для полной сигнатуры обратного вызова и типов возврата.
Когда использовать какой тип hook
| Тип hook | Лучше всего для |
|---|---|
Filesystem (settings.json) | Совместное использование hooks между сеансами CLI и SDK. Поддерживает "command" (shell-скрипты), "http" (POST на конечную точку), "mcp_tool" (вызов инструмента подключённого MCP-сервера), "prompt" (LLM оценивает запрос) и "agent" (порождает агента-верификатора). Они срабатывают в основном агенте и любых подагентах, которые он порождает. |
Programmatic (обратные вызовы в query()) | Логика, специфичная для приложения, структурированные решения и интеграция в процессе. Эти обратные вызовы также срабатывают внутри подагентов. Обратный вызов получает agent_id и agent_type для различения. |
TypeScript SDK поддерживает дополнительные события hook помимо Python, включая
SessionStart, SessionEnd, TeammateIdle и TaskCompleted. См. руководство 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: Концептуальный обзор всех функций расширения с таблицами сравнения и анализом затрат контекста
- Skills в SDK: Полное руководство по использованию skills программно
- Subagents: Определение и вызов subagents для изолированных подзадач
- Hooks: Перехват и управление поведением агента в ключевых точках выполнения
- Permissions: Управление доступом к инструментам с помощью режимов, правил и обратных вызовов
- System prompts: Внедрение контекста без файлов CLAUDE.md