Кастомный subagent: устройство

1. Свой агент команды vs встроенные

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

Встроенные агенты хороши там, где задача общая: поиск по коду, исследование файлов, планирование, сбор сведений. Но как только в команде начинает повторяться один и тот же рабочий ритуал, встроенного поведения уже не хватает. Вам нужно не просто «проверить код», а предсказуемо: смотреть готовый diff, не трогать файлы руками, возвращать замечания в одном формате и не превращать ревью во внезапный ремонт всего проекта.

Именно в этот момент и появляется смысл в custom subagent. Представьте ваш Workflow Kit: у вас там уже живут переиспользуемые артефакты — правила, skills, заготовки. Рядом с ними встаёт ещё один слой — агент, который делает повторяемую работу по правилам команды. Например, reviewer для Commerce OS. Готов diff по багу с возвратами или сортировкой заявок — и вы не хотите заново писать длинное «посмотри только изменённые файлы, не правь код, дай замечания по рискам и пропущенным тестам». Оформите это один раз как артефакт — и вместо личной шпаргалки получите часть рабочего набора команды: агент виден всем, попадает в Git, меняется через diff и ревьюится как любой инженерный файл.

У Workflow Kit это может выглядеть очень приземлённо:

workflow-kit/
  .claude/
    skills/
      issue-analysis/
    agents/
      reviewer.md

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

2. Область видимости агента

Перед созданием агента важно понять не «что он делает», а «где он вообще живёт». Звучит скучновато, но на практике это избавляет от классической ситуации: reviewer готов, всё работает — а коллега открывает репозиторий и ничего не видит. Агент остался у вас в личной папке и в командный проект так и не переехал.

У кастомного агента есть область видимости — проще говоря, место, где хранится его файл и откуда он становится доступен. Точные пути и названия в интерфейсе могут чуть отличаться от версии к версии, но сама логика стабильна:

personal

~/.claude/agents/

project

.claude/agents/

plugin-provided

managed

Здесь символ ~ означает домашнюю папку пользователя. Если говорить без Unix-магии и без попытки выглядеть серьёзнее, чем нужно: personal — это ваш личный ящик стола, а project — шкафчик на кухне команды. Личный ящик — только для вас; проектный шкафчик увидят все, кто клонирует репозиторий.

plugin-provided полезен, когда вы не храните агента прямо в репозитории, а приносите его через plugin, — удобно для нескольких проектов. managed — это история для компаний, где часть поведения задаётся централизованно; знать о нём полезно, чтобы не удивляться, когда в корпоративной среде «вдруг появился» агент, которого вы не создавали.

Для нашего Workflow Kit ключевой вариант — именно project. Почему? Потому что файл agents/reviewer.md — не приватная игрушка, а общекомандный артефакт: он должен одинаково работать у всех, кто ведёт изменения в Commerce OS. Положите reviewer в personal — заработает, но только у вас. Эгоистичная настройка, частью общей инженерной системы такой агент не станет.

3. Четыре поля стартового агента

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

Эти четыре поля удобно воспринимать не как «набор настроек», а как минимальную инженерную конструкцию: убери любое поле — что-то поедет. Агент либо не вызывается, либо вызывается не туда, либо делает лишнее.

name

description

tools

instruction body

Минимальный каркас файла может выглядеть так:

---
name: reviewer
description: Проверяет готовый diff и возвращает замечания без правки кода.
tools:
  - read
  - search
---

Проверь изменённые файлы и верни краткие замечания по найденным проблемам.

Это стартовая заготовка: четыре поля есть, но рабочего контракта пока нет — не зафиксированы findings, stop conditions и границы поведения in review. Как каркас для создания агента и первого сохранения в репозиторий — годится.

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

Есть и ещё один полезный момент для начинающих. instruction body — не особый бинарный формат и не «внутренний код агента», а обычный текст в markdown-файле под блоком frontmatter. Когда вы видите это глазами, половина мистики уходит сама собой: перед вами не чёрный ящик, а файл, который можно открыть в IDE и закоммитить.

4. description: решающее поле

Здесь у многих возникает естественная ошибка: кажется, что главное в агенте — «умная» инструкция внизу файла. На практике первое критическое поле почти всегда description. Это не подпись для красоты, а правило выбора: решая, делегировать ли задачу custom subagent, Claude смотрит именно на описанную вами область применения. Расплывчатое описание — плохая маршрутизация.

Сравните два варианта:

description: Reviewer для всего.

description: Read-only reviewer для готового diff. Использовать после того, как изменения собраны и нужен второй взгляд перед merge.

Во втором случае описание отвечает сразу на несколько скрытых вопросов. Кто это? Reviewer. Когда использовать? Когда diff готов. В каком режиме? Read-only. У Claude появляется не имя роли, а понятный триггер для делегирования.

