🤖 Мультиагентная QA-система на Claude Code: как мы автоматизировали тестирование
Тестирование новой фичи — это всегда набор повторяющихся шагов: прочитать задачу, понять бизнес-контекст, проверить API, проверить UI, написать автотест, создать тест-кейс в TMS. Каждый шаг требует разных навыков и инструментов. И каждый раз — ручная рутина.
Мы построили систему, где одна команда /qa <ссылка на задачу или описание> запускает полный цикл тестирования: от анализа задачи до написанного и отлаженного автотеста, тест-кейса в TMS и финального отчёта. Без вопросов, без пауз, без ручного вмешательства.
Расскажу архитектуру и принципы — чтобы можно было повторить на любом проекте.
🏗 Архитектура: один координатор, четыре исполнителя
Ключевая идея — разделение ответственности. Каждый агент делает одно дело хорошо.
Пользователь вводит /qa <ссылка на задачу или описание>, дальше:
👔 QA Manager (координатор) — принимает задачу, думает, делегирует
⬇ Параллельно запускает:
🌐 Web Tester — UI тестирование в браузере
🔌 API Tester — ручное API тестирование через curl
⬇ По результатам:
⚙ QA Automator — пишет Java-автотест на основе реального прогона
🏃 Test Runner — запускает тесты, анализирует логи
Все результаты стекаются обратно к менеджеру → финальный отчёт.
Что делает каждый:
👔 QA Manager — координирует, НЕ исполняет. Инструменты: Agent tool, файловая система.
🔌 API Tester — ручное API тестирование. Инструменты: curl, bash, скрипты.
🌐 Web Tester — UI тестирование. Инструменты: браузерная автоматизация (MCP).
⚙ QA Automator — пишет автотест. Инструменты: чтение/редактирование кода, mvn.
🏃 Test Runner — запускает тесты, ищет логи. Инструменты: mvn, Grafana Loki.
🚫 Почему координатор не делает ничего сам
Это критическое архитектурное решение. QA Manager запрещено выполнять curl, открывать браузер или писать код. Его задача — думать, делегировать и собирать результаты.
Почему:
• Контекстное окно конечно. Если менеджер сам начнёт делать curl-запросы, он быстро «забудет» общую картину
• Параллельность. Менеджер запускает Web Tester и API Tester одновременно — каждый в своём контексте
• Качество решений. Менеджер фокусируется на бизнес-логике: что тестировать, зачем, какие сценарии важнее
Это как если бы CEO компании сам пошёл на склад носить коробки. Вроде помог, но кто в это время рулит?
⚙ Как это устроено технически
1 Slash-команды как точки входа
Claude Code поддерживает slash-команды — markdown-файлы в .claude/commands/, которые становятся командами. Пользователь вводит /qa <ссылка на задачу или описание>, и Claude Code загружает инструкцию.
Структура проекта:
.claude/commands/ — точки входа
• qa.md → команда /qa — запуск QA Manager
• test.md → команда /test — запуск тестов
• qase.md → команда /qase — работа с TMS
.claude/agents/ — инструкции агентов
• qa-manager.md — координатор
• api-tester.md — API тестирование
• web-tester.md — UI тестирование
• qa-automator.md — автоматизация
Slash-команда — это промпт, который запускает координатора. $ARGUMENTS подставляет то, что пользователь написал после /qa.
2 Агентские инструкции — markdown-файлы
Каждый агент получает детальную инструкцию из своего .md файла. Это не «подсказка» — это полная спецификация поведения.
Хороший агентский файл содержит:
• Алгоритм работы — пронумерованные шаги от старта до финиша
• Формат ввода/вывода — какие файлы читать, какие создавать
• Правила автономности — что делать без вопросов, когда останавливаться
• Обработка ошибок — что делать при 404, 500, таймаутах
• Примеры — конкретные команды, шаблоны файлов
Чем детальнее инструкция, тем автономнее агент. Не полагайтесь на «здравый смысл» LLM — описывайте поведение явно. Иначе агент будет творить дичь с чистой совестью.
3 Файловый обмен между агентами
Агенты работают в разных контекстах и не видят друг друга напрямую. Коммуникация — через файловую систему, общую папку сессии:
.claude/test-sessions/2026-03-11_feature-name/
• manager-plan.md — план менеджера
• task-api.md — задача для API Tester
• task-web.md — задача для Web Tester
• task-automator.md — задача для QA Automator
• discoveries.md — обмен находками в реальном времени
• result-api.md — результаты API тестирования
• result-web.md — результаты UI тестирования
• result-automator.md — результаты автоматизации
• agent-api-completed — флаг: API Tester закончил
• agent-web-completed — флаг: Web Tester закончил
• report.md — финальный отчёт
Файлы-задачи (task-*.md) создаёт менеджер. Файлы-результаты (result-*.md) создают исполнители. Менеджер их читает и формирует финальный отчёт.
По сути, файловая система — это шина данных между агентами. Markdown — формат контрактов. Просто и надёжно.
4 Параллельность и синхронизация
Web Tester и API Tester работают одновременно. Это не псевдо-параллельность — они буквально запускаются в одном сообщении: Web Tester в фоне (run_in_background), API Tester в основном потоке.
Но параллельность создаёт проблему: что если один агент заблокирован, а другой нашёл ответ?
Решение — файл discoveries.md. Каждый агент периодически его читает и дописывает свои находки:
Например:
🌐 Web Tester пишет: «Фронт ходит на /api/v2/endpoint, а не на /api/v1/endpoint»
🔌 API Tester читает, переключается на v2, и пишет в ответ: «Endpoint требует заголовок X-Custom-Header, проверь фронт»
Если агент заблокирован (404, 403) — он входит в режим ожидания и каждую минуту проверяет discoveries на новую инфу от параллельного агента. Флаги завершения (agent-*-completed) — пустые файлы. Заблокированный агент видит флаг и понимает, что ждать больше нечего.
5 Конвейер: API Tester → QA Automator
После ручного тестирования API Tester создаёт задачу на автоматизацию с проверенными endpoints, примерами запросов/ответов и главным бизнес-сценарием.
QA Automator получает задачу и:
• Пишет тестовый метод в существующий класс
• Компилирует и запускает
• Если падает — исправляет (до 5 попыток)
• После успеха — маркирует @Disabled("WIP")
Ключевой принцип: автотест пишется на основе реального ручного прогона, а не на основе документации. Автоматор знает, что endpoint точно работает и какой ответ ожидать. Никаких «ну я подумал что там должен быть 200».
📐 Принципы, которые выработали
- Полная автономность исполнителей: Исполнители никогда не задают вопросов пользователю. Действуют, ошибаются, исправляются — но не останавливаются. Вопросы задаёт только координатор, и только в самом начале.Почему: каждый вопрос — это пауза в минуты или часы. Один вопрос от агента = весь конвейер стоит.
- Координатор не исполняет: Менеджер думает и делегирует. Точка.
- Тестируй эффект, а не CRUD: Недостаточно проверить «создал-прочитал-удалил». Автотест должен проверять бизнес-влияние: после действия X результат Y действительно изменился.Это правило зашито в инструкцию каждого агента — иначе они генерят тривиальные CRUD-тесты и считают что работа сделана.
- Инкрементальная запись результатов: Web Tester работает в браузере — каждый скриншот жрёт контекст. Если копить результаты до конца — контекст закончится раньше.Решение: записывать каждый результат сразу. Даже если агент оборвётся — результаты уже на диске.
- Автотест — зеркало реальности: Если фича сломана (500, ошибка БД) — автотест должен падать, а не обходить проблему мягкими проверками. Починят инфраструктуру — тест начнёт проходить. Это честный сигнал, а не зелёная галочка для самоуспокоения.
🔁 Как повторить у себя
- Определите агентов — какие роли участвуют в вашем процессе. Кто анализирует? Кто проверяет API? UI? Кто пишет автотесты? Каждая роль — отдельный агент.
- Напишите инструкции — для каждого агента .claude/agents/{role}.md с алгоритмом, форматом ввода/вывода, обработкой ошибок и примерами.
- Создайте slash-команду — .claude/commands/qa.md как точку входа.
- Определите файловый протокол — какие файлы создаёт координатор, какие исполнители, как обмениваются находками.
- Настройте CLAUDE.md — общие знания: структура проекта, окружения, аутентификация, скрипты.
- Вынесите рутину в скрипты — .claude/scripts/. Агенты не должны помнить длинные команды. Скрипт — это контракт: вызвал с простыми аргументами, получил результат.
📊 Что получилось
Одна команда /qa <ссылка на задачу или описание> запускает:
• Анализ задачи и уточнение scope
• Параллельное API + UI тестирование
• Обмен находками между агентами в реальном времени
• Написание и отладку автотеста
• Создание тест-кейса в TMS
• Обновление базы знаний проекта
• Финальный отчёт
Весь цикл — 15-30 минут. Ручного участия — ответить на 1-2 вопроса в начале.
Этот и другие великолепные посты о QA и AI в моем канале https://t.me/readyfortesting