Macetes de Orquestração de Agents

Anotações práticas da aula — o conhecimento "de bastidor" que faz o método render de verdade. Complementa o MANUAL-SDLC-MBK (o passo a passo técnico).

📚 Base: aula "Orquestração de Agents" (23/09/2026, ~2h52) · mentor: Junior · adaptado para uso interno MBK / Academy AI

1 A grande sacada: orquestrar = economizar + escalar

O ponto central da aula: você não precisa de modelo caro de fronteira. Você precisa saber orquestrar modelos baratos.

"Sabendo orquestrar você tem resultado absurdo de entrega. Reduzi custo e passei a pegar projetos mais robustos."
  • Time de agents em modelos baratos (GLM, DeepSeek, Qwen, MiniMax, Kimi) + Sonnet onde importa = resultado alto, custo baixo.
  • Prova real citada: projeto jurídico grande (27 módulos) chegou a 90% em 1 semana — seria ~1 mês numa sessão só, ~1 ano na mão.
  • ~30 milhões de tokens de Sonnet em 30 dias sem estourar o plano, porque o loop refaz com modelo pequeno e barato.
  • Não serve só pra código: gestor de tráfego, SDR, análise, delegação de tarefa — qualquer fluxo com etapas.
Mentalidade: aprenda a criar/entender, não a depender da ferramenta. Se uma parar, você monta noutra (Claude Code, Codex, OpenCode).

2 Orquestração ≠ organização (a confusão comum)

NÃO É

Você com várias sessões abertas mandando na mão tarefa pra cada uma. Isso é só organização — você é o gargalo no meio.

É

Um agente recebe a tarefa e delega pro próximo; cada um roda autônomo, em loop, executa e devolve. Você só entra nos pontos de decisão.

"Orquestração é eles trabalharem no modo autônomo, cada um dentro de um loop, executando a tarefa delegada — não você delegando um por um."

3 A arquitetura do Junior

O time padrão (Claude Code e Codex) é sempre: planeja → constrói → revisa → testa → documenta. A diferença dele está em como roda.

Abordagem comumAbordagem do Junior
Sub-agents dentro da mesma sessão (dividem a janela de contexto)Cada agent numa sessão separada do Claude Code, com janela própria — não estoura contexto
Loop básico / manualAdicionou engenharia de loop (3–4 tipos): trabalha autônomo por horas
Você acompanha tudoTime roda sozinho; humano só nos gates (intent, plano, merge)
Base: método de um engenheiro de software (que ele estuda) + a camada de loop dele. É o que virou o claude-agent-kit (time) + sdlc (método) que você já instalou.

4 Truque nativo: fazer sessões conversarem

Funciona sem plugin nenhum, direto no Claude Code. É a base de tudo.

1

Renomeie a sessão

Dê um nome à sessão (ex: orquestrador, dev). Ela vira um "agente" com nome + ID.

2

Liste os agents

/agents mostra as sessões renomeadas. Uma consegue conversar com qualquer outra que esteja ativa (não parada/stop).

3

Mande um conversar com o outro

Ex: "conversa com o dev". Ele cria uma sala entre os dois (comunicação bidirecional). Chame um terceiro pra entrar na sala; peça pra "tirar do time" pra isolar.

Uso genial: tem um CRM em outro repositório? Abra o Claude nele, renomeie, e mande o agente principal "conversar com o CRM" — ele descobre as funcionalidades sozinho, sem você explicar nada.
Sessão parada (stop) não recebe mensagem. Cada papel precisa de um nome único (senão o SendMessage pede referência).

5 Quando usar sub-agent (e quando não)

USE sub-agent
  • Code review de PR
  • Teste rápido
  • Tarefa pequena que complementa a sessão principal

Ele tem janela própria → processa e devolve só o resumo, sem estourar seu contexto.

NÃO use sub-agent
  • Tarefas grandes
  • Trabalho longo/contínuo

Pra isso → sessões separadas (a arquitetura do time).

6 O fluxo de PR + code review

A rotina dele ao terminar uma feature (ex: tela de login):

1

Abre a PR no GitHub

Da sessão que construiu.

2

Delega um code review

Sub-agent revisa a PR e acha o que a sessão principal errou — corrige, aprova/reprova, manda de volta.

3

Merge → deploy

Só depois do review passar.

Regra de ouro dos modelos: em revisão e planejamento, use sempre o melhor modelo (Sonnet/topo). "Modelo fraco na revisão aprova código fraco." No dev pode ser barato.
Código gerado costuma vir ~50% maior por causa das escolhas/revisão — normal, é o preço da qualidade.

7 Loop e autonomia

  • Claude Code tem /loop com intervalo. Ele tem trava de segurança contra loop infinito (corta sozinho).
  • Existem 3–4 tipos de loop no método (dev, review, verificação); o plugin escolhe sozinho conforme o projeto, pra não gastar token à toa.
Orquestração manual (sem o plugin): se você delega na mão, tem que dizer "quando terminar, me devolve" — senão o agente faz e não volta. O plugin sdlc já resolve isso (loop embutido).

