Свой подагент, ограничение инструментов и выбор модели — Claude Code: с нуля до уверенной работы

Встроенные подагенты покрывают базовые сценарии, но не ваши. У каждой команды есть задачи, которые повторяются: проверить миграции перед деплоем, пройтись по диффу с чек-листом, разобрать логи по знакомому формату. Каждый раз объяснять это заново — потеря времени и источник расхождений: сегодня вы попросили одно, завтра сформулировали иначе, результат отличается.

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

Что уже умеем / что добавим

В прошлом уроке вы разобрались с изоляцией контекста и научились пользоваться встроенными Explore, Plan и general-purpose. Вы знаете, что подагент стартует с чистым контекстом и возвращает только сводку.

Теперь мы перейдём к собственным подагентам: разберём, где живут их файлы, какие поля бывают во frontmatter, как устроены allowlist и denylist инструментов и как выбор модели влияет на скорость и стоимость.

Что вы узнаете в рамках статьи

Где лежат файлы подагентов и какой из них выигрывает при совпадении имён
Какие поля frontmatter обязательны, а какие настраивают поведение
Как ограничить набор инструментов через tools и disallowedTools
Как выбрать модель через model и зачем нужен inherit
Как передать подагенту скилл через поле skills

Ключевые термины

Файл подагента — markdown-файл с YAML-frontmatter: в шапке настройки, в теле системный промпт агента.
Frontmatter — блок YAML между строками --- в начале файла, задающий конфигурацию подагента.
Scope (область видимости) — уровень, на котором определён подагент: проект, пользователь, сессия или плагин; от него зависит приоритет при совпадении имён.
allowlist инструментов — поле tools: явный список того, что подагенту разрешено; всё остальное недоступно.
denylist инструментов — поле disallowedTools: список того, что вычитается из унаследованного набора.
Горячая перезагрузка — Claude Code следит за каталогами агентов, и правки применяются в течение секунд без перезапуска.

Где живут подагенты и кто выигрывает

Подагент — это markdown-файл. Основных мест два:

.claude/agents/ в проекте — доступен всем, кто работает с этим репозиторием, и коммитится вместе с кодом;
~/.claude/agents/ — ваши личные агенты, доступные во всех проектах.

Оба каталога сканируются рекурсивно, так что вы можете разложить агентов по подпапкам вроде agents/review/. На идентичность агента подпапка не влияет: имя берётся исключительно из поля name во frontmatter, а имя файла может быть любым.

Если два агента объявляют одно и то же name, приоритет такой: сначала управляемые настройки организации, затем сессионные агенты из флага --agents, затем .claude/agents/ проекта, затем ~/.claude/agents/ и в последнюю очередь агенты из плагинов. Проще говоря, проектный агент перекрывает ваш личный — команда может задать общий стандарт.

Важная деталь про интерфейс: начиная с версии 2.1.198 команда /agents больше не открывает мастер создания. Она лишь печатает напоминание о том, где лежат файлы. Создавать агента нужно вручную или попросить об этом Claude.

Минимальный файл подагента

Обязательных полей всего два: name и description. Всё остальное опционально.

---
name: migration-checker
description: Проверяет файлы миграций базы данных на обратимость и опасные операции
tools: Read, Glob, Grep
model: sonnet
---

Вы проверяете миграции базы данных. Для каждого файла миграции:

1. Проверьте, что есть обратная операция (down/rollback).
2. Найдите операции, блокирующие таблицу на запись.
3. Отметьте удаление колонок и таблиц как требующее ручного подтверждения.

Верните список найденных проблем с путями к файлам. Код не изменяйте.

Поле name пишется строчными буквами через дефис. Оно не может содержать двоеточие (оно зарезервировано за плагинами) и не может начинаться с дефиса — такой файл просто не загрузится.

Поле description — это то, по чему Claude решает, когда делегировать задачу этому агенту. Пишите его как ответ на вопрос «в каких случаях звать этого агента». Держите описание коротким: если суммарный объём всех описаний превысит 15 000 токенов, вы получите предупреждение при старте.

