Orquestração de agentes

Orquestração de agentes

Quando o trabalho é executado por vários agentes em paralelo (um orquestrador + teammates), valem regras firmes sobre banco de dados e ambiente, para que o paralelismo não gere conflitos.

Banco de dados de desenvolvimento

• Sempre desenvolvimento, nunca produção. Agentes operam apenas contra um banco de desenvolvimento. Acesso a produção é proibido (ver Segurança).
• Sempre em Docker, via um docker-compose.yml na raiz do projeto. Um único container PostgreSQL atende todos os agentes — não se sobe múltiplos containers.

Quem orquestra o banco

• Somente o agente principal (orquestrador) opera o banco. Ele é o único que cria e aplica migrations, roda seeds, faz reset e mexe no schema.
• Teammates (agentes secundários) não tocam o banco (sem migrations, sem reset, sem alterar schema). Eles consomem o banco que o orquestrador mantém. Isso evita conflitos de migration e dados inconsistentes entre execuções paralelas.
• Se um teammate precisar de isolamento de dados, é o orquestrador quem provisiona um database separado (no mesmo container PostgreSQL) — o ciclo de vida do banco continua centralizado nele.

Cada teammate em seu dev server

• Cada agente secundário roda em um dev server separado, com porta (e demais variáveis) definidas pelo seu próprio .env (ex.: um .env.local por teammate, gitignored).
• Assim vários agentes trabalham ao mesmo tempo sem colidir de porta. O que muda por teammate é a porta do app — o banco em Docker é compartilhado e gerenciado pelo orquestrador.

                 ┌──────────────────────────────┐
                 │  PostgreSQL (Docker)          │  ← só o orquestrador
                 │  docker-compose.yml           │     cria/migra/seeda
                 └──────────────────────────────┘
                      ▲           ▲           ▲
        ┌─────────────┘     ┌─────┘     ┌─────┘
   Orquestrador        Teammate A    Teammate B
   (dev server)        (dev server)  (dev server)
   porta via .env      porta via .env  porta via .env

Regras

• Banco de desenvolvimento em Docker (docker-compose.yml), nunca produção.
• Apenas o orquestrador cria/aplica migrations e mexe no schema.
• Teammates rodam dev servers próprios, com portas vindas do .env; não orquestram o banco.
• Nunca commitar .env.local.

Quando a montagem do ambiente paralelo for simples, faça direto. Quando houver decisões de isolamento, portas ou múltiplos databases que mereçam registro, use plan mode e documente no 003-plan.md da ADR.