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

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

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

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

Subagents помогают вам:

• Сохранять контекст, отделяя исследование и реализацию от основного разговора
• Применять ограничения, ограничивая доступ subagent к определённым инструментам
• Переиспользовать конфигурации в проектах с помощью subagents уровня пользователя
• Специализировать поведение с помощью сфокусированных системных приглашений для конкретных областей
• Контролировать затраты, маршрутизируя задачи на более быстрые и дешёвые модели, такие как Haiku

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

Claude Code включает несколько встроенных subagents, таких как Explore, Plan и general-purpose. Вы также можете создавать пользовательские subagents для обработки конкретных задач.

Встроенные subagents

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

Explore и Plan пропускают ваши файлы CLAUDE.md и статус git родительской сессии, чтобы исследование было быстрым и экономичным. Все остальные встроенные и пользовательские subagents загружают оба. Для полного разбора того, что достигает subagent, см. что загружается при запуске.

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

• Чтобы заблокировать определённый встроенный тип, добавьте его в permissions.deny, как показано в Отключение определённых subagents.
• Чтобы предотвратить делегирование Claude к любому subagent, запретите сам инструмент Agent с помощью permissions.deny.
• {/* min-version: 2.1.198 */}Чтобы удалить только встроенные subagents Explore и Plan, установите CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude читает и исследует файлы напрямую вместо делегирования им. Требуется Claude Code версии 2.1.198 или позже.
• В неинтерактивном режиме и Agent SDK установите CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 для удаления всех встроенных типов и предоставления только ваших собственных.

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

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

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

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

Это пошаговое руководство создаёт 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.

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

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

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

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

Настройка subagents

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

Выберите область subagent

Сохраняйте файлы subagent в разных местах в зависимости от области. Когда несколько subagents имеют одно и то же имя, Claude Code использует тот, который находится в местоположении с более высоким приоритетом.

Project subagents (.claude/agents/) идеальны для subagents, специфичных для кодовой базы. Проверьте их в систему контроля версий, чтобы ваша команда могла использовать и улучшать их совместно.

Project subagents обнаруживаются путём прохода вверх от текущей рабочей директории, поэтому каждый .claude/agents/ между ней и корнем репозитория сканируется. {/* min-version: 2.1.178 */}Начиная с версии 2.1.178, когда более одной из этих вложенных директорий определяет одно и то же name, Claude Code использует определение, ближайшее к рабочей директории.

Директории, добавленные с помощью --add-dir, также сканируются: папка .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 Code загружает только один из них. {/* min-version: 2.1.196 */}Начиная с версии 2.1.196, запуск /doctor сообщает об одинаковых именах агентов в одной области и показывает, какое определение активно.

Директории agents/ plugin также сканируются рекурсивно. В отличие от областей проекта и пользователя, подпапка внутри директории agents/ plugin становится частью scoped identifier: файл в agents/review/security.md в plugin my-plugin регистрируется как my-plugin:review:security.

CLI-определённые subagents передаются как JSON при запуске Claude Code. Они существуют только для этой сессии и не сохраняются на диск, что делает их полезными для быстрого тестирования или скриптов автоматизации. Вы можете определить несколько subagents в одном вызове --agents:

claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
},
"debugger": {
"description": "Debugging specialist for errors and test failures.",
"prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
}
}'

claude --agents @'
{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
},
"debugger": {
"description": "Debugging specialist for errors and test failures.",
"prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
}
}
'@

Флаг --agents принимает JSON с теми же полями frontmatter, что и файловые subagents: description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, isolation и color. Используйте prompt для системного приглашения, эквивалентного телу markdown в файловых subagents.

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, и товарищ использует его tools и model, с телом определения добавленным в качестве дополнительных инструкций к системному приглашению товарища. См. agent teams для того, какие поля frontmatter применяются на этом пути.

Напишите файлы 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.