Тело файла после frontmatter — системный промпт агента. Это его единственная постоянная инструкция.

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

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

Это главная причина заводить своего подагента. Есть два поля.

Поле tools — белый список. Указали — доступно только перечисленное:

---
name: log-analyst
description: Разбирает файлы логов и находит закономерности в ошибках
tools: Read, Grep, Glob, Bash
---

Если поле опущено, агент наследует все инструменты, доступные подагентам.

Поле disallowedTools — чёрный список, он вычитается из унаследованного набора:

---
name: safe-auditor
description: Аудит кода без права вносить изменения в файлы проекта
disallowedTools: Write, Edit
---

Порядок обработки такой: сначала применяется disallowedTools, потом tools разрешается из остатка. Инструмент, попавший в оба поля, будет удалён.

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

Выбор модели и другие поля

Поле model принимает sonnet, opus, haiku, fable, полный идентификатор модели или значение inherit. Последнее означает «использовать модель главной беседы».

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

---
name: todo-collector
description: Собирает по проекту все комментарии TODO и FIXME в единый список
tools: Grep, Glob, Read
model: haiku
---

Несколько других полезных полей, подтверждённых документацией:

permissionMode — режим разрешений для агента: default, acceptEdits, auto, dontAsk, bypassPermissions, plan, manual;
maxTurns — предел числа шагов агента; результат вернётся помеченным как частичный;
skills — список скиллов, чьё полное содержимое подгружается в контекст агента при старте;
color — цвет строки агента в списке задач: red, blue, green, yellow, purple, orange, pink, cyan;
effort — уровень усилий: low, medium, high, xhigh, max;
memory — постоянная память агента между сессиями: user, project или local.

Есть также поля hooks и mcpServers — они относятся к темам следующих глав, пока достаточно знать, что такая возможность существует.

Особенно полезно поле skills. Вы уже умеете писать скиллы; теперь их можно подключать к агенту как справочный материал:

---
name: api-developer
description: Реализует эндпоинты API по принятым в команде соглашениям
skills:
  - api-conventions
  - error-handling-patterns
---

Важно, что подгружается именно полное содержимое скилла, а не только его описание.

Частые ошибки

Ожидать, что /agents откроет мастер создания. Начиная с версии 2.1.198 команда лишь печатает подсказку с путями. Создавайте файл руками или попросите Claude.
Двоеточие или ведущий дефис в поле name. Такой файл молча не загрузится. Запускайте Claude Code с флагом -debug, чтобы увидеть причину пропуска.
Расплывчатое description. Claude выбирает агента именно по описанию. «Помогает с кодом» не даст ему повода делегировать задачу вам нужному агенту.
Опечатка в tools. Если ни одна запись не распознана, агент не запустится и выдаст ошибку с перечислением непонятых записей.

Наиболее частые вопросы

Обязательно ли имя файла совпадает с полем name? — Нет, идентичность агента определяет только name. Но одинаковые имена удобнее для поиска.
Что будет, если одинаковое name есть и в проекте, и в ~/.claude/agents/? — Победит проектный: .claude/agents/ имеет более высокий приоритет.
Нужно ли перезапускать Claude Code после правки файла агента? — Обычно нет, изменения применяются за несколько секунд. Перезапуск нужен, если каталога agents не существовало на момент старта сессии.
Чем tools отличается от disallowedTools? — Первое задаёт белый список, второе вычитает инструменты из унаследованного набора. Сначала применяется denylist.
Можно ли поставить подагенту модель дешевле, чем в главной беседе? — Да, через поле model. Это один из способов снизить стоимость механических задач.

Итоги

Поздравляем — вы прошли путь от использования готовых подагентов до создания собственных. Теперь вы знаете, что подагент это всего лишь markdown-файл с двумя обязательными полями, понимаете разницу между tools и disallowedTools, умеете выбирать модель под характер задачи и подключать к агенту уже написанные скиллы.

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