SpyBara
Go Premium

sub-agents.md 2026-10-01 23:59 UTC to 2026-10-02 20:57 UTC

This page contains 184 additions and 176 deletions.

2026
Fri 2 20:57

Создание пользовательских subagents

Создавайте и используйте специализированные AI subagents в Claude Code для рабочих процессов, ориентированных на конкретные задачи, и улучшенного управления контекстом.

Subagents — это специализированные AI-помощники, которые обрабатывают определённые типы задач. Используйте один, когда побочная задача заполнит основной разговор результатами поиска, логами или содержимым файлов, на которые вы больше не будете ссылаться: subagent выполняет эту работу в собственном контексте и возвращает только резюме. Определите пользовательский subagent, когда вы постоянно порождаете одного и того же рабочего с одинаковыми инструкциями.

Каждый subagent работает в собственном контекстном окне с пользовательским системным приглашением, специфическим доступом к инструментам и независимыми разрешениями. Он также отправляет свои собственные запросы, которые учитываются в тех же лимитах использования, что и ваш основной разговор. Когда Claude встречает задачу, соответствующую описанию subagent, он делегирует её этому subagent, который работает независимо и возвращает результаты. Чтобы увидеть экономию контекста на практике, визуализация контекстного окна проходит через сессию, где subagent обрабатывает исследование в собственном отдельном окне.

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: модель основного диалога. Когда основной диалог работает на Fable, модель Explore зависит от способа подключения:
  • С подпиской Claude, учётной записью Anthropic Console или LLM-шлюзом, доступным через ANTHROPIC_BASE_URL, Explore работает на модели Opus, в которую разрешается псевдоним opus.
  • На Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude Platform on AWS или шлюзе Claude apps Explore остаётся на модели основного диалога.
  • Tools: инструменты только для чтения; Write и Edit запрещены
  • Purpose: обнаружение файлов, поиск кода, исследование кодовой базы

Пользовательский или проектный субагент с именем Explore переопределяет встроенный и сохраняет собственное поле model, поэтому определите его с model: haiku, чтобы запускать исследование на модели с более низкой стоимостью. Чтобы принудительно назначить одну модель каждому субагенту, включая Explore, см. Запуск каждого субагента на одной модели.

Claude делегирует Explore, когда ему нужно искать или понимать кодовую базу без внесения изменений. Это сохраняет результаты исследования вне контекста основного разговора.

При вызове Explore Claude указывает уровень тщательности: quick для целевых поисков, medium для сбалансированного исследования или very thorough для комплексного анализа.

Встроенные subagents регистрируются по умолчанию в интерактивных сессиях. Чтобы ограничить их:

Вызов инструмента Agent, который опускает subagent_type, завершается ошибкой subagent_type is required, когда сессия не имеет general-purpose subagent для отката.

Помимо этих встроенных subagents, вы можете создавать свои собственные с пользовательскими приглашениями, ограничениями инструментов, режимами разрешений, hooks и skills. В следующих разделах показано, как начать работу и настроить subagents.

Быстрый старт: создание вашего первого субагента

Субагенты — это файлы Markdown с YAML frontmatter. Чтобы создать субагента, попросите Claude написать его для вас или напишите файл самостоятельно.

Это пошаговое руководство создаёт субагента уровня пользователя, который проверяет код и предлагает улучшения.

1

Попросите Claude создать субагента

В Claude Code опишите субагента, которого вы хотите создать, и где его сохранить:

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 и системным промптом.

2

Проверьте файл

Откройте ~/.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/, субагент доступен в каждом проекте на вашей машине. Чтобы ограничить его одним проектом, переместите его в каталог .claude/agents/ этого проекта. Выберите область действия субагента сравнивает эти два варианта.

3

Попробуйте

Попросите Claude делегировать задачу новому субагенту:

Use the code-improver agent to suggest improvements in this project

Claude делегирует задачу вашему новому субагенту, который сканирует кодовую базу и возвращает предложения по улучшению. В транскрипте делегирование отображается как строка вызова инструмента, показывающая имя субагента, за которым следует краткое описание задачи, например code-improver(Suggest code improvements).

Если Claude не может найти нового субагента, перезапустите Claude Code и попробуйте снова. Это происходит только когда ~/.claude/agents/ не существовал до начала сессии, потому что работающая сессия не обнаруживает вновь созданный каталог agents.

