15 субагентов Claude Code писали систему. Принял её по уликам, а не по отчётам

Субагент сдаёт волну: отчёт на страницу, тесты зелёные, «можно собирать». Запускаю сборку, она падает на компиляции. Открываю упомянутый файл: половины классов из отчёта в нём нет. Это не единичный случай, это нормальное поведение. В память проекта легла формула, вокруг которой построилась вся дальнейшая работа: субагент принял задачу, не значит код работает.

Контекст для тех, кто не читал первые две части: у меня небольшое производство электродвигателей, и под него я собрал свою систему вместо ERP (вводная здесь): Python-сервер, Android-планшеты в цеху, семь ИИ-агентов внутри системы (вторая часть). Писал я её не руками, а командой субагентов Claude Code. В этой статье техника: как настроены агенты, что у них в промптах, как устроен релизный конвейер и приёмка, после которой в цех больше не уезжает недоделанное.

Субагент: файл с фронтом и системным промптом

В Claude Code субагент это markdown-файл в .claude/agents/ репозитория. Фронт определяет, что он умеет делать и на чём думает, тело это системный промпт. Вот фронт контролёра релиза, дословно:

---
name: app-motors-release-controller
description: Проверяет, что релиз (Android APK + backend) реально готов
  по критериям Definition of Done — по уликам, а не по отчётам субагентов.
  Never writes code or edits files.
tools: Read, Glob, Grep, Bash
model: opus
---

Три решения в четырёх строках. Список tools белый: у контролёра нет Write и Edit, он физически не может поменять код, который проверяет. Модель подбирается под роль: семь агентов команды работают на Opus, семь на Sonnet. Правило у меня простое: рассуждение и решения это Opus, исполнение по ясному плану это Sonnet.

Всего таких файлов в проекте пятнадцать:

Агент

Модель

Зона

tech-lead

opus

планы релизов, соответствие ТЗ, конфликты спецификаций

backend-developer

sonnet

FastAPI, Pydantic, SQLAlchemy, сервисы

android-developer

opus

Kotlin, Compose, навигация

db-engineer

opus

миграции Alembic, триггеры, представления

ai-agent-engineer

opus

продуктовые агенты внутри системы

devops / worker / integration / web

sonnet

Docker, Celery, стыковки, админка

qa-engineer

sonnet

pytest, testcontainers, golden datasets

build-verifier

sonnet

сборки APK в Docker, тесты, smoke

security-reviewer

opus

security gate перед релизом

prod-auditor

opus

аудит боевого сервера

release-controller

opus

вердикт по DoD

Над ними главный агент (Claude Code в основной сессии): он интегрирует куски и делает все коммиты. Субагент в git не пишет никогда, свой результат он сдаёт отчётом. Автор в истории один, APP Motors Team, и по логу git не отличить, где работал агент, а где я.

Тех-лид: документы вместо памяти

Первый агент, промпт которого пришлось переписывать всерьёз, был тех-лид. Проблема оказалась не в коде, а в источниках: если агент «помнит» требования по себе, каждый волен додумывать. Решение: пять документов спецификации объявлены single source of truth, и в промпте это прошито жёстко:

В рабочей директории Docs/ лежат пять документов. Они утверждены заказчиком,
и команда не возвращается к их обсуждению — только реализует.
1. tz_app_motors_v2.md — главное ТЗ: цель, архитектура, стек, роли, план релизов.
2. db_schema_v1.md — полная схема PostgreSQL: 35+ таблиц, FK, индексы, триггеры.
3. api_v1.md — REST API v1: 100+ endpoint-ов, идемпотентность, optimistic locking.
...
Перед любой задачей прочитай релевантные разделы этих документов.
Не работай по памяти — читай конкретный файл и раздел.

Дальше в промпте одиннадцать архитектурных принципов, нарушение любого означает откат кода. Три из них:

- Реляционное и событийное ядро. AI — слой автоматизации поверх бизнес-правил, не вместо.
- Идемпотентность входящих через external_id + Redis + UNIQUE constraint.
- Critical AI actions FORBIDDEN_FOR_AGENT — выпуск ревизий, потребление материалов,
  релиз work_order — только человеком.

И формат, в котором тех-лид отдаёт план. Каждая задача спринта выглядит так, дословно:

