Como uso a squad de agentes (Maestri) pra acelerar entrega sem perder qualidade no Viajaflux

Sou Presidente e Tech Lead do Viajaflux ao mesmo tempo — e isso já é assunto pra outro post. Na prática, hoje eu reviso PR, decido arquitetura e escrevo bem menos código do que escrevia há um ano. Não foi preguiça, foi delegação: primeiro pro time, depois pra uma squad inteira de agentes que roda em paralelo com eles.

Essa squad eu chamo de Maestri.

O que é o Maestri, sem enrolação

Maestri é um app de workspace espacial pro macOS onde cada terminal roda um agente Claude independente. Os terminais conversam entre si via CLI (maestri list, maestri ask). Não é uma skill, é uma ferramenta externa — eu chamei ela de “squad” porque é literalmente isso: um time de especialistas, cada um com um papel fixo, que eu acordo digitando um comando.

Quem quiser testar: themaestri.app/pt-br.

Como criar um agente — o Atlas como modelo

Ponto importante que costuma confundir quem chega agora: um agente do Maestri não é uma configuração do próprio app. É um subagent normal do Claude Code — um arquivo Markdown com um formato específico. O Maestri só abre o terminal e manda rodar claude --agent <nome>; quem interpreta o arquivo é o Claude Code.

Isso significa duas coisas na prática:

• Se o arquivo mora em ~/.claude/agents/, o agente fica disponível globalmente, em qualquer projeto que você abrir o terminal.
• Se você criar dentro de .claude/agents/ na raiz de um repositório específico, o agente fica restrito àquele projeto — útil se a regra de negócio só faz sentido ali.

Copio abaixo o arquivo real do meu Atlas (~/.claude/agents/atlas.md), sem cortar nada, porque é mais fácil aprender o padrão vendo um caso de verdade do que uma explicação abstrata:

---
name: atlas
description: Desenvolvedor Backend Sênior. Acionar quando há uma task de backend definida pelo Morpheus — criação de endpoints, models, migrations, jobs, policies, events, integrações com APIs externas (Wooba, Infotera, Cora/Tecnospeed). Trabalha com Laravel X/PHP e Next.js API routes. NÃO faz frontend; descreve interfaces esperadas para o Iris quando necessário.
tools: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch
---

Você é Atlas, desenvolvedor Backend Sênior especializado em Laravel, Nextjs e APIs.

## Sua missão
Receber tasks do Arquiteto (Morpheus) e implementar a solução backend com excelência técnica.

## Comportamento
- Siga os padrões do Laravel: Eloquent, Policies, Form Requests, Resources, Jobs, Events.
- Se o projeto for Nextjs, siga o padrão clean code.
- Pense em N+1, índices de banco, transações e integridade referencial.
- Documente cada endpoint com contrato de entrada/saída (JSON).
- Sempre considere autenticação, autorização e sanitização de inputs.
- Prefira soluções idiomáticas do framework a gambiarras.

## Stack
- Laravel X.X, PHP 8.x
- Nextjs para alguns projetos
- PostgreSQL/Supabase (self-hosted em ************)
- Mysql para projetos Laravel
- Integrações: ************

## Formato de saída
- Código completo e funcional (com namespaces e imports)
- Comentários em pontos não óbvios
- Migration se houver mudança de schema
- Lista de variáveis de .env necessárias

Você NÃO faz frontend. Se precisar de algo do Iris, descreva a interface esperada.

Desmontando o padrão pra você replicar nos outros quatro:

• name — precisa bater com o nome do arquivo (atlas.md → name: atlas). É esse valor que você usa depois em claude --agent atlas.
• description — não é decoração, é o que o Claude Code usa pra decidir quando acionar esse agente automaticamente durante uma sessão normal. Escreva como um gatilho: em que situação ele deve entrar, e o que ele explicitamente não faz (aqui, “NÃO faz frontend”).
• tools — a lista de ferramentas que esse agente pode usar. Restrinja de propósito: o Atlas não tem acesso a nada de frontend porque a função dele é só backend; isso evita ele “invadir” território de outro agente.
• Corpo do arquivo — é o system prompt em si. Eu sempre estruturo em missão → comportamento (regras de como ele deve pensar e agir) → stack (contexto técnico fixo do projeto) → formato de saída (o que eu espero receber de volta). Copiar essa mesma ordem pros outros quatro agentes (Morpheus, Iris, Argos, Themis) é o que dá consistência à squad inteira — cada um “fala a mesma língua” de estrutura, mudando só o conteúdo técnico.

Depois de salvar o arquivo, não precisa reiniciar nada: na próxima vez que você abrir claude --agent <nome> (ou pedir pro Maestri acordar aquele agente), ele já lê a versão mais recente do Markdown.

Os agentes moram em ~/.claude/agents/ (globais, não presos a um projeto):

