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

Як створити агента в Claude: що саме ви створюєте

Якщо ви хочете створити власного агента в Claude, вам майже завжди потрібен субагент Claude Code. Субагент є файлом Markdown із заголовком YAML (простий текстовий формат «ключ: значення») у теці .claude/agents/. Обов'язкові лише два поля, name і description. Кожен субагент працює у власному контекстному вікні і повертає основній розмові тільки підсумок своєї роботи.

Проєкти (Projects) на claude.ai не є агентами: це набір файлів та інструкцій для звичайного чату. Agent SDK і Managed Agents призначені для розробників, які пишуть власний код поверх API, тому без програмування вам потрібен саме субагент.

Усе нижче перевірено на Claude Code 2.1.292 (випуск від 6 жовтня 2026 року) за документацією про субагентів станом на 7 жовтня 2026 року. Ця сторінка документації змінюється між мінорними випусками. Наприклад, команда /agents до версії 2.1.197 працювала зовсім інакше, ніж зараз. Тому спершу перевірте свою версію:

claude --version

Якщо ви ще не працювали з інструментом, почніть із короткого пояснення що таке Claude Code і як він працює в терміналі.

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

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

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

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

• власний системний промпт, тобто текст після заголовка YAML у файлі агента, плюс відомості про середовище;
• повідомлення із завданням, яке Claude пише, коли передає роботу;
• файли CLAUDE.md усіх рівнів;
• знімок git status вашого репозиторію на момент запуску;
• вміст навичок, перелічених у полі skills.

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

У Claude Code вже є вбудовані субагенти. Explore шукає по коду, а Plan досліджує кодову базу в режимі планування. Обидва мають лише інструменти читання, бо Write і Edit для них заборонені. general-purpose має всі інструменти і береться за складні багатокрокові завдання. Станом на 2.1.292 є ще кілька службових, наприклад statusline-setup і claude-code-guide. Власний субагент потрібен тоді, коли жоден із вбудованих не робить саме вашу роботу саме вашим способом.

Де лежать файли субагентів

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

1. Керовані налаштування (managed settings) організації: діють для всіх у компанії.
2. Прапорець --agents із JSON під час запуску: діє лише в поточній сесії.
3. Тека .claude/agents/ у корені проєкту: субагенти цього проєкту.
4. Тека ~/.claude/agents/ у вашому домашньому каталозі: особисті субагенти для всіх ваших проєктів.
5. Тека agents/ усередині плагіна: діє там, де плагін увімкнено.

Якщо два субагенти мають однакове ім'я, перемагає той, у кого вищий пріоритет. Отже, code-reviewer у .claude/agents/ проєкту перекриває ваш особистий code-reviewer з ~/.claude/agents/. Теку проєкту зручно закомітити в git, і тоді колеги отримають субагента разом із кодом. Якщо ж ви хочете роздати набір субагентів кільком командам і репозиторіям, їх пакують у плагін, і про це є окремий розбір як працюють плагіни Claude Code.

Чому /agents більше не відкриває майстер

Багато старих інструкцій описують інтерактивний майстер /agents із вкладками Running і Library. Так він працював до версії 2.1.197 включно. У 2.1.292 команда /agents лише виводить нагадування: попросіть Claude створити субагента або редагуйте .claude/agents/ і ~/.claude/agents/ напряму.

Отже, зараз є два способи. Перший: описати субагента звичайними словами, і Claude сам напише файл з полями name, description, tools, model і системним промптом. Другий: написати файл самому. Нижче ми йдемо другим шляхом, бо так ви бачите кожне поле і розумієте, за що воно відповідає.

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

Крок 1. Створіть теку і файл субагента-рецензента

Приклад, який ми збираємо: рецензент коду, що лише читає файли. Таке обмеження має сенс, бо рецензент повинен знаходити проблеми, а не тихо переписувати ваш код. Перейдіть у корінь свого репозиторію і створіть теку. Шлях ~/projects/my-app замініть на свій:

cd ~/projects/my-app
mkdir -p .claude/agents
nano .claude/agents/code-reviewer.md

Вставте у файл такий вміст:

---
name: code-reviewer
description: Рецензент коду лише для читання. Використовуй проактивно після змін у коді, щоб перевірити логіку, безпеку і зрозумілість. Ніколи не змінює файли.
tools: Read, Grep, Glob
model: sonnet
---

Ти рецензент коду. Ти можеш лише читати файли і нічого не змінюєш.

Коли тебе викликали:
1. Візьми список змінених файлів із завдання або зі знімка git status у своєму контексті.
2. Прочитай кожен такий файл повністю.
3. Через пошук знайди місця, де викликаються змінені функції.

Перевір:
- помилки логіки і крайні випадки;
- обробку помилок;
- секрети в коді, наприклад ключі API або паролі;
- зрозумілість назв.

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