8 Modelos por papel + economia

PapelModeloPor quê
plannertopo (Sonnet/Claude)planejamento é julgamento; erro aqui contamina tudo
reviewertopoé quem barra o dev; fraco aqui aprova lixo
devDeepSeek / GLM / Qwen / Kimivolume de código; o reviewer pega os erros
tester-e2ebarato (com visão!)abre o navegador e testa — precisa ser multimodal
documentbaratoescreve a partir do diff
Economia: usar via API sai mais barato (horário de pico deles ≠ o nosso; chega a <50% do preço). Modelos compatíveis com o SDK Anthropic (GLM 4.7, MiniMax M2/M2.5/M3, Qwen Plus/Max, Kimi, DeepSeek) rodam dentro do Claude Code via troca de ANTHROPIC_BASE_URL.
Verifique compatibilidade: nem todo modelo serve — só os que anunciam SDK/endpoint compatível com Anthropic. Modelos "OpenAI-only" não entram nessa rota.
Macete de preguiça 😅

Crie um alias/script no terminal (ele usa CMD no Windows) com o comando de troca de modelo, pra não digitar tudo toda vez. Peça pro próprio Claude criar o script e salvar.

9 Memória em VPS (anti-degradação)

"Se você não colocou a memória numa VPS, tá errado — faça o mais rápido possível."
  • O time roda com um MCP de memória instalado → não há degradação de contexto entre sessões e dias.
  • Trocar de agent (Claude → Qwen) sem perder o contexto: ele sabe onde parou porque está tudo persistido.
  • Combina com a doc que o /entrega gera (pasta docs/: progresso, bugs, arquitetura, estrutura).

10 Se a luz cair / PC desligar

O estado vive em arquivos (pipeline.json etc.), não na conversa. Então:

1

Reabra a sessão de controle

Aquela que você usou pra iniciar (o orquestrador).

2

"Liga o time de novo"

Ele sozinho reabre as abas, sabe qual tarefa parou e volta a delegar de onde estava.

Os agents não executam nada sem ordem e seguem o que foi planejado — por isso dá pra deixar rodando à noite com segurança.

11 Mantenha uma "sessão vigia" fora do time

  • Sempre deixe 1 sessão fora do time (ex: nome sessao-atual-<projeto>).
  • Serve pra checar o status do time ("como tá o time?") e reiniciar quando dá avaria (luz, aba fechada).
  • Também é ótima pra debater o PRD — ela tem noção do projeto sem estar executando.

12 Jev: quando usar e quando NÃO

Jev não é LLM gerador de texto — é modelo de tomada de decisão, responde em JSON (score/escolha), em milissegundos.

BOM para
  • Robótica (decisão rápida)
  • Roteamento em agentes de IA (ex: classificar mensagem por setor/urgência)
  • Leitura de documento (jurídico) — com camada de segurança
RUIM para
  • Codificação (não entrega bom resultado)
  • Validação financeira/PIX sem checagem real (ele só "enquadra" a entrada)
  • Atendimento humanizado no WhatsApp (rápido demais → risco de banimento)
Cuidado com burla de teste: modelos podem dizer "fiz o teste" sem ter feito. Sempre tenha um verificador na saída. No método, um "vigia" (código estático) impede o modelo de enganar o Jev.
No plugin, o Jev é opcional (precisa TYPESAFE_API_KEY). Sem a chave, o pipeline roda igual — não impacta nada.

13 Segurança ao usar ferramentas de terceiros

"Tem muito sistema com injeção de vírus. Projeto que bomba, com mil estrelas, é o que a galera mais visa."
  • Antes de usar repo popular: faça uma varredura no código todo (auditoria).
  • Se não confiar: reescreva ou não use.
  • Vale pra dependências que você instala nos projetos dos clientes também.

14 Planeje antes de rodar (PRD + grilling)

  • Antes do time, tenha um PRD/BRD. Debata a ideia numa sessão: "quero montar X, me dê ideias de tecnologia" → gere o PRD → o planner lê e preenche os <placeholders> do CLAUDE.md.
  • O planner faz muitas perguntas (grilling — chegou a 63–80 num projeto), cada uma já com a recomendação dele.
LEIA cada pergunta e resposta. Não pule. "Gasta tempo antes." O planner é chato de propósito: depois o time trabalha sozinho e não pode faltar contexto.
Trocar modelo no meio, sem perder nada: acabou o plano do dev? Na sessão: "troca o dev pra DeepSeek" → fecha e reabre esse papel; ele continua de onde parou (estado no pipeline.json + worktree).

15 A rotina que ele usa

"Converso e planejo com eles, vou dormir, e de manhã já tá prontinho. Não consigo mais trabalhar só numa aba do Claude."
  1. De dia: define a demanda e planeja com o planner (aprova intent e plano).
  2. À noite: deixa o time rodando em loop.
  3. De manhã: revisa o que ficou pronto e decide os merges.
  4. Roda vários projetos em paralelo, cada um com seu time.

✓ Checklist de boas práticas