Subagent начинает работу в текущей рабочей директории основного разговора. В пределах subagent команды cd не сохраняются между вызовами инструментов Bash или PowerShell и не влияют на рабочую директорию основного разговора. Чтобы дать subagent изолированную копию репозитория вместо этого, установите isolation: worktree.

Поддерживаемые поля frontmatter

Следующие поля могут использоваться в YAML frontmatter. Требуются только name и description.

Выберите модель

Поле model контролирует, какую AI модель использует subagent:

• Model alias: Используйте один из доступных псевдонимов: sonnet, opus, haiku или fable
• Full model ID: Используйте полный ID модели, такой как claude-opus-4-8 или claude-sonnet-5. Принимает те же значения, что и флаг --model
• inherit: Используйте ту же модель, что и основной разговор
• Omitted: Если не указано, по умолчанию inherit и использует ту же модель, что и основной разговор

Когда Claude вызывает subagent, он также может передать параметр model для этого конкретного вызова. Claude Code разрешает модель subagent в этом порядке:

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

{/* min-version: 2.1.196 */}Начиная с версии 2.1.196, установка CLAUDE_CODE_SUBAGENT_MODEL на inherit — это то же самое, что оставить его неустановленным: разрешение продолжается с параметром model для конкретного вызова, затем frontmatter. В более ранних версиях inherit заставлял subagents использовать модель основного разговора и игнорировал оба этих источника.

Переменная окружения, параметр для конкретного вызова и значения frontmatter проверяются на соответствие списку разрешений availableModels вашей организации. Значение, которое разрешается в исключённую модель, не используется, и subagent вместо этого работает на унаследованной модели.

{/* min-version: 2.1.198 */}Начиная с версии 2.1.198, subagents также наследуют конфигурацию extended thinking основного разговора: если thinking включен в вашей сессии, он включен для subagent, и если он выключен, он остаётся выключенным. Нет параметра thinking для каждого subagent. До версии 2.1.198 subagents запускались с отключённым extended thinking независимо от параметра основного разговора.

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

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

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

Subagents наследуют внутренние инструменты и MCP инструменты, доступные в основном разговоре по умолчанию. Следующие инструменты зависят от пользовательского интерфейса основного разговора или состояния сессии и недоступны для subagents, даже если они указаны в поле tools:

• AskUserQuestion
• EnterPlanMode
• ExitPlanMode, если только permissionMode subagent не является plan
• ScheduleWakeup
• WaitForMcpServers

Чтобы ограничить инструменты, используйте поле 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 every tool except file writes
disallowedTools: Write, Edit
---

Если оба установлены, disallowedTools применяется первым, затем tools разрешается против оставшегося пула. Инструмент, указанный в обоих, удаляется.

Оба поля принимают паттерны уровня 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
---

Ограничьте, какие 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_type) применяется только к агенту, работающему как основной поток с claude --agent. В определении subagent перечисление Agent в tools позволяет этому subagent порождать вложенные subagents, но любой список типов внутри скобок игнорируется.

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

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

• --strict-mcp-config и --bare
• Enterprise управляемая конфигурация MCP
• allowedMcpServers и deniedMcpServers политики

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

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

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

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

Если родитель использует bypassPermissions или acceptEdits, это имеет приоритет и не может быть переопределено. Если родитель использует auto mode, subagent наследует auto mode и любой permissionMode в его frontmatter игнорируется: классификатор оценивает вызовы инструментов subagent с теми же правилами блокировки и разрешения, что и родительская сессия.

Предварительная загрузка 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 отсутствует или отключен, 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.

Выберите область в зависимости от того, насколько широко должна применяться память:

Когда память включена:

• Системное приглашение 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

См. 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

Hooks в frontmatter subagent

Определите hooks непосредственно в файле markdown subagent. Эти hooks запускаются только во время активности этого конкретного subagent и очищаются при его завершении.

Поддерживаются все hook events. Наиболее распространённые события для subagents:

Этот пример проверяет команды 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"
---

Hooks Stop в frontmatter автоматически преобразуются в события SubagentStop.

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

Настройте hooks в settings.json, которые реагируют на события жизненного цикла 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.

