Перейти к основному содержимому

ADR 0053 — Dev Lead как область и параллелизм, разрешённый пользователем

  • Статус: Принят (реализован в ФАЗЕ 14d, 2026-08-07)
  • Дата: 2026-08-05
  • Контекст: ФАЗА 14d
  • Отменяет отсечения из: ADR 0038 (общий аппарат областей и динамические области через module_map)

Контекст​

Сегодня параллелизм dev agents таков: один агент на модуль при activate и один дополнительный на модуль (dev-<modulo>-2) по принятию одним кликом (AcceptParallelizationUseCase). Потолка сессии нет. Ничто не мешает проекту поднять по агенту на модуль плюс по дополнительному на каждый, и расходы растут вместе с этим, без чьего-либо разрешения.

ФАЗА 14d решает, что оценивает, сколько агентов того стоит, lead, и что выход за два в сессии требует разрешения пользователя.

Напряжение, которое разрешает этот ADR​

Речь идёт о параллелизме dev, а Dev Lead не существует. Существующих областей две, с фиксированными участниками, прописанными вручную в apps/web/src/lib/agents.ts: qa (lead qa, участники qa-automacao и qa-performance-seguranca) и infra.

Хуже того: CLAUDE.md явно запрещал обе необходимые вещи — «не реализовывать Dev Lead и динамические области через module_map» и «не реализовывать общий аппарат областей (agent_areas/budget по области)».

Решение пользователя — снять оба запрета и сделать настоящего Dev Lead. Этот ADR фиксирует это и почему.

Почему область dev не может быть зашита в код​

У qa и infra участники известны на этапе написания. У области dev — нет: участники — это по одному на модуль module_map, который решает Arquiteto, который различается в каждом проекте и меняется при пересмотре архитектуры.

Это ровно тот случай, который отложило отсечение Фазы 8. Оно было честным, пока все области были статическими; перестаёт быть таковым в момент, когда входит первая динамическая область. Невозможно сделать Dev Lead без аппарата — и именно поэтому оба отсечения падают вместе, а не ради удобства.

Решение​

1. Области становятся данными, на проект​

Входят agent_areas и agent_area_members, ограниченные проектом:

  • agent_areas: project_id, key (сегодня dev, qa, infra), lead_agent_id, max_parallel (по умолчанию 2)
  • agent_area_members: area_id, agent_id

qa и infra продолжают рождаться с уже имеющимися участниками — аппарат становится источником, а зашитый список исчезает из agents.ts. Внешний контракт gates не меняется: потребитель видит один вердикт на gate, ровно как сегодня, и набор тестов Фазы 4 должен оставаться зелёным без изменений. Это доказательство того, что смена источника не протекла за пределы области.

Область dev рождается в activate-execution, с одним участником на модуль действующего module_map.

2. Lead решает, пользователь разрешает выше 2​

Lead оценивает, сколько агентов стоит задействовать для текущей работы, — это больше не число в коде. Но его решение не суверенно в отношении расходов:

  • до max_parallel (по умолчанию 2) lead поднимает агентов и продолжает;
  • выше этого это становится proposed_action типа parallelize через тот же pipeline одобрения, что и любое действие с внешним эффектом. Решает пользователь, и решение остаётся в event log.

Потолок принадлежит сессии, а не модулю. Подсчёт по модулю позволил бы N модулей × 2 агента без какого-либо разрешения — а это сегодняшняя дыра под другим именем.

AcceptParallelizationUseCase (принятие одним кликом) поглощается: он становится путём одобрения этого proposed_action, а не кнопкой, параллельной pipeline.

3. max_parallel настраивается для каждого lead​

На экране Настроек у каждого lead свой, с 2 по умолчанию. Это потолок, который lead может использовать, не спрашивая, — а не потолок того, что пользователь может одобрить.

4. Anamnese предлагает поднять, когда разрешение повторяется​

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

Чего она не делает — так это поднимает сама. Автоматизировать это означало бы, что продукт поднимает собственный потолок расходов, а это именно то, что pipeline одобрения существует, чтобы предотвратить.

5. Dev Lead — разговорный агент и получает handoff от Arquiteto​

Это не роль Arquiteto при включении: это собственный агент (dev-lead), с инструкцией, binding модели и местом в ленте, как Criativo, PO и Arquiteto.

