Как я собрал команду AI-агентов в Claude Code

Большинство разработчиков используют Claude Code как умный автодополнитель – один промпт, один ответ. Я тоже так делал. А потом попробовал собрать из агентов полноценную команду. Разница – как между фрилансером-одиночкой и слаженным отделом.

Тут расскажу, как выстроить мульти-агентную систему с нуля. Без воды, с конкретными конфигами и примерами из моего проекта.

Почему один агент – это бутылочное горлышко

Представь, что ты поручаешь одному разработчику одновременно писать фронтенд, бэкенд, тесты и документацию. Результат предсказуем: человек переключается между контекстами, теряет фокус и работает медленнее, чем четыре специалиста.

С AI-агентами та же история. Один агент с широким промптом даёт посредственные результаты везде. Специализированный агент с чёткими границами ответственности работает кратно лучше в своём домене.

Когда я впервые это осознал, то посмотрел, как устроены официальные плагины Anthropic. Плагин code-review запускает 4-6 параллельных ревью-агентов, каждый со своей специализацией – покрытие тестами, поиск «молчащих» ошибок, проверка типов, анализ git-истории. Один агент физически не может покрыть всё это с тем же качеством.

Фундамент: три ключевых файла

Вся система строится на трёх артефактах. Разберу каждый.

SKILL.md – паспорт агента

Каждый агент определяется через файл SKILL.md. Это системный промпт плюс метаданные для автоматического обнаружения.

Frontmatter:

---
name: frontend-agent
description: >
  Специалист по React, TypeScript и UI/UX.
  Use when: нужно создать или изменить компоненты, страницы, стили.
  Triggers on: "создай компонент", "React", "TypeScript interface", "стили".
tools: Read, Write, Edit, Glob, Grep, Bash
model: sonnet
skills:
  - react-patterns
  - design-system
---

Поле description – критически важное. Именно по нему Claude решает, какого агента вызвать. Без явных триггеров агент работает только если позвать его по имени. У меня первые два дня агенты не запускались автоматически – потому что я не прописал триггеры. Обидная ошибка.

Тело SKILL.md – это системный промпт. Задаёт личность, экспертизу и границы:

# You are a Frontend Engineer

## Your strengths:
- React компоненты, TypeScript, Tailwind CSS
- Работа с дизайн-системами и accessibility

## Boundaries:
- НЕ трогаешь серверную логику (src/services/, src/api/)
- НЕ изменяешь конфигурацию базы данных
- НЕ коммитишь без тестов

## When spawned by manager:
- Работай только с файлами из files_modify в task spec
- Создай ветку feat/s{N}.{M}-short-slug
- Напиши тесты перед коммитом

ROLES.md – карта команды

Файл docs/tasks/ROLES.md описывает, какие агенты есть в проекте и какими файлами владеют:

## frontend
agent: frontend-agent
files: src/components/, src/pages/, src/styles/
stack: React, TypeScript, Tailwind

## nodejs
agent: nodejs-agent
files: src/services/, src/api/, src/utils/
stack: TypeScript, Node.js, Vitest

## content
agent: content-agent
files: docs/posts/, docs/research/
stack: Markdown, SEO

Это не просто документация. Менеджер-агент читает ROLES.md перед планированием спринта, чтобы понять, кому поручить задачу и какие файлы кому принадлежат.

Золотое правило: два агента никогда не модифицируют один файл в одной волне. ROLES.md – первый инструмент для соблюдения этого правила. Я нарушил его один раз – потратил 40 минут на разрешение merge conflict. Больше не нарушаю.

Task Spec – техническое задание

Каждая задача описывается в отдельном файле:

---
id: S2.3
title: Создать компонент карточки продукта
role: frontend
status: todo
wave: 1
depends: []
files_modify:
  - src/components/ProductCard.tsx
  - src/components/ProductCard.test.tsx
files_no_touch:
  - src/api/
  - src/services/
