SpyBara
Go Premium

sub-agents.md 2026-09-28 22:59 UTC to 2026-09-29 21:02 UTC

This page contains 144 additions and 140 deletions.

2026
Thu 10 23:00 Sat 12 03:02 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58 Mon 28 22:59 Tue 29 21:02

Создание пользовательских 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: наследуется из основного разговора, ограничен Opus на Claude API, поэтому Explore никогда не работает на более дорогой модели, чем та, которую вы уже выбрали для сессии, если только вы не установите CLAUDE_CODE_SUBAGENT_MODEL и не заставите его работать на каждом subagent
  • Tools: инструменты только для чтения; Write и Edit запрещены
  • Purpose: обнаружение файлов, поиск кода, исследование кодовой базы

Начиная с версии 2.1.198, Explore наследует модель основного разговора вместо того, чтобы всегда работать на Haiku. На Claude API унаследованная модель ограничена Opus: основной разговор на более высоком уровне запускает Explore на Opus, а основной разговор на Sonnet или Haiku запускает Explore на той же модели. На любом другом поставщике, таком как Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry или Claude Platform on AWS, Explore наследует модель основного разговора напрямую.

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

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

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

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

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

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

Quickstart: создание вашего первого subagent

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

Начиная с версии v2.1.198, команда /agents больше не открывает интерактивный мастер создания; её запуск выводит напоминание попросить Claude или отредактировать .claude/agents/ напрямую. Файлы subagent, поля frontmatter и местоположения .claude/agents/ и ~/.claude/agents/ остаются неизменными; удалён только терминальный мастер.

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

1

Попросите Claude создать subagent

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

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude создаёт файл с name, description, списком tools, model и системным приглашением.

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

3

Попробуйте

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

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

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

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

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

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

Настройка 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 или позже.

  • Если вы установили обе переменные, subagents работают на модели в CLAUDE_CODE_SUBAGENT_MODEL.
  • Если вы установили только CLAUDE_CODE_SUBAGENT_MODEL_FORCE, subagents работают на модели основного разговора.

Например, чтобы запустить каждый subagent на Haiku, установите обе переменные в блоке env файла настроек:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Чтобы проверить, что параметр вступил в силу, запустите /tasks пока работает subagent. Строка subagent показывает модель, на которой он работает.

Пока CLAUDE_CODE_SUBAGENT_MODEL_FORCE включен, Claude Code игнорирует поле model каждого определения subagent, включая встроенные subagents Explore и Plan, и Claude не может передать модель при запуске subagent. Два вида subagent по-прежнему работают на модели основного разговора:

Когда вы устанавливаете только CLAUDE_CODE_SUBAGENT_MODEL_FORCE, встроенный subagent Explore сохраняет свой model cap.

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

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

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

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

  • Agent, когда subagent находится на depth limit; в fork инструмент остаётся в списке, но возвращает ошибку вместо порождения
  • 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 получает инструменты; родительский разговор — нет.

Claude Code загружает встроенный сервер из файла агента в директории .claude/agents/ вашего проекта, или в директории .claude/agents/ директории, добавленной с помощью --add-dir, только после того, как вы доверяете папке, из которой пришёл файл агента. До версии 2.1.238 Claude Code загружал эти серверы без проверки доверия.

  • Доверие, которое не считается: доверие родительской папки и автоматическое доверие, которое сессия -p или SDK получает для hooks в файлах настроек
  • До тех пор: Claude Code пропускает каждый встроенный сервер в этом файле агента и записывает точный ключ projects["<path>"].hasTrustDialogAccepted для ~/.claude.json в журнал отладки
  • Директории --add-dir: директория вне репозитория вашего доверенного рабочего пространства нуждается в собственной записи доверия, поскольку её файлы .claude/agents/ не наследуют доверие вашего рабочего пространства

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

  • Имя, которое ссылается на сервер, который вы уже настроили
  • Встроенный сервер в файле агента из ~/.claude/agents/, в одном, который вы передаёте с помощью --agents или опции SDK agents, или в одном, который управляемые настройки предоставляют

Ограничения MCP, которые применяются к основной сессии, также охватывают серверы, объявленные в frontmatter subagent:

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

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

