Що таке sub-агент у двох реченнях

Sub-агент — окрема сесія CC, яка стартує всередині твоєї, виконує задачу і повертає один результат. Має власний контекст (твою сесію не бачить), власну роль (тип агента), власні дозволи. Запускається через tool Agent або кастомні .claude/agents/.

Це не «асинхронна задача», не «фоновий процес»: це послідовна делегація з чистим інтерфейсом prompt → result. Або, якщо явно вказати run_in_background=true — асинхронна задача, але все одно з тим самим інтерфейсом результату.

Базові типи агентів

Тип	Призначення	Що доступно
general-purpose	Багатокрокові задачі з невизначеним планом	Всі tools
Explore	Read-only пошук по кодбазі: «де визначено X», «які файли посилаються на Y»	Тільки Read, Glob, Grep, WebFetch/WebSearch (без Edit/Write)
Plan	Архітектурне планування: проектування підходу до завдання	Read-only + аналітика

Кастомні агенти описуються у .claude/agents/<type>.md з frontmatter (name, description, tools, model). Це окрема тема — для більшості задач достатньо трьох built-in типів.

Коли делегувати — а коли НЕ

Делегувати	Не делегувати
Пошук у великій кодбазі («де викликається parseConfig», «знайди всі імпорти X»)	Точкове читання відомого файла — швидше через Read
Паралельні незалежні запити (3 агенти на 3 різні питання одночасно)	Послідовна логіка, де кожен крок потребує бачити попередній
Ізольований експеримент (isolation=worktree) — спробувати ризиковану зміну, не псуючи поточне дерево	Експеримент, де треба «бачити» побічні зміни — sub-агент повертає тільки summary
Велика операція, яка з'їсть твій контекст (read 30 файлів, summary)	Операції, де треба контроль на кожному кроці — модель головної сесії має бачити деталі
Незалежний code review (друга думка від чистої моделі)	Синтез — «на основі знайденого виправ баг». Це антипатерн: ти даєш агенту НЕ те, що він може зробити, бо синтез — твоя робота

Золоте правило: не делегуй розуміння. Прийняття рішення — у твоїй сесії, бо тільки ти бачиш повний контекст. Sub-агент — інструмент збору фактів, не прийняття рішень.

Як писати prompt для sub-агента

Sub-агент не бачить твоїх повідомлень. Не бачить твою memory. Не бачить файли, які ти вже прочитав. Він стартує з чистого аркуша + системний промт + один твій input. Це означає:

Правило 1: prompt має бути self-contained

// Поганий prompt (передбачає, що агент знає контекст):
"Перевір цей баг."

// Хороший:
"Перевір баг у логіці retry у файлі src/api/client.ts:42.
 Контекст: ми хочемо, щоб при 429 робилось 3 retry з expontntial backoff.
 Зараз retry відбувається безкінечно при будь-якій 5xx.
 Очікую: report на 100 слів — у чому конкретно баг і яким одно-рядковим
 fix-ом його можна полагодити."

Правило 2: фіксований формат відповіді

Без явного формату агент відповість як завгодно. Скажи: «під 200 слів», «список з 3 пунктів», «таблиця з колонками: файл, рядок, проблема, fix». Це особливо важливо, бо результат потрапляє у твій контекст.

Правило 3: коротка передісторія тільки якщо потрібна

Не вали усі деталі проєкту. Дай рівно стільки, скільки треба для задачі. Якщо агенту знадобиться більше — він прочитає сам через Read.

Правило 4: lookups vs investigations

• Lookup («знайди файл, де визначено X») — давай точну команду / шаблон. Не пиши «дослідіи».
• Investigation («чому ці тести не пройшли») — давай питання, не приписи. Передбачені кроки стають баластом, коли початкова гіпотеза неправильна.

isolation=worktree — окрема магія

Параметр isolation: "worktree" у виклику Agent створює тимчасовий git worktree у окремому каталозі і запускає агента там. Це означає:

• Зміни агента не торкаються твоєї робочої копії.
• Якщо агент нічого не змінив — worktree автоматично видаляється.
• Якщо щось зробив — повертає шлях до worktree і назву гілки, щоб ти міг ревʼюти diff.

Це найбезпечніший спосіб запускати ризиковані експерименти: «спробуй переписати модуль X», «застосуй автоматичний рефакторинг», «вирівняй імпорти у всіх 200 файлах». Не вийшло — нічого не сталось. Вийшло — merge у свою гілку.

Реальні кейси

1. Огляд гілки перед релізом

Agent({
  subagent_type: "general-purpose",
  description: "Branch ship-readiness audit",
  prompt: "Audit what's left before this branch can ship. Check:
    uncommitted changes, commits ahead of main, whether tests exist,
    whether the GrowthBook gate is wired up, whether CI-relevant
    files changed. Report a punch list — done vs. missing. Under 200 words."
})

Агент проходить git status, log, diff, читає тести і конфіги — повертає список «що готово / що залишилось». Економить ~10 хв твого часу і ~5 тулз-викликів у твоєму контексті.

2. Code review другої думки

Agent({
  subagent_type: "general-purpose",
  description: "Independent migration review",
  prompt: "Review migration 0042_user_schema.sql for safety.
    Context: we're adding NOT NULL column to 50M-row table with backfill default.
    I want a second opinion on whether the backfill approach is safe under
    concurrent writes — I've checked locking behavior but want independent
    verification. Report: is this safe, and if not, what specifically breaks?"
})

Sub-агент починає з чистого аркуша, не бачить твоєї логіки. Його висновок — справді незалежний.

3. Експеримент з ризиковою зміною через worktree

Agent({
  subagent_type: "general-purpose",
  description: "Refactor experiment in worktree",
  isolation: "worktree",
  prompt: "Refactor src/auth/* to use the new SessionContext pattern
    (described in CLAUDE.md). Run all tests after each change.
    Don't touch anything outside src/auth/. Report: what was changed,
    test status, any unexpected coupling discovered."
})

Якщо рефакторинг провалиться — твоє дерево чисте, ти можеш ревʼюти diff у worktree і вирішити, забирати чи відкинути.

4. Паралельне виконання — 3 агенти одночасно

// В одному message — три виклики Agent одночасно:
Agent({ description: "Find all DB migrations", ... })
Agent({ description: "List webhook handlers",   ... })
Agent({ description: "Find feature flags usage", ... })

Три незалежні запити стартують паралельно. Результати приходять окремими повідомленнями. Корисно, коли треба зібрати дані з кількох незалежних кутів.

Підводні камені

Cross-refs

• Управління списком sub-агентів — slash /agents.
• PreToolUse-hook, який блокує виклик Agent — «Hooks у Claude Code».
• Permissions для tools, які доступні sub-агенту — «Permissions і settings.json».
• Sub-агент з власним MCP — «MCP-сервери».