---

## Goal
Создать переиспользуемый компонент ProductCard с поддержкой тёмной темы.

## Required Tests
- Рендер с обязательными пропсами
- Корректное отображение в тёмной теме
- Обработка отсутствующего изображения

## Acceptance Criteria
- Компонент соответствует дизайн-системе
- Все тесты проходят
- TypeScript strict mode без ошибок

Поля files_modify и files_no_touch – границы для агента. Без них воркер может случайно залезть в чужие файлы. Было у меня такое: контент-агент «заодно» поправил конфиг TypeScript. Спасибо, не надо.

Wave-based execution: параллелизм без конфликтов

Волновое выполнение – центральный механизм оркестрации.

Принцип прост: задачи без зависимостей и без общих файлов запускаются параллельно в одной волне. Задачи, зависящие от результатов предыдущих, – в следующей волне, после мёрджа и прогона тестов.

Волна 1: [Frontend  –  ProductCard] [Backend  –  Products API] [Content  –  Документация]
          ↓ merge gate ↓
          Слияние веток → тесты → коммит в main
          ↓
Волна 2: [Frontend  –  интеграция с API] [Tests  –  E2E тесты]
          ↓ merge gate ↓
Волна 3: [Deploy  –  подготовка к релизу]

Merge gate между волнами – это не просто git merge. Это чек-пойнт:

Последовательное слияние всех веток текущей волны
Разрешение конфликтов (если возникают)
Полный прогон тест-сьюта
Только если всё зелёное – обновление статусов и старт следующей волны

Как строить файловую карту

Перед распределением задач по волнам менеджер строит файловую карту – таблицу «файл -> задачи». Если один файл появляется в двух задачах – это зависимость, и задачи идут в разные волны.

src/api/products.ts  → [S2.1 Backend]
src/components/ProductCard.tsx → [S2.3 Frontend]
package.json → [S2.1 Backend, S2.5 Dependencies]  ← зависимость!

S2.1 и S2.5 нельзя выполнять параллельно – оба трогают package.json. Я это понял на практике, когда два агента одновременно добавили разные зависимости в package.json. Мёрдж превратился в головную боль.

Роли в команде агентов

Менеджер-оркестратор

Менеджер – единственный агент с правом спавнить других. Его задача: планирование, декомпозиция, координация и слияние результатов. Менеджер никогда не пишет код. Это фундаментальное правило. Нарушение ведёт к хаосу – проверено.

Менеджер использует model: opus – самую мощную модель для сложных рассуждений. Спавн воркера происходит через Agent tool:

Agent tool:
  subagent_type: "frontend-agent"
  isolation: "worktree"
  prompt: "[полный task spec + контекст]"
  run_in_background: true

Использование claude CLI через Bash – антипаттерн. Агент теряет контекст и фейлит молча. У меня был случай, когда воркер запущенный через CLI просто ничего не сделал и вернул пустой результат. Полчаса потратил, пока понял в чём проблема.

Специализированные воркеры

Каждый воркер – эксперт в своём домене:

Frontend-agent: React, TypeScript, UI компоненты, стили
Backend-agent: серверная логика, API, базы данных
Research-agent: исследования, анализ источников, сбор данных
Content-agent: статьи, документация, техническое письмо
Marketing-agent: копирайтинг, адаптация для соцсетей

Воркеры используют model: sonnet – оптимальный баланс качества и скорости.

Ревью-агенты

Для контроля качества добавляю специализированных ревьюеров – по аналогии с плагином pr-review-toolkit:

test-analyzer: покрытие тестами
silent-failure-hunter: поиск ошибок без выброса исключений
code-reviewer: общий code review
type-design-analyzer: качество типизации

Выбор модели: не переплачивай

Неверный выбор модели – одна из самых частых ошибок. Правило простое:

