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 охватывает пользовательские, проектные и локальные параметры. Несколько входов читаются независимо от его значения:
Инструкции проекта (CLAUDE.md и правила)
ФайлыCLAUDE.md и файлы .claude/rules/*.md дают вашему агенту постоянный контекст о вашем проекте: соглашения кодирования, команды сборки, архитектурные решения и инструкции. Когда settingSources включает "project" (как в примере выше), SDK загружает эти файлы в контекст при запуске сеанса. Затем агент следует вашим соглашениям проекта без необходимости повторять их в каждом запросе.
Местоположения загрузки CLAUDE.md
Все уровни являются аддитивными: если существуют как проектные, так и пользовательские файлы
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
TypeScript SDK поддерживает дополнительные события hook помимо Python, включая
SessionStart, SessionEnd, TeammateIdle и TaskCompleted. См. руководство hooks для полной таблицы совместимости событий.Выбор правильной функции
Agent SDK предоставляет вам доступ к нескольким способам расширения поведения вашего агента. Если вы не уверены, какой использовать, эта таблица отображает общие цели на правильный подход.
Каждая функция, которую вы включаете, добавляет к контекстному окну вашего агента. Для затрат на функцию и того, как эти функции слоятся вместе, см. Расширение Claude Code.
Связанные ресурсы
- Расширение Claude Code: Концептуальный обзор всех функций расширения с таблицами сравнения и анализом затрат контекста
- Skills в SDK: Полное руководство по использованию skills программно
- Subagents: Определение и вызов subagents для изолированных подзадач
- Hooks: Перехват и управление поведением агента в ключевых точках выполнения
- Permissions: Управление доступом к инструментам с помощью режимов, правил и обратных вызовов
- System prompts: Внедрение контекста без файлов CLAUDE.md