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

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

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

Цей гайд — розширений український переклад і переказ офіційної документації Anthropic Create custom subagents, доповнений досвідом інженерів, які вже щодня користуються субагентами. Для розділів про практику ми зібрали в NotebookLM 21 джерело: документацію, курс Claude Academy, Reddit-обговорення, блоги розробників і збірки готових агентів. Команди, назви полів і код лишаємо англійською, як вони є в Claude Code.

Гайд актуальний для Claude Code версії 2.1.3xx (листопад 2026). Де поведінка залежить від версії, ми це вказуємо. Перевірити свою версію: claude --version.

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

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

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

Кожен субагент:

• працює в окремому контекстному вікні;
• має власний системний промпт;
• має обмежений або повний доступ до інструментів;
• має незалежні дозволи (permissions);
• надсилає власні запити до моделі, і вони рахуються в ті самі ліміти використання, що й основна розмова.

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

Субагенти допомагають:

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

Субагенти працюють у межах однієї сесії. Якщо потрібно запустити багато незалежних сесій паралельно й стежити за ними з одного місця, це background agents. Для окремих сесій, що пересилають одна одній повідомлення, — cross-session messaging. Для скоординованої команди сесій, яку Claude запускає й контролює, — agent teams.

Чому опис агента такий важливий

Claude вирішує, кому делегувати задачу, за полем description кожного субагента. Тому опис має бути чітким: з нього має бути зрозуміло, коли цей агент потрібен.

Водночас описи всіх агентів постійно займають місце в контексті. Якщо сумарний обсяг описів ваших субагентів (без вбудованих) перевищує 15 000 токенів, Claude Code на старті показує попередження з підрахунком токенів. Рецепт простий: скорочуйте description, а подробиці переносьте в системний промпт агента — він завантажується лише тоді, коли агент реально запускається.

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

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

Explore і Plan стартують без ваших файлів CLAUDE.md і без знімка git status, щоб дослідження було швидким і дешевим. Інші вбудовані й кастомні субагенти завантажують і те, і інше, якщо у визначенні кастомного агента не вказано omitClaudeMd.

Explore

Швидкий агент лише для читання, оптимізований для пошуку й аналізу кодової бази.

• Модель: модель основної розмови. Якщо основна розмова працює на Fable, то з підпискою Claude, акаунтом Anthropic Console або через LLM-gateway (ANTHROPIC_BASE_URL) Explore працює на моделі, на яку вказує аліас opus. На Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry, Claude Platform on AWS і Claude apps gateway Explore лишається на моделі основної розмови.
• Інструменти: тільки читання, Write і Edit заборонені.
• Призначення: пошук файлів і коду, дослідження кодової бази.

Коли Claude викликає Explore, він задає рівень ретельності: quick для точкового пошуку, medium для збалансованого дослідження, very thorough для всебічного аналізу.

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

Plan

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

• Модель: успадковує модель основної розмови (якщо не примусово задано CLAUDE_CODE_SUBAGENT_MODEL для всіх субагентів).
• Інструменти: тільки читання.
• Призначення: дослідження кодової бази для планування.

General-purpose

Універсальний агент для складних багатокрокових задач, де потрібні і дослідження, і дії.

• Модель: CLAUDE_CODE_SUBAGENT_MODEL, якщо ви її задали й модель не визначено іншим способом; інакше — модель основної розмови.
• Інструменти: усі, доступні субагентам.
• Призначення: складне дослідження, багатокрокові операції, зміни в коді.

Інші допоміжні агенти

Агент	Модель	Коли Claude його використовує
claude	власної немає, діє порядок вибору моделі	коли задача не підходить жодному спеціалізованому агенту; має всі інструменти субагентів. Також стандартний агент для фонової сесії
statusline-setup	Sonnet	коли ви запускаєте /statusline
claude-code-guide	Haiku	коли ви питаєте про можливості Claude Code

Як обмежити вбудованих агентів

• Заблокувати конкретний вбудований тип — додати його в permissions.deny (див. вимкнення окремих субагентів).
• Повністю заборонити делегування — заборонити сам інструмент Agent через permissions.deny.
• Прибрати лише Explore і Plan — CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Тоді Claude читає й досліджує файли сам. Потрібна версія 2.1.198+.
• У неінтерактивному режимі та Agent SDK — CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1, щоб прибрати всіх вбудованих агентів і лишити тільки власних.

Якщо виклик Agent не містить subagent_type, а в сесії немає general-purpose, на який можна відступити, виклик завершиться помилкою subagent_type is required.

Швидкий старт: перший субагент за 3 хвилини

Субагенти — це Markdown-файли з YAML-frontmatter. Створити такий файл можна двома шляхами: попросити Claude або написати вручну. Створимо субагента рівня користувача, який переглядає код і пропонує покращення.

Крок 1. Попросіть Claude створити агента. Опишіть, що потрібно і куди зберегти:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Писати запит можна й українською: «Створи особистого субагента code-improver у ~/.claude/agents/, який…». Claude створить файл із полями name, description, tools, model і системним промптом.

Крок 2. Перевірте файл. Відкрийте ~/.claude/agents/code-improver.md і переконайтеся, що frontmatter відповідає запиту:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Оскільки файл лежить у ~/.claude/agents/, агент доступний у всіх проєктах на вашому комп’ютері. Щоб обмежити його одним проєктом, перенесіть файл у .claude/agents/ цього проєкту.

Крок 3. Випробуйте.

Use the code-improver agent to suggest improvements in this project

У транскрипті делегування виглядає як рядок виклику інструмента: назва агента й короткий опис задачі, наприклад code-improver(Suggest code improvements).

Якщо Claude не бачить нового агента, перезапустіть Claude Code. Це буває лише тоді, коли тека ~/.claude/agents/ не існувала до старту сесії: запущена сесія не помічає новоствореної теки agents.

Команда /agents у свіжих версіях лише нагадує, що агентів створюють через запит до Claude або редагуванням .claude/agents/ і ~/.claude/agents/. У версіях 2.1.197 і раніше /agents відкривала інтерактивний майстер із вкладками Running (запущені агенти) і Library (створення, редагування, видалення).

Де зберігати агентів: області видимості

Розташування файлу визначає, кому доступний агент, а frontmatter — що він уміє. Якщо кілька агентів мають однакову назву, перемагає той, що з вищим пріоритетом.

Розташування	Область	Пріоритет	Як створити
Managed settings	уся організація	1 (найвищий)	розгортає адміністратор через managed settings
Прапорець --agents	поточна сесія	2	JSON під час запуску Claude Code
.claude/agents/	поточний проєкт	3	попросити Claude або створити файл вручну
~/.claude/agents/	усі ваші проєкти	4	попросити Claude або створити файл вручну
тека agents/ плагіна	там, де ввімкнено плагін	5 (найнижчий)	встановлюється з плагіном

Агенти проєкту (.claude/agents/) ідеальні для всього, що стосується конкретної кодової бази. Додайте їх у git, щоб команда могла користуватися й покращувати їх разом. Claude Code шукає такі теки, піднімаючись від поточної робочої директорії до кореня репозиторію. Якщо кілька вкладених тек визначають агента з однаковим name, перемагає найближчий до робочої директорії.

Коли ви додаєте директорію через --add-dir або /add-dir, Claude Code завантажує і її .claude/agents/. Щоб ділитися агентами між проєктами без --add-dir, використовуйте ~/.claude/agents/ або плагін.

Агенти користувача (~/.claude/agents/) — ваші особисті, доступні в усіх проєктах.

