Руководства

Subagents в Claude Code: как создать, настроить и использовать

Опубликовано 30 октября 2026 г. · Проверено 30 октября 2026 г.

Subagent — это специализированный AI-помощник, который решает задачи одного типа в собственном контекстном окне и возвращает в основной разговор только краткое изложение. Эта страница разбирает документацию Anthropic Create custom subagents: что такое subagent, встроенные subagents, создание собственных, где лежат файлы, как писать frontmatter, выбор модели, как вызвать subagent и что проверить, если он не найден. Документация проверена 30 октября 2026 г.

Что такое subagent и когда его использовать

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

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

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

Ещё одно замечание из документации: subagents работают в рамках одной сессии. Чтобы запускать много независимых сессий параллельно и следить за ними из одного места, она указывает на фоновые агенты. Для скоординированной команды сессий, которые Claude порождает и контролирует, — на agent teams.

Встроенные subagents

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

Explore и Plan стартуют без ваших файлов CLAUDE.md и снимка статуса git, чтобы исследование было быстрым и недорогим. Остальные встроенные и пользовательские subagents загружают оба. При вызове Explore Claude указывает уровень тщательности: quick для точечных поисков, medium для сбалансированного исследования или very thorough для всестороннего анализа.

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

Чтобы заблокировать конкретный встроенный тип, добавьте его в permissions.deny, как показано в FAQ ниже. Чтобы убрать только встроенные subagents Explore и Plan, задайте CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1; тогда Claude читает и исследует файлы напрямую. Нужен Claude Code v2.1.198 или новее.

Создайте своего первого subagent

Subagents — это файлы Markdown с YAML frontmatter. Можно попросить Claude написать его за вас или написать файл самому. Это руководство взято из документации и создаёт subagent уровня пользователя, который проверяет код и предлагает улучшения.

Сначала в Claude Code опишите нужного subagent и где его сохранить:

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

Claude записывает файл с name, description, списком tools, model и системным промптом. Затем откройте ~/.claude/agents/code-improver.md и убедитесь, что frontmatter соответствует вашей просьбе. Результат выглядит так:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Поскольку файл лежит в ~/.claude/agents/, subagent доступен в каждом проекте на вашей машине. Чтобы ограничить его одним проектом, переместите его в каталог .claude/agents/ этого проекта. В-третьих, попросите Claude делегировать ему:

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

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

О /agents: в документации сказано, что выполнение /agents выводит напоминание попросить Claude или отредактировать .claude/agents/ и ~/.claude/agents/ напрямую. В Claude Code v2.1.197 и более ранних /agents открывает интерактивный мастер с вкладкой Running, где перечислены работающие subagents, и вкладкой Library для их создания, правки и удаления.

После изменения перезапуск не нужен. В документации сказано, что Claude Code следит за ~/.claude/agents/ и .claude/agents/: когда вы добавляете или правите файл subagent на диске или просите Claude его написать, он замечает изменение в течение нескольких секунд, и следующее делегирование использует обновлённое определение. Три случая всё же требуют перезапуска; они описаны в разделе об устранении неполадок.

Где лежат файлы subagents

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

• Subagents проекта (.claude/agents/) идеальны для subagents, специфичных для кодовой базы. Документация советует добавлять их в систему контроля версий, чтобы ваша команда могла совместно использовать и улучшать их.
• Subagents пользователя (~/.claude/agents/) — личные subagents, доступные во всех ваших проектах.
• Claude Code сканирует .claude/agents/ и ~/.claude/agents/ рекурсивно, так что определения можно раскладывать по подпапкам, например agents/review/ или agents/research/. Путь подкаталога не влияет на то, как subagent идентифицируется и вызывается, потому что идентичность определяется только полем frontmatter name.
• Делайте значения name уникальными во всём дереве: если два файла в одном каталоге .claude/agents/, включая его подпапки, объявляют одно имя, Claude Code загружает только один из них, выбранный порядком чтения файловой системы, а не документированным приоритетом.

Subagents проекта обнаруживаются подъёмом вверх от текущего рабочего каталога, так что сканируется каждый .claude/agents/ между ним и корнем репозитория. Когда в нескольких таких вложенных каталогах определено одно и то же name, Claude Code использует определение, ближайшее к рабочему каталогу.

Самые важные поля frontmatter