Збережіть файл. Якщо тека .claude/agents/ з'явилася щойно, а Claude Code уже був запущений, вийдіть і запустіть його знову. Опис і промпт можна писати українською, Claude їх розуміє. Одне застереження щодо YAML: двокрапка з пробілом усередині значення description ламає розбір заголовка, бо YAML сприймає її як початок нового ключа. Тому в описі вище немає двокрапок. Якщо вона вам потрібна, візьміть усе значення в лапки.

Крок 2. Що означає кожне поле

• name: унікальний ідентифікатор довжиною до 256 символів. Він не може містити : і не може починатися з -. Саме за цим ім'ям ви викликаєте субагента. Назвіть файл так само, тоді його легко знайти.
• description: коли Claude має передавати роботу цьому субагенту. Claude читає описи всіх субагентів і за ними вирішує, кому делегувати завдання. Розмитий опис означає, що Claude не викличе субагента сам. Документація радить додавати фрази на кшталт «use proactively», щоб Claude делегував охочіше. У нашому файлі ту саму роль виконує «Використовуй проактивно».
• tools: список дозволених інструментів. Якщо поле пропустити, субагент успадкує всі інструменти, доступні субагентам. Read читає файл, Grep шукає текст у файлах, Glob шукає файли за шаблоном імені.
• model: якою моделлю працює субагент. Це головний важіль витрат, і йому присвячено окремий розділ нижче.
• Текст після заголовка: системний промпт субагента.

Решта полів необов'язкова. Станом на 2.1.292 серед них є disallowedTools (заборонити окремі інструменти), permissionMode, maxTurns (найбільша кількість ходів до зупинки), effort, skills, mcpServers, hooks, memory, isolation: worktree і color для кольору в списку завдань. Поле skills підвантажує в субагента готові інструкції, і різницю між навичкою та субагентом добре видно в поясненні що таке навички агента (Agent Skills). Поле hooks прив'язує до субагента ті самі обробники подій, що описані в розборі хуків Claude Code.

Чому рецензент із Read, Grep, Glob нічого не зламає

Рядок tools: Read, Grep, Glob працює як білий список. Субагент не отримує Edit і Write, тому фізично не може змінити жоден файл. Він не отримує Bash, тому не може виконати жодної команди в терміналі. Він не отримує інструмента Agent, тому не може запускати власних субагентів, і це заодно обмежує витрати.

У такої безпеки є ціна, і її треба знати заздалегідь. Без Bash рецензент не може виконати git diff і не може запустити тести. Знімок git status у його контексті показує, які файли змінено, але не показує змінених рядків. Тому рецензент читає змінені файли цілком. Якщо вам потрібна перевірка саме по рядках diff, є два шляхи. Можна попросити основну сесію передати diff у тексті завдання. Або можна додати Bash до списку, але тоді субагент уже не є рецензентом лише для читання, бо через Bash можна виконати будь-яку команду, зокрема видалення файлів.

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

Крок 3. Як викликати субагента за іменем або через @

Найпростіший спосіб: назвати субагента у звичайному запиті.

Попроси субагента code-reviewer перевірити мої зміни в src/auth/

Другий спосіб: @-згадка. Наберіть @ і виберіть субагента зі списку підказок. У рядку з'явиться @"code-reviewer (agent)". Без списку можна написати згадку вручну:

@agent-code-reviewer перевір зміни в обробці входу

Для субагента з плагіна до імені додається назва плагіна, наприклад @agent-my-plugin:code-reviewer. Згадка прямо вказує, кого викликати, тому Claude не вгадує за описом.

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

Є ще прапорець командного рядка:

claude --agent code-reviewer

Він працює інакше. Уся сесія запускається з цим агентом як основним, тому окремого контекстного вікна вже немає: ваша основна розмова і є рецензентом. Щоб зробити такого агента типовим для проєкту, документація пропонує ключ agent у .claude/settings.json.

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

Субагенти і ліміти Pro та Max: чистий контекст коштує запитів

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

Механізм простий. Субагент стартує з порожнього контексту, тому знову читає файли, які основна сесія, можливо, вже прочитала. Він завантажує CLAUDE.md і свій промпт. Кожен виклик інструмента означає ще один запит до моделі. Три субагенти, запущені паралельно, дають три незалежні потоки запитів. Основна розмова отримує три короткі підсумки замість сотень прочитаних рядків, тож її контекст лишається чистим. Але ваш п'ятигодинний і тижневий ліміт на Pro чи Max витрачається швидше. Коли він закінчується, Claude Code показує You've hit your session limit або You've hit your weekly limit. Як рахуються ці вікна, детально пояснено в статті як працюють ліміти використання Claude, а план дій на момент, коли ліміт уже вичерпано, є в окремому тексті що робити, коли Claude пише про досягнутий ліміт.

Головний важіль тут: поле model. Станом на 2.1.292 воно приймає псевдоніми haiku, sonnet, opus, fable, повний ідентифікатор моделі або inherit:

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