Обидві теки скануються рекурсивно, тож агентів можна розкладати по підтеках: agents/review/, agents/research/. Підтека не впливає на ідентифікацію: агент визначається лише полем name. Стежте, щоб назви були унікальними: якщо в одній теці agents (з підтеками) два файли мають однаковий name, Claude Code завантажить лише один, і який саме — залежить від порядку читання файлової системи. Команда /doctor знаходить такі дублікати й пропонує перейменувати або видалити зайві.

У плагінах підтека стає частиною ідентифікатора: файл agents/review/security.md у плагіні my-plugin реєструється як my-plugin:review:security.

Агенти з командного рядка

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

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

У Windows PowerShell той самий JSON передається через here-string: claude --agents @' … '@.

У неінтерактивному режимі --agents приймає й шлях до JSON-файлу — для великих визначень: claude -p --agents ./agents.json "Review my changes". В інтерактивній сесії шлях до файлу не приймається. Потрібна версія 2.1.281+.

Кожен ключ верхнього рівня — назва агента (не починайте її з -), значення — його визначення:

• prompt — системний промпт агента, аналог тіла Markdown-файлу. Може бути порожнім (з 2.1.281).
• поля frontmatter: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, autoCompactWindow, skills, initialPrompt, memory, effort, background, omitClaudeMd, isolation.
• color і experimental тут ігноруються.

Агенти організації та плагінів

Managed-агентів розгортають адміністратори: Markdown-файли кладуть у .claude/agents/ всередині теки managed settings. Вони мають пріоритет над агентами проєкту й користувача з тією самою назвою.

Агенти плагінів завантажуються автоматично разом із вашими й показуються в підказках @-згадки під scoped-назвою.

З міркувань безпеки агенти плагінів не підтримують поля hooks, mcpServers і permissionMode — вони ігноруються. Якщо потрібні саме вони, скопіюйте файл агента в .claude/agents/ або ~/.claude/agents/. Автор плагіна може винести хуки в hooks/hooks.json, а MCP-сервери — в .mcp.json плагіна.

Як влаштований файл субагента

Файл субагента — це YAML-frontmatter для налаштувань і системний промпт у Markdown після нього:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

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

Claude Code стежить за ~/.claude/agents/ і .claude/agents/: якщо змінити файл агента, наступне делегування вже використає нову версію, без перезапуску. Перезапуск потрібен у трьох випадках:

• ви створили першого агента в новій теці agents, якої не було на старті сесії;
• агент лежить у .claude/agents/ теки, доданої через --add-dir або /add-dir, — за нею Claude Code не стежить;
• сесію запущено з --disable-slash-commands.

Субагент стартує в поточній робочій директорії основної розмови. Команди cd всередині субагента не зберігаються між викликами Bash і не змінюють директорію основної розмови. Щоб дати агенту ізольовану копію репозиторію, вкажіть isolation: worktree. Такий агент виконує команди всередині свого worktree, а Claude Code блокує команди, які намагаються «втекти» git-операціями в основний checkout.

У неінтерактивному режимі можна дописати текст у кінець системного промпту кожного субагента прапорцем --append-subagent-system-prompt (з 2.1.205) або з файлу через --append-subagent-system-prompt-file (з 2.1.261). Форків це не стосується.

Довідник полів frontmatter

Обов’язкові лише name і description. Багатослівні назви полів пишуться в camelCase (maxTurns, disallowedTools) і мають збігатися з таблицею точно: невідоме поле Claude Code мовчки ігнорує.

Поле	Що робить
name	Обов’язкове. Унікальний ідентифікатор до 256 символів, напр. code-reviewer. Назва файлу може відрізнятися. Двокрапка : заборонена (вона для плагінів)
description	Обов’язкове. Коли Claude має делегувати цьому агенту
tools	дозволені інструменти: рядок Read, Grep, Bash або YAML-список. Без поля — усі інструменти субагентів
disallowedTools	інструменти, які треба прибрати зі списку
model	sonnet, opus, haiku, fable, повний ID (claude-opus-5-5) або inherit
permissionMode	default, acceptEdits, auto, dontAsk, bypassPermissions, plan (manual = default)
maxTurns	максимум кроків; після нього результат позначається як частковий, і агента можна відновити
autoCompactWindow	раніше стискати контекст цього агента: від 100000 до 1000000 токенів (з 2.1.296)
skills	скіли, які треба одразу завантажити в контекст агента (повністю, не лише опис)
mcpServers	MCP-сервери саме для цього агента: назва вже налаштованого сервера або inline-визначення
hooks	хуки життєвого циклу лише для цього агента
memory	постійна пам’ять: user, project або local
background	true — завжди лишати агента у фоні, навіть коли Claude хоче на нього чекати
omitClaudeMd	true — стартувати без CLAUDE.md користувача, проєкту й локального (з 2.1.271)
effort	рівень зусиль: low, medium, high, xhigh, max (залежить від моделі)
isolation	worktree — запуск у тимчасовому git worktree; якщо агент нічого не змінив, worktree прибирається
color	колір агента в списку задач і транскрипті: red, blue, green, yellow, purple, orange, pink, cyan
initialPrompt	перше повідомлення, яке надсилається автоматично, коли агент працює як основна сесія (--agent)
experimental	експериментальні опції; ключ cacheTtl: 5m або 1h задає час життя prompt cache для запитів агента (з 2.1.248)

cacheTtl пишеться всередині experimental, а не на верхньому рівні:

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

Як знайти помилку в назві поля. Запустіть claude --debug і пошукайте в лозі ~/.claude/debug/<session-id>.txt рядок does not recognize or apply. Лог назве до п’яти нерозпізнаних полів і підкаже ймовірну правильну назву (з 2.1.296).

Коли Claude Code мовчки пропускає файл агента

Файл агента в теці проєкту, користувача чи організації не завантажиться, і сесія про це не повідомить, якщо:

• немає name — файл вважається документацією, яка просто лежить поруч з агентами;
• перший рядок файлу — не --- — frontmatter не розпізнається;
• name починається з -, містить : або довший за 256 символів — помилка пишеться в debug-лог;
• є name, але немає description — причина пишеться в debug-лог;
• YAML не парситься — файл пропускається, помилка в debug-лозі.

Перевірити теку до запуску сесії можна командою claude plugin validate .claude/agents (або ~/.claude/agents, з 2.1.233). Вона знайде файли з неробочим YAML, але не помітить файл без name.

Вибір моделі

Поле model визначає, на якій моделі працюватиме агент:

• аліас — sonnet, opus, haiku або fable;
• повний ID — наприклад claude-opus-5-5 або claude-sonnet-5 (ті самі значення, що й для --model);
• inherit — та сама модель, що й в основній розмові.

Claude може передати параметр model і для конкретного виклику, але лише як аліас. Модель субагента визначається в такому порядку:

1. параметр model конкретного виклику;
2. поле model у визначенні агента (inherit — модель основної розмови);
3. змінна середовища CLAUDE_CODE_SUBAGENT_MODEL;
4. модель основної розмови.

Нюанс, про який легко забути: якщо основна розмова вже працює на моделі тієї самої родини, аліас (напр. opus) вказує саме на модель основної розмови, включно з суфіксом [1m]. Тобто субагент отримає те саме розширене контекстне вікно.

Аліас у CLAUDE_CODE_SUBAGENT_MODEL завжди вказує на версію, на яку посилається аліас. Значення inherit у змінній еквівалентне її відсутності. Ця змінна сама по собі не змінює модель вбудованих Explore і Plan.

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

Перевірити, на якій моделі працює агент, можна командою /tasks: модель і рівень зусиль показуються в рядку агента (з 2.1.242).