Настраивайте subagent с помощью YAML frontmatter между маркерами --- в начале его файла, а его системный промпт пишите в Markdown после закрывающего ---. Обязательны только name и description. Имена полей из нескольких слов пишутся в camelCase, например maxTurns и disallowedTools, и должны в точности совпадать с таблицей: Claude Code игнорирует нераспознанное поле, не сообщая об ошибке.

В документации перечислены и другие поля, включая autoCompactWindow, omitClaudeMd, color, initialPrompt и experimental; здесь они не рассматриваются. Ещё один момент: тело файла становится системным промптом. Subagents получают только этот системный промпт плюс базовые сведения об окружении, например рабочий каталог, а не системный промпт Claude Code.

Ограничение инструментов

Чтобы ограничить инструменты, используйте поле tools как список разрешённых или поле disallowedTools как список запрещённых. Если заданы оба, сначала применяется disallowedTools, а затем tools разрешается относительно оставшегося набора. Инструмент, указанный в обоих, удаляется. Этот пример из документации использует tools, чтобы разрешить только Read, Grep, Glob и Bash. Subagent не может править файлы, записывать файлы или использовать какие-либо инструменты MCP:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

Этот использует disallowedTools, чтобы унаследовать набор инструментов subagent, кроме Write и Edit. Subagent сохраняет Bash, инструменты MCP и остальное из своего набора:

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

Выбор модели

Поле model определяет, какую модель использует subagent. Это может быть алиас (sonnet, opus, haiku или fable), полный ID модели вроде claude-opus-5-5 или claude-sonnet-5 (принимаются те же значения, что и у флага --model) либо inherit, то есть та же модель, что у основного разговора. Когда Claude вызывает subagent, он также может передать параметр model для этого конкретного вызова. Claude Code определяет модель subagent в таком порядке:

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

Чтобы проверить, на какой модели работает subagent, выполните /tasks. Claude Code указывает модель в строке subagent (нужен Claude Code v2.1.242 или новее). Пример из документации для запуска каждого subagent на Haiku задаёт обе переменные в блоке env файла настроек:

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

CLAUDE_CODE_SUBAGENT_MODEL_FORCE требует Claude Code v2.1.257 или новее. Пока она включена, Claude Code игнорирует поле model в определениях subagents.

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

Автоматическое делегирование и явный вызов

Автоматическое делегирование. Claude автоматически делегирует задачи на основании описания задачи в вашем запросе, поля description в конфигурациях subagents и текущего контекста. Чтобы поощрить проактивное делегирование, включите в поле description subagent фразы вроде «use proactively». Держите описания краткими: Claude Code показывает предупреждение при запуске, когда суммарные описания ваших subagents (кроме встроенных) превышают 15 000 токенов, но всё равно загружает каждого subagent.

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

• Естественный язык: назовите subagent в prompt; 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, а не оставляет выбор Claude:

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

Ваше сообщение целиком по-прежнему уходит Claude, который пишет prompt задачи для subagent на основе вашей просьбы. @-упоминание определяет, какого subagent вызывает Claude, а не какой prompt он получает. Упоминание можно также набрать вручную без выбора из списка: @agent-<name>.

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

claude --agent code-reviewer

Имя агента отображается как @<name> в заголовке при запуске, так что можно убедиться, что он активен. Чтобы сделать его значением по умолчанию для каждой сессии в проекте, задайте agent в .claude/settings.json. Флаг CLI переопределяет настройку, если присутствуют оба:

{
  "agent": "code-reviewer"
}

Передний план и фон: subagents переднего плана блокируют основной разговор до завершения, а запросы разрешений передаются вам. Фоновые subagents работают параллельно, пока вы продолжаете работать. В документации сказано, что при отсутствии настроек subagent, порождённый Claude из вашего основного разговора, стартует в фоне.

Полный пример: ревьюер кода

Этот пример взят из раздела Example subagents документации: subagent только для чтения, который проверяет код, не изменяя его. Он показывает, как спроектировать узкого subagent с ограниченным доступом к инструментам, исключающим Edit и Write, и подробным prompt, который точно указывает, на что смотреть и как оформлять вывод. Сохраните его как .claude/agents/code-reviewer.md.

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

В этом файле model: inherit означает, что используется та же модель, что и в основном разговоре, а формулировки «Proactively» и «Use immediately after writing or modifying code» в description подсказывают Claude, когда делегировать.

