Субагенты Claude Code: как создать своего под свои задачи в 2026

Что такое субагент в Claude Code?

Субагент Claude Code — это отдельный AI-помощник, который выполняет одну задачу в собственном контекстном окне: со своей инструкцией, своим набором инструментов и своей моделью. В основной чат он возвращает только результат, а не весь мусор из чтения файлов и поиска. Технически субагент — это markdown-файл с YAML-заголовком, который лежит в папке agents.

Главный агент читает поле description у каждого субагента и сам решает, кому делегировать задачу. Ты можешь и позвать его вручную — по имени. За счёт изоляции контекста разведка на 50 файлов не съедает основной чат: субагент прочитает их у себя и вернёт сжатую выжимку.

Про то, когда делегировать разведку субагентам и сколько это экономит токенов, у меня есть отдельный разбор — как эффективно использовать Claude Code. Здесь — про то, как собрать своего.

Чем субагент отличается от навыка и слэш-команды?

Коротко: субагент работает в отдельном контексте и может бежать параллельно, навык (skill) — это текст-инструкция, которая вставляется в основной чат, а слэш-команда — быстрый разовый вызов действия. Субагента берут под большую задачу с изоляцией, навык — под переиспользуемый набор правил, команду — под конкретное действие.

Вопрос	Субагент	Навык (skill)	Слэш-команда
Свой изолированный контекст?	Да	Нет	Нет
Свой набор инструментов?	Да (tools: Read, Grep, Glob, Bash)	Нет	Нет
Своя модель?	Опционально (model: sonnet, по умолчанию наследует)	Нет	Нет
Как вызывается?	Claude сам по description или вручную по имени	По /имени или текстом	Вручную через /
Где хранится?	.claude/agents/*.md	.claude/skills/	.claude/commands/*.md
Когда выбирать?	Тяжёлая изолированная задача	Переиспользуемая инструкция	Частый ручной триггер

Где хранятся субагенты: проектные и глобальные

Субагенты живут в двух местах: .claude/agents/ в корне проекта (доступны только в нём) и ~/.claude/agents/ в домашней папке (доступны во всех проектах). Если в обоих лежит файл с одним name, проектный побеждает глобального — это удобно, чтобы переопределить общий субагент под конкретный репозиторий.

• Проектные — .claude/agents/. Кладёшь в git, вся команда получает тех же субагентов.
• Глобальные — ~/.claude/agents/. Твои личные, для любого проекта на этой машине.

Оба каталога сканируются рекурсивно, так что можно раскладывать по подпапкам (agents/review/, agents/research/) — на распознавание это не влияет, важен только name в заголовке.

Как создать субагента: два способа

Способов два: интерактивно через команду /agents или руками — положить markdown-файл в папку agents. Команда удобнее для старта, файл руками — когда уже понимаешь формат и хочешь версионировать в git.

Способ 1. Команда /agents

Набери /agents в Claude Code → Create new agent → выбери область (Personal = глобальный, Project = проектный). Дальше можно описать субагента словами и нажать Generate with Claude — он сам составит инструкцию, а ты выберешь инструменты, модель и цвет. Созданный через UI субагент доступен сразу, без перезапуска сессии.

Способ 2. Файл руками

Создай файл вида ~/.claude/agents/code-reviewer.md. Внутри — YAML-заголовок между --- и текст-инструкция под ним:

---
name: code-reviewer
description: Ревьюит код на качество и безопасность. Use proactively сразу после правок кода.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Ты — старший ревьюер. Когда тебя зовут:
1. Запусти git diff и посмотри свежие изменения.
2. Пройди по изменённым файлам.
3. Выдай замечания по приоритету: критичные / предупреждения / советы.

Если добавляешь файл вручную — перезапусти сессию, чтобы Claude его подхватил.

Поля заголовка

Поле	Обязательно	Что делает
name	да	Имя субагента (строчные буквы, дефисы). По нему зовёшь вручную.
description	да	По этой фразе Claude решает, когда делегировать. Слова «use proactively» → зовёт сам, без явного указания.
tools	нет	Список разрешённых инструментов. Если не указан — наследуются все. Ограничиваешь — режешь риск (ревьюеру не нужен Edit).
model	нет	sonnet, opus, haiku или inherit. Дешёвую модель — на разведку, сильную — на анализ.

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

Это не выдуманные примеры — оба файла лежат у меня в ~/.claude/agents/ и работают на этом сайте. Первый, security-auditor, я зову перед каждым деплоем: он read-only (нет Edit/Write), поэтому ничего не сломает, только доложит.

---
name: security-auditor
description: Аудит проекта на риски перед деплоем. Use proactively перед kamal deploy,
  push в публичный репо или когда упоминаю деплой/выкатываем. Ищет утечки секретов,
  опасные паттерны, дыры в .gitignore, открытые admin-роуты.
tools: Read, Grep, Glob, Bash
model: sonnet
---

Проактивный аудитор. Проверяю перед деплоем:
- секреты в репо (.env, ключи, id_rsa) — должно быть пусто;
- .gitignore покрывает секреты и дампы;
- опасные паттерны (eval, system с интерполяцией, SQL без параметров);
- открытые admin-роуты без авторизации.

Обрати внимание на две вещи. Первая — tools: Read, Grep, Glob, Bash без Edit и Write: аудитор физически не может изменить код, только прочитать. Вторая — фраза «Use proactively перед kamal deploy» в описании: как только я пишу «выкатываем», Claude зовёт его сам.

Второй — research-synthesizer. Он собирает 5+ источников и возвращает в чат только выжимку, а простыни текста пишет в файл. Ему, в отличие от аудитора, разрешены веб-инструменты:

---
name: research-synthesizer
description: Синтез из множества источников в структурированное саммари с датами.
  Use proactively при сборе конкурентной разведки, GEO/SEO-ресёрче, сборе перед статьёй.
tools: Read, Grep, Glob, WebSearch, WebFetch, Write, Bash
model: sonnet
---

Собираю 5+ источников → дистиллят. В чат возвращаю только TL;DR + путь к файлу.
Каждое утверждение — с источником и датой. Claim vs verified разделяю.

Разница в одном поле tools задаёт два разных инструмента из одного механизма: один ничего не трогает, второй ходит в веб и пишет файлы. Модель у обоих sonnet — баланс цены и качества для их задач; на чистую разведку по файлам можно поставить haiku и платить меньше.

Когда субагент помогает, а когда мешает

Субагент выигрывает там, где задача объёмная и её результат сжимается: разведка по коду, чтение документации, аудит, ревью, сбор источников. Мешает — там, где нужен частый диалог: итеративная правка фичи, обсуждение архитектуры, рефакторинг связанных файлов. Субагент стартует с чистого листа и не видит историю чата, поэтому «пойми, что мы тут обсуждали» ему не поставишь.

3 ошибки при создании субагентов

Ошибка 1. Не ограничить tools

Без поля tools субагент наследует все инструменты, включая Edit, Write и Bash. Ревьюер или аудитор, который «случайно» может переписать файл — это риск. Режь набор до минимума под задачу.

Ошибка 2. Размытый description

Claude выбирает субагента по описанию. «Помогает с кодом» не сработает — он не поймёт, когда звать. Пиши конкретно: что делает, при каком триггере, и добавляй «use proactively», если хочешь автоделегирование.

Ошибка 3. Ждать, что субагент помнит контекст

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

Источники

1. Claude Code — Subagents (официальная документация)
2. Claude Code — Settings
3. Claude Code — Common workflows
4. Claude Code — Slash commands (/agents)
5. Anthropic — Building Effective Agents
6. Anthropic — Claude Code Best Practices