Fan out субагентів у Claude Code, і як перевірити те, що вони повернули

Люди вводять у Google «claude fan out subagents», і чимало з них додають у кінці «command», ніби десь є перемикач, який достатньо клацнути. Є прийом, і є також команда. Ми перевірили і те, і те на Claude Code 2.1.301 і за документацією Anthropic 16 жовтня 2026 року.

Лишається частина, про яку документація говорить мало, і саме через неї ми пишемо цю статтю: що робити з результатами. Ми запускаємо fan out щоночі. Шість субагентів перекладають кожну нову статтю цього блогу сімнадцятьма мовами, а основна сесія зливає їхню роботу. Кожен із них повідомляє, що дотримався правил. Перевірка, яку ми написали до їхнього запуску, все одно щось знаходить.

Коротка відповідь

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

Далі на цій сторінці розібрано кожен спосіб, а потім перевірки, які ми виконуємо на власному fan out.

Що субагент бачить і чого не бачить

Три факти з документації визначають, як ділити роботу.

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

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

Є обмеження. За замовчуванням у сесії одночасно можуть працювати 20 субагентів. Двадцять перший завершується помилкою Concurrent subagent limit reached, і помилка каже Claude не пробувати знову. Підняти чи знизити ліміт можна через CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Субагенти можуть запускати власних субагентів, аж до трьох рівнів нижче основної розмови, а загальна кількість за сесію не обмежена.

Спосіб 1: попросити звичайними словами

Найпростіший fan out вміщається в одне речення. Приклад із документації Anthropic:

Research the authentication, database, and API modules in parallel using separate subagents

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

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

Спосіб 2: /batch, найближче до команди fan out

/batch це скіл, вбудований у Claude Code. Ви даєте йому інструкцію:

/batch migrate src/ from JavaScript to TypeScript

Він вивчає кодову базу, розбиває роботу на незалежні одиниці, від 5 до 30, і показує вам план. Після вашого схвалення він запускає по одному фоновому субагенту на кожну одиницю, кожен в ізольованому git worktree. Кожен субагент реалізує свою одиницю, запускає тести й публікує свою зміну. Потрібен git-репозиторій або хук WorktreeCreate, який створює worktree для іншої системи контролю версій.

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

Спосіб 3: цикл із claude -p

Коли робота є списком файлів і ви хочете контролювати кожен виклик, рекомендації Anthropic описують цикл. Спершу попросіть Claude скласти список (list all 2,000 Python files that need migrating and save the list to files.txt). Потім:

for file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --permission-mode dontAsk
done

Три деталі цього прикладу варто перейняти.

• Відповідь читає машина. «Return OK or FAIL» означає, що ваш скрипт може порахувати невдачі, не читаючи прозу.
• Дозволи вирішено заздалегідь. --allowedTools дозволяє рівно те, що потрібно міграції, а --permission-mode dontAsk забороняє все інше, замість того щоб чекати на людину, якої поруч немає.
• Ви починаєте з двох-трьох файлів. Документація каже прямо: доопрацюйте промпт за тим, що пішло не так на перших файлах, а потім запускайте весь список.

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

Для CI документація радить додати --bare, який пропускає хуки, скіли, MCP-сервери й CLAUDE.md, щоб кожна машина отримувала однаковий запуск. Режим bare не використовує вхід за вашою підпискою: йому потрібен ANTHROPIC_API_KEY.

Як ми робимо fan out щоночі

Ось fan out, який ми запускаємо насправді. Наша нічна SEO-команда пише кожну нову статтю англійською та французькою вручну. Потім другий агент перекладає її ще сімнадцятьма мовами за допомогою субагентів Claude Code, а традиційну китайську отримує зі спрощеної скриптом, без перекладу. З 13 вересня 2026 року через цей процес пройшли одинадцять статей, і кожна приходить у вигляді двадцяти файлів.

Частини

Шість субагентів, по три мови на кожного (дві в останнього): іспанська, португальська та італійська; німецька, нідерландська та польська; російська, українська та турецька; японська, корейська та китайська; тайська, в'єтнамська та індонезійська; арабська та гінді. Жодна мова не залежить від іншої, і саме це робить такий fan out чистим.