Хорошее description почти всегда даёт три опоры: что агент делает, в какой момент workflow он нужен и где проходит его граница. Слишком широко — агент липнет ко всем похожим задачам подряд; слишком узко и странно — может вообще никогда не сработать. В этом смысле description напоминает папку «разное»: технически она есть, но никто не понимает, что туда класть.

Для нашего reviewer в Workflow Kit рабочий вариант — указать: проверяет готовый diff, не редактирует код, нужен перед merge или локальным принятием изменений. Этого уже достаточно, чтобы агент был инструментом, а не «чем-то про review».

5. tools: граница полномочий

Когда дело доходит до инструментов, у начинающих появляется любимая мысль: «Дам всё, а там он сам разберётся». Это очень человеческое желание, и для качества оно опасно. Агент с лишними tools не становится умнее — он получает больше способов сделать что-то неожиданное. А неожиданности в автоматизации приходят не с тортом, а с лишним diff на пол-репозитория.

Для первого reviewer логика почти всегда простая. Задача — читать изменения и возвращать замечания, значит, права на редактирование, широкий доступ к командам и режим «вдруг сам поправит» не нужны. Reviewer хорош тем, что смотрит и докладывает, а не хватает отвёртку и не начинает чинить мебель в соседней комнате.

Сравните слишком широкий и нормальный стартовый вариант:

tools:
  - read
  - search
  - edit
  - bash

tools:
  - read
  - search

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

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

Практически это значит следующее: сначала выдавайте минимум, потом смотрите, реально ли его не хватает. Упрётся reviewer в нехватку ещё одного read-only способа собрать доказательства — расширяете набор осознанно. Стартовать с «пусть умеет всё» — как выдавать стажёру ключи от склада, серверной и запасного выхода, потому что вдруг пригодится. Обычно пригождается только нервному тимлиду.

6. Создание agents/reviewer.md через /agents

После всей теории приятно дойти до самой приземлённой части. Агент создаётся не ритуалом при полной луне, а через интерфейс управления агентами — обычно команду /agents или близкую панель. Называется чуть иначе — сверьтесь с актуальным /help: важен сам workflow, а не совпадение букв.

flowchart TD
    A["/agents"] --> B["выбор scope"]
    B --> C["4 поля: name, description, tools, body"]
    C --> D["сохранение"]
    D --> E["файл в .claude/agents/"]
    E --> F["проверка через Git diff"]

Та же карта по-земному:

/agents

project

Содержательно после сохранения появится тот самый каркас из четырёх полей. Не путайте его с контрактом reviewer-а: здесь мы просто фиксируем агента в проекте и делаем его видимым в Git, а не вкладываем весь процесс review.

После сохранения, если вы выбрали project, файл обычно оказывается в репозитории примерно здесь:

.claude/
  agents/
    reviewer.md

И вот это очень важный момент. Если файл оказался в проекте, вы сразу видите его в IDE и в Git diff: можно прочитать, поправить, переименовать, обсудить в PR. Создали случайно в личной области — Git промолчит, и команда даже не узнает про полезного помощника. Это, кстати, один из лучших способов проверить, что вы всё сделали правильно: агент должен быть не только «виден в интерфейсе», но и понятен глазами как документ.

7. Агент как файл репозитория

Последняя важная привычка в этой теме связана не с созданием, а с отношением к результату. Очень легко настроить агента, порадоваться пять минут и забыть про него как про бытовую магию IDE. Но если reviewer полезен проекту, он должен читаться, обсуждаться, меняться и проходить через Git наравне с инженерными файлами.

Это особенно заметно в Workflow Kit. Через пару недель в Commerce OS меняются правила, появляются новые каталоги, вы иначе называете зоны риска, уточняете стиль ревью. Агент в репозитории — меняете description или инструкцию, смотрите diff, коммитите. Агент «где-то локально» — команда живёт со старой версией, вы с новой, и начинается редкий жанр инженерной боли, когда поведение одного и того же инструмента почему-то различается у разных людей.

Хороший финальный жест прозаичен: сделайте git status после сохранения. Файл agents/reviewer.md виден в diff, лежит в project-области, поедет к команде вместе с кодом — значит область видимости выбрана верно, и агент стал общим артефактом, а не личной настройкой в чужом интерфейсе. Промолчал Git — reviewer застрял в вашем ~/.claude/, и коллеги про него не узнают. Область видимости плюс место в репозитории — вот что превращает удачную заготовку в инструмент, который живёт и обновляется наравне с остальными файлами проекта.

1

Задача

Claude code, 11 уровень, 2 лекция

Недоступна

Создание project-scope agent через `/agents`

Создание project-scope agent через `/agents`

Открыть

1

Задача

Claude code, 11 уровень, 2 лекция

Недоступна

Создание первого project-scope reviewer-агента

Создание первого project-scope reviewer-агента

Открыть