Кастомний субагент: устрій

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 і межі поведінки в 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/, і колеги про нього не дізнаються. Область видимості плюс місце в репозиторії — ось що перетворює вдалу заготовку на інструмент, який живе й оновлюється нарівні з рештою файлів проєкту.