Пояснення субагентів Claude Code: що це таке та коли їх використовувати.

Агенти — це не просто навички під маскою

Звичайною першою реакцією на агентів Claude Code є думка, що це навички з додатковими кроками, „розумніші навички“, які діють більш автономно через те, що їхні інструкції сформульовані по-іншому. Це уявлення є хибним. Агент насправді — це також запит, як і навичка. Важлива різниця полягає у тому, де він працює. Агент не виконується всередині основного діалогу. У нього є власне вікно контексту, власний системний запит, власний доступ до інструментів та власні дозволи; він працює окремо та повертає результат.

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

Чотири значення терміна „агент“

У Claude Code термін „агент“ охоплює принаймні чотири різні речі, і їх змішування ускладнює розуміння всієї функції. Троха педантизму тут принесе користь, адже це допомагає віднести терміни до конкретних ресурсів, якими можна фактично скористатися.

1. Claude Code сам по собі є агентним середовищем. Anthropic презентує його як агентного помічника з кодування: він має інструменти та цикл виконання, може планувати та діяти у кількох кроках без необхідності постійних підказок. Він є агентним ще до того, як ви щось налаштуєте.
2. Підагенти — це спеціалізовані примітиви агентів у межах продукту. Коли фахівець каже, що створює агента в Claude Code, майже завжди має на увазі підагента. Згідно з офіційною документацією, це спеціалізовані помічники для певних типів завдань, кожен з яких має окреме вікно контексту, індивідуальний системний запит, визначений доступ до інструментів та незалежні права.

Команди агентів належать до іншої, багатосеансової функціональності. У документації до команд чітко вказано межу: підагенти існують у межах одного сеансу, тоді як команди координують свою роботу між кількома сеансами. Команда — це набір незалежних інстанцій Claude Code, які спілкуються через спільний список завдань та прямі повідомлення між учасниками. Ця функція є експериментальною, за замовчуванням вимкненою та увімкнутою за допомогою флага середовища. Це не „більше підагентів“ — вона знаходиться на іншому рівні архітектури.

Claude Agent SDK є четвертим рівнем. Він надає ті самі інструменти та механізм роботи агентів, які використовуються у Claude Code, у вигляді бібліотеки на Python та TypeScript для команд, які створюють власні додатки-агенти поза межами CLI.

Решта тексту присвятована другому пункту – підагентам. Команди заслуговують на окреме розглядання пізніше; детальне пояснення одного підагента є правильною точкою входу.

Чому існують підагенти

Основною причиною є те, що мовні моделі мають обмежений контекст, і рано чи пізно тривала сесія досягає цього ліміту. Без відповідних заходів це трапляється знову і знову.

Есе компанії Anthropic про кураторство контексту описує цю діяльність як вибір того, що потрапляє у обмежене вікно. Кожен виклик інструменту, завантаження файлу та незавершена аналіза додаються до контексту та залишаються в ньому. Чим довше триває сесія, тим більше місця у вікні займають елементи, які допомогли знайти відповідь, але потім стають марними. Цей безлад погіршує якість, що часто називається занепадом у вікні. У моделі залишається менше простору для роботи, а більше нерелевантних матеріалів конкурує за її увагу.

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

Конкретний приклад: ви просите Claude з’ясувати, чому невдається тестовий набір. Під час роботи в основній сесії для дослідження потрібно прочитати двадцять файлів, шукати шаблони помилок, перевіряти конфігурацію тестів та аналізувати останні зміни. Усе це потрапляє до вашого контексту. До кінця ви витратите кілька тисяч токенів на проміжні дії, причому майже ніщо з цього не впливає на подальші дії.

Підагент переформулює проблему. Розслідування відбувається у власному вікні контексту та з власним бюджетом токенів, і результатом є короткий вердикт на кшталт „причиною пошкодження є змінна середовища, відсутня у налаштуваннях CI; порушені три тести, ось як це виправити“. Основний потік ніколи не поглинає цей „шум“ від пошуку.

Основною причиною є ізоляція контексту, а також ще три менш значущі фактори:

1. Спеціалізація. Підагент має власний системний запит. Фахівець, який діє за чіткими інструкціями щодо стандартів вашої команди, буде більш стабільним у своїх діях, ніж загальний асистент, який намагається дотримуватися цих стандартів серед усього іншого, що він знає.