Режимы разрешений

Установите permissionMode для выбора режима разрешений, в котором работает subagent. Используйте значения конфигурации режимов, поэтому режим Manual — это default. Если вы оставите его неустановленным, subagent наследует режим основного разговора permission mode.

Режим разрешений основного разговора решает, использует ли Claude Code значение, которое вы установили:

  • Когда основной разговор находится в bypassPermissions, acceptEdits или auto mode, subagent работает в этом же режиме и Claude Code игнорирует permissionMode, который вы установили. Под auto mode классификатор оценивает вызовы инструментов subagent с правилами блокировки и разрешения основного разговора. Когда subagent завершается, классификатор также проверяет его работу и его финальный отчёт перед доставкой отчёта, как How auto mode handles subagents описывает.
  • Когда основной разговор находится в режиме default, dontAsk или plan, subagent работает в режиме разрешений, который вы установили, кроме bypassPermissions. Subagent, который объявляет bypassPermissions, сохраняет режим основного разговора вместо этого. Исключение bypassPermissions требует Claude Code v2.1.267 или позже.

permissionMode принимает эти значения и manual как псевдоним для default:

Mode Behavior
default Режим Manual: запрашивает разрешение
acceptEdits Автоматически принимать редактирование файлов и общие команды файловой системы для путей в рабочей директории или additionalDirectories
auto Auto mode: классификатор в фоне проверяет команды и записи в защищённые директории
dontAsk Автоматически отклонять запросы разрешений. Явно разрешённые инструменты по-прежнему работают; AskUserQuestion, MCP инструменты, отмеченные requiresUserInteraction, и инструменты соединителя которые ваша организация установила на ask в сессиях, где этот параметр достигает Claude Code, отклоняются, даже если вы их разрешили
bypassPermissions Пропустить запросы разрешений. Subagent работает в этом режиме только когда основной разговор это делает
plan Режим Plan (исследование только для чтения)

Предварительная загрузка skills в subagents

Используйте поле skills для инжекции содержимого skill в контекст subagent при запуске. Это даёт subagent знания в области без необходимости открывать и загружать skills во время выполнения.

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

Полное содержимое каждого перечисленного skill инжектируется в контекст subagent при запуске. Это поле контролирует, какие skills предварительно загружаются, а не какие skills может использовать subagent: без него subagent по-прежнему может открывать и вызывать project, user и plugin skills через инструмент Skill во время выполнения. Чтобы предотвратить использование subagent skills полностью, опустите Skill из списка tools или добавьте его в disallowedTools.

Вы не можете предварительно загружать skills, которые устанавливают disable-model-invocation: true, поскольку предварительная загрузка берёт из того же набора skills, который Claude может вызывать. Это включает встроенный skill /verify: только вы можете его запустить, поэтому он не может быть предварительно загружен либо.

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

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

Поле 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 $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

Когда агент вызывается как subagent, hooks Stop в frontmatter автоматически преобразуются в события SubagentStop.

Hooks уровня проекта для событий subagent

Настройте hooks в settings.json, которые реагируют на события жизненного цикла subagent в основной сессии.

Event Matcher input Когда это срабатывает
SubagentStart Имя типа агента Когда subagent начинает выполнение
SubagentStop Имя типа агента Когда subagent завершает выполнение

Оба события поддерживают matchers для нацеливания на конкретные типы агентов по имени. Значение matcher — это поле frontmatter name для project-level и user-level subagents, или scoped identifier, такой как my-plugin:db-agent для plugin subagents. Scoped name содержит двоеточие, поэтому он оценивается как unanchored regular expression; закрепите его с помощью ^ и $, как в ^my-plugin:db-agent$, чтобы соответствовать только этому агенту.

Этот пример запускает скрипт установки только при запуске subagent db-agent и скрипт очистки при остановке любого subagent:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

Matcher с дефисом, такой как db-agent, точно совпадает на Claude Code v2.1.195 или позже. На более ранних версиях он оценивается как unanchored regular expression и также срабатывает для любого типа агента, который его содержит, такого как prod-db-agent; закрепите его как ^db-agent$ на этих версиях.

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