Кожен бриф містить ті самі п'ять речей, бо субагент більше нічого не бачить:

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

Перевірка пишеться до запуску

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

• той самий slug і та сама дата, заголовок збігається з H1;
• та сама кількість розділів, підрозділів, зображень, посилань і рядків таблиці, і стільки ж відповідей FAQ у тексті, скільки запитань у метаданих;
• посилання ідентичні до байта, фрагменти коду ідентичні до байта;
• назви брендів пораховано, їх ніколи не менше, ніж в англійській;
• довжина в межах, відкаліброваних для кожної мови, бо китайська каже те саме приблизно в 36 % символів, потрібних англійській, а японська приблизно в половині;
• діакритичні знаки там, де вони є в мові (польська, турецька, в'єтнамська).

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

Що центральна перевірка впіймала, а звіти субагентів ні

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

Помилялася наша власна перевірка. 6 вересня перевірка довжини, відкалібрована за старим рядком, який ми замінювали, позначила 11 субагентів із 17. Усі 11 мали рацію: новий текст і мав бути довшим. Відкалібрована за вже виправленою французькою, вона не позначила жодного. Центральна перевірка теж може помилятися, і щоб це побачити, її треба спершу запустити на поставці, про яку ви вже знаєте, що вона добра.

Узгодженість між частинами. 15 жовтня, на новій сторінці функції, перекладеній тим самим способом, перевірка злиття підтвердила, що у 90 файлах змінилися лише очікувані рядки. Але японський, корейський і китайський субагенти обрали для «You may also like» кожен свій заголовок, не той, що їхня мова вже вживала на сусідній сторінці. Кожен варіант був правильним перекладом. Жоден не узгоджувався із сайтом. Жоден субагент не міг побачити цього зсередини своєї частини: це бачить лише прохід по об'єднаному результату.

Хибне слово проходить усі структурні перевірки. Одна з мовних версій сайту колись назвала ШІ-агентів автосалонами, і це висіло в мережі кілька місяців. Та сама довжина, та сама пунктуація, бренд на місці: усі підрахунки були зеленими. Впіймати таке може лише іменний список відомих хибних слів, який блокує кожен деплой і поповнюється на один рядок щоразу, коли ми знаходимо нове.

Повідомлення поза частиною. 15 жовтня субагент, який працював над турецькою, повідомив, що сайт у 97 наявних рядках писав для слова «agent» «ajans», тобто агентство. Він їх не чіпав, бо бриф це забороняв. Ми відкрили тікет, і виправлення вийшло наступного дня. Питати субагентів про те, що вони побачили, а не лише про те, що вони зробили, дешево й окупається.

Злиття відбувається в одному місці

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

Коли fan out не потрібен

• Частини залежать одна від одної. Якщо частині B потрібен результат частини A, виконуйте їх по черзі.
• Робота невелика. Кожен субагент починає з чистого аркуша й заново читає те, що йому потрібно. На десятихвилинному завданні нові старти коштують більше, ніж заощаджують.
• Ви не можете написати перевірку. Якщо неможливо відрізнити добру частину від поганої, не перечитавши все самому, саме на злиття й піде ваш час.
• Квота обмежена. Кожен субагент витрачає власні токени. Fan out заощаджує час і тримає основний контекст чистим, але не зменшує рахунок.

Де тут AgentsRoom

Субагенти живуть усередині однієї сесії Claude Code. Ви бачите їхні результати, а не їхню роботу, і не можете скерувати одного з них посеред завдання. Коли ви хочете, щоб кожна частина була агентом, за яким можна стежити, якому можна відповісти й чию роботу можна перевірити окремо, запускайте натомість окремі сесії: кожен тікет у власному git worktree, і Agent Teams, коли частини передають роботу одна одній. Крок у команді агентів може містити команду перевірки, і саме її код виходу, а не слова самого агента, вирішує, чи піде запуск далі. Це те саме правило, що й вище, тільки за його дотриманням стежить сам механізм запуску. Це працює з Claude Code, Codex та іншими CLI агентів, які підтримує AgentsRoom.

Якщо ви ще обираєте між субагентами та Agent Teams, це порівняння пояснює, для чого потрібен кожен із них.