Роли агентов

Coroid не использует один универсальный агент. Каждый этап пути от описания до pull request обрабатывается агентом с узкой специализацией и намеренно ограниченным набором инструментов.

Эти ограничения — ключевой момент. Агент, который не может писать код, не сможет случайно написать код.

Роли#

Роль	Этап	Может изменять ваш код
Архитектор	Техническое задание и план	Нет
Разработчик	Сборка	Да
Отдел тестирования	Проверить	Нет
Рецензент	Рецензирование	Нет
Веб-тестировщик	Проверить, браузерные потоки	Нет
Исследователь	Исследования, любой этап	Нет
Анализатор зависимостей	Анализ	Нет

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

Архитектор → Разработчик → Отдел тестирования → Рецензент

В режиме координатора координатор определяет порядок выполнения задачи. Оба режима описаны ниже.

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

Два способа выполнения задачи#

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

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

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

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

Координатор#

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

Что делает координатор#

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

Чего не может делать координатор#

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

1. Вердикты выносят служба контроля качества и рецензент. Вердикты выносят только служба контроля качества и рецензент, каждый через свой собственный результат. В инструкциях координатора нет места для вердикта, и координатор не может пометить проверку как пройденную.
2. Для завершения задачи необходимы контрольные точки. Задача может быть завершена только после того, как QA подтвердит корректность именно той версии, которая пойдет в релиз (или текущей версии кода, если изменений нет), а также после одобрения этой версии рецензентом, если для задачи требуется рецензирование. Если ветка изменилась после запуска QA, завершение задачи невозможно, и новая версия возвращается на проверку QA.
3. Доработка ограничена по количеству шагов. Каждый агент может быть запущен ограниченное число раз на одну задачу, а план можно скорректировать лишь несколько раз. Также установлены ограничения по количеству шагов и общему времени выполнения. При достижении лимитов координатор может лишь завершить задачу или пометить её как невыполненную.
4. Ожидание также ограничено по времени. Любое ожидание имеет чёткий временной лимит.

Таким образом, задача, которой руководит координатор, завершается одним из трех способов: pull request, который нужно утвердить вам; подтверждение QA о том, что код уже выполняет требования задачи, значит, менять его не нужно; или информация о причине сбоя задачи. Задача не завершается просто потому, что агент, ответственный за нее, объявил ее готовой.

Возможные маршруты координатора#

Координатор определяет, как задача попадет к контрольным точкам. Все вышеперечисленные контрольные точки одинаковы для любого маршрута.

• Полный маршрут. Планирование, разработка, проверка, рецензирование, завершение. Так выполняется задача, если у координатора нет причин выбрать другой маршрут.
• Отправка работы обратно. Если QA не проходит проверку или рецензент требует правок, исправления возвращаются разработчику. Новая версия должна пройти проверку QA, прежде чем задача сможет быть завершена. Успешная проверка предыдущей версии не распространяется на новую.
• Уже выполнено. Возможно, код уже выполняет требования задачи. Тогда координатор может поручить QA проверить неизмененный код на соответствие критериям приемки, вместо того чтобы создавать новый код. Если QA подтверждает корректность кода, а рецензент одобряет его при необходимости, задача завершается без pull request, так как нечего объединять. Результатом проверки QA и является итог выполнения задачи. Этот маршрут закрывается, как только запуск приводит к изменениям, ведь иначе QA могло бы подтвердить код, который не пойдет в релиз.

Два более коротких маршрута являются опциональными. По умолчанию Coroid их не использует. Они меняют маршрут координатора, но не контрольные точки:

• Быстрое исправление. Для небольшого исправления в знакомом месте координатор составляет более короткий план и дает разработчику четкие указания с перечислением файлов, затронутых изменениями. Разработчик работает в рамках ограниченного бюджета шагов, а любые изменения за пределами этих файлов сообщаются QA и рецензенту.
• Более узкая повторная проверка. После небольшого исправления ошибки, найденной QA или рецензентом, QA начинает проверку с этого результата и тестов проекта. При этом вердикт выносится по всей новой версии кода.

Когда требуется рецензент#

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

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

• если рецензирование задачи уже началось, или если правила рецензирования проекта или граф качества вашей организации предусматривают его;
• если изменения затрагивают аутентификацию, сессии, разрешения, секреты или криптографию, миграции баз данных, настройки сборки и развертывания, файлы зависимостей или код, взаимодействующий со сторонними сервисами;
• если изменения значительные (по умолчанию более 80 измененных строк) или включают бинарные файлы, символические ссылки или подмодули;
• Coroid не может прочитать эту политику или само изменение. При возникновении сомнений рецензент обязателен.

Изменение, не вносящее никаких изменений в код, никогда не требует рецензента. Это решение принимает код, а не координатор, и координатор не может обойти его. В конце описания pull request указывается, какой путь был выбран и почему. Оно начинается со строк «Рецензент требуется» или «Рецензент не требуется».

Архитектор#

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

Результат его работы — это документ, который вы утверждаете перед началом сборки. В режиме координатора этот агент продолжает выполнять функции координатора.

Разработчик#

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

Когда Рецензент отправляет результаты обратно, Разработчик — это роль, которая реагирует на них. В режиме координатора координатор передает результаты вместе с указаниями по исправлениям.

Специалист по контролю качества#

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

Специалист по контролю качества выносит вердикт. Он не исправляет найденные ошибки; они возвращаются разработчику для доработки. Разработчик как доработка.

Рецензент#

Читает готовый дифф и формирует результаты, применяя правила рецензирования, настроенные в вашей организации. Результаты либо отправляются разработчику для доработки, либо прикрепляются к pull request для вас.

Веб-тестировщик#

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

Исследователь#

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

Анализатор зависимостей#

Анализирует зависимости и то, как изменения распространяются по кодовой базе, включая проекты с настроенными межпроектными зависимостями.

Почему важно такое разделение#

Разделение работы таким образом обуславливает четыре свойства:

1. Проверка осуществляется независимо. Агент, который проверяет работу, не является тем же агентом, что и её создатель, поэтому он не заинтересован в конкретном результате.
2. Зона возможного ущерба ограничена. Только роль разработчика имеет доступ к инструментам для записи кода, поэтому сбой при рецензировании или анализе не может повредить вашу кодовую базу.
3. Каждая роль использует модель, подходящую именно ей. Планирование требует широких знаний о мире; написание компилируемого кода требует других навыков. AI профиль содержит одну модель на каждую роль именно по этой причине.
4. Завершение задачи определяется проверками, а не агентом, ответственным за неё. В режиме координатора агент, управляющий задачей, не может завершить её без вердиктов специалиста по контролю качества и рецензента.

Далее#

Вернуться к Как задача превращается в pull request для этапов, на которые соответствуют эти роли, или Что такое Coroid для краткого обзора.