Забезпечення дотримання обмежень. Ви самі вирішуєте, які інструменти може використовувати підагент. Агент для досліджень із правом лише на читання, який не може записувати файли чи виконувати команди шеллу, має зовсім інший профіль ризиків, ніж основний асистент, і ці обмеження прописуються та застосовуються чітко, а не лише очікуються.

Контроль витрат. Підагент може працювати на іншій моделі. Надсилання простих завдань на Haiku, поки основна сесія використовує Sonnet, — це практичний спосіб керування витратами, про який багато хто дізнається лише після неприємного рахунку.

Створення першого власного підагента

З технічної точки зору підагент — це не що інше, як документ Markdown із заголовком у форматі YAML. Допускаються два місця розміщення:

• .claude/agents/ усередині проекту для агентів, пов’язаних із цим кодовим базисом. Зберігайте їх, щоб команда могла ними ділитися та вдосконалювати їх.

~/.claude/agents/ у особистому каталозі — тут знаходяться персональні агенти, доступні в кожному проєкті.

Фронтматер заслуговує уваги

Люди зазвичай швидко проглядають YAML-фронтматер, але Claude Code зберігає його в пам’яті основної сесії, щоб зрозуміти, до чого призначений кожен агент. Фактично це є коротким описом агента. Два поля є обов’язковими, а кілька інших — необов’язковими. Простий приклад показує, як вони поєднуються:

---
name: code-reviewer
description: Reviews code changes for quality, security, and best practices.
             Use proactively after any significant code change.
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, read the changed files and provide
specific, actionable feedback on code quality, security, and best practices.
Focus on what matters. Don't restate what the code does — say what's wrong
or good about it. Flag security issues first, then logic problems, then style.

Розглядаємо поле за полем:

• name — це унікальний ідентифікатор, написаний маленькими літерами та складається лише з дефісів. Він відображається у журналах та використовується Claude для внутрішнього позначення агента.
• description має найвище значення. Claude користується нею, щоб вирішити, чи належить завдання цьому агенту, тому тут слід описати його функції: яку роботу він виконує та у яких ситуаціях його потрібно викликати. Додавання фрази „використовувати проактивно“ є задокументованим сигналом для Claude активувати агента без очікування прямого запиту. Видаліть цю фразу, якщо агент має відповідати лише при прямому запиті.

tools обмежує те, до чого може дістатися агент. Вищезгаданий ревізор може читати файли та шукати інформацію, але не може редагувати їх, виконувати команди оболонки чи здійснювати мережеві виклики. Це робиться навмисно: ревізор з правами лише на читання не може випадково змінити те, що перевіряє. Сама документація рекомендує надавати лише ті інструменти, які потрібні агенту, задля безпеки та забезпечення прогнозованої поведінки.

model спрямовує агента до певної моделі: sonnet, opus, haiku або повного ідентифікатора, наприклад claude-opus-4-6. Без цього агент використовує параметр inherit, що означає використання тієї самої моделі, що й у основній сесії.

Усе, що знаходиться під елементом frontmatter, стає системним запитом агента. Цей запит разом із робочою директорією — усе, що отримує агент від основної сесії.

Повний перелік необов’язкових полів показує, що ще можна налаштувати: permissionMode, maxTurns, skills, mcpServers, effort, memory, hooks, disallowedTools, color та інші.

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

Куди зберігати файл

Збережіть приклад як .claude/agents/code-reviewer.md у проекті. Отримана структура виглядає так:

your-project/
├── .claude/
│   ├── agents/
│   │   └── code-reviewer.md          ← your new agent file
│   ├── skills/
│   └── rules/
├── src/
├── tests/
├── README.md
└── package.json

Після збереження Claude виявляє агента. Попросіть його переглянути зміни в коді, і він самостійно делегує це завдання code-reviewer, залежно від того, наскільки запит відповідає опису. Для особистого агента, який працює у всіх проектах, перемістіть файл у ~/.claude/agents/code-reviewer.md. Формат та зміст залишаються незмінними; змінюється лише місцезнаходження.

Агенти проти навичок

Чому їх часто плутають

Три подібності пояснюють більшу частину плутанини:

1. Обидва налаштовуються через звичайну структуру папок у .claude/skills або .claude/agents.
2. Обидва використовують frontmatter, і в обох опис є найважливішим параметром.
3. Обидва є наборами інструкцій, іншими словами — запитами. Навичка та агент можуть містити абсолютно однакові слова.

Якщо дивитися з цієї точки зору, вони виглядають структурно схожими.

Де відбувається робота

Проте їх відрізняє одна очевидна, практична відмінність: місце, де виконується робота, тобто де витрачаються токени. Це найпростіше розуміння різниці.

