Агенти та subagents

Сьогодні зʼявляється третій командний артефакт - агент: спеціалізований виконавець із власним вікном контексту, своїм набором інструментів і своєю інструкцією.

Сьогодні розберемо:

• що таке субагенти, навіщо вони потрібні і як читати їхні зведення;
• чим subagent відрізняється від окремої сесії, фонового завдання та agent team;
• як створити свого агента і де він має жити;
• як написати інструкцію агента як контракт, а не як персонажа;
• ролі reviewer / tester / debugger / documenter і місце агента в review-процесі.

Наскрізний приклад - agents/reviewer.md: агент-ревʼюер, якого ми зберемо, покладемо в репозиторій і проженемо на готовому diff.

Що таке субагент і навіщо він

Субагент - це спеціалізований помічник, якому Claude Code передає завдання: він робить роботу у своєму власному вікні розмови і повертає у вашу сесію коротке зведення. Уся метушня - читання файлів, пошуки, виклики інструментів - залишається в нього.

Навіщо так: усе, що відбувається в сесії, накопичується в основному вікні контексту, а вікно скінченне. Заповнилося - Claude починає губити нитку розмови. ви це вже бачили, коли працювали з /context та /compact.

На старті субагент отримує два головні входи:

• system prompt із вашого файлу конфігурації - роль і правила поведінки;
• опис завдання, який головна сесія пише за вашим запитом.

На схемі важливе одне: далі субагент працює сам, а в основну сесію його чорнова робота не потрапляє - повертається лише зведення. Є і чесний tradeoff: ви не бачите, як він дійшов висновку, - тому зведення перевіряють, а не приймають на віру.

15 файлів заради одного факту

Уявіть: ви в незнайомому проєкті і хочете дізнатися, який сервіс обробляє refunds. Потрібен один факт.

• без субагента: Claude читає 15 файлів, ганяє кілька пошуків, трейсить ланцюжки викликів - і все це осідає у вашому вікні заради однієї відповіді;
• із субагентом: Explore робить ту саму роботу у своєму вікні, а у вас залишаються два рядки - питання і зведення.

Без субагента: 15 файлів + пошуки + трейс викликів -> усе у вашому вікні
Із субагентом:  питання -> зведення. Решта залишилася в Explore

Делегування не робить відповідь вірнішою - воно робить дослідження ізольованим і дешевим для вашого контексту. Відповідь та сама, рахунок за неї - інший.

Є й побічний бонус: субагент стартує з чистим контекстом, без багажу припущень, що накопичилися в основній сесії, - і часом копає туди, куди основна сесія вже не дивиться. А якщо два агенти перевірили одну гіпотезу і розійшлися - це не помилка, а сигнал: питання неоднозначне або в коді справді два шляхи. Як розбирати такі розбіжності - на наступному вебінарі.

Вбудовані субагенти

Частина субагентів уже вбудована в Claude Code - він обирає їх сам, за змістом завдання і description:

• Explore - read-only розвідка по коду: "покажи, де це лежить";
• Plan - research у plan mode: збирає матеріал для плану до будь-яких правок;
• general-purpose - багатокрокові підзавдання, де треба і шукати, і діяти.

А коли потрібна роль під ваш workflow - reviewer, test writer, генератор документації - субагента створюють свого. Цим займемося у другій половині вебінару.

Зведення - результат, який перевіряють

Зведення - єдине, що потрапляє у вашу сесію з роботи субагента. Тож увесь контроль якості відбувається тут - на тому, що він повернув.

Просимо дослідити баг із порядком refund-запитів - і дивимося, що повернеться. Зверніть увагу: цей запит адресований не субагенту, а звичайному Claude Code. Напряму задачі субагентам не ставлять - головна сесія сама вирішує, кому делегувати і що передати:

Досліди, де задається порядок refund-запитів в inbox.
Нічого не змінюй. Поверни:
1) ключові файли,
2) повʼязані тести,
3) що залишилося неперевіреним.