Теперь у вас есть субагент, которого вы можете использовать в любом проекте на вашей машине для анализа кодовых баз и предложения улучшений.

Вы также можете писать файлы субагентов вручную, определять их через флаги CLI или распространять их через плагины. В следующих разделах рассматриваются все параметры конфигурации.

Настройка 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."
}
}'

В 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.

Определения subagent из любой из этих областей также доступны для agent teams: при порождении товарища по команде вы можете ссылаться на тип subagent, и Claude Code применяет части этого определения к товарищу. См. agent teams для того, какие части применяются в каждом режиме отображения.

Напишите файлы subagent

Файлы subagent используют YAML frontmatter для конфигурации, за которым следует системное приглашение в Markdown:

---
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 в этом порядке:

  1. Параметр model для конкретного вызова
  2. Frontmatter model определения subagent, где inherit выбирает модель основного разговора
  3. Переменная окружения CLAUDE_CODE_SUBAGENT_MODEL, когда вы устанавливаете её на псевдоним модели или ID модели
  4. Модель основного разговора

В двух случаях семейный псевдоним, такой как 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 или позже.

Например, чтобы запустить каждый 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 в определениях субагентов, а Claude не может передать модель при запуске субагента. Следующие субагенты по-прежнему работают на модели основного диалога:

Контролируйте возможности subagent

Вы можете контролировать, что могут делать subagents, через доступ к инструментам, режимы разрешений и условные правила.

Доступные инструменты

Subagents наследуют встроенные инструменты и MCP инструменты, доступные в основном разговоре, сужены двумя фильтрами: первый удаляет короткий список инструментов из каждого subagent, и второй уменьшает набор встроенных инструментов для subagents, которые работают в фоне, что является значением по умолчанию. На macOS, Linux и WSL subagent также может получить инструменты Glob и Grep, когда основной разговор их не имеет, как описано в разделе Glob tool behavior. Forks пропускают оба фильтра и получают точный пул инструментов основного разговора. Первый фильтр удаляет эти инструменты, даже когда они указаны в поле tools:

  • Agent, когда subagent находится на depth limit; в fork инструмент остаётся в списке, но возвращает ошибку вместо порождения
  • AskUserQuestion
  • EndConversation, который может завершить только основной разговор; см. EndConversation tool behavior
  • EnterPlanMode
  • ExitPlanMode, если только permissionMode subagent не является plan
  • ScheduleWakeup
  • WaitForMcpServers
  • Workflow

Второй фильтр применяется к 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.

---
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, в соответствии с правилом доверия для папки файла агента, и отключаются при его завершении. Строковые ссылки используют соединение родительской сессии.

Каждая запись в списке — это либо встроенное определение сервера, либо строка, ссылающаяся на 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 получает инструменты; родительский разговор — нет.

Ограничения MCP, действующие для основной сессии, распространяются и на серверы, объявленные во frontmatter субагента:

Когда одно из этих ограничений блокирует сервер, Claude Code пропускает его и показывает предупреждение с перечнем заблокированных серверов.

Ограничения управляемых настроек применяются к каждому субагенту независимо от того, как он определён. --strict-mcp-config не фильтрует серверы, которые вы передаёте встроенно через --agents или параметр SDK agents, поскольку это явные входные данные вызывающей стороны.

Доверие, необходимое для встроенных MCP-серверов

Claude Code загружает встроенный MCP-сервер из файла агента в каталоге .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 или опции 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 пропускает его и регистрирует предупреждение в журнал отладки.

Включите постоянную память

Поле 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 уровня проекта запуститься, примите диалог доверия рабочего пространства для папки, которая содержит файл агента. 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"
  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" }
        ]
      }
    ]
  }
}

См. Hooks для полного формата конфигурации hook.

Работа с субагентами

Понимание автоматического делегирования

Claude автоматически делегирует задачи на основе описания задачи в вашем запросе, поля description в конфигурациях субагентов и текущего контекста. Чтобы поощрить проактивное делегирование, включите фразы вроде "use proactively" в поле описания вашего субагента.

Делайте описания краткими: Claude Code показывает предупреждение при запуске, когда суммарный объём описаний ваших субагентов превышает лимит в 15 000 токенов, и всё равно загружает каждого субагента.

Если субагент поставляется в плагине, вы можете измерить, насколько надёжно Claude делегирует ему работу на реалистичных промптах, вместо того чтобы проверять их по одному: claude plugin eval запускает каждый промпт с плагином и без него и оценивает результаты.

