Создание пользовательских subagents
Создавайте и используйте специализированные AI subagents в Claude Code для рабочих процессов, ориентированных на конкретные задачи, и улучшенного управления контекстом.
Subagents — это специализированные AI-помощники, которые обрабатывают определённые типы задач. Используйте один, когда побочная задача заполнит основной разговор результатами поиска, логами или содержимым файлов, на которые вы больше не будете ссылаться: subagent выполняет эту работу в собственном контексте и возвращает только резюме. Определите пользовательский subagent, когда вы постоянно порождаете одного и того же рабочего с одинаковыми инструкциями.
Каждый subagent работает в собственном контекстном окне с пользовательским системным приглашением, специфическим доступом к инструментам и независимыми разрешениями. Он также отправляет свои собственные запросы, которые учитываются в тех же лимитах использования, что и ваш основной разговор. Когда Claude встречает задачу, соответствующую описанию subagent, он делегирует её этому subagent, который работает независимо и возвращает результаты. Чтобы увидеть экономию контекста на практике, визуализация контекстного окна проходит через сессию, где subagent обрабатывает исследование в собственном отдельном окне.
Subagents работают в рамках одной сессии. Чтобы запустить множество независимых сессий параллельно и отслеживать их из одного места, см. background agents. Для отдельных сессий, которые передают сообщения друг другу, см. cross-session messaging. Для скоординированной команды сессий, которые Claude порождает и контролирует, см. agent teams.
Subagents помогают вам:
- Сохранять контекст, отделяя исследование и реализацию от основного разговора
- Применять ограничения, ограничивая доступ subagent к определённым инструментам
- Переиспользовать конфигурации в проектах с помощью subagents уровня пользователя
- Специализировать поведение с помощью сфокусированных системных приглашений для конкретных областей
- Контролировать затраты, маршрутизируя задачи на более быстрые и дешёвые модели, такие как Haiku
Claude использует описание каждого subagent для решения о делегировании задач. Когда вы создаёте subagent, напишите чёткое описание, чтобы Claude знал, когда его использовать.
Эти описания занимают контекст, поэтому держите их краткими. Когда объединённые описания ваших subagents, кроме встроенных, превышают 15 000 токенов, Claude Code показывает предупреждение при запуске с общим количеством токенов. Сократите поля description ваших subagents и переместите детали в системное приглашение каждого subagent, которое загружается только при запуске этого subagent.
Встроенные subagents
Claude Code включает встроенные subagents, которые Claude автоматически использует при необходимости. Каждый наследует разрешения родительского разговора; большинство работают с ограниченным набором инструментов.
Explore и Plan пропускают ваши файлы CLAUDE.md и снимок статуса git, чтобы исследование было быстрым и экономичным. Все остальные встроенные и пользовательские subagents загружают оба, если только их определение не устанавливает поле omitClaudeMd для пропуска файлов CLAUDE.md пользователя, проекта и локального. Для полного разбора того, что достигает subagent, см. что загружается при запуске.
Быстрый агент, доступный только для чтения, оптимизированный для поиска и анализа кодовых баз.
- Model: наследуется из основного разговора, ограничен Opus на Claude API, поэтому Explore никогда не работает на более дорогой модели, чем та, которую вы уже выбрали для сессии, если только вы не установите
CLAUDE_CODE_SUBAGENT_MODELи не заставите его работать на каждом subagent - Tools: инструменты только для чтения; Write и Edit запрещены
- Purpose: обнаружение файлов, поиск кода, исследование кодовой базы
Начиная с версии 2.1.198, Explore наследует модель основного разговора вместо того, чтобы всегда работать на Haiku. На Claude API унаследованная модель ограничена Opus: основной разговор на более высоком уровне запускает Explore на Opus, а основной разговор на Sonnet или Haiku запускает Explore на той же модели. На любом другом поставщике, таком как Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry или Claude Platform on AWS, Explore наследует модель основного разговора напрямую.
Пользовательский или проектный subagent с именем Explore переопределяет встроенный и сохраняет собственное поле model, поэтому определите его с model: haiku, чтобы сохранить исследование на модели с более низкой стоимостью.
Claude делегирует Explore, когда ему нужно искать или понимать кодовую базу без внесения изменений. Это сохраняет результаты исследования вне контекста основного разговора.
При вызове Explore Claude указывает уровень тщательности: quick для целевых поисков, medium для сбалансированного исследования или very thorough для комплексного анализа.
Исследовательский агент, используемый во время plan mode для сбора контекста перед представлением плана.
- Model: наследуется из основного разговора, если только вы не установите
CLAUDE_CODE_SUBAGENT_MODELи не заставите его работать на каждом subagent - Tools: инструменты только для чтения; Write и Edit запрещены
- Purpose: исследование кодовой базы для планирования
Когда вы находитесь в режиме плана и Claude нужно понять вашу кодовую базу, он делегирует исследование subagent Plan, чтобы результаты исследования оставались в отдельном окне контекста, а основной разговор оставался доступным только для чтения.
Способный агент для сложных многошаговых задач, требующих как исследования, так и действия.
- Model: модель
CLAUDE_CODE_SUBAGENT_MODEL, если вы её установили и ничто не назначает модель другим способом, иначе модель основного разговора; Выбор модели указывает полный порядок, и Запуск каждого subagent на одной модели показывает, как сделать переменную переопределением этих источников - Tools: каждый инструмент доступный для subagents
- Purpose: сложное исследование, многошаговые операции, модификация кода
Claude делегирует general-purpose, когда задача требует как исследования, так и модификации, сложного рассуждения для интерпретации результатов или нескольких зависимых шагов.
Claude Code включает дополнительные вспомогательные агенты для конкретных задач. Обычно они вызываются автоматически, поэтому вам не нужно использовать их напрямую.
| Agent | Model | Когда Claude его использует |
|---|---|---|
| claude | Нет собственной; следует порядку моделей, когда Claude порождает его как subagent | Когда задача не подходит более специализированному агенту. Универсальный агент со всеми инструментами доступными для subagents. Также агент по умолчанию для отправленной фоновой сессии; в каком режиме разрешений он запускается зависит от того, как была запущена сессия |
| statusline-setup | Sonnet | Когда вы запускаете /statusline для настройки строки состояния |
| claude-code-guide | Haiku | Когда вы задаёте вопросы о функциях Claude Code |
Встроенные subagents регистрируются по умолчанию в интерактивных сессиях. Чтобы ограничить их:
- Чтобы заблокировать определённый встроенный тип, добавьте его в
permissions.deny, как показано в Отключение определённых subagents. - Чтобы предотвратить делегирование Claude к любому subagent, запретите сам инструмент
Agentс помощьюpermissions.deny. - Чтобы удалить только встроенные subagents
ExploreиPlan, установитеCLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude читает и исследует файлы напрямую вместо делегирования им. Требуется Claude Code версии 2.1.198 или позже. - В неинтерактивном режиме и Agent SDK установите
CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1для удаления всех встроенных типов и предоставления только ваших собственных.
Вызов инструмента Agent, который опускает subagent_type, завершается ошибкой subagent_type is required, когда сессия не имеет general-purpose subagent для отката.
Помимо этих встроенных subagents, вы можете создавать свои собственные с пользовательскими приглашениями, ограничениями инструментов, режимами разрешений, hooks и skills. В следующих разделах показано, как начать работу и настроить subagents.
Quickstart: создание вашего первого subagent
Subagents определяются в файлах Markdown с YAML frontmatter. Чтобы создать один, попросите Claude написать его для вас или напишите файл самостоятельно.
Начиная с версии v2.1.198, команда /agents больше не открывает интерактивный мастер создания; её запуск выводит напоминание попросить Claude или отредактировать .claude/agents/ напрямую. Файлы subagent, поля frontmatter и местоположения .claude/agents/ и ~/.claude/agents/ остаются неизменными; удалён только терминальный мастер.
Это пошаговое руководство создаёт subagent уровня пользователя, который проверяет код и предлагает улучшения.
Попросите Claude создать subagent
В Claude Code опишите subagent, который вы хотите создать, и где его сохранить:
Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.
Claude создаёт файл с name, description, списком tools, model и системным приглашением.
Проверьте файл
Откройте ~/.claude/agents/code-improver.md и убедитесь, что frontmatter соответствует тому, что вы запросили. Результат выглядит так:
---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---
You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.
Поскольку файл находится в ~/.claude/agents/, subagent доступен в каждом проекте на вашей машине. Чтобы ограничить его одним проектом, переместите его в каталог .claude/agents/ этого проекта. Выберите область действия subagent сравнивает эти два варианта.
Попробуйте
Попросите Claude делегировать новому subagent:
Use the code-improver agent to suggest improvements in this project
Claude делегирует вашему новому subagent, который сканирует кодовую базу и возвращает предложения по улучшению. В расшифровке делегирование отображается как строка вызова инструмента, показывающая имя subagent, за которым следует краткое описание задачи, например code-improver(Suggest code improvements).
Если Claude не может найти новый subagent, перезагрузите Claude Code и попробуйте снова. Это происходит только когда ~/.claude/agents/ не существовал до начала сеанса, потому что работающий сеанс не обнаруживает вновь созданный каталог agents.
Теперь у вас есть subagent, который вы можете использовать в любом проекте на вашей машине для анализа кодовых баз и предложения улучшений.
Вы также можете писать файлы subagent вручную, определять их через флаги CLI или распространять их через plugins. В следующих разделах рассматриваются все параметры конфигурации.
На Claude Code v2.1.197 и более ранних версиях /agents открывает интерактивный мастер с вкладкой Running, которая отображает активные subagents, и вкладкой Library для их создания, редактирования и удаления.
Настройка subagents
Местоположение файла subagent определяет, кому он доступен, а его frontmatter определяет, что он может делать. В этом разделе рассматривается, где находятся файлы subagent и каждое поле, которое они поддерживают.
Выберите область subagent
Сохраняйте файлы subagent в разных местах в зависимости от области. Когда несколько subagents имеют одно и то же имя, Claude Code использует тот, который находится в местоположении с более высоким приоритетом.
| Location | Scope | Priority | Как создать |
|---|---|---|---|
| Managed settings | Организация | 1 (наивысший) | Развёрнуто через managed settings |
--agents CLI flag |
Текущая сессия | 2 | Передайте JSON при запуске Claude Code |
.claude/agents/ |
Текущий проект | 3 | Попросите Claude или создайте файл вручную |
~/.claude/agents/ |
Все ваши проекты | 4 | Попросите Claude или создайте файл вручную |
Директория agents/ plugin |
Где включен plugin | 5 (наименьший) | Установлено с plugins |
Project subagents (.claude/agents/) идеальны для subagents, специфичных для кодовой базы. Проверьте их в систему контроля версий, чтобы ваша команда могла использовать и улучшать их совместно.
Project subagents обнаруживаются путём прохода вверх от текущей рабочей директории, поэтому каждый .claude/agents/ между ней и корнем репозитория сканируется. Когда более одной из этих вложенных директорий определяет одно и то же name, Claude Code использует определение, ближайшее к рабочей директории.
Когда вы добавляете директорию с помощью --add-dir или /add-dir, Claude Code также загружает её папку .claude/agents/ вместе с project subagents. См. Additional directories для того, какие другие типы конфигурации загружаются из --add-dir. Чтобы поделиться subagents в проектах без --add-dir, используйте ~/.claude/agents/ или plugin.
User subagents (~/.claude/agents/) — это личные subagents, доступные во всех ваших проектах.
Claude Code сканирует .claude/agents/ и ~/.claude/agents/ рекурсивно, поэтому вы можете организовать определения в подпапки, такие как agents/review/ или agents/research/. Путь подпапки не влияет на то, как идентифицируется или вызывается subagent, потому что идентичность происходит только из поля name frontmatter.
Сохраняйте значения name уникальными по всему дереву: если два файла под одной директорией .claude/agents/, включая её подпапки, объявляют одно и то же имя, Claude Code загружает только один из них, выбранный по порядку чтения файловой системы, а не по документированному приоритету. Во вложенных директориях проекта определение, ближайшее к рабочей директории, побеждает, как описано выше. Проверка настройки /doctor сообщает о файлах в одной директории, которые имеют одно и то же имя, и предлагает переименовать или удалить все, кроме одного. До версии 2.1.205 /doctor открывал экран диагностики, который перечислял дубликаты и показывал, какое определение было активно.
Директории agents/ plugin также сканируются рекурсивно. В отличие от областей проекта и пользователя, подпапка внутри директории agents/ plugin становится частью scoped identifier: файл в agents/review/security.md в plugin my-plugin регистрируется как my-plugin:review:security.
CLI-определённые subagents передаются как JSON при запуске Claude Code. Они существуют только для этой сессии и не сохраняются на диск, что делает их полезными для быстрого тестирования или скриптов автоматизации. Вы можете определить несколько subagents в одном вызове --agents:
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
},
"debugger": {
"description": "Debugging specialist for errors and test failures.",
"prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
}
}'
claude --agents @'
{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
},
"debugger": {
"description": "Debugging specialist for errors and test failures.",
"prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
}
}
'@
В non-interactive mode --agents также принимает путь к файлу JSON, содержащему тот же объект, для определений, слишком больших для передачи в командной строке. Например, claude -p --agents ./agents.json "Review my changes" читает определения из этого файла. В интерактивной сессии Claude Code отказывает в пути к файлу. Форма файла требует Claude Code v2.1.281 или позже.
Каждый ключ верхнего уровня в JSON — это имя агента, и его значение — это определение этого агента. Не начинайте имя с -. Определение принимает эти поля:
prompt: системное приглашение агента, эквивалентное телу markdown в файловых subagents.promptможет быть пустым. Если вы выбираете агента с пустымpromptи без поляmemoryв качестве агента сессии с помощью--agent, системное приглашение сессии остаётся неизменным. Пустойpromptтребует Claude Code v2.1.281 или позже.- Поля Frontmatter:
description,tools,disallowedTools,model,permissionMode,mcpServers,hooks,maxTurns,skills,initialPrompt,memory,effort,background,omitClaudeMdиisolation. - Игнорируемые поля:
colorиexperimentalне принимаются здесь и игнорируются, а не отклоняются.
Для того, что Claude Code делает со значением, которое он не может загрузить, и флагов и переменной окружения, которые пропускают эту проверку, см. Invalid --agents configuration.
Managed subagents развёртываются администраторами организации. Поместите файлы markdown в .claude/agents/ внутри директории managed settings, используя тот же формат frontmatter, что и project и user subagents. Managed определения имеют приоритет над project и user subagents с тем же именем.
Plugin subagents поступают из plugins, которые вы установили. Они загружаются автоматически вместе с вашими пользовательскими subagents и появляются в typeahead @-упоминания под их scoped name. См. справку по компонентам plugin для деталей создания plugin subagents.
По соображениям безопасности plugin subagents не поддерживают поля frontmatter hooks, mcpServers или permissionMode. Эти поля игнорируются при загрузке агентов из plugin. Если они вам нужны, скопируйте файл агента в .claude/agents/ или ~/.claude/agents/. Вы также можете добавить правила в permissions.allow в settings.json или settings.local.json, но эти правила применяются ко всей сессии, а не только к plugin subagent.
Определения subagent из любой из этих областей также доступны для agent teams: при порождении товарища по команде вы можете ссылаться на тип subagent, и Claude Code применяет части этого определения к товарищу. См. agent teams для того, какие части применяются в каждом режиме отображения.
Напишите файлы subagent
Файлы subagent используют YAML frontmatter для конфигурации, за которым следует системное приглашение в Markdown:
Claude Code наблюдает за ~/.claude/agents/ и .claude/agents/. Когда вы добавляете или редактируете файл subagent на диск, или просите Claude написать его для вас, Claude Code обнаруживает изменение в течение нескольких секунд и следующее делегирование использует обновленное определение без необходимости перезагрузки.
Три случая по-прежнему требуют перезагрузки:
- Наблюдатель охватывает только директории, которые существовали при запуске сессии, поэтому после создания первого файла агента области в новой директории
agents, перезагрузитесь для его загрузки. - Claude Code не наблюдает
.claude/agents/внутри директорий, добавленных с помощью--add-dirили/add-dir, поэтому после добавления или редактирования subagent там, перезагрузитесь для загрузки изменения. - Сессии, запущенные с
--disable-slash-commands, вообще не наблюдают эти директории.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
Frontmatter определяет метаданные и конфигурацию subagent. Тело становится системным приглашением, которое направляет поведение subagent. Subagents получают только это системное приглашение плюс базовые детали окружения, такие как рабочая директория, а не системное приглашение Claude Code.
В non-interactive mode передайте --append-subagent-system-prompt для добавления вашего текста в конец системного приглашения каждого subagent, включая вложенные subagents, кроме forked subagent, который переиспользует приглашение разговора. Требует Claude Code v2.1.205 или позже. Если ваш текст слишком длинный для передачи в командной строке, сохраните его в файл и передайте путь с помощью --append-subagent-system-prompt-file вместо этого. Флаг файла требует Claude Code v2.1.261 или позже.
Subagent начинает работу в текущей рабочей директории основного разговора. В пределах subagent команды cd не сохраняются между вызовами инструментов Bash или PowerShell и не влияют на рабочую директорию основного разговора. Чтобы дать subagent изолированную копию репозитория вместо этого, установите isolation: worktree.
Subagent с isolation: worktree запускает свои команды Bash и PowerShell внутри своего worktree. Команда, рабочая директория которой разрешается в вашу основную копию вместо этого, например потому что директория worktree была удалена во время работы subagent, завершается с ошибкой. До версии 2.1.203 такая команда могла запуститься в основной копии.
Эта проверка рабочей директории охватывает весь репозиторий, содержащий директорию, из которой вы запустили Claude Code. Когда ваша сессия работает в связанном worktree своём собственном, проверка также охватывает основную копию, из которой этот worktree связан. До версии 2.1.210 проверка охватывала только саму директорию запуска. Команда, рабочая директория которой разрешалась в другом месте в том же репозитории, такая как корень репозитория, когда вы запустили Claude Code из подпапки monorepo, запускалась там вместо того, чтобы не выполняться.
Для команд Bash Claude Code также проверяет саму команду двумя способами:
- Он блокирует команду, которая перенаправляет git в основную копию.
- Он отказывает в команде, когда он не может проверить из текста команды, что любой git, который команда запускает, остаётся внутри worktree, например когда имя команды вычисляется во время выполнения.
Векторы перенаправления и правила формы перечислены в разделе How Claude Code enforces isolation. Команды PowerShell получают только проверку рабочей директории.
Команды Monitor проходят через те же проверки рабочей директории и содержимого команды, что и команды Bash.
Когда основной разговор сам работает изолированно в worktree, Claude Code применяет те же проверки к сессии и к каждому subagent, который он порождает, включая subagents без isolation: worktree; см. How Claude Code enforces isolation.
Справочник Frontmatter
Настройте subagent с помощью YAML frontmatter между маркерами --- в верхней части его файла, и напишите его системное приглашение как Markdown после закрывающего ---. Требуются только name и description.
Многословные имена полей используют camelCase, такие как maxTurns и disallowedTools, и должны точно совпадать с таблицей: Claude Code игнорирует поле, которое он не распознаёт, без сообщения об ошибке. Чтобы узнать, почему файл subagent не загрузился, см. Subagent files Claude Code skips.
| Field | Требуется | Description |
|---|---|---|
name |
Да | Уникальный идентификатор, такой как code-reviewer или reviewer-v2. Hooks получают это значение как agent_type. Имя файла не должно совпадать. Имена не могут содержать :, который зарезервирован для plugin-scoped identifiers таких как my-plugin:reviewer. Claude Code не загружает файл, чьё имя содержит один, и регистрирует ошибку в журнал отладки. До версии 2.1.218 такие имена были приняты |
description |
Да | Когда Claude должен делегировать этому subagent |
tools |
Нет | Инструменты, которые может использовать subagent, как строка, разделённая запятыми, такая как Read, Grep, Bash или список YAML. Наследует каждый инструмент, доступный для subagents, если опущено. Если ни один элемент в списке не разрешается в инструмент, subagent обычно не запускается с ошибкой, называющей элементы. Чтобы предварительно загрузить Skills в контекст, используйте поле skills вместо перечисления Skill здесь |
disallowedTools |
Нет | Инструменты для запрета, удалённые из унаследованного или указанного списка. Тот же формат, что и tools. Запись со спецификатором, такая как Bash(git push *), по-прежнему удаляет весь инструмент |
model |
Нет | Модель для использования: sonnet, opus, haiku, fable, полный ID модели, такой как claude-opus-5-5, или inherit. Когда вы опускаете его, Claude Code выбирает модель в subagent model order |
permissionMode |
Нет | Режим разрешений: default, acceptEdits, auto, dontAsk, bypassPermissions, plan, или manual как псевдоним для default. Псевдоним manual требует Claude Code v2.1.200 или позже. Игнорируется для plugin subagents |
maxTurns |
Нет | Максимальное количество агентских ходов перед остановкой subagent. Когда subagent достигает лимита, Claude Code возвращает его вывод, отмеченный как частичный, и Claude может возобновить его для продолжения. Частичная маркировка требует Claude Code v2.1.246 или позже |
skills |
Нет | Skills для предварительной загрузки в контекст subagent при запуске. Полное содержимое skill инжектируется, а не просто описание. Subagents по-прежнему могут вызывать неперечисленные project, user и plugin skills через инструмент Skill |
mcpServers |
Нет | MCP servers доступные этому subagent. Каждая запись — это либо имя сервера, ссылающееся на уже настроенный сервер (например, "slack"), либо встроенное определение с именем сервера в качестве ключа и полной конфигурацией MCP server в качестве значения. Игнорируется для plugin subagents |
hooks |
Нет | Lifecycle hooks в области этого subagent. Игнорируется для plugin subagents |
memory |
Нет | Область постоянной памяти: user, project или local. Включает кросс-сессионное обучение |
background |
Нет | Установите на true, чтобы держать этот subagent в фоне даже когда Claude просит запустить его на переднем плане. Где fork mode включен, Claude Code уже запускает subagents, которые Claude порождает, в фоне |
omitClaudeMd |
Нет | Установите на true, чтобы запустить этот subagent без файлов user, project и local CLAUDE.md; managed policy files по-прежнему загружаются, кроме managed subagents. Используйте это для subagents, которые берут всё необходимое из delegation prompt. Игнорируется, когда агент работает как основной агент сессии через --agent или параметр agent. Требует Claude Code v2.1.271 или позже |
effort |
Нет | Уровень усилий, когда этот subagent активен. Переопределяет уровень усилий сессии. По умолчанию: наследуется из сессии. Параметры: low, medium, high, xhigh, max; доступные уровни зависят от модели |
isolation |
Нет | Установите на worktree, чтобы запустить subagent во временном git worktree, дав ему изолированную копию репозитория, разветвлённую по умолчанию от вашей ветки по умолчанию, а не от HEAD родительской сессии. Worktree автоматически очищается, если subagent не вносит изменения |
color |
Нет | Цвет отображения для subagent в списке задач и транскрипте. Принимает red, blue, green, yellow, purple, orange, pink или cyan |
initialPrompt |
Нет | Автоматически отправляется как первый ход пользователя, когда этот агент работает как основной агент сессии (через --agent или параметр agent). Commands и skills обрабатываются. Добавляется в начало любого предоставленного пользователем приглашения. Игнорируется для plugin subagents |
experimental |
Нет | Карта экспериментальных опций. Установите её ключ cacheTtl на 5m или 1h для выбора lifetime кэша приглашения для запросов этого subagent, в месте frontmatter в cache lifetime precedence. Claude Code игнорирует любое другое значение, игнорирует 1h пока ваша подписка Claude использует кредиты использования, и читает поле только из файлов subagent. Требует Claude Code v2.1.248 или позже |
Напишите cacheTtl внутри карты experimental, а не на верхнем уровне frontmatter.
---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
cacheTtl: 1h
---
Файлы subagent, которые Claude Code пропускает
Claude Code пропускает файл в директории project, user или managed agents, или в одной под директорией, которую вы добавляете с помощью --add-dir, без сообщения об этом в сессии, когда frontmatter имеет любую из этих проблем:
- Нет
name: Claude Code рассматривает файл как документацию, хранящуюся рядом с вашими агентами. - Открывающий
---, который не является первой строкой файла: Claude Code читает файл как не имеющий frontmatter и рассматривает его как документацию. name, который начинается с-или содержит:: Claude Code пропускает файл и записывает ошибку в журнал отладки. См. строкуnameв таблице выше.name, но нетdescription: Claude Code пропускает файл и записывает причину в журнал отладки.- YAML, который не парсится: Claude Code не читает никакие поля из файла, пропускает его и записывает ошибку парсинга в журнал отладки.
Чтобы увидеть журнал отладки, запустите Claude Code с --debug.
Plugin subagent, чей frontmatter не имеет name или не парсится, по-прежнему загружается под его именем файла.
Проверьте директорию `agents` перед сессией
Чтобы найти файлы в директории agents, чей frontmatter не парсится, запустите claude plugin validate против директории, например .claude/agents или ~/.claude/agents. Claude Code проверяет только директорию, которую вы называете, и не помечает файл, чей frontmatter парсится, но не имеет name. Требует Claude Code v2.1.233 или позже.
Выберите модель
Поле model контролирует, какую модель использует subagent:
- Model alias: используйте один из доступных псевдонимов:
sonnet,opus,haikuилиfable - Full model ID: используйте полный ID модели, такой как
claude-opus-5-5илиclaude-sonnet-5. Принимает те же значения, что и флаг--model - inherit: используйте ту же модель, что и основной разговор
Когда Claude вызывает subagent, он также может передать параметр model для этого конкретного вызова. Claude Code разрешает модель subagent в этом порядке:
- Параметр
modelдля конкретного вызова - Frontmatter
modelопределения subagent, гдеinheritвыбирает модель основного разговора - Переменная окружения
CLAUDE_CODE_SUBAGENT_MODEL, когда вы устанавливаете её на псевдоним модели или ID модели - Модель основного разговора
В двух случаях семейный псевдоним, такой как opus, в параметре для конкретного вызова или frontmatter разрешается в модель основного разговора вместо версии, на которую указывает псевдоним:
- Модель основного разговора принадлежит этому семейству: subagent работает на точной модели основного разговора, включая любой суффикс
[1m], поэтому он получает то же extended context окно, что и основной разговор. - Claude Code не может определить семейство модели основного разговора, на поставщике, отличном от Anthropic API: это может произойти с application inference profile ARN на Amazon Bedrock, который Claude Code не разрешил в резервную модель. Этот случай охватывает только псевдоним
opusи не применяется, когда вы устанавливаетеANTHROPIC_DEFAULT_OPUS_MODEL, посколькуopusзатем разрешается в модель, которую вы установили.
Псевдоним в CLAUDE_CODE_SUBAGENT_MODEL всегда разрешается в версию, на которую указывает псевдоним, даже когда он называет семейство основного разговора.
Установка CLAUDE_CODE_SUBAGENT_MODEL сама по себе не изменяет модель, на которой работают встроенные subagents Explore и Plan. Чтобы изменить её, см. Run every subagent on one model.
До версии 2.1.251 CLAUDE_CODE_SUBAGENT_MODEL был первым в этом порядке и переопределял как параметр для конкретного вызова, так и frontmatter, включая model: inherit.
Установка переменной на inherit — это то же самое, что оставить её неустановленной. До версии 2.1.196 это значение заставляло subagents использовать модель основного разговора и игнорировало оба этих источника.
Claude Code проверяет параметр для конкретного вызова, frontmatter и значения переменной окружения на соответствие списку разрешений availableModels вашей организации. Для заблокированного значения он подставляет другую модель:
- Когда заблокированное значение — это семейный псевдоним, такой как
opus, Claude Code запускает subagent на самой новой версии этого семейства, которое разрешает список разрешений, следуя тем же правилам подстановки и области поставщика, что и/model. До версии 2.1.222 Claude Code запускал subagent на унаследованной модели для заблокированного семейного псевдонима также. - Для любого другого заблокированного значения, на поставщиках, где эта подстановка не работает, или когда список разрешений не разрешает никакую версию семейства, Claude Code запускает subagent на унаследованной модели вместо этого. Если вы установили
CLAUDE_CODE_SUBAGENT_MODEL, Claude Code сначала пробует эту модель, под этими же правилами.
В интерактивных сессиях Claude Code показывает предупреждение, называющее запрошенную модель и модель, на которой работает subagent, для любой подстановки.
Чтобы проверить, на какой модели работает subagent, запустите /tasks. Claude Code называет модель в строке subagent и добавляет уровень усилий, когда определение subagent или skill, из которого он был разветвлён, устанавливает effort. Требует Claude Code v2.1.242 или позже.
Параметр model для конкретного вызова также применяется, когда subagent возобновляется или получает последующее сообщение, поэтому subagent остаётся на этой модели. До версии 2.1.211 возобновление отбрасывало значение для конкретного вызова и subagent возвращался к полю model его определения или, без него, модели основного разговора.
Начиная с версии 2.1.198, subagents также наследуют конфигурацию extended thinking основного разговора: если thinking включен в вашей сессии, он включен для subagent, и если он выключен, он остаётся выключенным. Нет параметра thinking для каждого subagent. До версии 2.1.198 subagents запускались с отключённым extended thinking независимо от параметра основного разговора.
Запустите каждый subagent на одной модели
CLAUDE_CODE_SUBAGENT_MODEL — это значение по умолчанию, поэтому определение subagent или модель, которую передаёт Claude, по-прежнему имеют приоритет над ним. Чтобы применить одну модель к каждому subagent, teammate и workflow agent, также установите CLAUDE_CODE_SUBAGENT_MODEL_FORCE на 1. Требует Claude Code v2.1.257 или позже.
- Если вы установили обе переменные, subagents работают на модели в
CLAUDE_CODE_SUBAGENT_MODEL. - Если вы установили только
CLAUDE_CODE_SUBAGENT_MODEL_FORCE, subagents работают на модели основного разговора.
Например, чтобы запустить каждый subagent на Haiku, установите обе переменные в блоке env файла настроек:
{
"env": {
"CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
"CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
}
}
Чтобы проверить, что параметр вступил в силу, запустите /tasks пока работает subagent. Строка subagent показывает модель, на которой он работает.
Пока CLAUDE_CODE_SUBAGENT_MODEL_FORCE включен, Claude Code игнорирует поле model каждого определения subagent, включая встроенные subagents Explore и Plan, и Claude не может передать модель при запуске subagent. Два вида subagent по-прежнему работают на модели основного разговора:
- Fork
- Skill, который работает в subagent с
model: inherit
Когда вы устанавливаете только CLAUDE_CODE_SUBAGENT_MODEL_FORCE, встроенный subagent Explore сохраняет свой model cap.
Контролируйте возможности subagent
Вы можете контролировать, что могут делать subagents, через доступ к инструментам, режимы разрешений и условные правила.
Доступные инструменты
Subagents наследуют встроенные инструменты и MCP инструменты, доступные в основном разговоре, сужены двумя фильтрами: первый удаляет короткий список инструментов из каждого subagent, и второй уменьшает набор встроенных инструментов для subagents, которые работают в фоне, что является значением по умолчанию. На macOS, Linux и WSL subagent также может получить инструменты Glob и Grep, когда основной разговор их не имеет, как описано в разделе Glob tool behavior. Forks пропускают оба фильтра и получают точный пул инструментов основного разговора. Первый фильтр удаляет эти инструменты, даже когда они указаны в поле tools:
Agent, когда subagent находится на depth limit; в fork инструмент остаётся в списке, но возвращает ошибку вместо порожденияAskUserQuestionEndConversation, который может завершить только основной разговор; см. EndConversation tool behaviorEnterPlanModeExitPlanMode, если толькоpermissionModesubagent не являетсяplanScheduleWakeupWaitForMcpServersWorkflow
Второй фильтр применяется к subagents, работающим в фоне. Кроме Agent и ExitPlanMode, которые следуют условиям первого фильтра везде, где работает subagent, фоновый subagent сохраняет каждый MCP инструмент, но только эти встроенные инструменты: Read, Grep, Glob, LSP, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage и Artifact, плюс SubagentHandback для subagent, который сообщает через него. Claude Code удаляет каждый другой встроенный инструмент из фонового subagent, унаследованный или указанный в поле tools, поэтому одно и то же определение может разрешаться в разные инструменты на переднем плане и в фоне. Удаление сообщает об ошибке только в том случае, если после него список tools оказывается пустым.
До версии 2.1.280 фоновые subagents не могли использовать LSP.
ListAgents следует этим фильтрам как любой встроенный инструмент: передний subagent наследует его в сессиях, где включен кросс-сессионный обмен сообщениями, и фоновый subagent его не сохраняет.
Teammates в agent teams дополнительно сохраняют инструменты задач и инструменты cron: TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete и CronList.
В сессии без инструментов Task Claude Code не предоставляет инструменты задач subagents либо, даже когда subagent запускает другую модель. Встроенный teammate следует вашей сессии так же, пока teammate в своей собственной split pane работает как отдельный процесс Claude Code, поэтому его собственная модель решает.
Чтобы ограничить инструменты, используйте поле tools как список разрешений или поле disallowedTools как список запретов. Этот пример использует tools для исключительного разрешения Read, Grep, Glob и Bash. Subagent не может редактировать файлы, писать файлы или использовать какие-либо MCP инструменты:
---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---
Этот пример использует disallowedTools для наследования доступных инструментов, кроме Write и Edit. Subagent сохраняет Bash, MCP инструменты и остальное из своего пула:
---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---
Если оба установлены, disallowedTools применяется первым, затем tools разрешается против оставшегося пула. Инструмент, указанный в обоих, удаляется.
Когда ничего в списке tools не разрешается в инструмент, например потому что каждая запись неправильно написана или называет инструмент, который недоступен для subagents, Claude Code обычно отказывается запускать subagent и инструмент Agent возвращает ошибку, называющую неразрешённые записи; см. Agent would be spawned with zero tools для сообщения и как исправить каждую запись. До версии 2.1.208 этот subagent запускался без инструментов и мог вернуть пустой или запутанный результат.
Оба поля принимают паттерны уровня MCP сервера в дополнение к точным названиям инструментов: mcp__<server> или mcp__<server>__* предоставляет или удаляет каждый инструмент из названного сервера. В disallowedTools, mcp__* также удаляет каждый MCP инструмент из любого сервера. Этот пример удаляет каждый инструмент из MCP сервера github, сохраняя инструменты из других серверов и встроенные инструменты в его пуле:
---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---
Запись disallowedTools со спецификатором, такая как Bash(git push *), по-прежнему удаляет весь инструмент из subagent, а не только соответствующие команды. Чтобы сохранить Bash и заблокировать конкретные команды, добавьте Bash deny rule, такую как Bash(git push *), в permissions.deny в ваших настройках. Правило применяется к основному разговору и к subagents.
Ограничьте, какие subagents могут быть порождены
Когда агент работает как основной поток с claude --agent, он может порождать subagents, используя инструмент Agent. Чтобы ограничить, какие типы subagent он может порождать, используйте синтаксис Agent(agent_type) в поле tools.
В версии 2.1.63 инструмент Task был переименован в Agent. Существующие ссылки Task(...) в настройках и определениях агентов по-прежнему работают как псевдонимы.
---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---
Это список разрешений: только subagents worker и researcher могут быть порождены. Если агент попытается порождать любой другой тип, запрос не удастся и агент увидит только разрешённые типы в своём приглашении. Чтобы заблокировать конкретные агенты, разрешив все остальные, используйте permissions.deny вместо этого.
Чтобы разрешить порождение любого subagent без ограничений, используйте Agent без скобок:
tools: Agent, Read, Bash
Если Agent полностью опущен из списка tools, агент не может порождать никакие subagents с инструментом Agent.
Синтаксис списка разрешений Agent(agent_type) применяется только к агенту, работающему как основной поток с claude --agent. В определении subagent перечисление Agent в tools позволяет этому subagent порождать subagents своего собственного, пока depth limit позволяет это, но любой список типов внутри скобок игнорируется.
Область MCP servers для subagent
Используйте поле mcpServers для предоставления subagent доступа к MCP серверам, которые недоступны в основном разговоре. Встроенные серверы, определённые здесь, подключаются при запуске subagent, в соответствии с правилом доверия для папки файла агента, и отключаются при его завершении. Строковые ссылки используют соединение родительской сессии.
Поле mcpServers применяется в обоих контекстах, где может работать файл агента:
- Как subagent, порождённый через инструмент Agent или @-упоминание
- Как основная сессия, запущенная с
--agentили параметромagent
Когда агент является основной сессией, встроенные определения серверов подключаются при запуске вместе с серверами из .mcp.json и файлов настроек, под тем же правилом доверия для папки файла агента. В /mcp удалённый (HTTP или SSE) сервер, который вы использовали раньше, может показать cached статус вместо этого; Claude Code подключает его, когда Claude впервые вызывает один из его инструментов.
Каждая запись в списке — это либо встроенное определение сервера, либо строка, ссылающаяся на MCP сервер, уже настроенный в вашей сессии:
---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
# Inline definition: scoped to this subagent only
- playwright:
type: stdio
command: npx
args: ["-y", "@playwright/mcp@latest"]
# Reference by name: reuses an already-configured server
- github
---
Use the Playwright tools to navigate, screenshot, and interact with pages.
Встроенные определения используют ту же схему, что и записи сервера .mcp.json, ключевые по имени сервера, и поддерживают типы stdio, http, sse и ws.
Чтобы исключить MCP сервер из основного разговора полностью и избежать того, чтобы описания его инструментов потребляли контекст там, определите его встроенным здесь, а не в .mcp.json. Subagent получает инструменты; родительский разговор — нет.
Claude Code загружает встроенный сервер из файла агента в директории .claude/agents/ вашего проекта, или в директории .claude/agents/ директории, добавленной с помощью --add-dir, только после того, как вы доверяете папке, из которой пришёл файл агента. До версии 2.1.238 Claude Code загружал эти серверы без проверки доверия.
- Доверие, которое не считается: доверие родительской папки и автоматическое доверие, которое сессия
-pили SDK получает для hooks в файлах настроек - До тех пор: Claude Code пропускает каждый встроенный сервер в этом файле агента и записывает точный ключ
projects["<path>"].hasTrustDialogAcceptedдля~/.claude.jsonв журнал отладки - Директории
--add-dir: директория вне репозитория вашего доверенного рабочего пространства нуждается в собственной записи доверия, поскольку её файлы.claude/agents/не наследуют доверие вашего рабочего пространства
Claude Code загружает два вида сервера без проверки доверия для папки, из которой пришёл файл агента:
- Имя, которое ссылается на сервер, который вы уже настроили
- Встроенный сервер в файле агента из
~/.claude/agents/, в одном, который вы передаёте с помощью--agentsили опции SDKagents, или в одном, который управляемые настройки предоставляют
Ограничения MCP, которые применяются к основной сессии, также охватывают серверы, объявленные в frontmatter subagent:
--strict-mcp-configи--bare- Enterprise управляемая конфигурация MCP
allowedMcpServersиdeniedMcpServersполитики
Когда один из них блокирует сервер, Claude Code пропускает его и показывает предупреждение, называющее заблокированные серверы.
Ограничения управляемых настроек применяются к каждому subagent независимо от того, как он определён. --strict-mcp-config не фильтрует серверы, которые вы передаёте встроенным образом через --agents или опцию SDK agents, поскольку это явный ввод вызывающей стороны.
Режимы разрешений
Установите permissionMode для выбора режима разрешений, в котором работает subagent. Используйте значения конфигурации режимов, поэтому режим Manual — это default. Если вы оставите его неустановленным, subagent наследует режим основного разговора permission mode.
Режим разрешений основного разговора решает, использует ли Claude Code значение, которое вы установили:
- Когда основной разговор находится в
bypassPermissions,acceptEditsили auto mode, subagent работает в этом же режиме и Claude Code игнорируетpermissionMode, который вы установили. Под auto mode классификатор оценивает вызовы инструментов subagent с правилами блокировки и разрешения основного разговора. Когда subagent завершается, классификатор также проверяет его работу и его финальный отчёт перед доставкой отчёта, как How auto mode handles subagents описывает. - Когда основной разговор находится в режиме
default,dontAskилиplan, subagent работает в режиме разрешений, который вы установили, кромеbypassPermissions. Subagent, который объявляетbypassPermissions, сохраняет режим основного разговора вместо этого. ИсключениеbypassPermissionsтребует Claude Code v2.1.267 или позже.
permissionMode принимает эти значения и manual как псевдоним для default:
| Mode | Behavior |
|---|---|
default |
Режим Manual: запрашивает разрешение |
acceptEdits |
Автоматически принимать редактирование файлов и общие команды файловой системы для путей в рабочей директории или additionalDirectories |
auto |
Auto mode: классификатор в фоне проверяет команды и записи в защищённые директории |
dontAsk |
Автоматически отклонять запросы разрешений. Явно разрешённые инструменты по-прежнему работают; AskUserQuestion, MCP инструменты, отмеченные requiresUserInteraction, и инструменты соединителя которые ваша организация установила на ask в сессиях, где этот параметр достигает Claude Code, отклоняются, даже если вы их разрешили |
bypassPermissions |
Пропустить запросы разрешений. Subagent работает в этом режиме только когда основной разговор это делает |
plan |
Режим Plan (исследование только для чтения) |
Предварительная загрузка skills в subagents
Используйте поле skills для инжекции содержимого skill в контекст subagent при запуске. Это даёт subagent знания в области без необходимости открывать и загружать skills во время выполнения.
---
name: api-developer
description: Implement API endpoints following team conventions
skills:
- api-conventions
- error-handling-patterns
---
Implement API endpoints. Follow the conventions and patterns from the preloaded skills.
Полное содержимое каждого перечисленного skill инжектируется в контекст subagent при запуске. Это поле контролирует, какие skills предварительно загружаются, а не какие skills может использовать subagent: без него subagent по-прежнему может открывать и вызывать project, user и plugin skills через инструмент Skill во время выполнения. Чтобы предотвратить использование subagent skills полностью, опустите Skill из списка tools или добавьте его в disallowedTools.
Вы не можете предварительно загружать skills, которые устанавливают disable-model-invocation: true, поскольку предварительная загрузка берёт из того же набора skills, который Claude может вызывать. Это включает встроенный skill /verify: только вы можете его запустить, поэтому он не может быть предварительно загружен либо.
Если указанный skill отсутствует или отключен, например политикой вашей организации, Claude Code пропускает его и регистрирует предупреждение в журнал отладки.
Это противоположность запуску skill в subagent. С skills в subagent, subagent контролирует системное приглашение и загружает содержимое skill. С context: fork в skill, содержимое skill инжектируется в агента, который вы указываете. В обоих случаях subagent начинает работу без истории вашего разговора.
Включите постоянную память
Поле memory даёт subagent постоянный каталог, который сохраняется между разговорами. Subagent использует этот каталог для накопления знаний со временем, таких как паттерны кодовой базы, идеи отладки и архитектурные решения.
---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---
You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.
Выберите область в зависимости от того, насколько широко должна применяться память:
| Scope | Location | Используйте когда |
|---|---|---|
user |
~/.claude/agent-memory/<name-of-agent>/ |
subagent должен помнить обучение во всех проектах |
project |
.claude/agent-memory/<name-of-agent>/ |
знания subagent специфичны для проекта и доступны для совместного использования через систему контроля версий |
local |
.claude/agent-memory-local/<name-of-agent>/ |
знания subagent специфичны для проекта, но не должны проверяться в систему контроля версий |
Память subagent является частью auto memory: если вы отключите auto memory с помощью параметра autoMemoryEnabled или CLAUDE_CODE_DISABLE_AUTO_MEMORY, поле memory не имеет эффекта и subagent запускается без инструкций памяти или доступа к инструменту памяти, описанного ниже.
Когда память включена:
- Системное приглашение subagent включает инструкции для чтения и записи в каталог памяти.
- Системное приглашение subagent также включает первые 200 строк или 25KB
MEMORY.mdв каталоге памяти, в зависимости от того, что меньше, с инструкциями по курированиюMEMORY.md, если она превышает этот лимит. - Инструменты Read, Write и Edit автоматически включаются, чтобы subagent мог управлять своими файлами памяти.
Советы по постоянной памяти
-
project— рекомендуемая область по умолчанию. Это делает знания subagent доступными для совместного использования через систему контроля версий. -
Попросите subagent проверить его память перед началом работы: "Review this PR, and check your memory for patterns you've seen before."
-
Попросите subagent обновить его память после завершения задачи: "Now that you're done, save what you learned to your memory." Со временем это создаёт базу знаний, которая делает subagent более эффективным.
-
Включите инструкции по памяти непосредственно в файл markdown subagent, чтобы он активно поддерживал свою собственную базу знаний:
Update your agent memory as you discover codepaths, patterns, library locations, and key architectural decisions. This builds up institutional knowledge across conversations. Write concise notes about what you found and where.
Условные правила с hooks
Для более динамического контроля использования инструментов используйте PreToolUse hooks для проверки операций перед их выполнением. Это полезно, когда вам нужно разрешить некоторые операции инструмента, блокируя другие.
Этот пример создаёт subagent, который разрешает только запросы к базе данных только для чтения. Hook PreToolUse запускает скрипт, указанный в command, перед каждым выполнением команды Bash:
---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
Claude Code передаёт входные данные hook как JSON через stdin командам hook. Скрипт валидации читает этот JSON, извлекает команду Bash и выходит с кодом 2 для блокировки операций записи:
#!/bin/bash
# ./scripts/validate-readonly-query.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
echo "Blocked: Only SELECT queries are allowed" >&2
exit 2
fi
exit 0
На macOS и Linux сделайте скрипт исполняемым, или hook не выполнится вместо блокировки чего-либо:
chmod +x ./scripts/validate-readonly-query.sh
Чтобы протестировать правило, попросите subagent запустить оператор UPDATE: скрипт выходит с кодом 2, Claude Code блокирует команду, и subagent видит сообщение Blocked: Only SELECT queries are allowed.
См. Hook input для полной схемы входных данных и exit codes для того, как коды выхода влияют на поведение. На Windows напишите скрипты hook в PowerShell и добавьте shell: powershell к записи hook, как показано в запуске hooks в PowerShell.
Отключите конкретные subagents
Вы можете предотвратить использование Claude конкретных subagents, добавив их в массив deny в ваших settings. Используйте формат Agent(subagent-name), где subagent-name соответствует полю name subagent.
{
"permissions": {
"deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
}
}
Это работает как для встроенных, так и для пользовательских subagents. Вы также можете использовать флаг CLI --disallowedTools:
claude --disallowedTools "Agent(Explore)"
См. документацию Permissions для получения дополнительной информации о правилах разрешений.
Определите hooks для subagents
Subagents могут определять hooks, которые запускаются во время жизненного цикла subagent. Есть два способа настройки hooks:
- В frontmatter subagent: определите hooks, которые запускаются только во время активности этого subagent
- В
settings.json: определите hooks уровня сессии, которые также срабатывают внутри subagents. События инструментов, такие какPreToolUseиPostToolUse, срабатывают для вызовов инструментов subagent так же, как они срабатывают в основном разговоре, иSubagentStartиSubagentStopсрабатывают, когда subagent начинает или завершает работу
Hooks из файлов настроек, управляемых параметров политики и plugins все применяются внутри subagents, поэтому hook PreToolUse в settings.json также запускается перед каждым инструментом, который использует subagent.
Hooks в frontmatter subagent
Определите hooks непосредственно в файле markdown subagent. Эти hooks запускаются только во время активности этого конкретного subagent и очищаются при его завершении.
Frontmatter hooks срабатывают, когда агент порождается как subagent через инструмент Agent или @-упоминание, и когда агент работает как основной агент сессии через --agent или параметр agent. В случае основной сессии они запускаются вместе с любыми hooks, определёнными в settings.json.
Чтобы позволить frontmatter hooks subagent уровня проекта запуститься, примите диалог доверия рабочего пространства для папки, которая содержит файл агента. Hooks из user-level subagents в ~/.claude/agents/ и из определений, которые вы передаёте с помощью --agents, запускаются без этого шага. Если вы добавили папку с помощью --add-dir из вне репозитория вашего доверенного рабочего пространства, доверьте эту папку отдельно: её hooks .claude/agents/ не наследуют доверие рабочего пространства.
До тех пор, пока вы не доверяете папке, subagent по-прежнему работает, но Claude Code пропускает его frontmatter hooks и регистрирует ошибку в журнал отладки, объясняющую, как доверить папке. Это более строгое правило, чем для hooks в файлах настроек: доверие родительской папки недостаточно, и сессия -p не считается доверенной. What runs before you trust a folder сравнивает эти два. До версии 2.1.218 frontmatter hooks могли запускаться из папок, которым вы не доверяли, включая в non-interactive сессиях.
Поддерживаются все hook events. Наиболее распространённые события для subagents:
| Event | Matcher input | Когда это срабатывает |
|---|---|---|
PreToolUse |
Имя инструмента | Перед использованием инструмента subagent |
PostToolUse |
Имя инструмента | После использования инструмента subagent |
Stop |
(none) | Когда subagent завершается (преобразуется в SubagentStop во время выполнения) |
Этот пример проверяет команды Bash с помощью hook PreToolUse и запускает linter после редактирования файлов с помощью PostToolUse:
---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-command.sh $TOOL_INPUT"
PostToolUse:
- matcher: "Edit|Write"
hooks:
- type: command
command: "./scripts/run-linter.sh"
---
Когда агент вызывается как subagent, hooks Stop в frontmatter автоматически преобразуются в события SubagentStop.
Hooks уровня проекта для событий subagent
Настройте hooks в settings.json, которые реагируют на события жизненного цикла subagent в основной сессии.
| Event | Matcher input | Когда это срабатывает |
|---|---|---|
SubagentStart |
Имя типа агента | Когда subagent начинает выполнение |
SubagentStop |
Имя типа агента | Когда subagent завершает выполнение |
Оба события поддерживают matchers для нацеливания на конкретные типы агентов по имени. Значение matcher — это поле frontmatter name для project-level и user-level subagents, или scoped identifier, такой как my-plugin:db-agent для plugin subagents. Scoped name содержит двоеточие, поэтому он оценивается как unanchored regular expression; закрепите его с помощью ^ и $, как в ^my-plugin:db-agent$, чтобы соответствовать только этому агенту.
Этот пример запускает скрипт установки только при запуске subagent db-agent и скрипт очистки при остановке любого subagent:
{
"hooks": {
"SubagentStart": [
{
"matcher": "db-agent",
"hooks": [
{ "type": "command", "command": "./scripts/setup-db-connection.sh" }
]
}
],
"SubagentStop": [
{
"hooks": [
{ "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
]
}
]
}
}
Matcher с дефисом, такой как db-agent, точно совпадает на Claude Code v2.1.195 или позже. На более ранних версиях он оценивается как unanchored regular expression и также срабатывает для любого типа агента, который его содержит, такого как prod-db-agent; закрепите его как ^db-agent$ на этих версиях.
См. Hooks для полного формата конфигурации hook.
Работа с подагентами
Понимание автоматического делегирования
Claude автоматически делегирует задачи на основе описания задачи в вашем запросе, поля description в конфигурациях подагентов и текущего контекста. Чтобы поощрить проактивное делегирование, включите фразы вроде "use proactively" в поле описания вашего подагента.
Держите описания краткими: Claude Code показывает предупреждение при запуске, когда объединённые описания ваших подагентов превышают лимит в 15 000 токенов, и всё равно загружает каждого подагента.
Если подагент поставляется в плагине, вы можете измерить, насколько надёжно Claude делегирует ему работу на реалистичных подсказках вместо проверки по одной: claude plugin eval запускает каждую подсказку с плагином и без него и оценивает результаты.
Явное вызывание подагентов
Когда автоматического делегирования недостаточно, вы можете запросить подагента самостоятельно. Три паттерна переходят от одноразового предложения к стандарту для всей сессии:
- Естественный язык: назовите подагента в вашей подсказке; Claude решает, делегировать ли
- @-упоминание: гарантирует, что подагент запустится для одной задачи
- На уровне сессии: вся сессия использует системный prompt подагента, ограничения инструментов и модель через флаг
--agentили параметрagent
Для естественного языка нет специального синтаксиса. Назовите подагента и Claude обычно делегирует:
Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes
@-упомяните подагента. Введите @ и выберите подагента из выпадающего списка, так же как вы упоминаете файлы. Это гарантирует, что запустится конкретный подагент, а не оставляет выбор Claude:
@"code-reviewer (agent)" look at the auth changes
Ваше полное сообщение всё равно идёт к Claude, который пишет prompt задачи подагента на основе того, что вы попросили. @-упоминание контролирует, какой подагент Claude вызывает, а не какой prompt он получает.
Подагенты, предоставляемые включённым плагином, появляются в выпадающем списке под их scoped именем, например my-plugin:code-reviewer или my-plugin:review:security когда плагин организует агентов в подпапки. Именованные фоновые подагенты, в настоящий момент работающие в сессии, также появляются в выпадающем списке, показывая их статус рядом с именем.
Вы также можете ввести упоминание вручную без использования выбирателя: @agent-<name> для локальных подагентов или @agent- с последующим scoped именем для подагентов плагина, например @agent-my-plugin:code-reviewer. Пока вы вводите эту форму, выпадающий список показывает совпадения файлов, а не агентов. Упоминание агента всё равно разрешится при отправке.
Запустите всю сессию как подагента. Передайте --agent <name> чтобы запустить сессию, где основной поток сам принимает системный prompt подагента, ограничения инструментов и модель:
claude --agent code-reviewer
Если agent's prompt не пуст, системный prompt подагента полностью заменяет стандартный системный prompt Claude Code, так же как --system-prompt это делает. Файлы CLAUDE.md и память проекта всё равно загружаются через обычный поток сообщений, даже когда определение агента устанавливает omitClaudeMd.
Имя агента появляется как @<name> в заголовке при запуске, чтобы вы могли подтвердить, что он активен.
Это работает с встроенными и пользовательскими подагентами, и выбор сохраняется при возобновлении сессии: Claude Code восстанавливает ограничения инструментов и модель агента вместе с разговором. Если агент больше не существует при возобновлении, сессия продолжается со стандартными инструментами и показывает предупреждение с именем агента. Для системного prompt в обоих случаях см. Флаги системного prompt в возобновлённых разговорах.
Для подагента, предоставляемого плагином, вы можете передать только имя агента и Claude Code найдёт его:
claude --agent security-reviewer
Если несколько плагинов предоставляют агентов с одинаковым именем, передайте scoped имя для уточнения:
claude --agent my-plugin:security-reviewer
Если плагин размещает агента в подпапке своей директории agents/, включите подпапку в scoped имя, например claude --agent my-plugin:review:security.
Чтобы сделать это стандартом для каждой сессии в проекте, установите agent в .claude/settings.json:
{
"agent": "code-reviewer"
}
Флаг CLI переопределяет параметр, если оба присутствуют.
Запуск подагентов на переднем плане или в фоне
Подагенты могут работать на переднем плане или в фоне:
- Подагенты на переднем плане блокируют основной разговор до завершения. Подсказки разрешений передаются вам по мере их появления.
- Фоновые подагенты работают одновременно, пока вы продолжаете работать. Когда фоновый подагент достигает вызова инструмента, требующего разрешения, Claude Code выводит подсказку в вашу основную сессию и называет подагента, который спрашивает. Одобрите, чтобы позволить подагенту продолжить, или нажмите Esc, чтобы отклонить этот вызов инструмента без остановки подагента.
Для каждого подагента, который Claude порождает с помощью инструмента Agent, Claude Code выбирает передний план или фон из первого из этих случаев, который применяется:
- Если товарищ по команде команды агентов в процессе породил подагента, Claude Code запускает его на переднем плане. Claude Code отказывает с ошибкой при попытке породить подагента товарища, чьё определение устанавливает
background: true. Где режим fork отключён и вы не отключили фоновые задачи, Claude Code также отказывает с ошибкой, когда товарищ устанавливаетrun_in_background: true. - Если вы установили
CLAUDE_CODE_DISABLE_BACKGROUND_TASKSна1, Claude Code запускает подагента на переднем плане в каждом виде сессии и независимо от того, включён ли режим fork. - Где режим fork включён, как это по умолчанию в интерактивной сессии, Claude Code запускает подагента в фоне, как fork, так и non-fork подагентов, и Claude не может просить передний план.
- Где режим fork отключён, Claude запускает подагента в фоне по умолчанию и на переднем плане, когда ему нужен результат перед продолжением. Режим fork отключён в неинтерактивном режиме с
-pи в Agent SDK, если вы его не включите. Чтобы держать конкретный подагента в фоне даже когда Claude хочет результат, установите его frontmatter полеbackgroundнаtrue.
Для skill с context: fork, Claude Code следует правилам в Запуск skills в подагенте вместо этого, включён ли режим fork или нет.
Фоновые подагенты работают с меньшим встроенным набором инструментов, чем подагенты на переднем плане, за исключением conversation forks и возобновлённых подагентов на переднем плане.
Фоновые подагенты выводят каждую подсказку разрешения в вашу основную сессию. Когда вы отвечаете на одну из этих подсказок выбором, который длится дольше этого одного вызова инструмента, например разрешением, которое длится всю сессию, Claude Code применяет ваш ответ ко всей сессии, включая ваш основной разговор.
Фоновый подагент может оставить фоновую команду Bash или PowerShell работающей после конца его хода. Когда эта команда завершится, Claude Code отправляет подагенту уведомление.
Результаты фонового подагента достигают Claude как уведомление о завершении в более позднем ходе. Claude ждёт этого уведомления перед тем, как сообщить результаты подагента, и если вы сначала спросите о прогрессе, он сообщит, что подагент всё ещё работает. До v2.1.211 Claude иногда сообщал результаты для фонового подагента, который не закончил.
Вы также можете управлять этим самостоятельно:
- Где режим fork отключён, попросите Claude запустить задачу в фоне или на переднем плане
- Нажмите Ctrl+B чтобы отправить работающую задачу в фон
Claude Code очищает строку фонового подагента из панели подагентов ниже ввода prompt одним из двух способов, в зависимости от того, как закончился подагент:
- Когда подагент завершается успешно, Claude Code удаляет его строку немедленно и, кроме как в режиме чтения с экрана, показывает
/tasks to see subagentsв нижней части на 30 секунд. В течение этих 30 секунд запустите/tasksи нажмитеEnterна подагенте, чтобы открыть его транскрипт. До v2.1.232 Claude Code держал строку 30 секунд после завершения подагента, так же как неудачный, и не показывал подсказку в нижней части. - Когда подагент не удаётся или вы его останавливаете, Claude Code держит его строку 30 секунд. Чтобы очистить строку раньше, выберите её и нажмите
x.
Фоновый подагент, который завершается, остаётся в списке /tasks, отмечен как выполненный и отсортирован ниже работающих задач, на те же 30 секунд, что и подсказка в нижней части. Его представление деталей остаётся открытым, когда подагент завершается. Подагенты, которые не удаются или которых вы останавливаете, покидают список. До v2.1.208 завершённый подагент покидал список в момент завершения и его представление деталей закрывалось.
Имена подагентов
Claude может дать подагенту имя, передав параметр name при вызове инструмента Agent, и может сделать это самостоятельно, без предварительного спроса у вас. Имя делает подагента адресуемым: Claude может отправить ему сообщение или возобновить его по имени после завершения.
В интерактивной сессии с включёнными командами агентов, подагент, который Claude порождает из основного разговора с name, запускается как товарищ вместо этого, если только вызов не является fork или не передаёт isolation при самом вызове. Значение isolation в frontmatter подагента не предотвращает это, и товарищ затем работает в рабочей директории основной сессии. См. Как Claude запускает команды агентов.
Ошибки API в подагентах
Когда что-то прерывает ответ подагента в середине потока, и частичный ответ содержит текст, но не вызовы инструментов, Claude Code подсказывает подагенту продолжить, а не заканчивать запуск. Это происходит и в интерактивных сессиях. Запуск заканчивается на ошибке только после того, как эти продолжения исчерпаны.
Начиная с v2.1.199, подагент, чей запуск заканчивается на ошибке API, такой как лимит использования или повторяющаяся ошибка сервера, сообщает об этом отказе обратно Claude вместо возврата текста ошибки, как если бы это были выводы подагента. То, что получает Claude, зависит от того, где работал подагент:
- Передний план: если лимит скорости, перегрузка или ошибка сервера прерывает подагента, который уже произвёл текстовый вывод, инструмент Agent возвращает этот частичный вывод с примечанием, что подагент был прерван и не завершил свою задачу. Подагент, который ничего не произвёл или чей единственный вывод был вызовами инструментов, не удаётся с
Agent terminated early due to an API error, за которым следует деталь ошибки. В v2.1.199 лимит скорости, перегрузка или ошибка сервера, которые прерывали форму только вызовов инструментов, возвращали пустой частичный результат, содержащий только примечание о прерывании вместо этого. - Фон: подагент отмечен как неудачный, и сообщение, которое Claude получает при завершении, называет ошибку API и включает последний вывод подагента, поэтому частичная работа не теряется.
Когда вы настраиваете цепочку резервных моделей и подагент встречает отказ, который цепочка охватывает, например его модель недоступна, Claude Code переключает подагента на первую модель в цепочке, которая принимает запрос. Подагент продолжает работать вместо того, чтобы заканчиваться на ошибке.
Как только основная ошибка API очищается, попросите Claude повторить задачу или возобновить подагента.
Сканирование выходных данных подагента
Claude Code сканирует финальный отчёт каждого подагента перед тем, как Claude его прочитает. Подагент мог прочитать файлы, веб-страницы или вывод команд, которые вы никогда не проверяли, и текст из этих источников может содержать инструкции, направленные на основной разговор. Сканирование никогда не удаляет и не переформулирует ничего; оно делает два вида изменений, которые вы можете заметить в отчёте:
- Вставка обратной косой черты: сканирование вставляет обратную косую черту в текст, который имитирует собственный вывод Claude Code, такой как тег
<system-reminder>или строка, начинающаяся сHuman:илиAssistant:, чтобы имитация читалась как обычный текст вместо того, чтобы быть ошибочно принятой за часть разговора. - Строка маркера: сканирование добавляет строку, начинающуюся с
[harness: subagent output matched instruction-shaped pattern(s):когда отчёт имитирует тег вроде<system-reminder>или упоминает параметры разрешения такие какbypassPermissionsили--dangerously-skip-permissions. Упоминания параметров разрешения получают строку маркера, но сам текст остаётся как написано.
Сканирование не судит, является ли содержимое вредоносным, и оно не меняет то, что инструкция в отчёте может сделать: вызов инструмента, который отчёт приводит Claude к выполнению, всё равно проходит через проверки разрешений сессии и sandboxing. Это не замена ограничению того, что подагент может достичь.
Отчёт, который возвращается к Claude как результат подагента, также прибывает под заголовком, отмечающим его как выходные данные подагента. Заголовок указывает, что инструкции или утверждения одобрения внутри отчёта — это слова подагента и не несут никакого авторитета от вас.
Отчёт фонового подагента прибывает внутри уведомления о завершении, которое отмечено как автоматизированное событие, а не сообщение от вас.
Сканирование выходных данных подагента требует Claude Code v2.1.210 или позже.
Общие паттерны
Изолируйте высокообъёмные операции
Одно из наиболее эффективных применений подагентов — изоляция операций, которые производят большие объёмы вывода. Запуск тестов, получение документации или обработка файлов логов может потребить значительный контекст. Делегируя это подагентам, многословный вывод остаётся в контексте подагента, пока только релевантное резюме возвращается в ваш основной разговор.
Use a subagent to run the test suite and report only the failing tests with their error messages
Запустите параллельное исследование
Для независимых расследований порождайте несколько подагентов для одновременной работы:
Research the authentication, database, and API modules in parallel using separate subagents
Каждый подагент исследует свою область независимо, затем Claude синтезирует выводы. Это работает лучше всего, когда пути исследования не зависят друг от друга.
Когда подагенты завершаются, их результаты возвращаются в ваш основной разговор. Запуск многих подагентов, которые каждый возвращает подробные результаты, может потребить значительный контекст, и каждый подагент тратит свои токены, пока работает.
Для работы, которая должна продолжать работать параллельно или не поместится в одно окно контекста, запустите её в отдельных сессиях и позвольте Claude передавать выводы между ними.
Цепочка подагентов
Для многошаговых рабочих процессов попросите Claude использовать подагентов последовательно. Каждый подагент завершает свою задачу и возвращает результаты Claude, который затем передаёт релевантный контекст следующему подагенту.
Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them
Выбор между подагентами и основным разговором
Используйте основной разговор когда:
- Задача требует частого взаимодействия или итеративного уточнения
- Несколько фаз делят значительный контекст, такой как планирование, реализация и тестирование
- Вы делаете быстрое, целевое изменение
- Задержка имеет значение. Подагент, который не является fork, начинает с нуля и может потребовать время для сбора контекста
Используйте подагентов когда:
- Задача производит многословный вывод, который вам не нужен в вашем основном контексте
- Вы хотите применить конкретные ограничения инструментов или разрешения
- Работа самодостаточна и может вернуть резюме
Рассмотрите Skills вместо этого, когда вы хотите переиспользуемые prompts или рабочие процессы, которые работают в контексте основного разговора, а не в изолированном контексте подагента.
Для вопроса о чём-то уже в вашем разговоре используйте /btw вместо подагента. Он видит ваш полный контекст, но не имеет доступа к инструментам, и ответ не добавляется в историю.
Позвольте подагентам порождать своих собственных подагентов
По умолчанию подагент может порождать подагентов своих собственных, вплоть до трёх слоёв ниже основного разговора. На пределе глубины, Claude Code удерживает инструмент Agent от каждого подагента, кроме fork, поэтому подагент на пределе выполняет свою делегированную работу сам и возвращает одно резюме. Fork на пределе держит Agent в своём унаследованном списке инструментов, но инструмент возвращает ошибку вместо порождения.
Вложенные подагенты подходят для делегированной задачи, которая сама разбивается на параллельные подзадачи, такие как подагент рецензента, который отправляет верификатора на каждый вывод. В интерактивной сессии только резюме подагента верхнего уровня возвращается вам и промежуточный вывод остаётся вне вашего основного разговора: подагент, который запускает фоновые подагенты, ждёт их результатов перед завершением. В неинтерактивном режиме и Agent SDK, запускающий подагент не ждёт, поэтому вложенный фоновый подагент, который завершается после того, как его запускатель закончился, сообщает в ваш основной разговор вместо этого.
Чтобы изменить лимит, установите CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH на количество слоёв подагентов, которые вы хотите ниже вашего основного разговора. Например, эта запись в settings.json ограничивает вложение двумя слоями:
{
"env": {
"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
}
}
С этим значением ваши подагенты могут делегировать второму слою своих собственных, и этот второй слой не может делегировать дальше. Установите 1 чтобы отключить вложение.
Вложенный подагент настраивается так же, как подагент верхнего уровня и разрешается из тех же scopes. Чтобы держать один подагента от порождения, пока вложение включено, такой как рецензент, который должен остаться только для чтения, опустите Agent из его списка tools или добавьте его в disallowedTools.
В терминале Claude Code показывает вложенные подагенты как дерево в панели подагентов ниже ввода prompt и отмечает каждую строку, которая всё ещё имеет потомков в панели с подсчётом (+N) их. Откройте строку, чтобы увидеть товарищей этого подагента и прямых потомков с путём обратно к main.
Более ранние версии использовали разные стандарты:
- v2.1.172 через v2.1.216: подагенты могли вкладываться по умолчанию, вплоть до пяти слоёв глубины, и лимит не мог быть изменён.
- v2.1.217 через v2.1.218: лимит по умолчанию был один, поэтому подагент не мог порождать своих собственных, если вы не повысили его; v2.1.219 повысил стандарт до трёх.
Лимит одновременных подагентов
Два лимита контролируют использование подагентов, каждый со своей переменной: этот останавливает Claude от порождения большего количества подагентов, пока слишком много работает, и лимит глубины ограничивает, насколько глубоко вкладываются подагенты. Нет лимита на общее количество подагентов, которых Claude может породить за сессию.
По умолчанию, когда 20 подагентов работают в сессии, попытка породить другого с инструментом Agent не удаётся с Concurrent subagent limit reached, и ошибка говорит Claude не повторять попытку. Порождение успешно снова, когда работающий счёт падает ниже лимита. Чтобы изменить лимит, установите CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS на любое положительное целое число. Сессии с активным ultracode исключены: лимит не применяется там. Требует Claude Code v2.1.217 или позже.
Лимит блокирует только подагентов, которых Claude порождает с инструментом Agent, но другие запуски занимают те же слоты:
- Внутри сессии fork, который вы запускаете с
/subtask, занимает слот, пока работает, и никогда не блокируется лимитом. - Возобновление подагента, который уже завершился, занимает свежий слот без проверки лимита, поэтому возобновления могут толкнуть работающий счёт выше него.
Агенты, которых запускают другие функции, такие как workflow агенты и команда агентов товарищи, следуют своим собственным лимитам вместо этого.
Управление контекстом подагента
Что загружается при запуске
Каждый подагент начинает с свежего, изолированного окна контекста. Он не видит историю вашего разговора, skills, которые вы уже вызвали, или файлы, которые Claude уже прочитал. Claude составляет сообщение делегирования, которое резюмирует задачу, и подагент работает оттуда. Исключение — это fork, который наследует родительский разговор вместо начала с нуля.
Начальный контекст non-fork подагента содержит:
- System prompt: собственный prompt агента плюс детали окружения, которые Claude Code добавляет, не системный prompt Claude Code. Пользовательские подагенты определяют свои в теле markdown или поле
prompt. Встроенные агенты имеют предопределённые prompts. - Сообщение задачи: prompt делегирования, который Claude пишет, когда передаёт работу.
- Файлы CLAUDE.md: каждый уровень иерархии CLAUDE.md, который загружает основной разговор, включая
~/.claude/CLAUDE.md, правила проекта,CLAUDE.local.md, файлы управляемой политики и любыеAGENTS.mdфайлы, загруженные как инструкции проекта. Встроенные агенты Explore и Plan пропускают это. Подагент, чьё определение устанавливаетomitClaudeMd, загружает только файлы управляемой политики или ничего вообще, когда определение приходит из управляемых параметров. - Статус Git: снимок, который Claude Code читает из вашего репозитория, когда подагент запускается. Отсутствует вне Git репозитория или когда снимок отключён; см.
includeGitInstructions. Explore и Plan пропускают его независимо. - Предзагруженные skills: полное содержимое любого skill, названного в поле
skillsагента. Встроенные агенты не предзагружают skills. - Список товарищей: системное напоминание, перечисляющее
mainи каждого другого именованного агента в сессии, каждый действительное значениеtoдляSendMessage. Требует Claude Code v2.1.206 или позже. Список появляется только когда инструменты подагента включаютSendMessageи по крайней мере один другой агент имеет имя, будь то Claude назвал его при порождении или он работает как товарищ команды агентов. Это снимок, сделанный при запуске подагента, поэтому агенты, названные позже, не появляются.
Чтобы запустить один из ваших собственных подагентов без пользователя, проекта и локальных файлов CLAUDE.md, установите omitClaudeMd: true в его frontmatter или --agents JSON.
Основной разговор всё равно имеет ваш полный CLAUDE.md, когда он читает результаты этих подагентов, поэтому большинство правил не нужно достигать самого подагента. Если правило должно, такое как "ignore the vendor/ directory," переформулируйте его в prompt, который вы даёте Claude при делегировании.
Вы не можете изменить, какие подагенты получают статус git. Только Explore и Plan пропускают его.
Некоторое состояние основного разговора никогда не достигает non-fork подагента:
- Стиль вывода: подагент запускает свой собственный system prompt, поэтому ваш стиль вывода не формирует его ответы, кроме как в fork.
- Автоматическая память: автоматическая память основного разговора не загружается. Чтобы дать подагенту постоянную память своей собственной, используйте поле
memory. - Размер окна контекста: окно контекста подагента определяется размером его собственной модели, не родительской. Делегирование модели с меньшим окном даёт этому подагенту меньшее окно.
Возобновление подагентов
Каждый вызов подагента создаёт новый экземпляр, а не продолжает более ранний. Чтобы продолжить работу существующего подагента вместо начала с нуля, попросите Claude возобновить его.
Возобновлённые подагенты сохраняют полную историю разговора, включая все предыдущие вызовы инструментов, результаты и рассуждения. Если подагент породил фоновые подагенты своих собственных, эта история включает результаты, которые они доставили, пока он работал. Подагент продолжает точно с того места, где он остановился, а не начинает с нуля.
- Когда подагент завершается, Claude получает его agent ID.
- Встроенные агенты Explore и Plan — это one-shot и не возвращают agent ID, поэтому Claude не может их возобновить. Используйте
general-purposeили пользовательский подагент, когда вам нужно продолжить работу. - Когда подагент останавливается на его пределе
maxTurns, Claude Code отмечает возвращённый вывод как частичный. Для подагентов, которые возвращают agent ID, Claude Code также отмечает в результате, что Claude может отправить сообщение подагенту, чтобы продолжить с того места, где он остановился.
Claude использует инструмент SendMessage с ID или именем агента как поле to для возобновления его. SendMessage не требует команды агентов для включения; только структурированные сообщения протокола команды, такие как shutdown_request и plan_approval_response, это требуют. Помимо подагентов и товарищей, в сессиях, где включена cross-session messaging, Claude может использовать тот же инструмент для отправки сообщений вашим другим сессиям Claude Code, на этой машине или за её пределами.
Чтобы возобновить подагента, попросите Claude продолжить предыдущую работу:
Use the code-reviewer subagent to review the authentication module
[Agent completes]
Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]
Когда Claude отправляет завершённому подагенту сообщение с инструментом SendMessage, подагент возобновляется в фоне без нового вызова Agent. То же самое применяется к подагенту, которого Claude остановил с инструментом TaskStop, как только его остановленный запуск вышел. Возобновлённый запуск держит набор инструментов с того места, где подагент впервые запустился и может продолжить чтение кэша prompt, который исходный запуск разогрел.
Подагент, у которого есть инструмент SendMessage, может отправить это сообщение тоже. В интерактивной сессии возобновлённый агент затем сообщает обратно подагенту, который его возобновил, а не в ваш основной разговор. Этот подагент ждёт результата перед завершением своей собственной работы. Когда подагент отправляет сообщение агенту, которому он сообщает, такому как его собственный запускатель, Claude Code возобновляет этого агента без перенаправления его результатов.
Подагент, которого вы остановили сами, с x в /tasks или запросом SDK stop_task, не auto-resume. Если Claude отправляет ему сообщение, сообщение отказывается и Claude сообщается, что агент был отменён.
Пока строка этого подагента всё ещё в панели подагентов, введите в его транскрипт, чтобы возобновить его самостоятельно. После этого сообщение от Claude может auto-resume его снова.
Возобновление запускает новый запуск агента под тем же ID, поэтому подагент, который уже не удался или завершился, показывает как работающий снова в списке задач и в событиях задач Agent SDK. До v2.1.205 он продолжал показывать свой более ранний неудачный или завершённый статус, пока возобновлённый запуск работал.
Начиная с v2.1.199, SendMessage проверяет, что имя всё ещё относится к тому же агенту, которого оно достигло ранее в разговоре. Если более новый агент взял имя, такой как re-spawned фоновый агент, который переиспользовал его, Claude Code отказывает отправку, а не доставляет его неправильному агенту, и ошибка сообщает, какой агент имя теперь достигает, чтобы Claude мог перенаправить. Чтобы достичь более раннего агента, пока он всё ещё работает, Claude обращается к нему по agent ID, который он получил, когда породил этого агента. Проверка ограничена текущим разговором и сбрасывается на /clear.
Начиная с v2.1.198, подагент рассматривает сообщения от агента, который его запустил, как нормальное направление задачи, включая коррекции курса в середине задачи, и действует на них в рамках своих собственных параметров разрешения. Два лимита всё равно держат независимо от того, кто отправил сообщение: ни одно сообщение от любого агента не считается вашим одобрением для ожидающей подсказки разрешения, и ни одно сообщение агента не может изменить параметры разрешения подагента, CLAUDE.md или конфигурацию. Только система разрешений или ваши собственные сообщения могут предоставить одобрение.
Вы также можете попросить Claude для agent ID, если вы хотите ссылаться на него явно, или найти IDs в файлах транскрипта в ~/.claude/projects/{project}/{sessionId}/subagents/. Каждый транскрипт хранится как agent-{agentId}.jsonl.
Транскрипты подагентов сохраняются независимо от основного разговора:
- Компактирование основного разговора: когда основной разговор компактируется, транскрипты подагентов не затрагиваются. Они хранятся в отдельных файлах.
- Сохранение сессии: транскрипты подагентов сохраняются в их сессии. Вы можете возобновить подагента после перезагрузки Claude Code, возобновив ту же сессию.
- Автоматическая очистка: Claude Code удаляет транскрипты подагентов после периода сохранения
cleanupPeriodDays, 30 дней по умолчанию, следуя правилам развёртки очистки.
Автоматическое компактирование
Подагенты поддерживают автоматическое компактирование, используя ту же логику, что и основной разговор. Компактирование срабатывает при тех же условиях, и CLAUDE_AUTOCOMPACT_PCT_OVERRIDE применяется к подагентам также. См. переменные окружения для того, когда переопределение вступает в силу.
События компактирования регистрируются в файлах транскрипта подагентов:
{
"type": "system",
"subtype": "compact_boundary",
"compactMetadata": {
"trigger": "auto",
"preTokens": 167189
}
}
Значение preTokens показывает, сколько токенов было использовано перед тем, как произошло компактирование.
Разветвление текущего разговора
Запустите разветвленный subagent с помощью /subtask, что требует Claude Code v2.1.212 или позже. Когда представление агента отключено, /subtask недоступен и /fork запускает разветвленный subagent вместо этого; в противном случае /fork копирует всю сессию в новую фоновую сессию.
Fork — это subagent, который наследует весь разговор до сих пор вместо начала с нуля. Это отбрасывает входную изоляцию, которую subagents иначе предоставляют: fork видит то же системное приглашение, инструменты, модель и историю сообщений, что и основная сессия, поэтому вы можете передать ему побочную задачу без переобъяснения ситуации. Вызовы инструментов fork по-прежнему остаются вне вашего разговора и только его окончательный результат возвращается, поэтому ваше основное контекстное окно остаётся чистым. Используйте fork, когда любой другой subagent потребовал бы слишком много фона, чтобы быть полезным, или когда вы хотите попробовать несколько подходов параллельно с одной и той же отправной точки.
Claude запускает fork, запрашивая тип subagent fork через инструмент Agent. Вы контролируете, может ли он это делать, с помощью режима fork, который включен по умолчанию в интерактивных сессиях.
Вы можете запустить fork самостоятельно с помощью /subtask за которым следует задача, независимо от того, включен ли режим fork или нет. На v2.1.161 через v2.1.211 команда — это /fork. Claude Code называет fork из первых слов задачи. Следующий пример разветвляет разговор для черновика тестовых случаев, пока вы продолжаете с реализацией в основной сессии:
/subtask draft unit tests for the parser changes so far
Fork появляется в панели ниже вашего приглашения и работает в фоне, пока вы продолжаете работать. Когда он завершается, его результат приходит как сообщение в вашем основном разговоре. Следующий раздел охватывает элементы управления панели для наблюдения и управления forks во время их работы.
Наблюдение и управление работающими forks
Работающие forks появляются в панели ниже входа приглашения, с одной строкой для основной сессии и одной для каждого fork.
Когда fork завершается успешно, Claude Code удаляет его строку. Claude Code сохраняет строку fork, который не удался или который вы остановили, на 30 секунд, то же самое, что и для любого другого фонового subagent. До v2.1.232 Claude Code также сохранял строку завершённого fork на 30 секунд.
Используйте эти клавиши для взаимодействия с панелью:
| Key | Action |
|---|---|
↑ / ↓ |
Перемещение между строками |
Enter |
Откройте транскрипт выбранного fork и отправьте ему последующие сообщения |
x |
Остановите выбранный fork, если он работает, или отклоните его строку, если он больше не работает. На строке основной сессии или на строке fork, чей транскрипт вы открыли с помощью Enter, x вводит текст в приглашение вместо этого |
Esc |
Верните фокус на входное приглашение |
С открытым транскриптом fork или subagent, последующие сообщения и skills идут к этому агенту, но встроенные команды по-прежнему работают в вашем основном разговоре. Начиная с v2.1.199, ввод /model или /fast в этом представлении показывает уведомление о том, что это изменяет модель основного разговора или режим быстрого выполнения, а не просмотренного агента, вместо того чтобы запускать его молча.
Как forks отличаются от других subagents
Fork наследует всё, что основная сессия имеет в момент его порождения. Любой другой subagent начинает с нуля из своего определения.
| Fork | Non-fork subagent | |
|---|---|---|
| Context | Полная история разговора | Свежий контекст с приглашением, которое вы передаёте |
| System prompt and tools | Такие же как основная сессия | Из файла определения subagent, отфильтрованные для фоновых запусков |
| Model | Такая же как основная сессия | Из поля model subagent |
| Permissions | Запросы выводятся в вашем терминале | Запросы выводятся в вашей основной сессии при запуске в фоне |
| Prompt cache | Общий с основной сессией | Отдельный кэш |
Поскольку системное приглашение fork и определения инструментов идентичны родителю, его первый запрос повторно использует кэш приглашений родителя prompt cache. Это делает forking дешевле, чем порождение свежего subagent для задач, которые нуждаются в том же контексте.
Когда Claude порождает fork через инструмент Agent, он может передать isolation: "worktree", чтобы редактирования файлов fork были написаны в отдельный git worktree вместо вашего checkout. Fork не может порождать дальнейшие forks.
Включение или отключение режима fork
Claude Code включает режим fork по умолчанию в интерактивных сессиях и оставляет его отключённым по умолчанию в non-interactive mode с -p и в Agent SDK. Интерактивное значение по умолчанию требует Claude Code v2.1.232 или позже. На более ранних версиях установите CLAUDE_CODE_FORK_SUBAGENT на 1, чтобы включить режим fork.
Вы можете сказать, что режим fork включен, по тому, как Claude Code обрабатывает инструмент Agent:
- Claude может порождать fork, запрашивая тип subagent
fork. Когда Claude не запрашивает тип, он получает general-purpose subagent, если сессия всё ещё имеет этот тип. Subagents, порождённые из определения, такие как Explore, работают как обычно. - Claude Code запускает subagents, которые Claude порождает, в фоне, forks и non-fork subagents в равной степени, кроме случаев, которые остаются в переднем плане. Claude Code также удаляет параметр
run_in_backgroundинструмента Agent, поэтому Claude не может просить передний план.
Установите переменную окружения CLAUDE_CODE_FORK_SUBAGENT, чтобы переопределить значения по умолчанию:
1включает режим fork в non-interactive mode и Agent SDK также0отключает режим fork в каждом виде сессии
Чтобы сохранить режим fork включённым, но остановить Claude от порождения forks, запретите тип subagent fork с помощью правила Agent(fork). Claude Code по-прежнему запускает subagents, которые Claude порождает, в фоне, кроме тех же случаев, которые остаются в переднем плане.
Примеры subagents
Эти примеры демонстрируют эффективные паттерны для создания subagents. Используйте их как отправные точки или генерируйте настроенную версию с Claude.
Best practices:
- Проектируйте сфокусированные subagents: каждый subagent должен превосходить в одной конкретной задаче
- Напишите описания, которые выделяют один subagent: Claude использует описание для решения о делегировании. Сделайте каждое описание достаточно специфичным для маршрутизации к правильному subagent и держите объединённый набор в пределах бюджета описания в 15 000 токенов
- Ограничьте доступ к инструментам: предоставьте только необходимые разрешения для безопасности и сфокусированности
- Проверьте в систему контроля версий: поделитесь project subagents с вашей командой
Code reviewer
Subagent только для чтения, который проверяет код без его модификации. Этот пример показывает, как спроектировать сфокусированный subagent с ограниченным доступом к инструментам, который исключает Edit и Write, и подробным приглашением, которое точно указывает, что искать и как форматировать выход.
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
Include specific examples of how to fix issues.
Debugger
Subagent, который может как анализировать, так и исправлять проблемы. В отличие от code reviewer, этот включает Edit, потому что исправление ошибок требует модификации кода. Приглашение предоставляет чёткий рабочий процесс от диагностики к проверке.
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---
You are an expert debugger specializing in root cause analysis.
When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works
Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states
For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations
Focus on fixing the underlying issue, not the symptoms.
Data scientist
Специализированный subagent для работы анализа данных. Этот пример показывает, как создавать subagents для специализированных рабочих процессов вне типичных задач кодирования. Он явно устанавливает model: sonnet для более способного анализа.
---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---
You are a data scientist specializing in SQL and BigQuery analysis.
When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly
Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations
For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data
Always ensure queries are efficient and cost-effective.
Database query validator
Subagent, который разрешает доступ Bash, но проверяет команды для разрешения только запросов SQL только для чтения. Этот пример показывает, как использовать PreToolUse hooks для условной валидации, когда вам нужен более тонкий контроль, чем предоставляет поле tools.
---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.
When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context
You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.
Claude Code передаёт входные данные hook как JSON через stdin командам hook. Скрипт валидации читает этот JSON, извлекает выполняемую команду и проверяет её против списка операций записи SQL. Если обнаружена операция записи, скрипт выходит с кодом 2 для блокировки выполнения и возвращает сообщение об ошибке Claude через stderr.
Создайте скрипт валидации где-нибудь в вашем проекте. Путь должен соответствовать полю command в конфигурации hook:
#!/bin/bash
# Blocks SQL write operations, allows SELECT queries
# Read JSON input from stdin
INPUT=$(cat)
# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if [ -z "$COMMAND" ]; then
exit 0
fi
# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
exit 2
fi
exit 0
На macOS и Linux сделайте скрипт исполняемым:
chmod +x ./scripts/validate-readonly-query.sh
На Windows напишите скрипт валидации на PowerShell и добавьте shell: powershell к записи hook. См. запуск hooks в PowerShell.
Hook получает JSON через stdin с командой Bash в tool_input.command. Код выхода 2 блокирует операцию и передаёт сообщение об ошибке обратно Claude. См. Hooks для деталей кодов выхода и Hook input для полной схемы входных данных.
Системное приглашение говорит subagent отказывать запросам на запись, поэтому hook является подстраховкой: если subagent попытается выполнить запись в любом случае, Claude Code блокирует команду и subagent видит сообщение Blocked: Write operations not allowed. Use SELECT queries only..
Следующие шаги
Теперь, когда вы понимаете subagents, изучите эти связанные функции:
- Распространяйте subagents с помощью plugins для совместного использования subagents в командах или проектах
- Запустите Claude Code программно с помощью Agent SDK для CI/CD и автоматизации
- Используйте MCP servers для предоставления subagents доступа к внешним инструментам и данным