Зведення:
- src/support/refundInbox.ts:42 - сортування за createdAt ASC
- src/api/refundRoutes.ts:18 - endpoint /api/refunds/inbox кличе listInbox
- tests/refundInbox.test.ts:55 - тест фіксує порядок ASC
- Не перевірено: чи сортує таблиця на фронтенді повторно

Це сильне зведення: файли і рядки можна відкрити й перевірити, і є чесний блок "не перевірено". Слабке має інший вигляд - "схоже, проблема в support-модулі": настрій замість доказів.

Слабке зведення не оплакуємо, а дотискаємо формат: "для кожного висновку вкажи файл і рядок, гіпотези познач окремо". У житті сліди перевіряють вибірково - відкрити один-два ключові файли вже достатньо, щоб зрозуміти, чи можна зведенню вірити.

Коли делегувати, а коли самому

Після перших вдалих зведень хочеться делегувати взагалі все, аж до пошуку одного рядка. Вчасно пригальмуйте. "Самому" тут - це два варіанти, а не один: відкрити файл руками або поставити питання звичайному Claude Code в основній сесії, без субагентів. Ось простий орієнтир:

Питання-розвилка насправді одне: чи захаращить розслідування основну розмову? Так - ізоляція окупається. Ні - субагент зайвий прошарок: вистачить короткого питання, це інструмент, а не ритуал на кожен запит.

І не чекайте автоматики, якщо знаєте, чого хочете: делегувати можна явно - "винеси перевірку проти специфікації в субагента", "підсумуй цей модуль субагентом".

Два випадки, де субагент радше нашкодить:

• конвеєр reproduce -> debug -> fix - кроки залежать від знахідок одне одного, на стиках губиться інформація; такі завдання тримайте в основній сесії;
• прогін тестів заради результату - субагент поверне "tests failed" без повного виводу, який потрібен вам для дебагу.

Одне слово - пʼять механізмів

"Запусти ще одного агента" - цю фразу ви тепер будете чути постійно. Проблема в тому, що за словом agent ховаються зовсім різні речі, і в розмові їх плутають.

Розкласти будь-яку з них допомагають три питання - вони ж колонки цієї карти:

• де живе контекст?
• чи повертається результат сам?
• чи потрібна окрема файлова поверхня?

Робочий варіант за замовчуванням - subagent. Решта слів потрібні, щоб не сплутати його із сусідніми режимами. Одну відмінність варто запамʼятати одразу: субагент лише звітує нагору, у головну сесію, і з іншими субагентами не розмовляє - а в agent team кілька агентів ведуть спільний список завдань і листуються напряму одне з одним. Детально agent team розберемо на рівні 15, зараз його пропускаємо.

З чого складається субагент

Skill був рецептом, який ви записали. Plugin - коробкою з рецептами для команди. Агент у цьому ряду - найнятий спеціаліст. Досі ви працювали із вбудованими - тими, кого Claude Code дає з коробки. Суть будь-якого субагента вміщується в один рядок:

subagent = role + isolated context + tools + output contract

Читайте її як трудовий договір нового колеги:

• role - посада: ревʼюер, дослідник, документатор;
• isolated context - власний робочий стіл, щоб не шуміти у вас;
• tools - видані ключі: читати, шукати - або нічого зайвого;
• output contract - форма звіту: зведення, findings, відкриті питання.

Сила субагента - у спеціалізації та ізоляції, не в автономності. А далі ця формула стане файлом: role - у тіло інструкції, tools - у поле tools, output contract - у формат результату. Ідемо наймати свого.

Створюємо свого субагента

Claude Code іде зі вбудованими субагентами, але під свій робочий ритуал можна створити власного - спеціалізованого. reviewer перевіряє diff, тестер ганяє тести, документатор пише доки. Вбудованих вистачає для загальної роботи, а ревʼю за правилами вашої команди - це вже своя роль.