Одна модель для всіх субагентів

CLAUDE_CODE_SUBAGENT_MODEL — лише значення за замовчуванням. Щоб примусово перевести всіх субагентів, учасників agent teams і агентів workflows на одну модель, додайте CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (з 2.1.257). Наприклад, усі субагенти на Haiku:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Поки FORCE увімкнено, поле model у визначеннях ігнорується. Форки й скіли з context: fork і model: inherit усе одно лишаються на моделі основної розмови.

Рівень зусиль (effort)

Поле effort задає власний рівень зусиль агента. Claude може передати effort і для окремого виклику (з 2.1.292), він переважає поле й діє після відновлення агента. Змінна CLAUDE_CODE_EFFORT_LEVEL переважає обидва. Якщо effort не задано, агент на моделі основної розмови працює на рівні сесії (/effort, --effort), а на іншій моделі рівень сесії не застосовується.

Також з версії 2.1.198 субагенти успадковують налаштування extended thinking основної розмови: якщо thinking увімкнено у вас, він увімкнений і в субагента.

Що дозволено субагенту: інструменти, дозволи, хуки

Які інструменти доступні субагентам

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

Перший фільтр прибирає в будь-якого субагента (навіть якщо інструмент указано в tools):

• Agent — коли досягнуто ліміту вкладеності;
• AskUserQuestion;
• EndConversation;
• EnterPlanMode;
• ExitPlanMode — якщо тільки permissionMode агента не plan;
• ScheduleWakeup, WaitForMcpServers, Workflow.

Другий фільтр діє для фонових субагентів (а за замовчуванням вони саме фонові). Такий агент зберігає всі MCP-інструменти, але з вбудованих лише: Read, Grep, Glob, LSP, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage, Artifact. Решта вбудованих інструментів мовчки зникає, тому одне й те саме визначення може мати різні інструменти на передньому плані й у фоні. Форки обидва фільтри оминають.

Як обмежити інструменти

Є два способи: tools як білий список і disallowedTools як чорний. Якщо задано обидва, спершу застосовується disallowedTools, потім tools вибирає з того, що лишилося.

Агент-дослідник, який може лише читати й запускати команди, але не редагує файли й не має MCP:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

Агент, який успадковує все, крім запису файлів (Bash і MCP лишаються):

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

Якщо жоден запис у tools не відповідає реальному інструменту (усі з помилками в назвах або недоступні субагентам), Claude Code зазвичай відмовиться запускати агента з помилкою Agent would be spawned with zero tools.

Для MCP-серверів працюють шаблони:

Мета	Поле	Приклад
усі інструменти одного сервера	tools	mcp__github__*
прибрати інструменти одного сервера	disallowedTools	mcp__github або mcp__github__*
прибрати всі MCP-інструменти	disallowedTools	mcp__*

Пастка: запис зі специфікатором у disallowedTools, наприклад Bash(git push *), прибирає весь Bash, а не лише git push. Щоб лишити Bash і заборонити тільки окремі команди, додайте правило Bash(git push *) у permissions.deny в налаштуваннях — воно діє і для основної розмови, і для субагентів.

Якщо назва MCP-сервера містить подвійне підкреслення (напр. reports__v2), у tools пишіть повну назву із __* на кінці: mcp__reports__v2__*. А запис mcp__reports у disallowedTools зачепить і reports__v2, бо назви його інструментів теж починаються з mcp__reports__.

Яких субагентів може запускати агент-координатор

Коли агент працює як основна сесія (claude --agent), він може запускати субагентів. Обмежити, яких саме, можна синтаксисом Agent(agent_type):

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

Тут дозволено лише worker і researcher. Agent без дужок дозволяє будь-яких, а відсутність Agent у списку забороняє запуск субагентів зовсім. Список у дужках працює тільки для агента в ролі основної сесії; у звичайного субагента він ігнорується. (У версії 2.1.63 інструмент Task перейменували на Agent, старі записи Task(...) працюють як аліаси.)

MCP-сервери лише для одного агента

Поле mcpServers дає агенту доступ до MCP-серверів, яких немає в основній розмові. Inline-сервери підключаються на старті агента й відключаються після його завершення, а посилання за назвою використовують з’єднання батьківської сесії:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline: доступний лише цьому агенту
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # За назвою: вже налаштований сервер
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

Це ще й спосіб заощадити контекст: описи інструментів «важкого» MCP-сервера не займатимуть місце в основній розмові, якщо оголосити сервер тільки в агенті, а не в .mcp.json.

Підтримуються типи stdio, http, sse і ws. На такі сервери діють ті самі обмеження, що й в основній сесії (--strict-mcp-config, --bare, корпоративні політики allowedMcpServers/deniedMcpServers).

Довіра до теки. Inline-сервер з агента в .claude/agents/ проєкту завантажиться лише після того, як ви довіритеся теці, з якої взято файл агента (з 2.1.238). Довіра до батьківської теки не рахується. Без перевірки довіри завантажуються посилання на вже налаштовані сервери та inline-сервери з ~/.claude/agents/, --agents, SDK або managed settings.

Режими дозволів

Поле permissionMode задає режим дозволів агента. Без нього агент успадковує режим основної розмови.

Режим	Поведінка
default	ручний режим: запитує дозвіл
acceptEdits	автоматично приймає редагування файлів і типові файлові команди в робочій директорії
auto	auto mode: фоновий класифікатор перевіряє команди
dontAsk	автоматично відхиляє все, що вимагало б запиту; явно дозволені інструменти працюють
bypassPermissions	без запитів дозволу; працює лише тоді, коли так працює й основна розмова
plan	режим планування, лише дослідження

Але основна розмова може переважити вашу настройку:

• якщо основна розмова в bypassPermissions, acceptEdits або auto mode, агент працює в тому самому режимі, а permissionMode ігнорується. В auto mode класифікатор ще й перевіряє підсумковий звіт агента перед тим, як той потрапить до Claude;
• якщо основна розмова в plan, агент теж лишається в plan;
• якщо основна розмова в default або dontAsk, агент отримує ваш режим — крім випадків, коли ви вказали bypassPermissions або auto недоступний.

Скіли, завантажені наперед

Поле skills вставляє вміст скілів у контекст агента на старті. Агент одразу знає правила команди й не витрачає кроки на пошук:

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

Завантажується повний вміст перших 32 різних скілів зі списку. Це поле не обмежує доступ: без нього агент усе одно може викликати скіли через інструмент Skill. Щоб заборонити скіли взагалі, приберіть Skill із tools або додайте в disallowedTools. Скіли з disable-model-invocation: true (зокрема вбудований /verify) наперед завантажити не можна. Це дзеркальна ситуація до скілу, що запускається в субагенті через context: fork.

Постійна пам’ять агента

Поле memory дає агенту теку, яка переживає перезапуски. Там агент накопичує знання: патерни кодової бази, знахідки з налагодження, архітектурні рішення.

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

Область	Розташування	Коли обрати
user	~/.claude/agent-memory/<name-of-agent>/	знання корисні в усіх проєктах
project	.claude/agent-memory/<name-of-agent>/	знання про проєкт, якими можна ділитися через git
local	.claude/agent-memory-local/<name-of-agent>/	знання про проєкт, які не варто комітити

Коли пам’ять увімкнено, системний промпт агента містить інструкції щодо читання й запису в теку пам’яті, а також перші 200 рядків або 25 КБ файлу MEMORY.md (що настане раніше). Інструменти Read, Write і Edit вмикаються автоматично. Пам’ять агента — частина auto memory: якщо вимкнути auto memory (autoMemoryEnabled або CLAUDE_CODE_DISABLE_AUTO_MEMORY), поле memory не діятиме.