Цепочка становится Arquiteto → Dev Lead → выполнение. Сегодня Arquiteto заканчивает, и выполнение включается кнопкой пользователя, без кого-либо посередине, кто оценил бы работу; с Dev Lead появляется собеседник по поводу параллелизма — в этом смысл 14d, и это то, что требует «решает lead», чтобы не остаться фразой.

Это вписывается в уже существующее правило handoff, а не открывает исключение: внешний handoff адресуется только lead области или агенту без области. Сегодня dev-<modulo> — агенты без области и потому адресуемы; став участниками области dev, они перестают быть таковыми — и единственным внешним адресом выполнения становится Dev Lead. Иерархия ADR 0038 действует для dev без особого случая.

Прямые последствия:

  • Внутреннее делегирование. Dev Lead → dev-<modulo> — это делегирование области, приватное, в таблице delegations с area = "dev" — тот же путь, что у QA и Infra. Сбой субагента сообщает источник lead, который решает и записывает событие.
  • Кнопка «Ativar execução» меняет владельца. Она перестаёт быть триггером и становится принятием плана Dev Lead: он говорит, сколько агентов хочет и почему, а пользователь одобряет — в пределах потолка без церемоний, выше него через proposed_action из пункта 2.
  • Собственная инструкция. Dev Lead нужно знать module_map, доступный для взятия backlog и действующий потолок. Он не пишет код: он распределяет работу и отвечает за неё.

ОТВЕЧЕНО 2026-08-07: исправление после gate по-прежнему идёт напрямую в dev-<modulo>, который открыл PR. Это сохраняет набор тестов Фазы 4 нетронутым и текущий внутренний контракт; это менее согласуется с иерархией и обратимо — можно будет пропускать через lead позже, когда он будет существовать и будет доказан. Решать сейчас, без реализованного Dev Lead, значило бы выбирать вслепую.

Последствия​

За

  • Расходы на параллелизм получают потолок и владельца. Сегодня нет ни того, ни другого.
  • Аппарат областей перестаёт быть объявленным долгом и становится механизмом, с первой динамической областью как доказательством того, что он годится для трудного случая.
  • budget por área (другой пункт отсечения Фазы 8) оказывается в одном шаге: недостающая таблица начинает существовать.

Против

  • Это крупнейшее структурное изменение со времён Фазы 8, и оно затрагивает поток handoff: Arquiteto начинает передавать Dev Lead, а не ручному включению пользователем.
  • Ещё один разговорный агент — это ещё один ход LLM на выполнение, до того как будет написан хоть какой-то код. Он покупает то, что у потолка расходов появляется владелец; если его план укладывается в потолок, его стоимость — это стоимость самого запроса.
  • delegations.area — TEXT с «qa» и «infra» сегодня; он получает «dev» и начинает иметь источник истины в таблице. Миграция должна сохранить историю читаемой.
  • Смена источника участников qa/infra — чистый риск без немедленной выгоды для них — смягчён тем, что набор тестов Фазы 4 остаётся нетронутым как критерий приёмки.

Рассмотренные альтернативы​

Потолок сессии без Dev Lead. Дал бы центральную ценность — потолок расходов с разрешением — не нарушая ни одного отсечения, и это была рекомендация. Отвергнуто, потому что оставляет «решает lead» без владельца: потолок существовал бы, но никто не оценивал бы, сколько агентов того стоит, а это половина того, что просит 14d.

Применить только к QA и Infra. Верно тексту и реализуемо сегодня, но с низкой ценностью: у обеих областей фиксированные участники, решать почти нечего, и это не касается параллелизма dev — а именно там происходят расходы.

Большее фиксированное число в коде. Это то, что существует сегодня, с другим значением. Это не решает ничего: без разрешения любое число произвольно.

Ссылки​

  • ADR 0038 — иерархия по областям и отсечения, которые этот ADR отменяет
  • ADR 0045 — машина состояний dev agent, куда входят дополнительные агенты
  • apps/api/src/db/schema.ts (примечание в delegations) — где сказано об отсечении
  • apps/api/src/application/use-cases/execution/accept-parallelization.use-case.ts — сегодняшний механизм, поглощённый пунктом 2