Субагент - це markdown-файл у теці .claude/agents/. Створити його можна двома шляхами:

Найкращий шлях той самий, що зі skill на вебінарі 5: описуєте словами - "read-only reviewer, перевіряє готовий diff, повертає findings" - і Claude сам згенерує name, description та інструкцію. Вам залишиться відревʼюити чернетку. Де агент житиме, вирішує тека: .claude/agents/ у репозиторії їде до команди з кодом, ~/.claude/agents/ у домашній теці - тільки ваш, у всіх проєктах.

Налаштування: інструменти та модель

При створенні ви налаштовуєте, що агенту доступно. Перше - tools: дайте лише потрібне для його роботи. В інструментів промовисті імена: Read читає файл, Glob знаходить файли за маскою, Grep шукає за вмістом, Bash запускає команди. reviewer'у потрібна ця четвірка - Bash заради git diff і безпечних read-only перевірок; а Edit і Write - право змінювати файли - йому ні до чого.

• не вказали tools - агент успадковує усі інструменти сесії;
• зайві tools не додають розуму - додають способів зробити несподіване;
• стартуйте з мінімуму, розширюйте, лише коли реально вперлися.

Як проєктувати мінімум під кожну роль - reviewer, tester, documenter - і чим ще обмежувати агента, розберемо на наступному вебінарі. Сьогодні вистачає четвірки для reviewer.

Друге - модель під завдання. Агенту можна привʼязати свою: швидку Haiku для легкого пошуку, Opus для складного аналізу або inherit - ту саму, що у вашій сесії. Це одна із сильних сторін агентів: різній роботі - різний рушій, а не один на все.

У файлі .claude/agents/reviewer.md це має вигляд frontmatter на початку документа:

---
name: reviewer
description: Read-only review готового diff перед merge
tools: Read, Glob, Grep, Bash
model: inherit
---

Файл конфігурації

Після створення агент лежить у репозиторії - .claude/agents/reviewer.md. Усередині frontmatter з полями і тіло інструкції:

---
name: reviewer
description: Read-only review готового diff перед merge
tools: Read, Glob, Grep, Bash
model: inherit
---

Перевір змінені файли і поверни короткі зауваження.

Розберемо поля - name і description знайомі по skills, працюють так само:

• name - ідентифікатор; за ним кличете агента точково: наберіть @ і виберіть зі списку, або напишіть @agent-reviewer вручну;
• description - коли Claude делегує завдання. Роль подвійна: за ним же головна сесія пише промпт для агента, тому конкретний опис дає конкретне завдання. Слово PROACTIVELY вмикає автовиклик, а приклади сценаріїв лагодять "не підхоплюється, коли має";
• tools - межі, model - рушій, тіло під frontmatter - інструкція; її розгорнемо далі.

Пишемо інструкцію агента

Першу інструкцію дуже хочеться написати в чатовому стилі: "ти досвідчений, уважний, дуже сильний reviewer". Звучить як опис супергероя. Користі - нуль. Згадайте аналогію: ви найняли спеціаліста - йому потрібна посадова інструкція, а не комплімент.

Погано:
Ти дуже досвідчений code reviewer. Думай як senior,
перевіряй глибоко й уважно, знаходь усе важливе.

Добре:
Роль: reviewer готового diff.
Коли: зміна готова до перевірки.
Можна: читати diff і тести, повернути findings з evidence.
Стоп: diff надто великий або зачеплено чутливу зону.

Різниця принципова: задасте характер - отримаєте характер; задасте межі - отримаєте результат. Поганий варіант не відповідає на жодне робоче питання: коли запускати? що повернути? де зупинитися? За контрактом же результат приймають або відхиляють без гадання.

Окремий анти-патерн - агент-"експерт": "ти Python-експерт" не додає здібностей, ці знання в Claude уже є. Цінність агента - у межах і форматі, а не у званні.

З чого складається інструкція