Работа с подагентами

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

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

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

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

Явное вызывание подагентов

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

  • Естественный язык: назовите подагента в вашей подсказке; Claude решает, делегировать ли
  • @-упоминание: гарантирует, что подагент запустится для одной задачи
  • На уровне сессии: вся сессия использует системный prompt подагента, ограничения инструментов и модель через флаг --agent или параметр agent

Для естественного языка нет специального синтаксиса. Назовите подагента и Claude обычно делегирует:

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@-упомяните подагента. Введите @ и выберите подагента из выпадающего списка, так же как вы упоминаете файлы. Это гарантирует, что запустится конкретный подагент, а не оставляет выбор Claude:

@"code-reviewer (agent)" look at the auth changes

Ваше полное сообщение всё равно идёт к Claude, который пишет prompt задачи подагента на основе того, что вы попросили. @-упоминание контролирует, какой подагент Claude вызывает, а не какой prompt он получает.

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

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

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

claude --agent code-reviewer

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

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

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

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

claude --agent security-reviewer

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

claude --agent my-plugin:security-reviewer

Если плагин размещает агента в подпапке своей директории agents/, включите подпапку в scoped имя, например claude --agent my-plugin:review:security.

Чтобы сделать это стандартом для каждой сессии в проекте, установите agent в .claude/settings.json:

{
  "agent": "code-reviewer"
}

Флаг CLI переопределяет параметр, если оба присутствуют.

Запуск подагентов на переднем плане или в фоне

Подагенты могут работать на переднем плане или в фоне:

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

Для каждого подагента, который Claude порождает с помощью инструмента Agent, Claude Code выбирает передний план или фон из первого из этих случаев, который применяется:

  • Если товарищ по команде команды агентов в процессе породил подагента, Claude Code запускает его на переднем плане. Claude Code отказывает с ошибкой при попытке породить подагента товарища, чьё определение устанавливает background: true. Где режим fork отключён и вы не отключили фоновые задачи, Claude Code также отказывает с ошибкой, когда товарищ устанавливает run_in_background: true.
  • Если вы установили CLAUDE_CODE_DISABLE_BACKGROUND_TASKS на 1, Claude Code запускает подагента на переднем плане в каждом виде сессии и независимо от того, включён ли режим fork.
  • Где режим fork включён, как это по умолчанию в интерактивной сессии, Claude Code запускает подагента в фоне, как fork, так и non-fork подагентов, и Claude не может просить передний план.
  • Где режим fork отключён, Claude запускает подагента в фоне по умолчанию и на переднем плане, когда ему нужен результат перед продолжением. Режим fork отключён в неинтерактивном режиме с -p и в Agent SDK, если вы его не включите. Чтобы держать конкретный подагента в фоне даже когда Claude хочет результат, установите его frontmatter поле background на true.

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

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

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

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

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

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

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

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

  • Когда подагент завершается успешно, Claude Code удаляет его строку немедленно и, кроме как в режиме чтения с экрана, показывает /tasks to see subagents в нижней части на 30 секунд. В течение этих 30 секунд запустите /tasks и нажмите Enter на подагенте, чтобы открыть его транскрипт. До v2.1.232 Claude Code держал строку 30 секунд после завершения подагента, так же как неудачный, и не показывал подсказку в нижней части.
  • Когда подагент не удаётся или вы его останавливаете, Claude Code держит его строку 30 секунд. Чтобы очистить строку раньше, выберите её и нажмите x.

Фоновый подагент, который завершается, остаётся в списке /tasks, отмечен как выполненный и отсортирован ниже работающих задач, на те же 30 секунд, что и подсказка в нижней части. Его представление деталей остаётся открытым, когда подагент завершается. Подагенты, которые не удаются или которых вы останавливаете, покидают список. До v2.1.208 завершённый подагент покидал список в момент завершения и его представление деталей закрывалось.

Имена подагентов

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

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

Ошибки API в подагентах

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