### Task R0-02: SQLAlchemy 2 baseline + naming conventions
- Владелец: app-motors-db-engineer
- Acceptance: app/db/base.py с naming_convention, пустая Alembic-конфигурация,
  baseline миграция применяется
- Зависимости: R0-01
- Источник: db_schema_v1.md §1, §2

Владелец это всегда конкретный субагент. Acceptance всегда ссылка на раздел документа, не на устную договорённость. Задачи размером в один-три дня, фича, задевающая несколько слоёв, идёт цепочкой: сперва база, затем бэкенд, тесты и только потом Android. И отдельный раздел в конце промпта, «Что НЕ делать»: «Не пиши код сам. Твоя задача координировать. Код пишут специализированные агенты».

У бэкенд-агента то же правило первым пунктом: «Реализуешь HTTP API строго по Docs/api_v1.md». Плюс ссылки на конкретные пункты правил проекта: «CLAUDE_RULES.md правила 7, 19, 23, 24, 27, 28: single source of truth, не дублируй защиту, идемпотентность, audit_log в одной транзакции». Субагент не гадает, как «правильно», он идёт к документу.

Волны: параллельная работа без конфликтов

Релиз идёт волнами по два-четыре субагента параллельно. Чтобы агенты не перезаписывали друг друга, файлы поделены между потоками, а общие заморожены: пока android-developer переписывает навигацию, backend-developer не трогает его экраны. Каждый поток работает в своём git worktree, сборка идёт из корня.

Мелочь между волнами (лишний импорт, строка в конфиге) главный агент правит сам. Дальше вступает проверяющая четвёрка.

Верификатор: сборка как правда

build-verifier запускает реальные сборки и тесты. Пара строк его промпта, самых дорогих:

Ты запускаешь реальные сборки и тесты и честно отчитываешься.
Ты не исправляешь код — даже очевидную опечатку.
...
- Собирай один раз.
- Не интерпретируй «BUILD SUCCESSFUL» в старом логе как успех текущей сборки —
  сверяй время файла APK с временем запуска.

Вторая строка родом из реального инцидента: сборка упала, агент посмотрел на старый лог, увидел BUILD SUCCESSFUL и отчитался. Теперь вердикт верификатора привязан к времени файла APK, а не к наличию успешной строки где-то в логах.

Формат ответа у него тоже прошит:

# Сборка: УСПЕХ / ОШИБКА / ТАЙМАУТ
**Команда:** bash scripts/build-android-apk.sh debug
**APK:** android/apk/appmotors-latest-debug.apk (48.1 MB, 2026-10-18 14:02)
## Ошибки компиляции
| # | Файл:строка | Сообщение | Вероятная причина |

APK собирается в Docker-образе с JDK 21 и Android SDK 35, это занимает от тринадцати до тридцати четырёх минут, поэтому прогоны заказываются по расписанию волн, а не на каждое изменение.

Контролёр: приёмка по уликам

Теперь главный агент этой конструкции. Задача, из которой он родился: субагенты регулярно рапортуют «готово» про код, который не компилируется или не делает заявленного. Запретить это в промптах разработчиков нельзя, значит нужен тот, кто отчётам не верит по определению. Начало его системного промпта:

Ты агент контроля верхнего уровня. Твоя единственная задача: сказать правду
о готовности релиза. Субагенты-разработчики регулярно рапортуют «готово» про код,
который не компилируется или не делает того, что заявлено. Ты — заслон против этого.

Ты не пишешь код, не правишь файлы, не запускаешь сборки и тесты.
Ты читаешь, ищешь, сверяешь и выносишь вердикт.

И обязательный порядок для каждого пункта плана:

1. Сформулируй, какая улика его доказывает (файл + grep, строка лога, вывод curl,
   наличие APK с датой позже последнего коммита).
2. Добудь улику сам: Grep/Read/Glob/Bash (только чтение).
3. Если улики нет — пункт не закрыт, даже если отчёт говорит обратное.
   Так и пиши: «заявлено, не подтверждено».

Дальше типовые проверки, из которых видно, что «улика» это не метафора, а конкретная команда и конкретное место в коде:

- Экран Android заявлен → Glob файла экрана + Grep его маршрута
  в ui/navigation/AppNavGraph.kt + Grep точки входа (кнопка/иконка на home-экране роли).
  Экран без маршрута = недоступен пользователю = не закрыт.
