Модуль 1 · Субагенты · урок 2 из 4

Создаём субагента

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

Файл субагента

Субагент — это один markdown-файл. В начале — шапка в формате YAML между двумя строками ---, дальше — обычный текст, который становится системной инструкцией субагента. Вот минимальный рабочий пример:

markdown

---
name: a11y-checker
description: Проверяет вёрстку на доступность (WCAG). Use proactively после изменений в компонентах интерфейса.
tools: Read, Grep, Glob
model: sonnet
---

Ты — специалист по доступности веб-интерфейсов. Тебе передают
файлы или директорию с вёрсткой. Проверь:

- у всех изображений есть осмысленный alt;
- интерактивные элементы доступны с клавиатуры;
- у полей форм есть подписи (label или aria-label);
- контраст текста и фона не ниже 4.5:1;
- заголовки идут по порядку без пропусков уровней.

Ничего не исправляй. Верни отчёт: список найденных проблем
с путём к файлу, номером строки и рекомендацией.

Имя файла обычно совпадает с name: .claude/agents/a11y-checker.md. Тело файла — то, что субагент прочитает как свою системную инструкцию. Он получит её плюс базовые сведения об окружении (рабочую директорию), а не полный системный промпт Claude Code.

Поля шапки

Обязательных полей два: name и description. Остальные — по необходимости. Ниже — те, что вам понадобятся чаще всего; полный список есть в документации.

Поле	Что делает
`name`	Уникальный идентификатор: строчные буквы, дефисы допускаются, двоеточия — нет.
`description`	Когда Claude должен передать задачу этому субагенту. По этому тексту Claude решает сам. Фраза «use proactively» подталкивает делегировать без явной просьбы.
`tools`	Список разрешённых инструментов. Если не указан — субагент наследует все доступные.
`disallowedTools`	Список запрещённых: субагент получает всё, кроме перечисленного. Например, `Write, Edit` делает его read-only.
`model`	Модель: `sonnet`, `opus`, `haiku`, полный идентификатор или `inherit`. Если не указана — модель основного разговора.
`permissionMode`	Режим разрешений: `default`, `acceptEdits`, `plan` (только чтение), `dontAsk`, `bypassPermissions`.
`skills`	Навыки, которые загрузятся в контекст субагента целиком при старте.
`memory`	Постоянная память субагента между сессиями: `user`, `project` или `local`.
`maxTurns`	Ограничение на число шагов; при достижении результат помечается как частичный.

Ещё есть hooks (хуки, работающие только пока субагент активен), mcpServers (MCP-серверы, подключаемые только для этого субагента), background, effort, isolation: worktree (работа в отдельной копии репозитория), color (цвет в интерфейсе). Начинать с них не нужно.

Обратите внимание на tools. Для ревьюера, аналитика, проверяющего достаточно Read, Grep, Glob. Так субагент точно ничего не изменит, даже если ему покажется, что «проще починить». Если нужен запуск команд — добавьте Bash. MCP-серверы указываются по шаблону mcp__имя-сервера.

Два способа создать

Попросить Claude. Это способ, который рекомендует документация. Формулируете, что должен делать субагент, и Claude пишет файл:

text

Создай проектного субагента a11y-checker в .claude/agents/, который
проверяет вёрстку на доступность по WCAG: alt у картинок, подписи
у полей, клавиатурная навигация, контраст. Только чтение,
ничего не исправляет, возвращает список проблем с путями и строками.
Модель — sonnet.

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

Написать руками. Создайте файл .claude/agents/<имя>.md в редакторе. Формат простой, и для правок существующего субагента это часто быстрее.

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

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

Для автоматизации есть третий путь — флаг --agents при запуске с JSON-описанием субагентов прямо в командной строке. Он для скриптов и CI, не для повседневной работы.

Где лежит и что важнее

Одно и то же имя может встретиться в нескольких местах. Порядок приоритета от высшего к низшему:

Управляемые настройки организации.
Флаг --agents в командной строке.
.claude/agents/ — проектные, попадают в git.
~/.claude/agents/ — личные, работают во всех проектах.
agents/ внутри плагина.

Для командных субагентов правильное место — .claude/agents/ в репозитории проекта. Так их получают все, кто клонирует проект, а изменения проходят через код-ревью. Личные эксперименты держите в ~/.claude/agents/. Папки сканируются рекурсивно, поэтому можно раскладывать по подпапкам: agents/review/a11y-checker.md, agents/research/competitors.md.

Как вызвать