Работа с subagents

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

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

Явно вызывайте subagents

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

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

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

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

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

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

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

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

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

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

claude --agent code-reviewer

Системное приглашение subagent полностью заменяет системное приглашение Claude Code по умолчанию, так же как --system-prompt это делает. Файлы CLAUDE.md и память проекта по-прежнему загружаются через обычный поток сообщений. Имя агента появляется как @<name> в заголовке запуска, чтобы вы могли подтвердить, что он активен.

Это работает с встроенными и пользовательскими subagents, и выбор сохраняется при возобновлении сессии.

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

claude --agent security-reviewer

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

claude --agent my-plugin:security-reviewer

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

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

{
  "agent": "code-reviewer"
}

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

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

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

• Foreground subagents блокируют основной разговор до завершения. Запросы разрешений передаются вам по мере их возникновения.
• Background subagents работают параллельно, пока вы продолжаете работать. {/* min-version: 2.1.186 */}Начиная с v2.1.186, когда фоновый subagent достигает вызова инструмента, требующего разрешения, приглашение появляется в вашей основной сессии и называет subagent, который спрашивает. Одобрите, чтобы позволить subagent продолжить, или нажмите Esc, чтобы отклонить этот вызов инструмента без остановки subagent. До v2.1.186 фоновые subagents автоматически отклоняли любой вызов инструмента, который иначе потребовал бы приглашения.

{/* min-version: 2.1.198 */}Начиная с v2.1.198, subagents работают в фоне по умолчанию. Claude запускает subagent в переднем плане, когда ему нужен результат перед продолжением. По умолчанию изменяется место выполнения subagent, а не то, что ему разрешено делать: фоновые subagents по-прежнему выводят каждый запрос разрешения в вашу основную сессию. До v2.1.198 Claude выбирал между передним планом и фоном на основе задачи.

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

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

Чтобы отключить всю функциональность фоновых задач, установите переменную окружения CLAUDE_CODE_DISABLE_BACKGROUND_TASKS на 1. См. Environment variables.

Когда CLAUDE_CODE_FORK_SUBAGENT установлена на 1, каждый spawn subagent работает в фоне и поле frontmatter background не имеет эффекта, потому что режим fork удаляет параметр run_in_background из инструмента Agent. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS имеет приоритет над режимом fork и сохраняет spawns subagent в переднем плане.

Ошибки API в subagents

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

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

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

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

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

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

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

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

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

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

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

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

Цепочка subagents

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

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

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

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

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

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

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

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

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

Порождайте вложенные subagents

{/* min-version: 2.1.172 */}Начиная с Claude Code v2.1.172, subagent может порождать собственные subagents. Используйте это, когда делегированная задача сама разбивается на параллельные подзадачи, например subagent-рецензент, который отправляет верификатор для каждого обнаружения, так что промежуточный выход никогда не достигает основного разговора. Только резюме subagent верхнего уровня возвращается вам.

Вложенный subagent конфигурируется так же, как subagent верхнего уровня и разрешается из тех же областей видимости.

Панель subagent ниже ввода приглашения показывает полное дерево: каждая строка отображает счётчик (+N) потомков, и {/* min-version: 2.1.193 */}начиная с v2.1.193, открытие строки показывает прямых потомков этого subagent с путём обратно к main.

Глубина считается количеством уровней subagent ниже основного разговора, независимо от того, работает ли каждый уровень в переднем плане или фоне. Subagent на глубине пять не получает инструмент Agent и не может порождать дальше. Лимит фиксирован и не конфигурируется.

Начиная с Claude Code v2.1.187, глубина фонового subagent фиксируется при его первом порождении, и возобновление его позже не изменяет эту глубину. Например, если ваш основной разговор порождает subagent A, и A порождает фоновый subagent B на глубине два, B по-прежнему находится на глубине два при возобновлении его непосредственно из основного разговора. Возобновление subagent из более поверхностного контекста не позволяет ему порождать дополнительные уровни, которые лимит глубины уже предотвратил.