Cada um abre num terminal separado:

claude --agent morpheus
claude --agent atlas
claude --agent iris
claude --agent argos
claude --agent themis

Alias pra não digitar maestri ask toda vez

Sem alias, chamar um agente é maestri ask "Atlas" "sua mensagem aqui" — funciona, mas cansa depois da vigésima vez no dia. Eu resolvi isso com uma função de shell por agente, salva no .zshrc (se você usa Bash, a mesma sintaxe funciona igual no .bashrc):

alias mlist="maestri list"
alias mmorpheus='f() { maestri ask "Morpheus" "$*"; }; f'
alias matlas='f() { maestri ask "Atlas" "$*"; }; f'
alias miris='f() { maestri ask "Iris" "$*"; }; f'
alias margos='f() { maestri ask "Argos" "$*"; }; f'
alias mthemis='f() { maestri ask "Themis" "$*"; }; f'

O truque é o f() { ... }; f dentro do alias: isso transforma o alias numa função que aceita o resto da linha como argumento ($*), em vez de só um comando fixo. Sem isso, maestri ask "Atlas" sem a mensagem colada no mesmo alias não funcionaria.

Depois de colar isso no arquivo, recarrega o shell:

source ~/.zshrc   # ou source ~/.bashrc, se for Bash

A partir daí é só matlas "cria a migration de tal coisa" e a mensagem já sai direto pro Atlas, sem precisar lembrar da sintaxe completa do maestri ask.

O fluxo real, não o fluxo bonito de slide

Requisito → Morpheus (decompõe)
          → Atlas (backend) + Iris (frontend) em paralelo
          → Argos (testes)
          → Themis (revisão)
          → merge

Isso é o caminho ideal. Mas a decisão de quando seguir esse caminho é o que realmente importa — e é aí que a maioria que tenta copiar esse setup se perde.

Eu não delego tudo. Regra que eu mesmo apliquei no meu CLAUDE.md global:

• Requisito novo, feature grande, bug complexo, mudança arquitetural → vai pro Morpheus decompor antes de qualquer linha de código.
• Correção pontual de 1-3 linhas, pergunta, explicação rápida → eu resolvo direto, sem acordar a squad. Chamar o Morpheus pra renomear uma variável é usar canhão pra matar mosquito.
• Você (usuário) pediu explicitamente pra eu resolver → eu resolvo, ponto.

E dentro da própria squad tem outra decisão: paralelo ou sequencial.

Paralelo só quando os três critérios batem ao mesmo tempo: 3+ tasks independentes, sem estado compartilhado, cada agente mexendo em arquivo diferente. Exemplo real: quando peguei o requisito dos alertas de milhas via WhatsApp (viajaflux-api-alertas-whatsapp), o Atlas montou os endpoints de notificação enquanto a Iris já ia adiantando o componente de configuração de alerta no Livewire — sem risco de um pisar no arquivo do outro.

Sequencial é obrigatório quando task B depende do output de A, ou quando o schema/arquivo é compartilhado. Migration → API → componente é sempre sequencial: não adianta a Iris montar tela pra um endpoint que o Atlas ainda não decidiu o contrato.

Onde isso rendeu de verdade no Viajaflux

O Viajaflux tem histórico de integrações externas pesadas — Wooba, Infotravel, Cora, BuscaIdeal — cada uma com fila e job próprios (SincronizarVendasWoobaJob, BuscarVoosJob…). Esse tipo de trabalho é ótimo pra Atlas: ele lê o padrão que já existe no projeto (a doc de arquitetura fica em .github/AI_ARCH.md, versionada no repo) e replica a convenção em vez de inventar uma nova a cada integração.

Quando o Themis entra depois pra revisar, ele não está validando “o código funciona”, está validando “o código funciona do jeito que o resto do projeto funciona” — segurança, performance, e se bate com o plano que o Morpheus desenhou lá atrás. Isso é o que evita a maior armadilha de usar IA em produção: código que roda isolado, mas que não conversa com o resto do sistema.

O que eu não abro mão

Eu não deixo a squad decidir arquitetura sozinha, e não deixo ela mexer em main ou beta sem passar pelo fluxo de PR normal — tenho uma skill (gitflow-viajaflux) só pra isso, que recusa push direto e força a convenção de commit com ID do ClickUp. Squad de agente acelera execução, não substitui review humano nem protocolo de branch. Se eu tirasse essas travas, seria rápido pra entregar e rápido pra quebrar produção — e no Viajaflux quem sente isso primeiro é o usuário pagando mensalidade, não eu.

Minha conclusão

Squad de agentes não é sobre ter mais gente digitando código. É sobre ter papéis fixos, critério claro de quando delegar e quando resolver na mão, e revisão que não é cortesia — é etapa obrigatória. Sem isso, “orquestração multi-agente” é só um jeito bonito de multiplicar bug por cinco.