• Навичка інтегрується у поточну розмову. Її інструкції, шаблони та допоміжні файли приєднуються до активного контексту; Claude обробляє їх у тому ж потоці, і кожен крок додається до головного вікна.
• Підагент працює окремо у власному вікні контексту. Він виконує роботу, а головна розмова отримує результат.

Параметри налаштувань

Раніше існував довгий список полів, які агент може налаштувати у своєму фронтматері. Натомість навички приймають значно коротший список, який частково також відрізняється. Це свідчить про те, наскільки більше контролю надають агенти. Це не означає, що потрібно перетворювати все на агента. Суть у тому, що ментальну модель, використану для створення надійної системи, може знадобитися переосмислити.

Одне завдання, дві відповіді

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

Якщо Claude має бути обізнаним про ці стандарти протягом усієї сесії, використовувати їх під час написання коду, цитувати їх у порадах та вказувати на порушення щоразу, коли вони трапляються, тоді підходять навички. Стандарти потрібно написати один раз, а Claude буде використовувати їх у відповідних ситуаціях, щоб усе, що робиться під час сесії, ґрунтувалося на них.

Якщо ж ви хочете, щоб сорок файлів були переглянуті за один прохід, без того, щоб основний контекст заповнювався даними про читання файлів, тимчасовими коментарями та результатами пошуку, то для цього потрібен підагент. Налаштуйте агента для перегляду коду, дозвольте йому працювати у власному вікні та отримайте структурований огляд. Ви навіть можете запустити сорок підагентів паралельно — по одному на кожен файл. Основна розмова отримує результат, без деталей про процес його створення.

Одне речення може описати цю різницю: навичка змінює те, що знає Claude чи як він підходить до робочого процесу, тоді як підагент змінює те, хто виконує роботу, у якому контексті та з якими інструментами.

Практики роботи, які є ефективними

Розглядайте опис як інтерфейс маршрутизації

Цьому аспекту надається менше уваги, ніж слід. Claude читає описи підагентів, щоб вирішити, коли делегувати завдання, і не читає сам текст запиту перед прийняттям рішення. Будь-яка конкретна інформація, яку ви вказуєте у тілі запиту, залишається невидимою до того моменту, поки підагент не буде створений. Тому опис має містити достатньо інформації, щоб Claude зрозумів, коли потрібен агент.

• Використовуйте конкретні, описові формулювання.
• Вкажіть, що робить агент та в яких ситуаціях його слід обирати.
• Згадайте типи завдань, з якими він ефективно справляється, а також, за потреби, ті, якими він не повинен займатися.
• „Використовувати проактивно після змін у коді“ — це перевірений підхід, згаданий у документації як спосіб заохочення делегування без прямого запиту. Пропустіть його для агентів, які мають працювати лише при прямому запуску.

Уникайте описів, які вказують на ідентичність агента, наприклад «експерт-рецензент із двадцятирічним досвідом». Це має бути в системному запиті. Опис призначений для моделі маршрутизації, а не для агента.

Щоб побачити різницю, поставте нечіткий опис («Допомагає з якістю коду та завданнями рецензування») поруч із описом, призначеним для маршрутизації: «Перевіряє внесені зміни на наявність проблем із безпекою, логічних помилок та проблем зі стилем. Запускається проактивно після кожної значної зміни. Він ніколи не пише код та не редагує файли».

Навмисно обмежуйте інструменти

Агент, який успадковує всі інструменти з основної сесії, ускладнює аналіз у разі проблем. Надавайте лише те, що потрібно для виконання завдання.

• Рецензент повинен мати можливість лише читати, і нічого більше: без можливості писати, без шеллу, без доступу до мережі.
• Дослідницька робота вимагає пошуку та отримання інформації, без можливості редагування файлів.
• Виконання тестів передбачає доступ до Bash, але немає потреби користуватися вебом.

Обмеження набору інструментів сприяє безпеці та ясності. Вузький набір інструментів робить поведінку прогнозованою, і коли агент зазнає невдачі чи повертає щось дивне, короткий список можливих інструментів прискорює діагностику. Це також робить способи збою обмеженими та відомими. Поле disallowedTools дозволяє агенту успадкувати інструменти основної сесії, а потім вилучити певні з них, що підходить у випадках на кшталт „усе, крім Bash“ чи „усе, крім Write“.

Дайте кожному агенту одне завдання