Чтобы предотвратить порождение других subagents конкретным subagent, опустите Agent из его списка tools или добавьте его в disallowedTools.

Fork по-прежнему не может порождать другой fork. Он может порождать другие типы subagent, и они считаются в сторону лимита глубины.

Управляйте контекстом subagent

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

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

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

• System prompt: собственное приглашение агента плюс детали окружения, которые добавляет Claude Code, а не полное системное приглашение Claude Code. Пользовательские subagents определяют свои в markdown body или поле prompt. Встроенные агенты имеют предопределённые приглашения.
• Task message: приглашение делегирования, которое Claude пишет при передаче работы.
• CLAUDE.md and memory: каждый уровень иерархии памяти, который загружает основной разговор, включая ~/.claude/CLAUDE.md, правила проекта, CLAUDE.local.md и управляемые файлы политики. Встроенные агенты Explore и Plan пропускают это.
• Git status: снимок, сделанный в начале родительской сессии. Отсутствует, когда рабочая директория не является Git репозиторием или когда includeGitInstructions имеет значение false. Explore и Plan пропускают это независимо.
• Preloaded skills: полное содержание любого навыка, названного в поле skills агента. Встроенные агенты не предзагружают навыки.

Explore и Plan — единственные subagents, которые опускают CLAUDE.md и git status. Нет поля frontmatter или параметра per-agent для изменения того, какие агенты их пропускают.

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

Возобновите subagents

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

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

Когда subagent завершается, Claude получает его ID агента. Встроенные агенты Explore и Plan — это одноразовые и не возвращают ID агента, поэтому они не могут быть возобновлены; используйте general-purpose или пользовательский subagent, когда вам нужно продолжить работу.

Claude использует инструмент SendMessage с ID агента или именем агента в качестве поля to для возобновления его. SendMessage не требует включения agent teams; только структурированные сообщения протокола команды, такие как shutdown_request и plan_approval_response, это требуют.

Чтобы возобновить subagent, попросите 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]

Если остановленный subagent получает SendMessage, он автоматически возобновляется в фоне без необходимости нового вызова Agent.

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

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

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

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

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

Auto-compaction

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

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

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

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

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

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

Чтобы управлять режимом fork независимо от поэтапного развертывания, установите CLAUDE_CODE_FORK_SUBAGENT на 1, чтобы явно включить его, или на 0, чтобы отключить его. Переменная учитывается в интерактивном режиме и через SDK или claude -p.

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

• Claude может порождать fork, явно запрашивая тип subagent fork. Порождения без типа subagent по-прежнему используют general-purpose subagent, и именованные subagents, такие как Explore, по-прежнему порождаются как раньше.
• Каждый spawn subagent работает в фоне, будь то fork или именованный subagent. Установите CLAUDE_CODE_DISABLE_BACKGROUND_TASKS на 1, чтобы сохранить spawns синхронными.

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

/fork draft unit tests for the parser changes so far

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

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

Работающие forks появляются в панели ниже входа приглашения, с одной строкой для основной сессии и одной для каждого fork. Используйте эти клавиши для взаимодействия с панелью:

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

Как forks отличаются от именованных subagents

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

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

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

Ограничения

Установка CLAUDE_CODE_FORK_SUBAGENT=1 включает режим fork в интерактивных сессиях, non-interactive mode и Agent SDK; установка на 0 отключает режим fork везде, включая любое развертывание на стороне сервера. Fork не может порождать дальнейшие forks.

Примеры subagents

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

Проверяющий кода

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.

Отладчик

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

Специалист по данным

Специализированный 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.

Валидатор запросов к базе данных

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 для полной схемы входных данных.

Следующие шаги

Теперь, когда вы понимаете subagents, изучите эти связанные функции:

• Распространяйте subagents с помощью plugins для совместного использования subagents в командах или проектах
• Запустите Claude Code программно с помощью Agent SDK для CI/CD и автоматизации
• Используйте MCP servers для предоставления subagents доступа к внешним инструментам и данным