Щоб інструкція не розповзалася в трактат, тримайте перед очима рамку з чотирьох елементів.

Кілька спостережень із практики до цієї таблиці:

• легке "коли НЕ використовувати" цінніше за довгий список дозволів - без нього агент липне до невідповідних завдань;
• у формат одразу вшиваємо evidence: findings з file:line; гіпотези - з поміткою, про яку домовилася команда, напр. [hypothesis], - і здогад перестає видавати себе за факт;
• формат - ще й вбудований стоп: заповнив усі секції - значить готово; без формату агент не знає, коли досліджено достатньо, і бігає довше;
• стоп-умови - не слабкість агента, а його зрілість: великий diff, чутливі зони, брак доказів.

Збираємо agents/reviewer.md

Беремо каркас зі слайда "Файл конфігурації" і перетворюємо його на повний контракт:

---
name: reviewer
description: Read-only reviewer готового diff. Запускати
  для локального review перед merge, коли тести прогнані.
tools: Read, Glob, Grep, Bash
model: inherit
---

## Роль
Reviewer готового diff. Код не редагуєш.

## Коли використовувати
Є diff, зрозумілий scope, тести по можливості прогнані.
Не використовувати для написання коду й дослідження з нуля.

## Дії та формат результату
Запусти git diff, прочитай зачеплені файли і тести.
З команд - лише read-only.
Поверни: summary, findings зі severity, file:line, evidence
і suggested action, окремо open questions.
Гіпотези без доказів помічай [hypothesis].

## Умови зупинки
Diff надто великий - попроси звузити scope.
Зачеплено чутливу зону - не роби висновків без evidence.
Після findings рішення за людиною.

Уявний тест: відкрийте файл очима нового колеги. За хвилину зрозуміло, коли кликати, чого чекати і де стоп? Так - файл живий. Ні - він написаний для автора, а не для команди.

Готово - файл у project-scope, коміт, і reviewer поїде до команди разом із кодом.

Ролі: reviewer, tester, debugger, documenter

Reviewer - перший із чотирьох базових каркасів. Будь-яку роль зручно описувати за чотирма осями: що читає, що запускає, що пише, де зупиняється.

Вісь write у reviewer порожня - і це принципово: write-доступ "на випадок дрібних правок" перетворює його на тихого співавтора diff. А tester із правом змінювати логіку одного разу піджене код під зелений тест - і проблема сховається під килим. І не плутайте tester з анти-патерном тест-раннера: tester ганяє тести, працюючи над ними; виносити прогін ваших тестів заради "passed/failed" так само не варто - повний вивід потрібен вам.

І обіцяний прогін: кличемо зібраного reviewer'а на готовий diff - @agent-reviewer перевір diff останнього коміту. Хороший результат має вигляд нудний і перевірюваний:

severity: medium
file: src/payments/refundService.ts:48
evidence: статус замовлення перевіряється, роль оператора - ні
suggested_action: додати guard і тест на доступ

Три шари review: місце агента

Агент не висить у вакуумі - він вбудовується в review-процес команди. Ось навчальна карта з трьох шарів - це спосіб побачити місце агента, а не термін Claude Code:

На схемі - драбина від дешевої перевірки до дорогої. Наш reviewer живе на Layer 1: поки diff свіжий і відкат дешевий, він ловить грубі ризики до Layer 2 - CI, автоматичної перевірки коду перед публікацією - і до Layer 3, людини на чутливих рішеннях. Тести, build і логи reviewer при цьому не підміняє - він перевіряє, що вони є і стосуються завдання.

Чому окреме вікно взагалі працює: та сама модель у свіжому контексті знаходить баги, які пропустив автор - рівно як колега на ревʼю надійніше ловить ваш баг, ніж ви самі. В Anthropic це робоча практика: кожен PR - пропозиція влити гілку в основну - проходить вбудований Code Review, який ганяє кілька ревʼю-агентів паралельно.