У документації до підагента чітко зазначено, що кожен підагент має досконало виконувати лише одне завдання. Опис на кшталт „переглядає код, пише тести, оновлює документацію та займається перевірками під час розгортання“ містить чотири функції в одному полі. Claude може нерівномірно їх розподіляти, а системний запит мусить одночасно працювати з чотирма режимами роботи.

Звузьте сферу діяльності та створіть три окремі файли, кожен з яких має чіткий опис. У науці про дані це можуть бути агент для перевірки моделей, інструмент для перевірки якості даних та переглядач нотаток. У програмному забезпеченні — це може бути переглядач коду, генератор тестів та оновлювач документації. Цей принцип діє у будь-якій галузі. Кожен агент отримує одне завдання, власний файл та опис, який забезпечує однозначне спрямування дій.

Використовуйте поле моделі для керування витратами

Люди, яких ще не здивував рахунок за використання, зазвичай ігнорують це поле. Встановлення model: haiku у легких агентах значно знижує витрати, коли кілька агентів працюють у одній сесії. Використання model: opus у агенті, який мусить довго обробляти великий контекст, виправдовує його ціну. Залишення значення за замовчуванням inherit означає, що кожен агент працюватиме за тими ж параметрами, що й основна сесія, часто з найсильнішим моделлю, яка застосовується однаково до завдань, що не вимагають її потужностей.

Що обрала спільнота

Каталог підагентів VoltAgent містить понад сто спеціалізованих підагентів – від експертів з мов до перевіряючих безпеку, дебагерів, помічників з інфраструктурою та оркестраторів. Ще один хороший набір знаходиться у репозиторії Everything Claude Code. Лише декільком людям знадобиться навіть п’ята частина цих агентів, тож кількість не є найважливішою частиною – важлива структура. Кожен елемент у цих колекціях має вузьку спеціалізацію: чи то експерт з TypeScript, SQL, Kubernetes або аудитор безпеки. Жоден з них не намагається охоплювати більше однієї галузі. Це єдиний консенсус після більш ніж року реального використання: багато спеціалізованих агентів кращі за одного універсального.

Короткий огляд команд агентів

Варто знати про команди агентів, але це інша функція, ніж підагенти.

Підагенти працюють у межах однієї сесії. Основна інстанція Claude Code створює їх, вони працюють ізольовано та повертають результати, а ви залишаєтесь оркеструвальником.

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

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

Налаштування їх не є простим, тому вони поза межами цього опису, і немає причин поспішати використовувати їх через страх залишитися позаду. Команди збільшують навантаження на координацію та спалюють значно більше токенів, оскільки кожен учасник команди має власне вікно контексту, за яке оплачується окремо. Вони є експериментальними та за замовчуванням вимкнені; їх можна увімкнути за допомогою змінної середовища.

Практичне правило: якщо ваші підагенти повідомляють вам про результати та не потребують спілкування один з одним, команди не потрібні. Коли один підагент мусить передати свої висновки іншому або поставити під сумнів його висновки, таке оновлення починає виправдовувати свою вартість. До цього моменту достатньо підагентів.

Коли агент є неправильним інструментом

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

Це безпосередньо стосується деяких ситуацій, коли підагент створює перешкоди та не приносить жодних результатів:

• Одноразові завдання. Підагент потребує додаткових зусиль для створення: найменування, написання опису, вибір інструментів, тестування, обслуговування. Завдання, яке потрібно виконати лише один раз, не виправдовує цього, тому краще написати хороший запит. Інвестиції окупаються лише тоді, коли робочий процес повторюється достатньо часто, щоб було доцільно підтримувати відповідну конфігурацію.

Ситуації, коли контекст не є проблемою. Основна причина використання підагента — захистити основний контекст від важкої роботи. Якщо завдання легке, вікно не заповнюється та не потрібні жодні особливі обмеження інструменту, підагент лише додає непрямість. Звичайне запитування в основній сесії є кращим з точки зору швидкості, простоти та легкості відлагодження.

Пастка моноліту. Один агент, який намагається охопити дослідження, реалізацію, перевірку та документування, не є всебічним. Він неперевірюваний та обирається неконсистентно. Більш точний та конкретний опис забезпечує набагато кращу послідовність.

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

Коротка версія

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

Один ретельно налаштований агент — це достатня кількість роботи на один полудень. Тут немає потреби у системі оркестрації: достатньо чіткого опису завдання, обмеженого набору інструментів та одного ясного завдання. Складність може зрости згодом, але не обов’язково починатися саме з цього.

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