Задача	Модель	Зачем
Оркестрация, архитектурные решения	Opus	Сложные многошаговые рассуждения
Разработка, контент, исследования	Sonnet	Основная рабочая модель
Валидация, линтинг, простые проверки	Haiku	Быстро и дёшево для рутины

Не ставь Haiku на оркестрацию – качество планирования падает критично. Не ставь Opus на форматирование файлов – это как нанять архитектора красить стены.

Worktree isolation: каждый агент в своей песочнице

Git worktrees позволяют каждому агенту работать в отдельной директории с собственной веткой – буквально в физически отдельной копии репозитория.

Важный нюанс: Claude Code определяет git-репозитории при старте сессии. Если ты выполнил git init в текущей сессии, worktree isolation не будет работать до перезапуска. Я на это наткнулся при настройке нового проекта – всё выглядело правильно, но воркеры не изолировались. Перезапустил Claude Code – заработало.

При правильной настройке структура выглядит так:

/project/               ← main worktree (менеджер)
/project-worktrees/
  feat-s2.1/            ← воркер 1 (backend)
  feat-s2.3/            ← воркер 2 (frontend)
  feat-s2.4/            ← воркер 3 (content)

Три воркера работают параллельно в изолированных директориях. Никаких конфликтов – если файловая карта составлена правильно.

Быстрый старт: три шага

Чтобы начать, достаточно минимума.

Шаг 1: Создай SKILL.md для каждого агента в ~/.claude/agents/{agent-name}/SKILL.md.

Шаг 2: Создай docs/tasks/ROLES.md с описанием ролей и file ownership.

Шаг 3: Создай task spec для первой задачи в docs/tasks/sprint-1/S1.1-slug.md.

Запусти менеджера и скажи: «Выполни спринт 1». Он прочитает ROLES.md, разберёт task specs, построит файловую карту и начнёт спавнить воркеров.

У меня первый спринт с тремя агентами отработал за 12 минут. Вручную я бы делал то же самое минут 40.

Когда это окупается (а когда нет)

Настройка SKILL.md, ROLES.md и task specs требует времени. Вот когда это стоит вложений:

Имеет смысл когда:

Проект содержит 3+ разделённых домена (frontend, backend, content)
Задачи повторяются регулярно (code review, контент, тестирование)
Есть тестовая инфраструктура для верификации результатов
Готов потратить 2-4 часа на первоначальную настройку

Проще без агентов когда:

Разовая задача, которая не повторится
Маленький проект на 1-3 файла
Нет чёткого разделения доменов
Задача требует глубокого бизнес-контекста, который сложно формализовать

Итого

Один агент = одна роль = один worktree = одна ветка
SKILL.md определяет экспертизу и границы агента
ROLES.md устанавливает file ownership для всей команды
Wave-based execution гарантирует параллелизм без конфликтов
Merge gate – обязательный чек-пойнт между волнами
Менеджер планирует и координирует, воркеры исполняют

Начни с малого: два-три агента, простая файловая карта, один спринт. Когда почувствуешь паттерн – масштабируй.

Попробуй сам: создай SKILL.md для одного агента в своём проекте и поручи ему задачу, которую обычно делаешь вручную. Результат может удивить.

Если есть вопросы или хочешь поделиться своим опытом с мульти-агентными системами – пиши мне в Telegram: @sergey_akhantev_it_mentor или в группу @gigaexp

Как я собрал команду AI-агентов в Claude Code#

Почему один агент – это бутылочное горлышко#

Фундамент: три ключевых файла#

SKILL.md – паспорт агента#

ROLES.md – карта команды#

Task Spec – техническое задание#

Wave-based execution: параллелизм без конфликтов#

Как строить файловую карту#

Роли в команде агентов#

Менеджер-оркестратор#

Специализированные воркеры#

Ревью-агенты#

Выбор модели: не переплачивай#

Worktree isolation: каждый агент в своей песочнице#

Быстрый старт: три шага#

Когда это окупается (а когда нет)#

Итого#