Моя команда ИИ-агентов: как я веду разработку нескольких модулей

Каждый ищет свой путь

Каждый программист рано или поздно ищет свой способ писать хороший код: свои привычки, свои проверки, свой порядок работы. Идеального способа нет — есть подходящий тебе и твоему проекту.

С ИИ-агентами этот поиск становится ещё и поиском того, как организовать команду. Агент пишет быстро, но видит только своё окно контекста — ту часть разговора и файлов, которую он держит в памяти прямо сейчас. Проект целиком он не видит, поэтому порядок, роли и проверки выстраивает человек.

То, что я описываю, — мой путь, найденный методом проб и ошибок. Он не единственно правильный. Берите то, что подходит вам, и меняйте остальное.

Как устроена команда

Возьмём проект из трёх независимых модулей. У каждого модуля своя маленькая команда: контролёр и программист. Я каждый день работаю напрямую с контролёрами: проблемы возникают по ходу разработки, и у каждого модуля свои. Координатор стоит в стороне: в конце каждого этапа контролёры отчитываются ему, он независимо проверяет итог и докладывает мне.

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

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

Координатор

Что делает.

• В конце каждого этапа принимает отчёты контролёров и проверяет итог как сторонний наблюдатель. В ежедневную работу модулей он не вмешивается.

• Проверяет, правильно ли агенты ставят отметки в задачах и закрыты ли пункты требований.

• Проверяет, что работа доведена до конца: агенты любят сделать половину и отчитаться за целое.

• Запускает фоновые проверки готовых модулей, например на безопасность, и другие проверки, которые я ему назначил. Обо всём недоделанном докладывает мне.

Ещё через координатора идут общие команды для всех — например, пауза перед перезагрузкой компьютера или обновлением программы. Я говорю её координатору, он передаёт контролёрам, а те — своим программистам, так что каждый получает команду по своему обычному каналу.

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

Слабые места. Координатор — ещё один агент, а значит, ещё токены. Проект он видит только через отчёты и отметки: если отметка поставлена правильно, а работа сделана плохо, он может этого не заметить. Проблем по ходу работы он не видит вовсе — их ловлю я вместе с контролёрами.

Контролёр модуля

Что делает.

• Ведёт доску задач модуля: очередь, приоритеты, задачи из найденных дефектов, разбор зависших.

• Пишет требования (техническое задание) и ведёт их исполнение: принимает замечания программиста, вносит правки, согласует пункты.

• Даёт разрешение на каждый этап: пробную сборку, начало пакета работ, проверку кода, выкладку и прогон тестов.

• Принимает работу сам: данные — сверкой на установленной программе, интерфейс — по картинке. По каждой задаче выносит решение: «проверено» или «нужны правки».

• Ведёт документацию по правилам раздела, который ему выделен.

• После каждой принятой задачи выбирает следующие цели.

• Держит связь со мной и координатором: по ходу работы задаёт мне вопросы-стикеры, а в конце этапа отчитывается координатору.

Как он пишет документацию. За основу взята Diátaxis — открытая методика документации (diataxis.fr), автор Daniele Procida; по ней написана, например, документация Django и Ubuntu. Diátaxis делит все тексты на четыре вида по тому, что нужно читателю:

• Обучение — первые шаги за руку, «Начало работы».

• Инструкции — как решить конкретную задачу, «Руководство».

• Справочник — точные факты о командах, настройках и программных интерфейсах.

• Объяснения — как устроено и почему, «Архитектура».

Навигация — по образцу документации Microsoft Learn: обзор, посадочные страницы разделов, «Устранение неполадок» и отдельный раздел для ИИ-агентов. Раздел «Интерфейс программы» собирается по пунктам меню в том порядке, в каком они идут в программе. Структура пока разрабатывается, и в итоге из неё вырастет мой собственный стандарт. Каждый сам выбирает, как ему удобнее строить документацию.

Почему контролёр не пишет код. Только по прямой просьбе владельца. Если контролёр начинает программировать, он перестаёт контролировать: внимание уходит в код, а не в проверку. К тому же два агента, правящие один код, мешают друг другу.

Почему весь обмен идёт через контролёра. Если написать программисту напрямую, он бросает свою задачу и начинает решать чужую проблему. У меня это категорически запрещено: начатая работа остаётся недоделанной. Контролёр сам решает, когда и в каком виде передать вопрос программисту.

Почему это важно. Если требования и задачи написаны хорошо, программа пишется практически без моего участия. Контролёр делает работу проверяющего, которую иначе пришлось бы делать мне.

Слабые места. Контролёр — узкое место: всё идёт через него, и если он ошибся или потерял детали разговора, ошибается весь модуль. И он тоже что-то пропускает на проверке.

Программист

Что делает.

• Пишет код и тесты, поднимает версию, делает коммиты, собирает, выкладывает и прогоняет. Каждый этап — только после разрешения контролёра.

• Сам свою работу не принимает. Отчитывается с контрольными суммами — отпечатками файлов, по которым контролёр убеждается, что проверяет ровно то, что сделано.

• Проверяет требования и задачи как исполнитель: находит в них ошибки и противоречия, и они с контролёром согласуют общее решение.

Почему это важно. «Один пишет, другой принимает» — старое правило хорошей разработки: автор не видит своих ошибок, проверяющий видит. А то, что программист проверяет требования, ловит ошибки ещё до кода, когда их исправить дешевле всего.

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

