Субагенти Claude Code: як делегувати роботу і не засмічувати контекст

Коротко (TL;DR)

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

Коли це потрібно: розвідка по кодовій базі, важкий веб-ресерч, незалежне рев’ю, будь-яке завдання, яке «прочитає багато, а поверне мало». Коли не потрібно: коротка правка одного файлу або послідовна робота, де кожен крок залежить від попереднього, — там субагент лише додасть накладних витрат.

З чого почати: у Claude Code вже є вбудовані субагенти (Explore, Plan, general-purpose) — їх можна викликати одразу, нічого не налаштовуючи. Власний субагент — це один markdown-файл у .claude/agents/. Далі розберемо механізм, рецепт створення, вирішальну таблицю «субагент чи щось інше», чесну собівартість у токенах і ризики безпеки з конкретними датами й номерами багів.

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

Що таке субагент і що саме він повертає

Звичайний діалог із Claude Code іде в одному контекстному вікні. Усе, що агент прочитав, викликав і обдумав, лежить у цьому вікні й поступово його заповнює. Що більше сміття (вміст двадцяти файлів, вивід команд, глухі гілки міркувань) — то ближче вікно до межі і то гірше модель тримає нитку.

AMD купує собі місце в Anthropic: 2 гігавати MI450 в обмін на інвестицію до $5 млрд

Один агент чи кілька: як обрати мультиагентну архітектуру

П’ять патернів агентних систем: механіка, приклади та ціна кожного

Воркфлоу проти ШІ-агента: як обрати і не переплатити за автономність

Як не втрачати контекст у Claude Code: компакт, resume і handoff

Субагент вирішує цю проблему архітектурно. Формально це ізольоване контекстне вікно з власним системним промптом, власним переліком інструментів і власними правами. Головна сесія (її називають оркестратором) надсилає субагенту завдання, субагент відпрацьовує його у своєму вікні, а назад оркестратору йде лише останнє повідомлення — підсумок. Усе проміжне лишається всередині субагента і в контекст оркестратора не потрапляє.

Саме тому в інженерних матеріалах Anthropic субагентів відносять до механізмів стиснення контексту: сто прочитаних файлів згортаються до одного абзацу виводу. Тонкість, яку рідко проговорюють: субагенти працюють не тому, що «акуратніші» за головний потік, а тому, що дають змогу витратити на складне завдання більше токенів, не роздуваючи одне вікно. У власних вимірах Anthropic на бенчмарку багатокрокового пошуку обсяг витрачених токенів пояснював близько 80% розкиду в успішності — тобто важке завдання просто вимагає багато «думання», і субагент дає цьому думанню окрему кімнату.

Звідси ж випливає межа застосовності. Субагент невидимий: доки він не завершить роботу, оркестратор (і ви) не бачите його кроків. Офіційний блог Anthropic про «steering» проводить за цією ознакою чітку межу між субагентом і навичкою (skill): навичка крутиться в головному потоці на виду, а субагент за конструкцією невидимий до фінального результату. Це точніше за розхоже кліше «навичка — це знання, субагент — це делегування».

Не плутати: субагенти CLI і субагенти Agent SDK

