10 ошибок при настройке команды AI-агентов (и как я их допускал)
Настроил агентов, запустил спринт – получил хаос: конфликты при слиянии, агенты лезут в чужие файлы, молчаливые падения без объяснения. Знакомо? У меня было именно так. Большинство проблем – из-за одних и тех же граблей. На каждые я наступил лично.
Вот 10 ошибок, которые я собрал за время работы с мульти-агентными командами в Claude Code.
Ошибка 1: Спавн воркеров через CLI вместо Agent tool
Что происходит: Менеджер-агент вызывает claude через Bash для запуска воркера. Агент стартует, но теряет контекст, не получает изоляцию и завершается молча.
У меня был случай: воркер запустился через CLI, отработал 3 минуты, вернул пустой результат. Никаких ошибок в логах. Я полчаса искал проблему, пока не понял, что CLI-процесс не имеет доступа к worktree isolation.
✅ Правильно:
Agent tool call:
subagent_type: "frontend-agent"
isolation: "worktree"
prompt: "[полный task spec]"
run_in_background: true
❌ Неправильно:
claude --agent frontend-agent --prompt "..."
Ошибка 2: Пересечение файлов в одной волне
Что происходит: Два воркера в одной волне модифицируют один файл. При мёрдже – merge conflict.
Это не просто неудобство. Менеджер останавливает всё, разбирается что правильно, вручную разрешает конфликт, перезапускает тесты. Блокируется вся команда. У меня два агента одновременно добавили зависимости в package.json – результат мёрджа выглядел как каша.
✅ Правильно: Стройте файловую карту перед планированием волн:
package.json → [S1.1 Backend, S1.3 Frontend] ← КОНФЛИКТ!
Если файл в двух задачах – это зависимость. Одна задача в Wave 1, вторая в Wave 2.
❌ Неправильно: Надеяться, что «ну они же разные части файла трогают, авось не будет конфликта». Будет.
Ошибка 3: Менеджер-агент пишет код
Что происходит: Менеджер не только планирует, но и сам берётся за реализацию – «быстренько поправлю этот файл».
Я это делал. Один раз. Менеджер работает в main worktree. Его изменения не изолированы. Воркеры, которые получают задачи позже, видят несогласованное состояние. Тесты ломаются по непонятным причинам. Потратил час, пока понял, откуда ноги растут.
✅ Правильно: Менеджер планирует, декомпозирует, спавнит, мёрджит, верифицирует. Код пишут воркеры. Пропиши это в SKILL.md менеджера явно: НЕ пишешь код. НЕ модифицируешь файлы проекта.
❌ Неправильно: «Ну это же одна строчка, зачем спавнить воркера…»
Ошибка 4: Слишком крупные задачи
Что происходит: В task spec 15 файлов для модификации. Воркер пытается сделать всё за одну сессию.
Контекстное окно агента конечно. При работе с большим количеством файлов агент начинает терять детали, принимать упрощённые решения и пропускать edge cases. Качество падает нелинейно – не в 2 раза хуже, а в 5.
✅ Правильно: Правило 5-7 файлов на задачу. Больше – разбивай. Несколько доменов – разные задачи для разных воркеров.
❌ Неправильно: «Ну он же умный, справится с 20 файлами». Не справится. Проверено.
Ошибка 5: Нет тестов в task spec
Что происходит: Task spec описывает задачу, но нет секции «Required Tests». Воркер выполняет работу без тестов. Менеджер принимает.
Без тестов невозможно верифицировать результат. Баг попадает в main. Следующие волны строятся на сломанном фундаменте. Merge gate без тестов – это просто git merge, а не верификация.
У меня так один раз контент-агент «написал» адаптер для API. Без тестов. На первый взгляд – красиво. При запуске – undefined is not a function. Классика.
✅ Правильно: Каждый task spec содержит секцию Required Tests с конкретными тест-кейсами. Правило: «нет тестов = работа не принята».
❌ Неправильно: «Тесты напишем потом». Потом – это никогда.
Ошибка 6: Неверный выбор модели
Что происходит: Менеджер на Haiku (дёшево!), воркеры на Opus (качественно!).
Haiku не справляется с оркестрацией: плохо разбивает задачи, строит неправильные зависимости, пропускает конфликты в файловой карте. Opus для воркеров – как нанять профессора для раскраски стен. Дорого и бессмысленно.
✅ Правильно:
| Роль | Модель | Зачем |
|---|---|---|
| Менеджер | Opus | Сложные рассуждения, архитектура |
| Воркеры | Sonnet | Баланс качества и стоимости |
| Валидация, хуки | Haiku | Быстро и дёшево |
❌ Неправильно: Экономить на менеджере и транжирить на воркерах.
Ошибка 7: Description без триггеров
Что происходит: SKILL.md содержит общее описание: «Frontend-разработчик, работает с React и TypeScript.» Без конкретных триггеров.
Claude не может автоматически выбрать агента. Каждый раз приходится явно указывать имя. Auto-discovery не работает. Первые два дня я не понимал, почему агенты не запускаются автоматически – оказалось, просто не прописал триггеры.
✅ Правильно:
description: >
Специалист по React, TypeScript и UI компонентам.
Use when: нужно создать UI компонент, страницу, стили.
Triggers on: "создай компонент", "React", "TypeScript interface",
"стили", "дизайн-система", "Tailwind".
❌ Неправильно:
description: "Frontend developer"
Ошибка 8: Нет files_no_touch
Что происходит: Task spec содержит files_modify, но без files_no_touch. Воркер «заодно» редактирует смежные файлы.
У меня контент-агент однажды «исправил» tsconfig.json. Просто потому что увидел в нём что-то, что показалось неправильным. Спасибо, не надо. Это создаёт скрытые зависимости и потенциальные конфликты в следующих волнах.
✅ Правильно: Всегда указывай files_no_touch:
files_no_touch:
- src/api/
- src/services/
- docs/tasks/
Хорошее правило: всё, что не в files_modify, – потенциальный files_no_touch.
❌ Неправильно: Надеяться, что агент сам поймёт границы. Не поймёт.
Ошибка 9: Нет merge gate между волнами
Что происходит: Менеджер мёрджит ветки после волны и сразу запускает следующую. Без тестов.
Сломанный код в main. Следующая волна строит на сломанном фундаменте. Когда тесты наконец запускаются – непонятно, в каком коммите проблема. Откатывать или чинить? Каждый раз – лотерея.
✅ Правильно: Merge gate – обязательный ритуал:
- Мёрдж веток последовательно (по номеру задачи)
- Разрешение конфликтов
- Полный прогон тест-сьюта
- Только при всех зелёных – старт следующей волны
❌ Неправильно: «Тесты долго бегут, запущу следующую волну пока». Не запускай.
Ошибка 10: Worktree isolation без инициализированного git
Что происходит: Репозиторий создаётся прямо в сессии Claude Code через git init. Спавн воркеров с isolation: "worktree" – не работает.
Claude Code определяет git-репозитории при старте сессии. Если git init после старта – worktree isolation недоступна. Я на это наткнулся при настройке нового проекта. Всё выглядело правильно в конфигах, но воркеры не изолировались.
✅ Правильно: Убедись, что git-репозиторий существовал до запуска Claude Code. Новый проект – git init, закрой Claude Code, открой снова.
❌ Неправильно: git init внутри сессии и удивляться, почему изоляция не работает.
Бонус: чек-лист перед запуском спринта
Большинство ошибок ловится одним подходом – пройдись по списку перед стартом:
- ROLES.md актуален: все агенты и их file ownership описаны
- Файловая карта построена: нет пересечений в одной волне
- Каждый task spec содержит: files_modify, files_no_touch, Required Tests
- Модели назначены: Opus для менеджера, Sonnet для воркеров
- SKILL.md агентов содержат триггеры в description
- Git-репозиторий инициализирован до старта сессии
- Merge gate настроен между волнами
5 минут на чек-лист экономят час на разрешение конфликтов. Серьёзно.
Итого
Мульти-агентные системы в Claude Code мощные, но требовательные к аккуратности. Большинство проблем – не из-за ограничений платформы, а из-за нарушения базовых принципов: file ownership, merge gates, правильный выбор модели, атомарные задачи с тестами.
Хорошая новость: каждая ошибка допускается один раз. После первого merge conflict из-за пересечения файлов ты навсегда запомнишь строить файловую карту.
Если узнал себя в каком-то пункте – не переживай, я допустил все 10 🙂 . Есть вопросы или хочешь обсудить свою настройку – пиши в Telegram: @sergey_akhantev_it_mentor или в группу @gigaexp