Когда контролёр недоступен. Программист может какое-то время работать без контролёра по уже согласованным задачам, но о каждом сделанном шаге отправляет отчёт, чтобы контролёр потом его проверил. Если контролёр — как и любой агент — упирается в лимит подписки (значок lim), а у программиста свой лимит ещё не кончился, программист не стоит: он идёт дальше по своим задачам и сам проверяет свою работу тестами. Когда лимит снимается, контролёр просматривает всё накопившееся и принимает работу или возвращает её на доработку. Так время не теряется, а правило «автор не принимает свою работу» сохраняется. Это работает именно потому, что роли идут на разных помощниках или разных подписках. Если же оба работают на одной подписке и упираются в лимит вместе, модуль целиком встаёт на паузу до снятия лимита. Уведомление и автоматическое продолжение работы от программы действуют и тогда.

Как помогает программа (в версии 2.40). Тот, кто пишет агенту в лимите, получает одно автоматическое уведомление: до какого времени агент недоступен и что письма он прочитает позже. Дальше — тишина до конца лимита, без повторов. Когда лимит действительно снят, ожидающие письма доходят до агента примерно за две минуты, и он сам берётся за работу — например, за проверку накопившихся отчётов, — без напоминания человека. Некоторые агенты становятся доступны лишь через несколько минут после объявленного времени сброса. Поэтому программа ждёт настоящей доступности агента, а не только часов, чтобы письма не потерялись в лимите.

Человек

Что делает. Каждый день работает напрямую с контролёрами каждого модуля: отвечает на их вопросы-стикеры (жёлтые карточки с вопросом) и правильно направляет проект. Проблемы возникают по ходу разработки, и у каждого модуля свои, поэтому ждать отчёта в конце этапа нельзя. Ещё он ставит цели и следит за правилами: агенты забывают запреты — например, делают рассылку «всем», — и человек замечает и напоминает.

Почему это важно. Человек — единственный, кто видит проект целиком: и цель, и то, что сейчас важнее. Быстрый ответ на стикер разблокирует контролёра, а значит, и весь модуль. Отчёт координатора в конце этапа — второй, независимый взгляд на ту же работу.

Слабые места. При 3–5 модулях это много параллельных разговоров и стикеров одновременно, и нить легко потерять. Я смягчаю это так: отвечаю на стикеры по приоритету; контролёры спрашивают меня только о решениях владельца и сразу предлагают свой вариант; один вопрос — одна карточка.

Разные агенты — разные роли

Я использую двух разных ИИ-помощников — Codex и Claude — и даю им разные роли: один в основном пишет код, другой в основном проверяет. Важен не выбор помощника на роль, а сам принцип: пишет один, проверяет другой. Распределение ролей по разным помощникам или подпискам ещё и страхует команду: когда у одного кончается лимит, другой продолжает работу, и проект не встаёт целиком. К тому же у каждого помощника и каждой подписки свои лимиты, и часто один позволяет работать заметно дольше другого. Это ещё одна причина отдать долгую непрерывную работу — например, написание кода по задачам — тому, чьих лимитов хватает дольше, а проверку — другому. Лимиты и тарифы тоже меняются, так что это стоит время от времени перепроверять.

Почему писать и проверять должны разные агенты.

• Независимый взгляд. Автор видит в коде то, что хотел написать, а не то, что написал. Проверяющий смотрит свежими глазами.

• Другой контекст. У проверяющего своё окно контекста: он не несёт в себе допущения автора и поэтому их замечает.

• Автор никогда не принимает свою работу сам. Это правило не зависит от того, насколько хорош агент.

Типичные проблемы любого агента и чем помогает контроль. Это не свойства конкретной модели: так ведёт себя любой агент, который видит только своё окно контекста.

Отсюда главный вывод: качество задачи определяет качество кода. Чем точнее задача, тем меньше места для догадок.

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

Цена. Токены: проверка — это ещё один агент, который читает тот же код. И накладные расходы на координацию: разрешения, отчёты, ожидание проверки.

ИИ-помощники быстро меняются: то, что верно сегодня, через месяц может стать другим. Поэтому роли стоит распределять по тому, что работает у вас сейчас, и время от времени пересматривать выбор.

Недостатки схемы и как я с ними живу

В любой схеме есть недостатки, и в моей тоже. Вот главные: как они проявляются и чем я их смягчаю.

Многое из этого держится на одном принципе: всё важное записывается. Правила — в файлы правил, задачи — на доску задач, требования — в документ требований, знания — в «Документы». Тогда ни я, ни агенты не зависим от того, что помним прямо сейчас.

Когда эта схема лишняя

Для маленького проекта из одного модуля три уровня — перебор. Координатор там не нужен: итог этапа можно проверить самому. А если задача совсем простая, достаточно одного программиста и вашей собственной проверки.

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

Итог

Мой путь — команда, в которой каждый агент делает одну работу и не мешает другим. Программист пишет, контролёр проверяет и ведёт модуль, я каждый день отвечаю контролёрам и направляю проект, а координатор в конце этапа независимо проверяет итог. Цена — токены и скорость. Выигрыш — программа, которая пишется почти без меня и не разваливается по дороге.

Как научить самих агентов соблюдать правила такой команды, я подробно разобрал в статье «Как научить ИИ-агентов работать с OfficeSentinel AI Terminal».