Є дві різні речі зі схожою назвою. Ця стаття — про субагентів Claude Code CLI: файли .claude/agents/*.md, виклик через інструмент Task/Agent. Є ще субагенти в Claude Agent SDK — це програмний шар для розробників, де агенти задаються параметром у коді застосунку. Механіка схожа за змістом, але це інша продуктова поверхня; далі йдеться тільки про CLI.

Вбудовані субагенти: принцип видно одразу

Перш ніж налаштовувати власне, корисно поглянути на готові субагенти — вони демонструють принцип «прочитав багато, повернув мало» без жодного рядка конфігурації.

• Explore — субагент лише для читання (read-only). Ходить по кодовій базі, шукає, де що визначено, і повертає стиснену карту. З версії v2.1.198 він успадковує модель батьківського процесу, щоб розвідка не деградувала на слабшій моделі.
• Plan — теж read-only, використовується в режимі планування: збирає контекст і пропонує план, не чіпаючи файли.
• general-purpose — субагент із повним набором інструментів, для багатокрокових завдань, яким потрібні і читання, і запис, і пошук.
• Службові — statusline-setup, claude-code-guide і подібні, під вузькі завдання конфігурації.

Важлива деталь механіки: Explore і Plan під час старту пропускають завантаження CLAUDE.md і git-статусу (їм це не потрібно і лише зайняло б контекст), тоді як звичайний субагент ці дані підхоплює. Це теж про економію вікна.

Як створити власного субагента: покроково

Власний субагент — це markdown-файл із YAML-заголовком (front-matter). Фіча з’явилася в Claude Code v1.0.60 (24 липня 2025); того самого дня профільний issue з цитатою з реліз-ноуту завели в сторонньому репозиторії спільноти — це зручне незалежне підтвердження дати.

Крок 1. Визначте, де зберігати. Claude Code читає субагентів із п’яти рівнів, і за збігу імен пріоритет такий: managed (корпоративна політика) → прапорець CLI --agents → проєкт → користувач → плагін. (Не плутайте прапорець --agents — JSON-набір субагентів на сесію — із --agent, який призначає одного субагента на всю сесію; про нього нижче.) – Проєктний рівень: .claude/agents/<ім'я>.md у репозиторії — субагент їде разом із проєктом і працює в усієї команди. – Користувацький: ~/.claude/agents/<ім'я>.md — ваш особистий субагент у всіх проєктах.

Крок 2. Опишіть front-matter. Обов’язкові лише два поля — name і description; решта опційна:

---
name: research-competitor
description: Важкий веб-ресерч за темою. Використовувати на початку написання статті.
tools: [WebSearch, WebFetch, Read]   # опційно; не задано → успадковує УСІ інструменти батьківського процесу
model: sonnet                        # опційно: sonnet | opus | haiku | inherit
permissionMode: default              # опційно
---

Ти — ресерчер. Твоє завдання — зібрати факти за темою і повернути
компактний бриф: теза → джерело → дата. Не пиши статтю,
поверни лише структурований список фактів.

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

Крок 3. Перевірте tools — це і налаштування, і питання безпеки. Якщо поле tools не задано, субагент успадковує всі інструменти батьківського процесу. Хочете обмежити — перелічіть інструменти явно. Тут легко помилитися (детально про це в розділі про ризики): поля tools: і allowed-tools: — не те саме, і плутанина між ними вже призводила до інцидентів.

Крок 4. Викличте субагента. Три способи: 1. Природною мовою — просто попросіть: «нехай субагент-ресерчер збере дані за темою X». Оркестратор сам підбере відповідного за description. 2. Через @-згадування конкретного субагента в запиті. 3. Прапорцем --agent <ім'я> — призначити субагента на всю сесію.

Крок 5. Запускайте паралельно, коли завдання незалежні. Кілька субагентів можна підняти в одному зверненні — наприклад, віддати розвідку по трьох підсистемах трьом копіям Explore одразу. Вони відпрацюють одночасно, і оркестратор збере три карти. Це саме той прийом, на якому будуються складніші оркестрації (про них — окрема стаття серії).

Конкретний приклад, навіщо це потрібно. Припустимо, ви просите: «розберися, як у проєкті влаштовані авторизація, платежі й сповіщення». В одному вікні агент прочитав би десятки файлів по трьох підсистемах, і до моменту відповіді контекст був би забитий їхнім вмістом. Із субагентами ви піднімаєте три Explore одразу — кожен читає свою підсистему у своєму вікні, а в головний потік повертаються три короткі резюме замість трьохсот кілобайтів коду. Головне вікно лишається чистим для власне роботи.

Як фіча змінювалася

Субагенти — жива частина продукту, і їхня поведінка помітно еволюціонувала, що важливо враховувати під час читання старих гайдів:

• v1.0.60 (24 липня 2025) — реліз кастомних субагентів.
• v2.1.63 — інструмент виклику перейменовано з Task на Agent (старі матеріали й досі пишуть «Task tool»).
• v2.1.117 — з’явилися форки контексту; v2.1.161 — команда /fork стала доступна за замовчуванням (без окремої змінної середовища).
• v2.1.172 — зафіксовано ліміт вкладеності 5 рівнів.
• v2.1.198 — Explore почав успадковувати модель батьківського процесу, доопрацьовано фоновий режим.

Практичний висновок: якщо гайд написаний до осені 2025 і говорить про «Task tool» або інакше описує форки — звіряйтеся з актуальною документацією, деталі вже інші.

Коли субагент, а коли щось інше

Субагент — не єдиний спосіб змінити поведінку Claude Code. Офіційний блог Anthropic про «steering» зводить воєдино цілих сім механізмів: CLAUDE.md, правила (Rules), навички (Skills), субагенти (Subagents), хуки (Hooks), стилі виводу (Output styles) і дописка до системного промпту (system prompt append). Більшість гайдів порівнюють три-чотири — ось ці сім за ключовою ознакою (плюс MCP окремим рядком як суміжний механізм, якого в «сімці» немає, але він часто стоїть поруч у виборі):

Офіційна документація прямо називає випадки, коли субагент не потрібен: – послідовна залежна робота, де кожен крок спирається на результат попереднього (ізоляція лише завадить — контекст доведеться ганяти туди-сюди); – правка одного файлу або точкова зміна; – дрібні завдання, де накладні витрати на запуск субагента більші за саму користь.

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

Окреме питання рівнем вище — чи потрібна завданню автономність узагалі: часто дешевше і передбачуваніше заздалегідь описаний воркфлоу замість ШІ-агента.

Скільки це коштує в токенах

Єдиної виміряної цифри «оверхеду субагента» для Claude Code CLI не існує, і матеріали, які називають точне число, зазвичай не розкривають методику.

Що відомо достовірно. Anthropic публікувала архітектурні цифри 4x і 15x (13 червня 2025): агентні системи витрачають приблизно вчетверо більше токенів, ніж звичайний чат, а мультиагентні — приблизно вп’ятнадцятеро більше. Але ці числа стосуються їхнього продукту Claude Research, а не Claude Code CLI безпосередньо — переносити їх один в один некоректно, хоча так роблять часто.

Що гуляє мережею про сам Claude Code CLI — розбіжні community-оцінки без спільної методики:

Висновок для практики: субагенти — це усвідомлена плата за глибину, а не безкоштовна «чистота». Знизити витрати допомагають три прийоми: (1) призначити субагенту простішу модель (model: haiku або sonnet для розвідки замість opus); (2) звузити завдання й набір інструментів, щоб субагент не блукав зайвого; (3) задати в системній інструкції стиснутий формат повернення — тоді підсумок коротший і токенів на нього йде менше.

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

Де ламається

Ізоляція субагента — сильна сторона, але в неї є ціна і кілька неочевидних обмежень.

• Субагент за замовчуванням успадковує всі права батьківського процесу. Це не пісочниця. Якщо ви не звузили tools, субагент може робити все, що може головна сесія. «Ізольований контекст» не означає «ізольовані права».
• Субагенти не спілкуються між собою. Кожен звітує лише оркестратору. Жодне повідомлення субагента не може підтвердити запит на дозвіл за інший субагент чи змінити його конфігурацію. Для координації кількох виконавців потрібен рівень вище — оркестрація.
• Ліміт вкладеності — 5 рівнів (зафіксований від версії v2.1.172, не налаштовується). Штатно субагент може породжувати субагентів не глибше п’яти рівнів.
• Завантаження під час старту. Звичайний субагент підтягує CLAUDE.md і git-статус; Explore і Plan — ні. Якщо ваш кастомний субагент несподівано «знає» зайве про проєкт — імовірно, річ у цьому автозавантаженні.

Окрема тонкість про модель субагента: порядок розв’язання — змінна середовища → вказівка під час виклику → поле model у front-matter → успадкування від батьківського процесу. Якщо субагент вперто бере не ту модель, шукайте перевизначення вище цим ланцюжком.

Ризики безпеки

Технічній темі теж потрібен чесний розділ ризиків — тут він не абстрактний, а з конкретними датами й номерами.

1. Плутанина tools: і allowed-tools: → реальні інциденти. В issue #27099 (створений 20 лютого 2026) описано два випадки, коли через переплутані поля субагент отримав більше прав, ніж передбачав автор, і це призвело до credential-hunting: в одному випадку — спроба дампу Keychain, в іншому — видобуття JWT-токена. Issue закрито як not_planned — тобто мовчазне ігнорування неправильної назви поля інструментарій сам не впіймає. Урок простий: явно перелічуйте tools і перевіряйте, яким саме полем ви обмежуєте доступ.

2. Обхід PreToolUse-хуків — історія з двох частин, які зазвичай зливають в одну. – Загальний випадок (issue #21460): субагент міг обходити блокувальний хук PreToolUse. Мейнтейнер Anthropic підтвердив виправлення 29 травня 2026 з описом тесту на конкретних версіях — ця діра закрита. – Вузький випадок у режимі bypassPermissions (issue #43772): відкритий 5 квітня, закритий як not_planned 15 травня 2026. Тобто не виправлений — для тих, хто використовує bypassPermissions разом із субагентами, ризик лишається практичним.

Картина чесніше звучить як «частково виправлено», а не «все зламано» чи «все чисто».

3. Свіжий баг рекурсивного спавну (issue #68619, 15 червня 2026, статус OPEN). За певної відмови в правах субагенти можуть запустити нескінченний цикл повторного спавну — у звіті фігурують 50+ рівнів вкладеності та спалювання до 4 мільйонів токенів за п’ять хвилин. Формально це не суперечить ліміту в 5 рівнів (там інший механізм — не штатна вкладеність, а баг-цикл), але для гаманця й нервів різниця невелика. Баг потрапив у топ обговорень спільноти за місяць — тобто це не поодинока скарга.

4. Ізоляція від prompt injection реальна, але не абсолютна. Окреме контекстне вікно субагента обмежує шкоду від шкідливої інструкції — але лише якщо шкідливий текст потрапив саме субагенту і не ескалює через успадковані права. Повної гарантії ізоляція не дає.

Як клас інструментів субагенти — частина ширшої автоматизації всередині однієї ШІ-сесії; для порівняння, агент із постійною пам’яттю і власною базою знань — це вже інший сценарій, де немає «одноразової» ізоляції і ризики інші.

Що обрати для моделі субагента

Коротка практична відповідь: для розвідки й ресерчу беріть модель швидшу й дешевшу, для написання та складних міркувань — флагман. Вибір задається полем model у front-matter (haiku/sonnet/opus/inherit) або перевизначається вище ланцюжком розв’язання. Якщо сумніваєтеся в можливостях конкретної моделі під завдання субагента, орієнтуйтеся на її профіль — наприклад, ми детально розбирали можливості Claude Sonnet 5 як робочого коня для делегованих завдань.

FAQ

Чим субагент відрізняється від навички (skill)? Навичка виконується в головному контекстному вікні, і її кроки видно; субагент працює в окремому вікні й невидимий до фінального результату. Навичку беруть для повторюваної процедури на виду, субагента — для завдання «прочитати багато, повернути мало» без засмічування головного контексту.

Субагент економить токени? Ні — він економить контекстне вікно, але зазвичай витрачає більше токенів, а не менше. Сенс у тому, щоб витратити їх в окремій «кімнаті» і повернути в головний потік лише стиснутий підсумок. Точної виміряної цифри оверхеду для Claude Code CLI немає; офіційні 4x/15x Anthropic стосуються іншого продукту (Claude Research).

Як обмежити, що може робити субагент? Явно задайте поле tools у front-matter — інакше субагент успадкує всі інструменти батьківського процесу. Перевірте, що використовуєте саме tools, а не схоже поле: плутанина вже призводила до інцидентів із доступом до секретів (issue #27099, лютий 2026).

Чи можна запустити кілька субагентів одразу? Так, кілька субагентів піднімаються в одному зверненні й працюють паралельно — це підходить для незалежних завдань (наприклад, розвідка по різних частинах проєкту). Між собою вони не спілкуються; результати збирає оркестратор.

Де зберігати субагента — у проєкті чи в користувача? У проєкті (.claude/agents/ у репозиторії), якщо субагент потрібен усій команді й їде разом із кодом; на рівні користувача (~/.claude/agents/), якщо це ваш особистий помічник у всіх проєктах. За збігу імен проєктний рівень пріоритетніший за користувацький.

Чи правда, що глибше 5 рівнів вкладеності субагенти не йдуть? Штатно — так, ліміт 5 рівнів зафіксований і не налаштовується. Але відомий баг рекурсивного спавну (issue #68619, червень 2026, ще відкритий), за якого через відмову в правах виникає цикл на десятки рівнів і величезні витрати токенів. Це не штатна вкладеність, а дефект — але знати про нього варто.