Спеціалізації reviewer, а не зоопарк агентів

Наступна спокуса - завести окремого агента на кожен випадок життя. Не поспішайте: security, performance, test quality, architecture, DB і frontend - це фокуси одного шаблону reviewer, а не шість різних механік.

• різниця - у description і фокусі інструкції, решта збігається;
• інакше .claude/agents/ перетворюється на зоопарк файлів, що відрізняються однією фразою;
• один і той самий diff: security-фокус спитає про обхід перевірки прав, performance - про зайвий запит у циклі, test quality - де тест на повторний запит.

Спеціалізації заводять за реальним болем - після першого інциденту з доступами, а не заздалегідь заради краси. так ніхто і не робить "шість ревʼюерів на старті".

Ще й тому агент у репозиторії цінний: reviewer.md фіксує критерії ревʼю вашої команди в одному файлі - усі перевіряють за однаковими правилами, а не хто як запамʼятав.

І фінальна звичка: агент - живий артефакт. Змінюється кодова база - оновлюєте чутливі зони і правила в інструкції через звичайний PR, який Claude Code допомагає готувати і ревʼюити.

Далі - точні межі агентів: мінімум прав за інструментами, ізоляція контексту та оцінка роботи агента.

Практика: завдання і мета

Тепер ви зберете агента іншого ґатунку - агент-інструмент md2html. reviewer з лекції перевіряв чужий diff, а тут агент сам робить невеликий результат: верстає resume.md у self-contained resume.html.

Мета практики - спроєктувати субагента як конфігурований інструмент: роль, межі, параметри, дефолти й обовʼязкове рішення, яке агент здобуває запитанням. Домен верстки тут полігон; головна навичка - engineering contract для агента з вузьким write.

У готовому результаті мають бути:

• .claude/agents/md2html.md у Git;
• resume.html, який відкривається без зовнішніх CSS і JS;
• README з таблицею параметрів і логом запитання про контакти;
• 4 демо-прогони у log/.

Практика: деталі реалізації

Вхід - resume.md зі стартового репо: досвід, освіта, навички, проєкти. Агент читає один .md, пише один .html, сам resume.md не чіпає. У тілі агента потрібна специфікація параметрів - це його сигнатура.

Пресети light і dark - короткі CSS-блоки прямо в інструкції агента. Stop conditions теж пишемо явно: немає вхідного файлу - спитати; невідомий theme - відкотитися на light і попередити; після запису одного .html - стоп.

Уся різниця видна на поведінці: theme без значення мовчить і бере дефолт, а контакти без значення агент витребує. Це багата конфігурація поверх того самого контракту, що ви писали для reviewer.

Практика: як довести, що працює

Головний доказовий прогін - як агент здобуває обовʼязкове рішення. Контакти ви не передали, і агент не починає верстати, доки не спитає.

Запит: зверстай resume.md

Агент (ДО верстки):
  Додати блок контактів у футер? Телефон / email / посилання?
Ви: лише email, jane@example.com

Агент: готово. resume.html - тема light, усі секції,
       у футері email. Відкривається у браузері, нуль зовнішніх запитів.

Гілка "ні, не треба" теж валідна: агент пропускає блок цілком, не залишає порожній футер і не пише "контакти не вказані". А передали контакти одразу в запиті - верстає з ними, не перепитуючи.

Готовий агент поводиться правильно, якщо коротко:

• агент у Git, tools - лише читання .md і запис .html;
• light і dark працюють, sections фільтрує блоки;
• обовʼязкове рішення здобувається запитанням до верстки, і це видно в логах; гілка "ні" відпрацьована;
• негатив: сміттєва theme - відкат на light з явним рядком-попередженням; немає вхідного файлу - агент питає, який верстати, а не вигадує;
• повторний прогін перезаписує resume.html, а не плодить копій;
• 4 демо-прогони (А, Б, В, Г) у log/; README - таблиця параметрів і лог запитання про контакти.