Поради з пам’яттю:

• project — рекомендована область за замовчуванням: знаннями агента можна ділитися через систему контролю версій.
• Просіть агента звірятися з пам’яттю: «Переглянь цей PR і перевір у пам’яті патерни, які ти вже бачив».
• Після задачі просіть зберегти досвід: «Збережи в пам’ять, що ти дізнався».
• Найкраще — вписати інструкцію про пам’ять прямо в промпт агента:

Update your agent memory as you discover codepaths, patterns, library
locations, and key architectural decisions. This builds up institutional
knowledge across conversations. Write concise notes about what you found
and where.

Умовні правила через хуки

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

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Claude Code передає хуку JSON через stdin. Скрипт дістає команду й завершується з кодом 2, щоб заблокувати запис:

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Блокуємо SQL-операції запису (без урахування регістру)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

На macOS і Linux зробіть скрипт виконуваним, інакше хук завершиться помилкою й нічого не заблокує:

chmod +x ./scripts/validate-readonly-query.sh

Перевірка: попросіть агента виконати UPDATE. Скрипт поверне код 2, Claude Code заблокує команду, а агент побачить повідомлення Blocked: Only SELECT queries are allowed. У Windows хуки пишуть на PowerShell і додають shell: powershell.

Як вимкнути окремих субагентів

Додайте агента в масив deny налаштувань у форматі Agent(назва):

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

Працює і для вбудованих, і для кастомних агентів. Те саме з командного рядка: claude --disallowedTools "Agent(Explore)".

Хуки для субагентів

Хуки можна налаштувати двома способами:

• у frontmatter агента — працюють лише поки цей агент активний;
• у settings.json — хуки сесії, які спрацьовують і всередині субагентів. PreToolUse/PostToolUse з налаштувань спрацюють і перед інструментами субагента, а SubagentStart і SubagentStop — коли агент стартує й завершується.

Хуки у frontmatter агента проєкту запускаються лише після того, як ви прийняли діалог довіри для теки з файлом агента. До того агент працює, але хуки пропускаються (з помилкою в debug-лозі). Хуки агентів із ~/.claude/agents/ і --agents працюють без цього кроку.

Найуживаніші події:

Подія	Matcher	Коли спрацьовує
PreToolUse	назва інструмента	перед використанням інструмента
PostToolUse	назва інструмента	після використання інструмента
Stop	—	коли агент завершує роботу (перетворюється на SubagentStop)

Агент, який перевіряє Bash-команди перед запуском і запускає лінтер після кожного редагування:

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

У settings.json можна реагувати на події життєвого циклу агентів. Цей приклад запускає скрипт підготовки лише для db-agent і прибирання — після завершення будь-якого агента:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

Для агентів плагінів matcher — scoped-назва з двокрапкою, яка обробляється як регулярний вираз. Щоб зачепити лише одного агента, якоріть її: ^my-plugin:db-agent$.

Як працювати з субагентами щодня

Автоматичне делегування

Claude делегує задачі сам, зважаючи на ваш запит, description агентів і поточний контекст. Щоб заохотити проактивне делегування, додайте в опис фрази на кшталт «use proactively». Якщо агент поставляється в плагіні, надійність делегування можна виміряти на реалістичних запитах командою claude plugin eval.

Явний виклик: три рівні

Звичайною мовою. Назвіть агента в запиті, і Claude зазвичай делегує:

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

Через @-згадку. Наберіть @ і виберіть агента з підказок, як файл. Це гарантує, що запуститься саме цей агент:

@"code-reviewer (agent)" look at the auth changes

Повне повідомлення все одно йде до Claude, який сам формулює задачу для агента. @-згадка визначає, кого запустити, але не що саме йому сказати. Згадку можна набрати й вручну: @agent-<name> або @agent-my-plugin:code-reviewer для агентів плагінів.

Уся сесія як агент. Прапорець --agent <name> запускає сесію, у якій основний потік сам стає цим агентом, з його обмеженнями інструментів і моделлю:

claude --agent code-reviewer

Системний промпт кастомного агента повністю замінює стандартний системний промпт Claude Code (як --system-prompt), але CLAUDE.md і пам’ять проєкту все одно завантажуються. Назва агента показується в заголовку як @<name>, а вибір зберігається при відновленні сесії. Щоб зробити агента типовим для проєкту, задайте його в .claude/settings.json:

{
  "agent": "code-reviewer"
}

Прапорець CLI має пріоритет над налаштуванням.

Передній план і фон

• Субагенти на передньому плані блокують основну розмову, поки не завершаться. Запити дозволів передаються вам по черзі.
• Фонові субагенти працюють паралельно, поки ви продовжуєте роботу. Коли фоновому агенту потрібен дозвіл, Claude Code показує запит в основній сесії й називає агента. Можна погодитися або натиснути Esc, щоб відхилити лише цей виклик, не зупиняючи агента.

За замовчуванням субагент, якого Claude запускає з основної розмови, стартує у фоні. У claude -p і Agent SDK Claude може чекати на результат на власний розсуд. В інтерактивному терміналі, VS Code і desktop-застосунку, щоб Claude міг чекати на агента, треба вимкнути режим форків:

{
  "env": {
    "CLAUDE_CODE_FORK_SUBAGENT": "0"
  }
}

Після цього перезапустіть claude і просіть: «запусти reviewer-агента й дочекайся звіту». Щоб працювати далі, поки Claude чекає, натисніть Ctrl+B у терміналі або Run in background у VS Code. Змінна CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 змушує Claude завжди чекати на агентів, але вимикає й фонові команди.

Що варто знати про фонових агентів:

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

Успішно завершений агент одразу зникає з панелі під полем вводу, а внизу на 30 секунд з’являється підказка /tasks to see subagents. За цей час можна відкрити /tasks і переглянути транскрипт агента. Агенти, що впали або були зупинені, лишаються в панелі 30 секунд; прибрати рядок раніше — виділити й натиснути x.

Імена субагентів

Якщо ввімкнено agent teams, Claude може дати субагенту ім’я параметром name — і зробити це без вашого запиту. Ім’я робить агента адресованим: після завершення йому можна написати або відновити його за іменем. В інтерактивній сесії з agent teams субагент з іменем запускається як teammate (крім форків і викликів з isolation).

Коли API повертає помилку

Якщо відповідь субагента обірвалася на півдорозі й містить текст без викликів інструментів, Claude Code просить агента продовжити, а не завершує роботу. Якщо ж робота закінчилася на помилці API (ліміт використання, повторна помилка сервера):

• на передньому плані — Claude отримує частковий результат з позначкою, що агент не завершив задачу, або помилку Agent terminated early due to an API error;
• у фоні — агент позначається як невдалий, а повідомлення містить помилку й останній вивід, тож часткова робота не губиться.

Якщо звіт починається з рядка ⚠ This agent switched to <model> because its earlier model could not be used., агент завершив роботу на резервній моделі з ланцюжка fallback-моделей. Коли помилка зникне, попросіть Claude повторити задачу або відновити агента.

Захист від інструкцій у звітах агентів

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