Начиная с v2.1.199, подагент, чей запуск заканчивается на ошибке API, такой как лимит использования или повторяющаяся ошибка сервера, сообщает об этом отказе обратно Claude вместо возврата текста ошибки, как если бы это были выводы подагента. То, что получает Claude, зависит от того, где работал подагент:

  • Передний план: если лимит скорости, перегрузка или ошибка сервера прерывает подагента, который уже произвёл текстовый вывод, инструмент Agent возвращает этот частичный вывод с примечанием, что подагент был прерван и не завершил свою задачу. Подагент, который ничего не произвёл или чей единственный вывод был вызовами инструментов, не удаётся с Agent terminated early due to an API error, за которым следует деталь ошибки. В v2.1.199 лимит скорости, перегрузка или ошибка сервера, которые прерывали форму только вызовов инструментов, возвращали пустой частичный результат, содержащий только примечание о прерывании вместо этого.
  • Фон: подагент отмечен как неудачный, и сообщение, которое Claude получает при завершении, называет ошибку API и включает последний вывод подагента, поэтому частичная работа не теряется.

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

Как только основная ошибка API очищается, попросите Claude повторить задачу или возобновить подагента.

Сканирование выходных данных подагента

Claude Code сканирует финальный отчёт каждого подагента перед тем, как Claude его прочитает. Подагент мог прочитать файлы, веб-страницы или вывод команд, которые вы никогда не проверяли, и текст из этих источников может содержать инструкции, направленные на основной разговор. Сканирование никогда не удаляет и не переформулирует ничего; оно делает два вида изменений, которые вы можете заметить в отчёте:

  • Вставка обратной косой черты: сканирование вставляет обратную косую черту в текст, который имитирует собственный вывод Claude Code, такой как тег <system-reminder> или строка, начинающаяся с Human: или Assistant:, чтобы имитация читалась как обычный текст вместо того, чтобы быть ошибочно принятой за часть разговора.
  • Строка маркера: сканирование добавляет строку, начинающуюся с [harness: subagent output matched instruction-shaped pattern(s): когда отчёт имитирует тег вроде <system-reminder> или упоминает параметры разрешения такие как bypassPermissions или --dangerously-skip-permissions. Упоминания параметров разрешения получают строку маркера, но сам текст остаётся как написано.

Сканирование не судит, является ли содержимое вредоносным, и оно не меняет то, что инструкция в отчёте может сделать: вызов инструмента, который отчёт приводит Claude к выполнению, всё равно проходит через проверки разрешений сессии и sandboxing. Это не замена ограничению того, что подагент может достичь.

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

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

Общие паттерны

Изолируйте высокообъёмные операции

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

Use a subagent to run the test suite and report only the failing tests with their error messages

Запустите параллельное исследование

Для независимых расследований порождайте несколько подагентов для одновременной работы:

Research the authentication, database, and API modules in parallel using separate subagents

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

Для работы, которая должна продолжать работать параллельно или не поместится в одно окно контекста, запустите её в отдельных сессиях и позвольте Claude передавать выводы между ними.

Цепочка подагентов

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

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

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

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

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

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

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

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

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

Позвольте подагентам порождать своих собственных подагентов

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

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

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

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

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

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

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

Лимит одновременных подагентов

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

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

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

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

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

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

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

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

Начальный контекст non-fork подагента содержит:

  • System prompt: собственный prompt агента плюс детали окружения, которые Claude Code добавляет, не системный prompt Claude Code. Пользовательские подагенты определяют свои в теле markdown или поле prompt. Встроенные агенты имеют предопределённые prompts.
  • Сообщение задачи: prompt делегирования, который Claude пишет, когда передаёт работу.
  • Файлы CLAUDE.md: каждый уровень иерархии CLAUDE.md, который загружает основной разговор, включая ~/.claude/CLAUDE.md, правила проекта, CLAUDE.local.md, файлы управляемой политики и любые AGENTS.md файлы, загруженные как инструкции проекта. Встроенные агенты Explore и Plan пропускают это. Подагент, чьё определение устанавливает omitClaudeMd, загружает только файлы управляемой политики или ничего вообще, когда определение приходит из управляемых параметров.
  • Статус Git: снимок, который Claude Code читает из вашего репозитория, когда подагент запускается. Отсутствует вне Git репозитория или когда снимок отключён; см. includeGitInstructions. Explore и Plan пропускают его независимо.
  • Предзагруженные skills: полное содержимое любого skill, названного в поле skills агента. Встроенные агенты не предзагружают skills.
  • Список товарищей: системное напоминание, перечисляющее main и каждого другого именованного агента в сессии, каждый действительное значение to для SendMessage. Требует Claude Code v2.1.206 или позже. Список появляется только когда инструменты подагента включают SendMessage и по крайней мере один другой агент имеет имя, будь то Claude назвал его при порождении или он работает как товарищ команды агентов. Это снимок, сделанный при запуске подагента, поэтому агенты, названные позже, не появляются.

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

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

Вы не можете изменить, какие подагенты получают статус git. Только Explore и Plan пропускают его.

Некоторое состояние основного разговора никогда не достигает non-fork подагента:

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

Возобновление подагентов

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

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

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

Claude использует инструмент SendMessage с ID или именем агента как поле to для возобновления его. SendMessage не требует команды агентов для включения; только структурированные сообщения протокола команды, такие как shutdown_request и plan_approval_response, это требуют. Помимо подагентов и товарищей, в сессиях, где включена cross-session messaging, Claude может использовать тот же инструмент для отправки сообщений вашим другим сессиям Claude Code, на этой машине или за её пределами.

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

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

Когда Claude отправляет завершённому подагенту сообщение с инструментом SendMessage, подагент возобновляется в фоне без нового вызова Agent. То же самое применяется к подагенту, которого Claude остановил с инструментом TaskStop, как только его остановленный запуск вышел. Возобновлённый запуск держит набор инструментов с того места, где подагент впервые запустился и может продолжить чтение кэша prompt, который исходный запуск разогрел.

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

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

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

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

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

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

Вы также можете попросить Claude для agent ID, если вы хотите ссылаться на него явно, или найти IDs в файлах транскрипта в ~/.claude/projects/{project}/{sessionId}/subagents/. Каждый транскрипт хранится как agent-{agentId}.jsonl.

Транскрипты подагентов сохраняются независимо от основного разговора:

  • Компактирование основного разговора: когда основной разговор компактируется, транскрипты подагентов не затрагиваются. Они хранятся в отдельных файлах.
  • Сохранение сессии: транскрипты подагентов сохраняются в их сессии. Вы можете возобновить подагента после перезагрузки Claude Code, возобновив ту же сессию.
  • Автоматическая очистка: Claude Code удаляет транскрипты подагентов после периода сохранения cleanupPeriodDays, 30 дней по умолчанию, следуя правилам развёртки очистки.

Автоматическое компактирование

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

События компактирования регистрируются в файлах транскрипта подагентов:

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

Значение preTokens показывает, сколько токенов было использовано перед тем, как произошло компактирование.

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

Fork — это subagent, который наследует весь разговор до сих пор вместо начала с нуля. Это отбрасывает входную изоляцию, которую subagents иначе предоставляют: fork видит то же системное приглашение, инструменты, модель и историю сообщений, что и основная сессия, поэтому вы можете передать ему побочную задачу без переобъяснения ситуации. Вызовы инструментов fork по-прежнему остаются вне вашего разговора и только его окончательный результат возвращается, поэтому ваше основное контекстное окно остаётся чистым. Используйте fork, когда любой другой subagent потребовал бы слишком много фона, чтобы быть полезным, или когда вы хотите попробовать несколько подходов параллельно с одной и той же отправной точки.

Claude запускает fork, запрашивая тип subagent fork через инструмент Agent. Вы контролируете, может ли он это делать, с помощью режима fork, который включен по умолчанию в интерактивных сессиях.

Вы можете запустить fork самостоятельно с помощью /subtask за которым следует задача, независимо от того, включен ли режим fork или нет. На v2.1.161 через v2.1.211 команда — это /fork. Claude Code называет fork из первых слов задачи. Следующий пример разветвляет разговор для черновика тестовых случаев, пока вы продолжаете с реализацией в основной сессии:

/subtask draft unit tests for the parser changes so far

Fork появляется в панели ниже вашего приглашения и работает в фоне, пока вы продолжаете работать. Когда он завершается, его результат приходит как сообщение в вашем основном разговоре. Следующий раздел охватывает элементы управления панели для наблюдения и управления forks во время их работы.

Наблюдение и управление работающими forks

Работающие forks появляются в панели ниже входа приглашения, с одной строкой для основной сессии и одной для каждого fork.

Когда fork завершается успешно, Claude Code удаляет его строку. Claude Code сохраняет строку fork, который не удался или который вы остановили, на 30 секунд, то же самое, что и для любого другого фонового subagent. До v2.1.232 Claude Code также сохранял строку завершённого fork на 30 секунд.

Используйте эти клавиши для взаимодействия с панелью:

Key Action
↑ / ↓ Перемещение между строками
Enter Откройте транскрипт выбранного fork и отправьте ему последующие сообщения
x Остановите выбранный fork, если он работает, или отклоните его строку, если он больше не работает. На строке основной сессии или на строке fork, чей транскрипт вы открыли с помощью Enter, x вводит текст в приглашение вместо этого
Esc Верните фокус на входное приглашение

С открытым транскриптом fork или subagent, последующие сообщения и skills идут к этому агенту, но встроенные команды по-прежнему работают в вашем основном разговоре. Начиная с v2.1.199, ввод /model или /fast в этом представлении показывает уведомление о том, что это изменяет модель основного разговора или режим быстрого выполнения, а не просмотренного агента, вместо того чтобы запускать его молча.

Как forks отличаются от других subagents

Fork наследует всё, что основная сессия имеет в момент его порождения. Любой другой subagent начинает с нуля из своего определения.

Fork Non-fork subagent
Context Полная история разговора Свежий контекст с приглашением, которое вы передаёте
System prompt and tools Такие же как основная сессия Из файла определения subagent, отфильтрованные для фоновых запусков
Model Такая же как основная сессия Из поля model subagent
Permissions Запросы выводятся в вашем терминале Запросы выводятся в вашей основной сессии при запуске в фоне
Prompt cache Общий с основной сессией Отдельный кэш

Поскольку системное приглашение fork и определения инструментов идентичны родителю, его первый запрос повторно использует кэш приглашений родителя prompt cache. Это делает forking дешевле, чем порождение свежего subagent для задач, которые нуждаются в том же контексте.

Когда Claude порождает fork через инструмент Agent, он может передать isolation: "worktree", чтобы редактирования файлов fork были написаны в отдельный git worktree вместо вашего checkout. Fork не может порождать дальнейшие forks.

Включение или отключение режима fork

Claude Code включает режим fork по умолчанию в интерактивных сессиях и оставляет его отключённым по умолчанию в non-interactive mode с -p и в Agent SDK. Интерактивное значение по умолчанию требует Claude Code v2.1.232 или позже. На более ранних версиях установите CLAUDE_CODE_FORK_SUBAGENT на 1, чтобы включить режим fork.

Вы можете сказать, что режим fork включен, по тому, как Claude Code обрабатывает инструмент Agent:

  • Claude может порождать fork, запрашивая тип subagent fork. Когда Claude не запрашивает тип, он получает general-purpose subagent, если сессия всё ещё имеет этот тип. Subagents, порождённые из определения, такие как Explore, работают как обычно.
  • Claude Code запускает subagents, которые Claude порождает, в фоне, forks и non-fork subagents в равной степени, кроме случаев, которые остаются в переднем плане. Claude Code также удаляет параметр run_in_background инструмента Agent, поэтому Claude не может просить передний план.

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

  • 1 включает режим fork в non-interactive mode и Agent SDK также
  • 0 отключает режим fork в каждом виде сессии

Чтобы сохранить режим fork включённым, но остановить Claude от порождения forks, запретите тип subagent fork с помощью правила Agent(fork). Claude Code по-прежнему запускает subagents, которые Claude порождает, в фоне, кроме тех же случаев, которые остаются в переднем плане.

Примеры subagents

Эти примеры демонстрируют эффективные паттерны для создания subagents. Используйте их как отправные точки или генерируйте настроенную версию с Claude.

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