Советы из документации

Рекомендации документации:

• Проектируйте узких subagents: каждый subagent должен отлично справляться с одной конкретной задачей.
• Пишите описания, выделяющие одного subagent: Claude по описанию решает, когда делегировать. Делайте каждое описание достаточно конкретным, чтобы задача направлялась нужному subagent, и держите весь набор в пределах бюджета описаний 15 000 токенов.
• Ограничивайте доступ к инструментам: выдавайте только необходимые права ради безопасности и сосредоточенности.
• Добавляйте в систему контроля версий: делитесь subagents проекта с командой.

Типовые паттерны из документации:

• Изолируйте операции с большим объёмом вывода. Запуск тестов, получение документации или обработка лог-файлов могут занять много контекста. Делегирование оставляет многословный вывод в контексте 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. Лучше всего это работает, когда пути исследования не зависят друг от друга.
• Выстраивайте subagents в цепочку. Для многошаговых процессов просите Claude использовать subagents последовательно. Например: Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

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

Когда не использовать: используйте основной разговор, если задаче нужны частые уточнения и итеративная доработка, несколько этапов делят значительный контекст, вы вносите быстрое точечное изменение или важна задержка (subagent, не являющийся форком, стартует с нуля и может тратить время на сбор контекста). Для повторно используемых prompts или процессов, которые выполняются в контексте основного разговора, а не в изолированном контексте subagent, документация предлагает рассмотреть вместо этого skills.

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

Claude не находит нового subagent

Перезапустите Claude Code и попробуйте снова. В документации сказано, что это бывает, только когда ~/.claude/agents/ не существовал до начала сессии, потому что запущенная сессия не обнаруживает только что созданный каталог agents. Три случая всё же требуют перезапуска: после создания первого файла агента области в новом каталоге agents; после добавления или правки subagent в каталоге, добавленном через --add-dir или /add-dir; и в сессиях, запущенных с --disable-slash-commands, которые вообще не следят за этими каталогами.

Файл молча пропускается

В документации сказано, что Claude Code пропускает файл, не сообщая об этом в сессии, если во frontmatter есть любая из этих проблем:

• Нет name: Claude Code считает файл документацией, лежащей рядом с вашими агентами.
• Открывающий --- не на первой строке файла: Claude Code читает файл как не имеющий frontmatter и считает его документацией.
• name начинается с -, содержит : или длиннее 256 символов: Claude Code пропускает файл и записывает ошибку в отладочный лог.
• Есть name, но нет description: Claude Code пропускает файл и записывает причину в отладочный лог.
• YAML не разбирается: Claude Code не читает из файла никаких полей, пропускает его и записывает ошибку разбора в отладочный лог.

Чтобы увидеть отладочный лог, запустите Claude Code с --debug. Чтобы найти файлы, frontmatter которых не разбирается, выполните claude plugin validate для каталога, например .claude/agents или ~/.claude/agents (нужен Claude Code v2.1.233 или новее). Он не помечает файл, frontmatter которого разбирается, но в нём нет name.

Поле написано с ошибкой, и ничто об этом не сообщает

Claude Code игнорирует нераспознанное поле, не сообщая об ошибке. Для загруженного subagent выполните в оболочке claude --debug и найдите в отладочном логе ~/.claude/debug/<session-id>.txt строку does not recognize or apply. Лог называет до пяти полей верхнего уровня в файле subagent, которые Claude Code не распознаёт, с предполагаемым именем, если поддерживаемое поле похоже (нужен Claude Code v2.1.296 или новее).

Subagent не запускается

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

Subagent не знает ваших правил и разговора

Каждый subagent стартует со свежего изолированного контекстного окна. Он не видит историю вашего разговора, уже вызванные вами skills и файлы, которые Claude уже прочитал. Claude составляет сообщение о делегировании, кратко излагающее задачу, и subagent работает от него. Если правило должно дойти до subagent, например «ignore the vendor/ directory», повторите его в prompt, который вы даёте Claude при делегировании.

FAQ

Источники

• Claude Code: Create custom subagents (встроенные subagents, пошаговое создание, расположение файлов и приоритет, поля frontmatter, порядок выбора модели, вызов, типовые паттерны, примеры, устранение неполадок)