Субагенти в Claude Code. Помічник читає логи, а в розмову повертається лише висновок

Нічний імпорт замовлень знову впав, і розробник просить Claude Code знайти причину. Claude читає довгі логи, результати тестів і три модулі. Причину він знаходить, але контекстне вікно вже заповнене логами, до яких ніхто не повернеться. Для такої роботи в Claude Code є субагенти.

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

Що таке субагент у Claude Code

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

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

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

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

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

Субагент є файлом Markdown із заголовком YAML. Субагенти проєкту лежать у .claude/agents/, а ті, що потрібні в усіх ваших проєктах, у ~/.claude/agents/. Обов'язкових полів лише два, name і description. Можна також обмежити інструменти й вибрати легшу модель.

---
name: chytach-lohiv
description: Читає логи й результати тестів. Повертає лише помилки з назвою файлу й номером рядка. Використовуй, коли треба переглянути довгі логи.
tools: Read, Grep, Glob
model: haiku
---

Прочитай вказані логи. Випиши помилки з файлом і номером рядка
і додай одне речення про ймовірну причину.
Нічого не змінюй у файлах.

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

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

Коли Claude доручає задачу сам

Чи передати задачу субагенту, Claude вирішує сам з огляду на ваш запит, поле description і поточний контекст. Тому опис є найважливішим рядком у файлі. Він має казати, у якій ситуації брати помічника. «Помічник для коду» нічого Claude не каже, а «використовуй, коли треба переглянути довгі логи» каже, коли саме.

Anthropic підказує, що фраза на кшталт «use proactively» в описі заохочує Claude доручати частіше.

Можна й попросити прямо, звичайним реченням, наприклад «використай субагента chytach-lohiv для нічних логів». Згадка через @ з назвою агента гарантує, що запуститься саме він.

Коли поділ допомагає, а коли лише з'їдає ліміт

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

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

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

Документація так само чітко пише, коли краще лишитися в головній розмові:

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

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

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