Явный вызов субагентов

Когда автоматического делегирования недостаточно, вы можете запросить субагента самостоятельно. Три паттерна идут по нарастающей — от разового предложения до поведения по умолчанию для всей сессии:

  • Естественный язык: назовите субагента в своём промпте; Claude решает, делегировать ли задачу
  • @-упоминание: гарантирует, что субагент запустится для одной задачи
  • На уровне сессии: вся сессия работает как этот субагент благодаря флагу --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, который пишет промпт задачи для субагента на основе вашей просьбы. @-упоминание определяет, какого субагента вызывает Claude, но не то, какой промпт тот получает.

Субагенты, предоставляемые включённым плагином, отображаются в списке автодополнения под именем с областью действия, например my-plugin:code-reviewer или my-plugin:review:security, когда плагин раскладывает агентов по подпапкам. Именованные фоновые субагенты, работающие в данный момент в сессии, также отображаются в списке автодополнения, а рядом с именем показывается их статус.

Вы также можете ввести упоминание вручную, не используя список выбора: @agent-<name> для локальных субагентов или @agent-, за которым следует имя с областью действия, для субагентов плагинов, например @agent-my-plugin:code-reviewer. Пока вы вводите такую форму, список автодополнения показывает совпадающие файлы, а не агентов. Упоминание агента всё равно будет распознано при отправке.

Запустите всю сессию как субагента. Передайте --agent <name>, чтобы начать сессию, в которой сам основной поток перенимает ограничения инструментов и модель этого субагента:

claude --agent code-reviewer

Если только промпт агента не пуст, системный промпт пользовательского субагента полностью заменяет стандартный системный промпт Claude Code — так же, как это делает --system-prompt. Файлы CLAUDE.md и память проекта всё равно загружаются через обычный поток сообщений, даже если в определении агента задано omitClaudeMd.

Имя агента отображается как @<name> в заголовке при запуске, чтобы вы могли убедиться, что он активен.

Это работает со встроенными и пользовательскими субагентами, и выбор сохраняется при возобновлении сессии: Claude Code восстанавливает ограничения инструментов и модель агента вместе с диалогом. Если при возобновлении агент больше не существует, сессия продолжается со стандартными инструментами и показывает предупреждение с именем агента. О системном промпте в обоих случаях см. Флаги системного промпта в возобновлённых диалогах.

Для субагента, предоставляемого плагином, можно передать только имя агента, и Claude Code найдёт его:

claude --agent security-reviewer

Если несколько плагинов предоставляют агентов с одинаковым именем, передайте имя с областью действия для устранения неоднозначности:

claude --agent my-plugin:security-reviewer

Если плагин размещает агента в подпапке своего каталога agents/, включите подпапку в имя с областью действия, например 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 запускает субагента в фоне — как форки, так и обычных субагентов, — и Claude не может запросить передний план.
  • Если режим fork выключен, Claude по умолчанию запускает субагента в фоне, а на переднем плане — когда ему нужен результат, чтобы продолжить. Режим fork выключен в неинтерактивном режиме с -p и в Agent SDK, если вы его не включите. Чтобы определённый субагент оставался в фоне, даже когда Claude нужен результат, установите поле frontmatter background этого субагента в true.

Для скилла с context: fork Claude Code вместо этого следует правилам из раздела Запуск скиллов в субагенте, независимо от того, включён ли режим fork.

Фоновые субагенты работают с меньшим набором встроенных инструментов, чем субагенты на переднем плане, за исключением форков диалога и возобновлённых субагентов переднего плана.

Фоновые субагенты показывают каждый запрос разрешения в вашей основной сессии. Когда вы отвечаете на такой запрос вариантом, действие которого выходит за рамки одного вызова инструмента, например разрешением до конца сессии, Claude Code применяет ваш ответ ко всей сессии, включая основной диалог.

Фоновый субагент может оставить фоновую команду Bash или PowerShell работающей после окончания своего хода. Когда эта команда завершается, Claude Code отправляет субагенту уведомление.

Результаты фонового субагента поступают к Claude в виде уведомления о завершении в одном из последующих ходов. Claude дожидается этого уведомления, прежде чем сообщить результаты субагента, а если вы сначала спросите о ходе работы, он сообщит, что субагент ещё работает. До v2.1.211 Claude иногда сообщал результаты фонового субагента, который ещё не завершил работу.

