Orquestração inteligente de agentes Codex

1. O AGENTS.md como contrato de engenharia

O arquivo AGENTS.md consolida instruções operacionais que não deveriam depender de cada novo prompt: preservação da Clean Architecture, separação de responsabilidades, componentização, reutilização, proteção de credenciais, princípios de LGPD e isolamento rigoroso entre clínicas.

Isso é especialmente relevante em um SaaS multitenant. Uma alteração aparentemente localizada pode atravessar autenticação, autorização e acesso a dados. O agente precisa investigar o fluxo afetado, identificar dependências e evitar atalhos que eliminem filtros ou regras existentes.

O agente deve trabalhar dentro da arquitetura do produto, não remodelar o produto indiscriminadamente ao gerar uma solução.

2. Agentes especializados e responsabilidades claras

As configurações foram distribuídas entre .codex/config.toml e definições em .codex/agents/, respeitando as capacidades verificadas na versão utilizada. No backend, a estrutura incluiu seis especialistas; no frontend, quatro. As responsabilidades abrangem áreas como engenharia de API, frontend, segurança, dados, DevOps, arquitetura e qualidade, conforme o escopo de cada repositório.

Uma tarefa de autenticação exige atenção a sessões e permissões; uma migração exige análise de dados, rollback e compatibilidade; uma alteração visual exige revisão de responsividade, acessibilidade e testes E2E. A especialização ajuda a manter essas disciplinas explícitas.

3. Esforço proporcional ao risco

A delegação passa por uma avaliação de complexidade técnica, risco de regressão e segurança, impacto arquitetural e dependências entre módulos. Mudanças triviais podem ser executadas diretamente. Fluxos críticos justificam investigação aprofundada e revisão especializada.

Níveis como Low, Medium, High e Extra High servem como referência de planejamento quando efetivamente suportados pelo ambiente. Não é adequado presumir que todo parâmetro ou capacidade de subagente esteja disponível em qualquer versão.

4. Concorrência com limites

As configurações iniciais estabeleceram concorrência máxima de dois agentes, acompanhada de uma regra essencial: não editar o mesmo arquivo simultaneamente. Mais paralelismo sem coordenação pode significar conflitos, retrabalho e desperdício de contexto.

A estratégia é dividir tarefas somente quando há independência real entre elas, consolidando depois alterações, testes e revisão.

5. Segurança desde o planejamento

O HemoDinks processa dados em um contexto de saúde. Por isso, proteção de informações sensíveis, autorização no backend e isolamento multiclínica são prioridades. Instruções explícitas vedam remover controles para simplificar implementações, registrar segredos, alterar regras fora do escopo ou criar migrations destrutivas sem análise.

O mesmo princípio orienta infraestrutura: auditorias de imagens no GHCR, automações Azure e deploy Blue/Green precisam manter garantias de rollback e mecanismos fail-closed. A IA apoia a engenharia, mas não substitui a verificação operacional.

6. Testes, GitHub Projects e revisão humana

Uma mudança produzida por agentes não é automaticamente uma entrega concluída. O processo exige critérios de aceite, testes unitários, integração e E2E na medida do impacto, além de rastreabilidade em GitHub Issues, Pull Requests e Projects.

Commits e PRs demonstram implementação; execução de testes, revisão e verificação em ambiente apropriado demonstram qualidade de entrega. Essa distinção evita confundir produtividade aparente com software confiável.