Якщо поле model не вказати, Claude Code вибирає модель у такому порядку: параметр model, який Claude передає під час конкретного виклику; потім поле model у файлі; потім змінна середовища CLAUDE_CODE_SUBAGENT_MODEL; потім модель основної розмови. Звідси два практичні висновки. Без поля і без змінної субагент фактично працює як inherit. А параметр конкретного виклику стоїть вище за ваш файл, тому якщо Claude явно вибрав модель для виклику, вона перекриє model: sonnet. Змінна CLAUDE_CODE_SUBAGENT_MODEL корисна, якщо ви хочете запускати всіх субагентів на одній моделі. Вбудований Explore зазвичай бере модель основної розмови, тому на Opus він теж працює на Opus.

Є ще три допоміжні важелі. maxTurns обмежує кількість ходів, і субагент зупиняється, навіть якщо завдання сформульовано надто широко. effort знижує глибину міркувань для простих задач. omitClaudeMd: true запускає субагента без файлів CLAUDE.md, якщо вони великі і для його роботи не потрібні.

Перевірити реальну картину можна командою /usage. На планах Pro, Max, Team і Enterprise вона показує, яку частку недавнього використання забрали навички, субагенти, плагіни і окремі сервери MCP (Model Context Protocol, протокол підключення зовнішніх інструментів). Клавіші d і w перемикають період між останніми 24 годинами і 7 днями. Ці цифри приблизні і рахуються з локальної історії на цьому комп'ютері, тому використання з інших пристроїв або з claude.ai туди не входить. Якщо частка субагентів велика, почніть із поля model.

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

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

Є дві межі. За замовчуванням субагент може запускати власних субагентів до трьох рівнів нижче основної розмови. Глибину змінює змінна CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. І коли в сесії вже працюють 20 субагентів, спроба запустити ще одного завершується помилкою Concurrent subagent limit reached. Ліміт підписки може закінчитися значно раніше, ніж ви дійдете до цієї межі, тому паралельність варто вмикати свідомо, а не за звичкою.

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

Чому субагент не з'являється або не спрацьовує

Субагента немає після створення файла. Найчастіша причина: тека .claude/agents/ не існувала, коли ви запустили сесію, тому спостерігач за нею не стежить. Перезапустіть Claude Code. Ще два випадки з документації: теки, додані через --add-dir або /add-dir, не відстежуються взагалі, а сесії з прапорцем --disable-slash-commands не стежать за жодною текою агентів. В обох випадках після зміни файла потрібен перезапуск.

Claude не викликає субагента сам. Опис занадто загальний, тому Claude не бачить збігу між завданням і субагентом. Напишіть у description, коли саме його використовувати, і додайте вказівку діяти проактивно. Або викликайте явно через @agent-code-reviewer.

Рецензент не запускає тести. Так і задумано: у списку tools немає Bash. Тести запускайте в основній сесії або створіть окремого субагента для тестів зі своїм набором інструментів.

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

Якщо ви запускаєте Claude Code на віддаленому сервері, а не на ноутбуці, ті самі файли працюють і там. Як ізолювати таку машину, щоб агент не мав доступу до зайвого, описано в посібнику безпечний запуск Claude Code на VPS.

Що читати далі

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

FAQ

Як створити агента в Claude без програмування?

Створіть субагента Claude Code. Це файл Markdown у теці .claude/agents/ проєкту або в ~/.claude/agents/ для всіх ваших проєктів. Обов'язкові лише поля name і description у заголовку YAML, а текст під заголовком стає інструкцією для агента. Можна також просто описати потрібного субагента словами, і Claude сам напише файл. Проєкти на claude.ai агентами не є, а Agent SDK і Managed Agents потребують власного коду.

Чи витрачають субагенти ліміт моєї підписки Pro або Max?

Так. Кожен субагент надсилає власні запити, і за документацією вони зараховуються в ті самі ліміти, що й основна розмова. Субагент стартує з порожнього контексту і знову читає потрібні файли, тому кілька паралельних субагентів витрачають ліміт помітно швидше. Найсильніший важіль: поле model. Беріть haiku для простих завдань, sonnet для рецензії, а inherit лише тоді, коли справді потрібна модель основної розмови. Частку субагентів показує /usage.

Чому новий субагент не з'являється в Claude Code?

Claude Code стежить лише за тими теками агентів, які існували на момент запуску сесії. Якщо ви створили .claude/agents/ уперше, перезапустіть Claude Code. Теки, додані через --add-dir, теж потребують перезапуску. Якщо субагент усе одно не з'являється, перевірте, що заголовок YAML починається і закінчується рядком із трьох дефісів і що в description немає двокрапки з пробілом без лапок.

Як зробити субагента, який лише читає код і нічого не змінює?

Вкажіть у заголовку tools: Read, Grep, Glob. Поле tools працює як білий список, тому субагент не отримає Edit, Write і Bash і не зможе змінити файл чи виконати команду. Він також не отримає інструмента Agent і не запустить власних субагентів. Ціна такого обмеження: рецензент не може виконати git diff або тести, тому зміни йому передає основна сесія, або він читає змінені файли цілком.