Orquestração de agentes

Quando o trabalho é feito por vários agentes em paralelo, um deles é o orquestrador (a sessão principal, a que conversa com o dono) e os outros trabalham cada um numa frente — uma ADR, quase sempre. Há dois modos de pôr os agentes para trabalhar, teammates e workflows, e as mesmas regras valem para os dois: são elas que impedem o paralelismo de virar conflito.

Os dois modos

Teammates

Um agente por frente, conversando com o orquestrador enquanto trabalha: recebe a tarefa por mensagem, pergunta quando trava, manda o relatório no fim e pode receber ajustes no meio do caminho.

Quando usar: trabalho longo e iterativo, em que o dono vai olhando e ajustando — uma tela que ele quer ver antes de seguir, uma decisão que só aparece no meio, uma investigação sem roteiro. O orquestrador repassa o que o dono disse e o teammate continua de onde estava.

Workflows

Uma execução roteirizada de vários agentes, com etapas fixas escritas antes de começar: quem faz o quê, em que ordem, e o que cada etapa entrega à seguinte. Ninguém conversa no meio; o roteiro roda até o fim e devolve o resultado de cada etapa.

Quando usar: um lote de ADRs bem definidas em paralelo — o plano (003) e os passos (004) já decididos, as perguntas do quiz respondidas. O padrão é:

1. implementar — um agente por ADR, cada um no seu worktree, até os portões passarem;
2. revisão adversarial contra as palavras do dono — outro agente lê o que foi feito procurando o que não atende ao pedido, comparando com as frases do dono citadas no 001 e no 003 (não com o resumo de quem implementou); o que ele achar volta ao passo 1;
3. integrar — uma ADR de cada vez, pela trava (abaixo).

Qual escolher

Situação	Modo
O dono quer acompanhar e ajustar no meio	Teammates
Ainda há decisão em aberto, ou o caminho depende do que se descobrir	Teammates
Várias ADRs com plano fechado, para rodar de uma vez	Workflow
A mesma sequência (implementar → revisar → integrar) para muitas frentes	Workflow
Uma frente só, curta	Nenhum: o orquestrador faz direto

Os dois convivem: um workflow para o lote de ADRs prontas e um teammate para a que ainda está sendo decidida com o dono.

Regras comuns

Cada frente no seu lugar

• Um worktree por frente (git worktree add ../<projeto>-adrNNN -b adrNNN), a partir da branch de integração, com pnpm install próprio. Nunca duas frentes no mesmo checkout.
• Porta própria para o app de cada frente (no .env.local do worktree, gitignored), para os dev servers não disputarem a mesma.
• Banco de teste próprio, quando a frente precisa de banco: um database separado no mesmo contêiner PostgreSQL, criado pelo orquestrador (uma cópia do banco de desenvolvimento ou um vazio com as migrations). A frente roda os testes e as migrations dela nesse banco.
• Os números das ADRs são distribuídos antes: cada frente pede a reserva ao Gestor, que nunca dá o mesmo número duas vezes; sem o Gestor, o orquestrador distribui (o maior + 1, contando os já distribuídos). O índice e o CLAUDE.md não dizem “a próxima ADR é a…”.

O banco é do orquestrador

• Sempre desenvolvimento, nunca produção. Agentes operam só contra bancos de desenvolvimento; produção é proibida (ver Segurança).
• Sempre em contêiner, pelo compose.yml na raiz (pnpm db:start): o Docker é o recomendado, porque já vem instalado nos espaços do Gestor; o Podman também funciona (o kit usa o que houver). Um contêiner PostgreSQL só atende todos os agentes.
• Só o orquestrador toca o banco principal de desenvolvimento: aplica as migrations, roda os seeds, faz reset e mexe no schema. A frente escreve a migration e a prova no banco de teste dela; aplicá-la ao banco principal é do orquestrador, na integração — ou de quem ele delegar explicitamente, por escrito, para aquela migration.

A integração é serializada

• Uma frente integra por vez, com uma trava: mkdir .git/integracao.lock (o mkdir é atômico: se a pasta já existe, outro está integrando; espere), apagada no fim, também quando falha.
• Dentro da trava: rebase na branch de integração, os portões (lint, typecheck, testes), o merge local (git merge --no-ff, sem pull request; ver Git e commits), a migration no banco principal (orquestrador), o fechamento da ADR, e a remoção do worktree e da branch.
• Conflito no CLAUDE.md e no índice das ADRs: mantenha os dois lados (cada frente acrescenta a sua linha).

Relatórios honestos

• O relatório de cada frente diz o que foi verificado (rodado e visto passar: o comando e o resultado) e o que não foi verificado (e por quê). “Deve funcionar” não é verificado.
• Antes de cada deploy, a verificação final roda numa branch de integração limpa (sem worktree sujo, sem arquivo esquecido): os portões completos sobre o que de fato está lá.

A armadilha da mensagem atrasada

Uma mensagem que chega a um agente depois que ele integrou se perde: o trabalho dele já está na branch de integração e ele não volta a mexer. Por isso o orquestrador não confia no que pediu, confere no git o que de fato entrou (git log, o diff do merge) e, se faltou o ajuste, abre a correção ele mesmo (ou numa frente nova).

Push

Agente secundário e workflow nunca fazem git push. Empurrar é do dono, ou do orquestrador quando o dono pede ou autoriza (ver Git e commits).

                    ┌────────────────────────────────┐
                    │  PostgreSQL (contêiner)         │  banco principal: só o
                    │  compose.yml (Docker ou Podman) │  orquestrador migra/seeda
                    └────────────────────────────────┘
                       ▲              ▲              ▲
          ┌────────────┘     ┌────────┘     ┌────────┘
     Orquestrador       Frente A        Frente B           (teammate ou etapa
     checkout principal worktree adrNNN worktree adrMMM     de um workflow)
     integra, um por vez porta e banco  porta e banco
                         de teste       de teste

Regras em uma linha

• Teammates para o trabalho longo e ajustado no caminho; workflow para o lote de ADRs bem definidas (implementar → revisão adversarial contra as palavras do dono → integrar).
• Uma frente = um worktree, uma porta, um banco de teste.
• Só o orquestrador toca o banco principal; migration nele só delegada por escrito.
• Integração uma por vez, com a trava; merge local, sem PR.
• Relatório com verificado e não verificado; verificação final numa branch limpa antes do deploy.
• O orquestrador confere no git o que entrou; nenhum agente secundário faz push.

Quando a montagem do paralelismo tiver decisões que mereçam registro (quantas frentes, que bancos, o roteiro do workflow), escreva-as no 003-plan.md da ADR que as motivou.