Вы также можете управлять этим самостоятельно:

  • Если режим fork выключен, попросите Claude запустить задачу в фоне или на переднем плане
  • Нажмите Ctrl+B, чтобы отправить выполняющуюся задачу в фон

Claude Code убирает строку фонового субагента из панели субагентов под полем ввода промпта одним из двух способов, в зависимости от того, как завершился субагент:

  • Когда субагент завершается успешно, 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, вместо этого запускается как участник команды, если только вызов не является форком и не передаёт 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, всё равно проходит проверки разрешений и изоляцию в песочнице сессии. Оно не заменяет ограничение того, к чему у субагента есть доступ.

Отчёт, который возвращается к Claude как результат субагента, также поступает под заголовком, помечающим его как вывод субагента. В заголовке указано, что инструкции или заявления о подтверждении внутри отчёта — это слова субагента и не имеют никаких полномочий от вашего имени.

Отчёт фонового субагента поступает внутри уведомления о завершении, которое помечено как автоматическое событие, а не как сообщение от вас.

Распространённые паттерны

Изоляция операций с большим объёмом вывода

Одно из самых эффективных применений субагентов — изоляция операций, которые производят большой объём вывода. Запуск тестов, получение документации или обработка файлов логов может занимать значительную часть контекста. Если делегировать такие операции субагенту, подробный вывод остаётся в контексте субагента, а в ваш основной диалог возвращается только релевантная сводка.

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

Выбор между субагентами и основным диалогом

Используйте основной диалог, когда:

  • Задача требует частого обмена репликами или итеративного уточнения
  • Несколько этапов, например планирование, реализация и тестирование, используют значительный общий контекст
  • Вы вносите быстрое точечное изменение
  • Важна задержка. Субагент, который не является форком, начинает с чистого листа, и ему может потребоваться время на сбор контекста

Используйте субагентов, когда:

  • Задача производит подробный вывод, который не нужен в основном контексте
  • Вы хотите применить определённые ограничения инструментов или разрешений
  • Работа самодостаточна и может вернуть сводку

Рассмотрите вместо этого скиллы, если вам нужны переиспользуемые промпты или рабочие процессы, которые выполняются в контексте основного диалога, а не в изолированном контексте субагента.

Для вопроса о чём-то, что уже есть в вашем диалоге, используйте /btw вместо субагента. Он видит весь ваш контекст, но не имеет доступа к инструментам, и ответ не добавляется в историю.

Разрешите субагентам порождать собственных субагентов

По умолчанию субагент может порождать собственных субагентов — до трёх уровней ниже основного диалога. На пределе глубины Claude Code не предоставляет инструмент Agent ни одному субагенту, кроме форка, поэтому субагент на пределе выполняет делегированную работу сам и возвращает одну сводку. Форк на пределе сохраняет Agent в унаследованном списке инструментов, но этот инструмент возвращает ошибку вместо порождения субагента.

Вложенные субагенты подходят для делегированной задачи, которая сама разбивается на параллельные подзадачи, например для субагента-ревьюера, который отправляет верификатора на каждую находку. В интерактивной сессии к вам возвращается только сводка субагента верхнего уровня, а промежуточный вывод остаётся за пределами основного диалога: субагент, запускающий фоновых субагентов, дожидается их результатов, прежде чем завершиться. В неинтерактивном режиме и в Agent SDK запускающий субагент не ждёт, поэтому вложенный фоновый субагент, завершившийся после своего запускающего, отчитывается вместо этого в ваш основной диалог.

Чтобы изменить лимит, задайте в CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH нужное число уровней субагентов ниже основного диалога. Например, эта запись в settings.json ограничивает вложенность двумя уровнями:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

С этим значением ваши субагенты могут делегировать работу второму уровню собственных субагентов, а этот второй уровень уже не может делегировать дальше. Задайте 1, чтобы отключить вложенность.

Вложенный субагент настраивается так же, как субагент верхнего уровня, и разрешается из тех же областей действия. Чтобы запретить одному субагенту порождать других при включённой вложенности, например ревьюеру, который должен оставаться только для чтения, исключите Agent из его списка tools или добавьте его в disallowedTools.

В терминале Claude Code показывает вложенных субагентов в виде дерева в панели субагентов под полем ввода промпта и помечает каждую строку, у которой в панели ещё есть потомки, счётчиком (+N). Откройте строку, чтобы увидеть соседних субагентов и прямых потомков этого субагента вместе с путём обратно к main.