Есть три способа, от мягкого к жёсткому.

Автоматически. Claude сам решает делегировать, сопоставляя вашу просьбу с description субагентов. Если в описании стоит «use proactively после изменений в компонентах интерфейса», то после правки компонента Claude с большой вероятностью запустит проверку сам.

Просьбой. «Используй субагента a11y-checker для директории src/components/forms». Это подсказка, и Claude ей обычно следует.

Упоминанием через @. Наберите @, выберите субагента из списка — в чате это выглядит как @"a11y-checker (agent)". Это гарантированный вызов. Субагенты из плагинов показываются с префиксом плагина.

Есть и четвёртый вариант: запустить Claude Code с флагом --agent a11y-checker или указать "agent": "a11y-checker" в .claude/settings.json. Тогда субагент становится основным для всей сессии: его инструкция, инструменты и модель применяются к главному разговору. Это уже не делегирование, а смена «личности» Claude Code.

Проверяем, что получилось

После создания файла спросите: «Какие субагенты тебе доступны?» — новый должен быть в списке. Можно выполнить /context и посмотреть раздел Custom Agents.

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

Попробуйте сами

10–15 мин на рабочем месте

Создайте в рабочем проекте субагента a11y-checker из этого урока (попросите Claude или скопируйте файл). Убедитесь, что он появился в списке доступных.
Запустите его через @-упоминание на одной директории с компонентами. Оцените отчёт: есть ли пути и номера строк, нет ли лишних рассуждений.
Замените tools: Read, Grep, Glob на disallowedTools: Write, Edit и проверьте, изменилось ли поведение. Подумайте, какой вариант понятнее коллегам, которые откроют файл через полгода.

Коротко

Субагент — markdown-файл: YAML-шапка плюс текст, который становится системной инструкцией.
Обязательные поля — name и description; tools, model, permissionMode, memory — по необходимости.
Создавать проще всего, попросив Claude; /agents теперь только напоминает об этом.
Проектные субагенты — в .claude/agents/ (в git), личные — в ~/.claude/agents/.
Изменения подхватываются за секунды без перезапуска.
Вызов: автоматически по description, просьбой в тексте или гарантированно через @.

Видеоверсия

Сценарий озвучки · 482 слова, ≈ 4 мин

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

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

Обязательных полей в шапке два. Первое — имя: строчными буквами, можно с дефисами. Второе — описание. Описание читает не сам субагент, а основной Claude: по нему он решает, когда передать задачу этому помощнику. Если написать в описании фразу «use proactively» и указать, после чего запускать, Claude будет делегировать сам, без вашей просьбы.

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

Как создать файл? Самый простой способ — попросить Claude. Например: «Создай проектного субагента, который проверяет вёрстку на доступность: подписи у полей, alt у картинок, контраст. Только чтение, возвращает список проблем с путями и номерами строк». Claude напишет файл, вам останется прочитать и поправить. Второй способ — написать руками в редакторе, формат простой.

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

Где файл должен лежать? Проектные субагенты — в папке точка-клод, агентс внутри проекта. Они попадают в git, и их получают все, кто клонирует репозиторий. Личные — в такой же папке в домашней директории, они работают во всех ваших проектах. Ещё субагенты приходят с плагинами. Если имена совпадают, проектный важнее личного, а личный важнее плагинного. Изменения Claude Code подхватывает за секунды, перезапускать ничего не нужно.

Теперь — как вызвать. Три способа. Первый — автоматический: Claude сам сопоставляет вашу просьбу с описаниями субагентов. Второй — попросить словами: «используй субагента для проверки доступности в папке с формами». Третий — гарантированный: набрать собаку и выбрать субагента из списка. Тогда он точно запустится.

Есть и четвёртый вариант, но это уже не делегирование. Если запустить Claude Code с флагом «агент» и именем, субагент станет основным на всю сессию: его инструкция, инструменты и модель применятся к главному разговору. Это способ сменить «личность» Claude Code, например, на время ревью, а не поручить ему часть работы.

И последнее — проверка. Спросите Claude: «какие субагенты тебе доступны?» Новый должен быть в списке. Потом прогоните его на задаче, ответ которой вы знаете: возьмите компонент, где заведомо нет alt у картинки. Если субагент нашёл проблему и вернул путь с номером строки — работает. Если вернул общие рассуждения — правьте инструкцию. Как писать инструкцию так, чтобы отчёт был полезным, — тема следующего урока.

Отметка хранится только в вашем браузере