• вставляє зворотну косу риску в текст, що імітує службовий вивід Claude Code (тег <system-reminder>, рядки Human: чи Assistant:), щоб імітація читалася як звичайний текст;
• додає службовий рядок [harness: subagent output matched instruction-shaped pattern(s): …, якщо звіт імітує такі теги або згадує налаштування дозволів на кшталт bypassPermissions.

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

Контекст субагента: що він бачить і що пам’ятає

Що завантажується на старті

Кожен субагент (крім форка) стартує зі свіжим ізольованим контекстом. Він не бачить історії вашої розмови, скілів, які ви вже викликали, і файлів, які Claude уже прочитав. Claude складає для нього повідомлення-делегування з описом задачі.

Початковий контекст звичайного субагента:

• системний промпт — власний промпт агента плюс відомості про оточення (не системний промпт Claude Code);
• повідомлення із задачею — промпт-делегування, яке пише Claude;
• файли CLAUDE.md — уся ієрархія, яку завантажує основна розмова (~/.claude/CLAUDE.md, правила проєкту, CLAUDE.local.md, managed-політики, AGENTS.md). Explore і Plan це пропускають; агент з omitClaudeMd завантажує лише managed-політики;
• git status — знімок репозиторію на момент старту агента (для агента у worktree — стан worktree). Explore і Plan пропускають завжди;
• наперед завантажені скіли з поля skills;
• перелік «сусідів» — список main і всіх інших іменованих агентів сесії, яким можна написати через SendMessage (лише якщо агент має SendMessage і в сесії є інші іменовані агенти).

Чого субагент ніколи не отримує: вашого output style, auto memory основної розмови і розміру контекстного вікна батьківської моделі — вікно визначається моделлю самого агента.

Практичний висновок: якщо правило конче має дійти до агента (наприклад, «не чіпай теку vendor/»), повторіть його в запиті, коли делегуєте задачу. Основна розмова однаково має ваш повний CLAUDE.md, коли читає результати.

Як продовжити роботу субагента

Кожен виклик створює новий екземпляр агента. Щоб продовжити роботу наявного, а не починати з нуля, попросіть Claude його відновити. Відновлений агент має всю історію: попередні виклики інструментів, результати й міркування.

Use the code-reviewer subagent to review the authentication module
[агент завершує роботу]

Continue that code review and now analyze the authorization logic
[Claude відновлює агента з повним контекстом попередньої розмови]

Як це працює:

• коли агент завершується, Claude отримує його ID;
• Claude відновлює агента інструментом SendMessage, передаючи ID або ім’я в поле to. Для цього не потрібні agent teams;
• вбудовані Explore і Plan одноразові, ID не повертають і відновити їх не можна. Для тривалої роботи використовуйте general-purpose або власного агента;
• агента, зупиненого на ліміті maxTurns, можна відновити, щоб він закінчив роботу;
• агента, якого ви зупинили самі (x у /tasks), автоматично не відновиш: повідомлення від Claude буде відхилено. Але поки його рядок у панелі, можна написати в його транскрипт самостійно.

Відновлений агент продовжує працювати у фоні з тим самим набором інструментів і може використати prompt cache попереднього запуску.

Транскрипти субагентів зберігаються окремо: ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl. Вони не зачіпаються, коли основна розмова стискається, переживають перезапуск Claude Code при відновленні тієї самої сесії й видаляються через cleanupPeriodDays (за замовчуванням 30 днів).

Якщо після перезапуску Claude не може написати агенту за іменем, дайте йому ID агента: його можна знайти у файлах agent-{agentId}.meta.json у тій самій теці.

Автоматичне стискання контексту

Субагенти підтримують автоматичне стискання (compaction): воно спрацьовує, коли заповнюється власне вікно агента. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE діє і на субагентів. У транскрипті подія виглядає так:

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

preTokens показує, скільки токенів було до стискання. Щоб конкретний агент стискався раніше (наприклад, той, що читає довгі логи), задайте autoCompactWindow:

---
name: log-reader
description: Reads long log files and reports the errors it finds
autoCompactWindow: 200000
---

Пишіть число повністю (200000): 200k у frontmatter прочитається як 200, а це поза дозволеним діапазоном, і поле просто проігнорується. Якщо задано змінну CLAUDE_CODE_AUTO_COMPACT_WINDOW, вона переважає поле.

Субагенти всередині субагентів

За замовчуванням субагент може запускати власних субагентів — до трьох рівнів нижче основної розмови. На граничному рівні Claude Code забирає інструмент Agent (у форка інструмент лишається, але повертає помилку), тож агент виконує задачу сам і повертає один підсумок.

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

Змінити глибину можна змінною CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Значення 1 вимикає вкладеність. Щоб окремий агент (скажімо, рев’юер лише для читання) не запускав інших, приберіть Agent з його tools або додайте в disallowedTools. У терміналі вкладені агенти показуються деревом, а рядки з нащадками мають лічильник (+N).

Ліміт одночасних субагентів

Окремо від глибини діє ліміт одночасності: коли в сесії працює 20 субагентів, запуск ще одного завершується помилкою Concurrent subagent limit reached, і Claude отримує вказівку не повторювати спробу. Змінити ліміт можна змінною CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (з 2.1.217). Загальної кількості агентів за сесію ніщо не обмежує. Агенти workflows і учасники agent teams мають власні ліміти.

Форки: гілка поточної розмови

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

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

/subtask draft unit tests for the parser changes so far

Форк з’явиться в панелі під полем вводу й працюватиме у фоні, а ви продовжите реалізацію в основній сесії. Коли він закінчить, результат прийде повідомленням.

Якщо agent view вимкнено, /subtask недоступна, і форк запускає /fork. В іншому разі /fork копіює всю сесію в нову фонову сесію.

Керування панеллю форків:

Клавіша	Дія
↑ / ↓	переміщення між рядками
Enter	відкрити транскрипт форка й писати йому повідомлення
x	зупинити форк або прибрати рядок завершеного
Esc	повернути фокус у поле вводу

У відкритому транскрипті форка повідомлення й скіли йдуть цьому агенту, /btw відповідає з його транскрипту (з 2.1.314), а /compact, /clear і /rewind діють на основну розмову й потребують підтвердження. Ctrl+Enter надсилає повідомлення так, щоб агент прочитав його, не чекаючи завершення поточної роботи.

Чим форк відрізняється від звичайного субагента

	Форк	Звичайний субагент
Контекст	уся історія розмови	свіжий контекст із промптом-задачею
Системний промпт та інструменти	як в основній сесії	з файлу агента, з фільтрами для фону
Модель	як в основній сесії	з поля model
Prompt cache	спільний з основною сесією	окремий

Через спільний кеш форк дешевший за свіжого агента там, де потрібен той самий контекст. Форк може отримати isolation: "worktree", щоб писати зміни в окремий worktree. Форк не може запускати інші форки.

Вимкнути форки: додати "Agent(fork)" у permissions.deny або задати CLAUDE_CODE_FORK_SUBAGENT=0. Режим форків увімкнений за замовчуванням із 2.1.302 (в інтерактивному терміналі — з 2.1.232).

Готові субагенти: що інженери реально використовують

Теорія закінчилася, переходимо до практики. Нижче зібрано агентів, які найчастіше трапляються в документації Anthropic, на Reddit (r/ClaudeAI, r/ClaudeCode), у DEV Community і збірках на кшталт ClaudeWorld, VibeKits та PrompTessor. Кожен файл можна скопіювати в .claude/agents/ і підлаштувати під свій стек. Системні промпти лишаємо англійською: так їх простіше ділити з командою, а модель однаково зрозуміє.

1. Code reviewer — рев’юер лише для читання

Найпопулярніший агент у всіх джерелах. Він не має Edit і Write, тож фізично не може «виправити» код під час перевірки, а великий diff лишається в його контексті. Ось приклад з офіційної документації:

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

Що можна покращити, за досвідом спільноти: додати жорсткий формат звіту (див. розділ про контракт виводу) і model: sonnet замість inherit, якщо основна сесія працює на дорожчій моделі. Автори збірок ClaudeWorld і PrompTessor називають такого рев’юера одним із найкорисніших кастомних агентів.

2. Debugger — шукає першопричину й виправляє

На відміну від рев’юера, цей агент має Edit, бо виправлення бага вимагає змін у коді. Промпт задає чіткий процес від діагностики до перевірки:

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

Практична порада зі слайдів NotebookLM і блогів: додайте maxTurns: 15 як запобіжник. Агент, який крутиться в циклі «відтворити → виправити → перевірити», без ліміту може довго палити токени на безнадійній гіпотезі.

3. Test runner — тести на дешевій моделі

Запуск тестів генерує тисячі рядків логів, які миттєво з’їдають контекст. У блозі TrueFoundry це названо «підручниковою задачею для Haiku»: модель дешева, а роботи на міркування мало.

---
name: test-runner
description: Runs the test suite and returns only failing cases. Use proactively after code changes.
tools: Read, Edit, Bash, Grep, Glob
model: haiku
maxTurns: 20
---

You run tests and fix only what is broken.

Process:
1. Detect the test command (package.json scripts, Makefile, pytest.ini).
2. Run the full suite once.
3. For each failing test: read the test and the code under test, find the cause.
4. Fix the code, not the test. Never delete or skip a failing test.
5. Re-run only the failing tests until they pass, then run the full suite once more.

Output:
- Summary line: X passed, Y failed before; X passed, Y failed after.
- For each fix: file:line, cause in one sentence, what changed.
Do not print passing test output or full logs.

Рядок «Fix the code, not the test. Never delete or skip a failing test» — не перестраховка. Користувачі Reddit описують ситуації, коли агент «досягав успіху», видаляючи тести, що падали.

4. Security auditor — другі очі перед деплоєм

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

---
name: security-auditor
description: Audits auth, payments, personal data handling and secrets for OWASP Top 10 issues. Use proactively before deploys and after changes in these areas.
tools: Read, Grep, Glob
model: sonnet
---

You are an application security reviewer. Check the changed code for:
- injection (SQL, command, template), XSS, SSRF
- broken auth and session handling, missing authorization checks
- secrets in code or logs, weak crypto
- unsafe deserialization and file uploads

Rules:
- Report only issues you can point to in the code. No theoretical lists.
- Do not modify files.

For each finding: Severity (Critical/High/Medium/Low), Location (file:line),
Evidence (the code), Impact, Recommended fix.

5. «Перевіряльник реальності» — проти фейкового успіху

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

У треді «Sub Agents are a GAME CHANGER!» автор описує агента quality-control-enforcer, який на кожній точці зупинки шукає обхідні рішення, фейкові дані й виправлення симптомів замість причини. В іншому треді r/ClaudeAI агента з тією самою роллю назвали karen і описали як «найкориснішого субагента»: вона «викриває все, що інші агенти підфарбували», а інші агенти працюють відповідальніше, бо знають, що попереду перевірка. Спрощена версія:

---
name: reality-check
description: Verifies that tasks marked complete actually work. Use proactively whenever an agent or the main session reports a task as done.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You verify claims of completion. Trust nothing, check everything.

For each claimed result:
1. Find the code that implements it. Look for mocks, hardcoded values,
   TODOs, commented-out checks, skipped or deleted tests.
2. Run the relevant tests or commands yourself.
3. Check that the root cause is fixed, not just the symptom.

Output a table: Claim | Status (works / partial / fake) | Evidence | What is missing.
End with a realistic list of remaining work.

Автор треду радить ще й таку хитрість: додати в промпт або CLAUDE.md рядок IMPORTANT: USE THIS AGENT AGAIN NEXT TIME, щоб основна сесія не забувала викликати перевіряльника на наступній точці зупинки.

6. Git workflow — рутина на Haiku

Створення гілок, коміти за конвенцією, опис PR, changelog. Задача механічна, тому Haiku тут вистачає з головою, а за сотень викликів на місяць економія помітна. Такого агента описує автор статті на DEV Community, який розбив свій React-проєкт на 12 спеціалізованих агентів.

---
name: git-workflow
description: Creates branches, conventional commits, PR descriptions and changelog entries. Use when the user asks to commit, branch or open a PR.
tools: Bash, Read
model: haiku
---

Follow Conventional Commits (feat, fix, docs, refactor, test, chore).
Before committing: run git status and git diff --staged, never commit
.env files or secrets. Never push or force-push unless explicitly asked.
Return: the commit message(s) and the list of committed files.

7. Read-only researcher — дослідник із таблицею на виході

Агент для пошуку по кодовій базі або документації за фіксованим шаблоном звіту. Японський автор на note.com описує, як обмеження до Read, Grep, Glob, WebFetch дало «зовсім інший рівень спокою»: агент більше не кидався сам виправляти й комітити код, а повертав акуратну таблицю.

---
name: code-researcher
description: Read-only research of the codebase: architecture, dependencies, call sites. Use for questions like "where is X used" or "how does Y work".
tools: Read, Grep, Glob, WebFetch
model: haiku
---

Answer the question with evidence from the code. Never modify files.

Output exactly these sections:
1. Short answer (2-3 sentences)
2. Key files (path:line — role)
3. Call flow (numbered steps)
4. Open questions / what you could not verify

8. Data scientist — аналітика поза програмуванням

Приклад з документації Anthropic, який показує, що субагенти корисні не лише для коду. Тут явно задано model: sonnet для якіснішого аналізу:

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

Якщо агент працює з продакшн-базою, поєднайте його з хуком read-only з прикладу db-reader вище. Промпт просить агента не писати в базу, а хук гарантує це на рівні системи.

Як писати description і системний промпт

Від description залежить, чи покличе Claude агента взагалі, а від промпту — що агент поверне. Джерела тут напрочуд одностайні.

Формула опису

description — це правило маршрутизації, а не реклама агента. Робоча формула:

що робить агент + коли його кликати + що він повертає

Погано	Добре
Helps with code	Review recent code changes for bugs, security problems and readability. Use proactively after writing or changing code.
Testing agent	Runs the test suite and returns only failing cases. Use proactively after code changes.
Debugger	Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.

Фрази use proactively або MUST BE USED прямо підштовхують Claude делегувати без вашого нагадування. Але не ставте їх на всіх агентів підряд: якщо кожен «must be used», жоден не виділяється. І пам’ятайте про бюджет у 15 000 токенів на всі описи.

Структура промпту з п’яти блоків

Автори практичних гайдів радять будувати тіло агента з п’яти розділів:

## Objective
What the final result must be.

## Required context
What to read first: git diff, PR description, spec, failing test output.

## Process
1. Gather evidence  2. Analyze  3. Verify conclusions

## Constraints
What the agent must NOT do: "Do not modify files", "Never delete a test".

## Output
The exact report format (see below).

Контракт виводу: найважливіше, що ви напишете

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

## Output Format

Report findings by priority:
- 🔴 Must fix (critical bugs, security flaws, missing validation)
- 🟡 Should fix (poor error handling, missing tests, anti-patterns)
- 🟢 Nice to have (readability, naming)

For each item:
1. File and line
2. Evidence (what was observed)
3. Impact and suggested fix

Do not print raw logs, passing test output, or full file contents.
Return only the actionable summary.

Патерни оркестрації: як поєднувати агентів

Один агент — це інструмент. Кілька агентів, правильно з’єднаних, — це вже процес. У джерелах повторюються шість схем.

Паралельне дослідження

Основна сесія одночасно запускає 3–5 агентів лише для читання, зазвичай на Haiku, і кожен досліджує свою частину проєкту. Назад повертаються стислі підсумки, а сотні прочитаних файлів лишаються поза основним контекстом.

Research the authentication, database, and API modules in parallel
using separate subagents. Use haiku, read-only. Each returns a
10-line summary with key files.

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

Послідовний ланцюжок

Результат одного агента стає вхідними даними для наступного: дослідник → планувальник → виконавець → тести → рев’ю.

Use the code-reviewer subagent to find performance issues in
src/services/, then use the optimizer subagent to fix them.

Оркестратор і виконавці

Основна сесія (або агент-координатор, запущений через claude --agent) ділить фічу на вузькі підзадачі й роздає спеціалістам. Цікаво, що той самий принцип рольової декомпозиції використовують і поза програмуванням: наприклад, TradingAgents відтворює трейдингову фірму з аналітиків, дослідників і ризик-менеджерів. Приклад з DEV Community:

Implement the Departments feature:
1. Have component-architect design the component hierarchy.
2. Have schema-type-generator create TypeScript types and Zod schemas.
3. Have senior-dev implement services and UI based on those types.
4. Have git-workflow commit the changes.

Реалізація, потім незалежна перевірка

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

Review the changes after implementation: run code-reviewer for quality,
security-auditor for the auth module, and reality-check to confirm that
tests actually pass without shortcuts.

Спершу план, потім код

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

Use feature-planner to analyze migrating the user service from REST to
GraphQL. Produce a step-by-step file plan with risks. Do not modify any
files until I approve the plan.

Паралельні зміни в ізольованих worktree

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

---
name: ui-implementer
description: Implements isolated UI changes in its own worktree
isolation: worktree
tools: Read, Edit, Write, Bash
---

Run 3 subagents in parallel, each in its own worktree: one refactors
payment/checkout.ts, one payment/subscription.ts, one payment/types.ts.

Скільки це коштує і як не переплатити

Субагенти не безкоштовні фонові процеси: їхні запити списуються з того самого ліміту підписки чи API-кредитів. До того ж кожен агент на старті заново завантажує свій промпт, CLAUDE.md і знімок git status. У практичних гайдах (TrueFoundry, Nimbalyst) трапляється оцінка, що інтенсивна мультиагентна робота може споживати до ~7 разів більше токенів, ніж одна послідовна сесія. Це оцінка авторів блогів, а не офіційна цифра, але порядок витрат вона показує добре.

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

Головний важіль — модель під задачу

Модель	Для яких ролей
haiku	пошук по коду, запуск тестів, читання логів, git-операції, документація
sonnet	написання коду, рев’ю, налагодження, аудит безпеки, рефакторинг
opus / fable	складні архітектурні рішення, великий рефакторинг, критичні оцінки ризиків

Що саме вміє найновіша модель і коли вона виправдовує свою ціну, ми розбирали окремо: Claude Fable 5.2: що вміє нова модель Anthropic.

Пастка, про яку пишуть майже всі: якщо не вказати model, агент успадкує модель основної сесії. Працюєте в Opus — і test-runner теж ганятиме тести на Opus. Вказуйте модель явно або задайте для всіх CLAUDE_CODE_SUBAGENT_MODEL (див. вибір моделі).

Інші способи економити:

• обмежуйте tools — агент лише для читання не тільки безпечніший, а й має менше описів інструментів у контексті;
• ставте maxTurns агентам, що працюють у циклі;
• забирайте Agent в агентів, яким не треба запускати власних субагентів;
• використовуйте форки там, де потрібен весь контекст розмови: вони діляться prompt cache з основною сесією.

Коли субагент не потрібен

• Дрібна одноразова задача. У субагента є накладні витрати на старт і збирання контексту. Відформатувати файл чи відповісти на коротке питання основна сесія зробить швидше.
• Тісно пов’язана робота. Агенти не бачать роботи один одного. Якщо дві підзадачі мають спільний стан (наприклад, інтерфейс і його реалізацію), розбиття призведе до розсинхрону.
• Потрібні постійні уточнення. Якщо задачу треба коригувати на кожному кроці, лишайтеся в основній розмові.
• Етапи спираються на один контекст. Коли планування, реалізація й тести опираються на накопичене обговорення, винесення кожного кроку в окремого агента змусить щоразу збирати цей контекст заново.
• Питання про те, що вже є в розмові. Для цього є /btw: без інструментів, і відповідь не додається в історію.

Субагенти не лише для коду

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

Продакт-менеджмент. Курс «Claude Code for PMs» (ccforpms.com) пропонує набір ролей для рев’ю продуктових документів: executive перетворює розлогий звіт спринту на три пункти для керівництва, user-researcher розбирає транскрипти інтерв’ю й витягає болі користувачів із цитатами, engineer оцінює технічну здійсненність PRD і крайні випадки, qa-tester шукає прогалини в user stories і нечіткі критерії приймання.

Аналітика. Окрім data-scientist з документації, трапляються агенти для розрахунку продуктових метрик і розбору результатів A/B-тестів.

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

Контент і документація. docs-writer на Haiku оновлює README, інструкції й описи API та редагує лише Markdown-файли.

Ось як це може виглядати для SEO-фахівця чи маркетолога. Цей приклад наш, ми склали його для ілюстрації (а про те, як потрапити у відповіді самих ШІ-асистентів, читайте в гайді про GEO):

---
name: seo-page-auditor
description: Audits a single page or a built HTML file for on-page SEO issues. Use when the user asks to check a page's SEO.
tools: Read, Grep, Glob, WebFetch
model: sonnet
---

Check: title (length, keyword), meta description (120-160 chars), one H1,
heading hierarchy, canonical, robots meta, alt texts, internal links,
JSON-LD validity, hreflang if present.

Output a table: Check | Status (ok / warning / error) | Evidence | Fix.
Do not rewrite the page. Max 20 rows, most important first.

Субагенти, скіли, команди, хуки чи agent teams?

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

Механізм	Де працює контекст	Хто запускає	Найкраще для
Субагенти	окреме вікно, повертає підсумок	Claude автоматично (за description) або ви явно	пошук, рев’ю diff, логи й тести без засмічення розмови
Skills	основна розмова	модель за контекстом або ви через /назва	повторювані інструкції, плейбуки, процедури
Slash-команди	основна розмова	лише ви	швидкі ручні дії й керування сесією
Hooks	поза моделлю, це скрипти	подія (PreToolUse, PostToolUse…)	гарантовані дії: лінтер, блокування небезпечних команд
Agent teams	окремі незалежні сесії	агент-лідер, спільний список задач	великі паралельні задачі, де агенти мають спілкуватися між собою

Як обирати:

• Skill чи субагент? Скіл пояснює, як зробити задачу всередині поточної розмови. Субагент — окремий працівник, який забирає «шум» у своє вікно. Потрібна процедура й важливий поточний контекст — скіл. Задача породжує сотні рядків виводу — субагент. Їх можна поєднати: скіл можна запускати в субагенті через context: fork або завантажити в агента полем skills.
• Hook чи субагент? Хук — детермінований код без участі моделі. Якщо дія має відбуватися завжди, без винятків (лінтер після кожного редагування, заборона git push --force), це хук. Якщо потрібне судження — субагент.
• Agent teams чи субагенти? Субагент підпорядковується основній сесії й звітує лише їй. Учасники agent teams — незалежні сесії, які спілкуються напряму й ділять список задач. Teams коштують помітно дорожче, тому джерела радять починати з субагентів.

Типові помилки та як їх уникнути

1. Агенти-«швейцарські ножі» і зоопарк із 50 агентів. Один агент, який планує, пише код, рев’юїть і пише документацію, або десятки агентів з інструкцією «допомагай з кодом». Оркестратор плутається, підтримувати це важко. Рішення: одна задача — один агент. Почніть із двох-трьох вузьких агентів, наприклад code-reviewer і debugger, і додавайте нових лише тоді, коли бачите повторювану потребу.

2. Розмитий або роздутий description. Helps with code — і Claude або кличе агента не до місця, або не кличе взагалі. Протилежна крайність — довгі інструкції прямо в описі, які постійно сидять у контексті. Рішення: опис — коротке правило маршрутизації, а все інше — в тіло файлу.

3. Незадана модель. Агент успадковує дорогу модель основної сесії й ганяє на ній рутину. Рішення: явно вказуйте model під складність задачі.

4. Дослідник, який раптом став виконавцем. Агенту, що мав лише проаналізувати код, дали Edit і Write, і замість звіту він почав правити й комітити. Рішення: принцип мінімальних привілеїв. Дослідникам, рев’юерам і аудиторам — лише Read, Grep, Glob (і за потреби Bash).

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

6. Агент сам приймає власну роботу. Пише код, сам перевіряє, рапортує успіх, а насправді там моки або видалені тести. Рішення: окремий незалежний перевіряльник на кшталт reality-check і правило «ніколи не видаляй тест, що падає» в промпті виконавця.

7. Немає контракту виводу. Агент повертає гігантський лог і перекреслює всю користь ізоляції. Рішення: жорсткий формат звіту в кінці промпту із забороною виводити сирі логи.

8. Правила з CLAUDE.md, які «загубилися». Ви розраховуєте, що агент знає правило з вашої розмови, а він його не бачив. Рішення: пам’ятайте, що агент бачить лише свій промпт, CLAUDE.md (крім Explore/Plan і агентів з omitClaudeMd) і повідомлення-делегування. Критичні правила повторюйте в запиті.

9. Помилка в назві поля. allowedTools замість tools або max_turns замість maxTurns, і обмеження просто не діє, бо невідомі поля мовчки ігноруються. Рішення: claude --debug і пошук does not recognize or apply у лозі.

Чекліст ідеального субагента

Перш ніж зберегти нового агента, пройдіться списком:

• Одна задача. Можете описати роль агента одним реченням.
• Точний тригер. description відповідає на питання «коли мене кликати?» і вміщується у два речення.
• Мінімальні привілеї. Агенти, які лише аналізують, не мають Edit і Write; MCP-сервери, яких агент не потребує, прибрані.
• Явна модель. haiku для рутини, sonnet для коду й аналізу, opus лише там, де це виправдано.
• Контракт виводу. Промпт закінчується форматом звіту й забороною сирих логів.
• Запобіжники. maxTurns для агентів у циклі; хук для операцій, які мають бути заблоковані гарантовано.
• Правильне місце. Агент проєкту — в .claude/agents/ і в git; особистий — у ~/.claude/agents/.
• Перевірка. Запустіть агента явно на реальній задачі й подивіться його транскрипт у /tasks.

З чого почати сьогодні

1. Створіть .claude/agents/code-reviewer.md з прикладу вище й попросіть: «Use the code-reviewer subagent to review my recent changes».
2. Додайте test-runner на Haiku і подивіться, наскільки чистішою лишається основна розмова після прогону тестів.
3. Коли побачите, що щодня даєте Claude ту саму інструкцію, — це кандидат у наступного агента.
4. Ще через тиждень перегляньте описи всіх агентів і скоротіть ті, що розрослися.

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

Часті запитання

Як створити субагента в Claude Code?

Найпростіше — попросити самого Claude: «Створи субагента code-reviewer у .claude/agents/, лише для читання, на Sonnet». Або створіть Markdown-файл вручну: у frontmatter вкажіть щонайменше name і description, а під ним напишіть системний промпт. Файл у .claude/agents/ діє в поточному проєкті, у ~/.claude/agents/ — в усіх ваших проєктах. Покроково це описано в розділі «Швидкий старт».

Чим субагент відрізняється від skill?

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

Скільки коштують субагенти?

Окремої плати немає: запити субагентів списуються з того самого ліміту підписки або API-кредитів, що й основна розмова. Кожен агент на старті заново завантажує промпт, CLAUDE.md і git status, тому інтенсивна мультиагентна робота витрачає помітно більше токенів. Зекономити допомагають дешевша модель для рутини, обмеження інструментів і maxTurns.

Як запустити субагента на Haiku?

Додайте у frontmatter агента рядок model: haiku. Щоб усі субагенти за замовчуванням працювали на Haiku, задайте змінну CLAUDE_CODE_SUBAGENT_MODEL=haiku. Щоб примусово перевести на неї всіх, включно з агентами, де модель уже вказана, додайте ще й CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1.

Чому Claude не викликає мого субагента?

Найчастіші причини: розмитий description, файл без name або description, помилка в YAML або тека agents створена вже після старту сесії (тоді потрібен перезапуск). Перевірте файл командою claude plugin validate .claude/agents, а в описі чітко вкажіть, коли агента кликати, наприклад «Use proactively after code changes». Або викличте агента явно через @-згадку.

Чи бачить субагент мою розмову і CLAUDE.md?

Історію розмови звичайний субагент не бачить: він отримує лише свій системний промпт, повідомлення із задачею від Claude, файли CLAUDE.md і знімок git status. Виняток — вбудовані Explore і Plan, а також агенти з omitClaudeMd: true: вони стартують без CLAUDE.md. Усю історію розмови бачить лише форк.

Скільки субагентів можна запустити одночасно?

За замовчуванням до 20 одночасно (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) і до трьох рівнів вкладеності (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH). Загальну кількість агентів за сесію ніщо не обмежує. На практиці паралельно варто тримати 3–5 агентів, інакше їхні звіти самі почнуть засмічувати контекст.

Як заборонити субагенту редагувати файли?

Задайте білий список tools: Read, Grep, Glob або чорний disallowedTools: Write, Edit. Так агент фізично не зможе змінювати код. Якщо потрібно лишити Bash, але заборонити окремі команди, додайте правило на кшталт Bash(git push *) у permissions.deny в налаштуваннях або хук PreToolUse, як у прикладі з db-reader.

Джерела

Основне джерело — офіційна документація Anthropic Create custom subagents. Практичні розділи зібрано з таких матеріалів (через NotebookLM):

• Creating a subagent — Claude Academy
• Sub Agents are a GAME CHANGER! — r/ClaudeCode
• What’s your best way to use Sub-agents in Claude Code so far? — r/ClaudeAI
• How I Turned Claude Code Into a Multi-Agent Dev Team — DEV Community
• 10 Essential Claude Code Custom Agents — ClaudeWorld
• Claude Code Agents: Complete Guide — ClaudeWorld
• Claude Code Subagents Examples: 7 to Copy — VibeKits
• Best Claude Code Subagents and Custom Agent Examples in 2026 — PrompTessor
• Claude Code Subagents: What They Are and How to Use Them — TrueFoundry
• Claude Code Subagents: A Practical 2026 Guide — Nimbalyst
• Claude Code Subagents: Build a Custom Code Reviewer — Jonathan’s Blog
• Claude Code Subagents Documentation and Examples — Better Design
• Custom AI Agents for Product Reviews — Claude Code for PMs
• The night I had Claude Code create a 6-item fixed Markdown — note.com