Лимит одновременных субагентов

Использование субагентов регулируют два лимита, у каждого из которых своя переменная: этот не позволяет Claude порождать новых субагентов, пока их работает слишком много, а лимит глубины ограничивает глубину вложенности субагентов. Ограничения на общее число субагентов, которых Claude может породить за сессию, нет.

По умолчанию, когда в сессии работают 20 субагентов, попытка породить ещё одного с помощью инструмента Agent завершается ошибкой Concurrent subagent limit reached, и ошибка сообщает Claude, что повторять попытку не нужно. Порождение снова становится возможным, когда число работающих субагентов опускается ниже лимита. Чтобы изменить лимит, задайте в CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS любое положительное целое число. На сессии с активным ultracode это не распространяется: там лимит не применяется. Требуется Claude Code v2.1.217 или новее.

Лимит блокирует только субагентов, которых Claude порождает с помощью инструмента Agent, но другие запуски занимают те же слоты:

  • Форк внутри сессии, который вы запускаете с помощью /subtask, занимает слот, пока работает, и никогда не блокируется лимитом.
  • Возобновление субагента, который уже завершился, занимает новый слот без проверки лимита, поэтому возобновления могут вывести число работающих субагентов за пределы лимита.

Агенты, которых запускают другие функции, например агенты workflow и участники команды агентов, вместо этого подчиняются собственным лимитам.

Управление контекстом субагентов

Что загружается при запуске

Каждый субагент начинает работу с новым изолированным контекстным окном. Он не видит историю вашего диалога, уже вызванные вами скиллы или файлы, которые Claude уже прочитал. Claude составляет сообщение делегирования, кратко описывающее задачу, и субагент работает, отталкиваясь от него. Исключение — форк, который наследует родительский диалог, а не начинает с чистого листа.

Начальный контекст субагента, не являющегося форком, содержит:

  • Системный промпт: собственный промпт агента плюс сведения об окружении, которые добавляет Claude Code, — а не системный промпт Claude Code. Пользовательские субагенты задают свой промпт в теле markdown или в поле 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 агента. Встроенные агенты не предзагружают скиллы.
  • Список соседних агентов: системное напоминание со списком main и всех остальных именованных агентов в сессии; каждый из них — допустимое значение to для SendMessage. Требуется Claude Code v2.1.206 или новее. Список появляется, только если инструменты субагента включают SendMessage и хотя бы у одного другого агента есть имя — неважно, дал ли его Claude при порождении или агент работает как участник команды агентов. Это снимок на момент запуска субагента, поэтому агенты, получившие имя позже, в нём не отображаются.

Чтобы запустить одного из своих субагентов без пользовательских, проектных и локальных файлов CLAUDE.md, задайте omitClaudeMd: true в его frontmatter или в JSON --agents.

Когда основной диалог читает результаты таких субагентов, у него по-прежнему есть весь ваш CLAUDE.md, поэтому большинству правил не нужно доходить до самого субагента. Если же правило должно до него дойти, например "ignore the vendor/ directory," повторите его в промпте, который вы даёте Claude при делегировании.

Изменить, какие субагенты получают статус git, нельзя. Его пропускают только Explore и Plan.

Часть состояния основного диалога никогда не доходит до субагента, не являющегося форком:

  • Стиль вывода: субагент работает со своим собственным системным промптом, поэтому ваш стиль вывода не влияет на его ответы, кроме случая форка.
  • Автоматическая память: автоматическая память основного диалога не загружается. Чтобы дать субагенту собственную постоянную память, используйте поле memory.
  • Размер контекстного окна: размер контекстного окна субагента определяется его собственной моделью, а не родительской. При делегировании модели с меньшим окном этот субагент получает меньшее окно.

Возобновление субагентов

Каждый вызов субагента создаёт новый экземпляр, а не продолжает предыдущий. Чтобы продолжить работу существующего субагента, а не начинать заново, попросите Claude возобновить его.

Возобновлённые субагенты сохраняют полную историю диалога, включая все предыдущие вызовы инструментов, результаты и рассуждения. Если субагент порождал собственных фоновых субагентов, эта история включает результаты, которые они доставили, пока он работал. Субагент продолжает ровно с того места, где остановился, а не начинает с чистого листа.

  • Когда субагент завершается, Claude получает его ID агента.
  • Встроенные агенты Explore и Plan одноразовые и не возвращают ID агента, поэтому Claude не может их возобновить. Используйте general-purpose или пользовательского субагента, когда нужно продолжить работу.
  • Когда субагент останавливается на своём лимите maxTurns, Claude Code помечает возвращённый вывод как частичный. Для субагентов, возвращающих ID агента, Claude Code также указывает в результате, что Claude может отправить субагенту сообщение, чтобы тот продолжил с места остановки.