- Endpoint заявлен → путь в OpenAPI локального стека + функция в app/api/v1/*.py
  + сервис в app/services/*.py (бизнес-логика не в роутере).
- Сборка прошла → в логе сборки BUILD SUCCESSFUL и файл android/apk/appmotors-latest-*.apk
  новее последнего изменения в android/.

Формат вердикта единый: ГОТОВО или НЕ ГОТОВО, счёт закрытых пунктов, таблица «пункт / статус / улика или что не так», список рисков и ровно один следующий шаг с путями файлов.

Релиз 18 октября: три вердикта за день

Как это работает на практике. Суббота, 18 октября, закрытие релиза «склад и диспетчер», 42 коммита за сутки. План релиза содержит таблицу DoD, и у каждого критерия третья колонка заполнена заранее:

| # | Критерий | Улика для контролёра |
|---|---|---|
| A5 | Экран «Документы» на всех ролях | файл экрана + маршрут в AppNavGraph.kt |
| A9 | APK доставлен, инструкция | сообщение в чате со ссылкой |
| A12 | Новые маршруты отвечают | OpenAPI + curl в отчёте волны |

15:15, вердикт первый: НЕ ГОТОВО, десять из двенадцати. Сокращённо:

| Пункт | Статус | Улика / что не так |
|---|---|---|
| Экран «Документы» | не закрыт | файл есть, перехода нет ни с одного главного экрана |
| Доставка APK | не закрыто | сообщения с инструкцией не было |
| Логгер HTTP | риск | пишет пароль и токены открытым текстом |

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

Волна исправлений, меньше часа: переходы добавлены на четыре home-экрана, логгер переведён на режим без тел запросов. 16:15, вердикт второй: ГОТОВО, двенадцать из двенадцати, один пункт закрыт «по заявлению» (про доставку контролёр принял моё слово, в чат он не ходит). И в этом же вердикте находка: отладочный ключ подписи не сохранялся между сборками, каждый APK подписывался новым, свежая версия не установится поверх старой.

В 20:10 вечера третий вердикт по следующему куску: НЕ ГОТОВО, четырнадцать из шестнадцати, два пункта не сошлись с уликами, релиз ждёт волны. Пока счёт не полный, на планшеты в цех не уезжает ничего.

Параллельно с контролёром свой гейт проходит security-reviewer. В тот же день его находки: XSS в веб-шаблоне (фильтр вывода JSON не экранировал угловые скобки) и общий кэш идемпотентности: чужой ключ повторного запроса возвращал чужой ответ. Обе вещи мимо зелёных тестов.

Что метод не делает

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

Расходы на агентную разработку я не считал. У продуктовых агентов в системе журнал каждого вызова пишется автоматически (цена, токены, время), и за три дня беглой работы они съели восемнадцать центов. У самой разработки такого журнала нет, и сколько стоила та суббота с сорока двумя коммитами, я теперь не покажу. Учёт с первого дня это первый пункт в моём списке «сделал бы иначе».

Сессии падают: то контекст исчерпан, то API отвергает запрос с картинкой больше двух тысяч пикселей. Лечение хендоффом: файл состояния релиза ведёт главный агент, каждая сессия поднимает проект с него, и это же файл, по которому работает контролёр.

Цифры

  • 73 тысячи строк Python на сервере, 43 тысячи Kotlin в приложении;

  • 1559 тест-функций, с параметризацией 1817 проверок, стабильно падают шесть старых;

  • 287 коммитов с конца апреля, 120 из них в субботы и воскресенья, самый продуктивный день недели: воскресенье;

  • рекорд: 42 коммита за 18 октября, день описанного релиза.

Чистого времени в этом около трёх недель: разработка шла вечерами и выходными, в свободное от производства время.

Вместо вывода

Модель не умеет проверять, она умеет убедительно отвечать. Поэтому «готово» от субагента это гипотеза, а доказательство всегда снаружи: маршрут в навигации, строка в логе сборки, файл APK новее последнего коммита. Как только у каждого пункта плана появилась колонка «улика», споры «сделано или нет» закончились: ответ либо находится grep-ом, либо пункт не закрыт.

В следующей статье цикла разберу другую историю про планшет в цеху: приложение говорило «нет соединения», когда сервер отвечал 200. Пять находок подряд, от молчаливых соединений HTTP/2 до лимита nginx, и ни одна не нашлась бы по отчётам.

Автор: Aflubin1978

Источник

Оставить комментарий