Чтобы возобновить агента, Claude использует инструмент SendMessage, указывая ID или имя агента в поле to. Для SendMessage не нужно включать команды агентов; это требуется только для структурированных сообщений протокола команды, таких как shutdown_request и plan_approval_response. Помимо субагентов и участников команды, в сессиях с включённым обменом сообщениями между сессиями 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, после того как остановленное выполнение завершилось. Возобновлённое выполнение сохраняет набор инструментов, с которым субагент работал изначально, и может продолжать читать кэш промптов, прогретый исходным выполнением.

Субагент, у которого есть инструмент SendMessage, тоже может отправить такое сообщение. В интерактивной сессии возобновлённый агент затем отчитывается субагенту, который его возобновил, а не в ваш основной диалог. Этот субагент дожидается результата, прежде чем завершить собственную работу. Когда субагент отправляет сообщение агенту, которому он подотчётен, например собственному запускающему агенту, Claude Code возобновляет этого агента без перенаправления его результатов.

Субагент, которого вы остановили сами — клавишей x в /tasks или запросом SDK stop_task, — автоматически не возобновляется. Если Claude отправит ему сообщение, оно будет отклонено, а Claude получит уведомление, что агент был отменён.

Пока строка этого субагента ещё есть в панели субагентов, введите текст в его транскрипт, чтобы возобновить его самостоятельно. После этого сообщение от Claude снова сможет автоматически его возобновить.

Возобновление запускает новое выполнение агента под тем же ID, поэтому субагент, который ранее завершился с ошибкой или успешно, снова отображается как работающий в списке задач и в событиях задач Agent SDK. До v2.1.205 он продолжал показывать прежний статус ошибки или завершения, пока возобновлённое выполнение работало.

Начиная с v2.1.199, SendMessage проверяет, что имя по-прежнему указывает на того же агента, которого оно достигало ранее в диалоге. Если имя занял более новый агент, например повторно порождённый фоновый агент, который использовал то же имя, Claude Code отказывает в отправке, а не доставляет сообщение не тому агенту, и ошибка сообщает, к какому агенту теперь ведёт это имя, чтобы Claude мог сменить адресата. Чтобы обратиться к прежнему агенту, пока тот ещё работает, Claude использует ID агента, полученный при его порождении. Проверка действует в пределах текущего диалога и сбрасывается при /clear.

Субагент воспринимает сообщения от агента, который его запустил, как обычные указания по задаче, включая корректировки посреди выполнения, и действует по ним в рамках собственных настроек разрешений. Два ограничения действуют независимо от отправителя сообщения: никакое сообщение от какого-либо агента не считается вашим подтверждением для ожидающего запроса разрешения, и никакое сообщение агента не может изменить настройки разрешений, CLAUDE.md или конфигурацию субагента. Дать подтверждение могут только система разрешений или ваши собственные сообщения.

Вы также можете попросить у Claude ID агента, если хотите явно на него сослаться, или найти ID в файлах транскриптов в ~/.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 показывает, сколько токенов было использовано до сжатия контекста.

Разветвление текущего разговора

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 или субагента, последующие сообщения и скиллы отправляются этому агенту, а встроенные команды — в ваш основной диалог, со следующими мерами предосторожности:

  • /compact, /clear и /rewind действуют на основной диалог, поэтому Claude Code просит вас подтвердить запуск любой из них из этого представления.
  • /model и /fast задают модель и быстрый режим основного диалога, а не просматриваемого агента, поэтому из этого представления они не запускаются. Уведомление объясняет причину.

Чтобы просматриваемый агент прочитал ваше сообщение до завершения работы, которую он ожидает, отправьте его с помощью Ctrl+Enter или Ctrl+X Ctrl+S. Любая shell-команда или субагент, которых ожидает агент и которые можно перевести в фон, переводятся туда и продолжают работать. Если агент пишет ответ или ожидает работу, которую нельзя перевести в фон, он продолжает и прочитает ваше сообщение, когда она завершится. Требуется Claude Code v2.1.286 или новее.

Как 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.

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, изучите эти связанные функции: