Modelo, custo e orquestração

Haiku é o modelo mais rápido e barato da família Claude. Ideal para tarefas repetitivas, de baixo raciocínio: ler arquivos, buscar padrões, resumir trechos curtos, executar comandos.

A maioria dos subagentes de uma frota não precisa de raciocínio profundo. Usar Haiku neles reduz o custo total em até 10×. Escolher Opus para varredura é erro de orçamento, não de qualidade.

Custo por token muito baixo; latência menor; contexto próprio (começa do zero); não herda raciocínio do maestro — recebe instruções explícitas.

Sonnet equilibra capacidade de raciocínio e custo. Excelente para escrever código, revisar PRs, sintetizar resultados de outros subagentes e tomar decisões intermediárias.

É o modelo padrão do Claude Code. Na maioria dos workflows, Sonnet cuida do "meio": recebe dados brutos do Haiku e entrega material refinado para o Opus avaliar.

Ótimo para geração de código e síntese; custo médio; usado como maestro em pipelines de médio porte; substitui Opus em 80% dos casos sem perda perceptível.

Opus tem o raciocínio mais profundo. Reservado para: decisões arquiteturais, avaliação de segurança, síntese de longa duração e situações onde errar é caro.

Usar Opus em toda a frota multiplica o custo por 5–20×. Saber identificar os momentos em que só Opus serve (e os que não precisam) é a habilidade central desta trilha.

Custo alto; latência maior; melhor para raciocínio multi-etapa; use como chefe de frotaHaiku/Sonnet; nunca no loop interno de subagentes baratos.

Todo subagente começa com contexto limpo. Ele não sabe o que você acabou de discutir — precisa receber instruções completas na sua descrição e nas mensagens do maestro.

Um Haiku bem instruído supera um Opus mal instruído. O modelo escolhido só importa depois que as instruções estão corretas. A "armadilha" é pagar mais esperando que o modelo adivinhe o contexto.

Sem herança de histórico; o maestro passa o contexto necessário via mensagem; CLAUDE_CODE_SUBAGENT_MODEL sobrescreve o modelo padrão da frota.

Uma heurística simples: Haiku para "ler e reportar", Sonnet para "construir e revisar", Opus para "decidir e arquitetar". Aplique às tarefas antes de codificar o subagente.

Erros de atribuição de modelo são invisíveis — o resultado parece igual, mas o custo é 5–10× maior. Ter a tabela internalizada evita decisões automáticas de "usar o modelo mais capaz".

Haiku: busca, leitura, extração, resumo. Sonnet: escrita, código, síntese, revisão. Opus: arquitetura, segurança, avaliação final, raciocínio profundo.

Dado um pipeline hipotético com 6 tarefas (varrer logs, escrever testes, revisar PR, propor arquitetura, buscar docs, avaliar segurança), atribua o modelo correto a cada uma.

A prática de atribuição consolida a heurística. Errar no exercício é barato; errar num sistema real com 100 subagentes custa muito.

Critério de avaliação: custo estimado × qualidade esperada. Um gabarito comentado está no módulo completo.

Cada subagente tem seu próprio contexto, sistema prompt, ida-e-volta com a API. Com 10 subagentes rodando em paralelo, o número de tokens consumidos multiplica rapidamente.

Sem essa consciência, é fácil criar workflows que custam dezenas de dólares por execução. Conhecer o multiplicador permite planejar com antecedência — e saber quando o multiagente vale o preço.

Custo por execução = (tokens entrada + saída) × preço × nº subagentes; sistema prompt repetido por agente; contexto passado pelo maestro também conta.

O chefe (Opus ou Sonnet) orquestra o trabalho: decide estratégia, decompõe tarefas, avalia resultados. A frota (Haiku) executa em paralelo: lê, busca, extrai, reporta.

É o padrão de maior custo-benefício: um único agente caro faz as decisões inteligentes enquanto muitos agentes baratos fazem o trabalho mecânico. A qualidade sobe; o custo médio por resultado cai.

1 chefe, N trabalhadores; chefe avalia e consolida; trabalhadores reportam de volta; a decisão de "o que fazer" fica no chefe, "como fazer" na frota.

Variável de ambiente que força todos os subagentes a usar um modelo específico, independente do default do sistema. Útil para controlar custo em batches grandes.

Sem essa variável, subagentes usam o modelo padrão — que pode ser Sonnet ou Opus. Com ela, você garante que toda a frota usa Haiku sem alterar o código de cada agente.

`CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku-4-5` no ambiente; sobrescreve apenas os subagentes (o agente principal mantém o modelo original); útil em workflows de alta escala.

Parâmetro que limita quantas rodadas de ida-e-volta um subagente pode fazer. Cada turno consome tokens. Sem limite, um agente preso num loop pode gastar indefinidamente.

Subagentes ocasionalmente entram em loops de tentativa-e-erro. Com `maxTurns` definido, o custo máximo por execução é previsível — e o agente falha de forma controlada em vez de gastar silenciosamente.

Configurado no CLAUDE.md do subagente ou via SDK; valor típico: 10–20 turnos; depois do limite, o agente retorna o que tem até o momento.

Critérios objetivos para decidir: tarefas em paralelo que cada uma levaria 10+ min sequencialmente; jobs com "parede de output" que num único contexto causariam truncamento; codebase com 10+ arquivos interdependentes.

Usar multiagente para tarefas pequenas é pagar 15× por 0% de ganho real. O critério claro evita esse desperdício e justifica o custo quando a tarefa realmente exige.

Sinal positivo: paralelismo genuíno, separação de contexto, output volumoso. Sinal negativo: tarefa sequencial curta, contexto compartilhado necessário, resultado simples.

Dado um job de análise de repositório (identificar code smells em 50 arquivos), projete a divisão: qual agente é o chefe, quantos trabalhadores, qual modelo para cada papel, como o resultado é consolidado.

Projetar antes de implementar evita redesenhos caros. O exercício força pensar em granularidade de tarefas, custo estimado e pontos de falha.

Entregável: diagrama simples (pode ser texto estruturado) com papéis, modelos, fluxo de dados e estimativa de custo por execução.

O maestro é o agente principal que recebe a tarefa do usuário, decompõe em subtarefas e despacha cada uma a um subagente. Ele aguarda os resultados, consolida e entrega a resposta final.

Sem maestro explícito, não há coordenação — os subagentes não "conversam" entre si. Reconhecer o maestro como ponto único de orquestração é a peça central do design de workflows.

Topologia estrela: maestro no centro, subagentes nas pontas; o maestro passa contexto a cada subagente explicitamente; resultados voltam ao maestro, nunca circulam entre subagentes.

Um agente (CLAUDE.md) não pode invocar outro agente diretamente. A invocação acontece via skill (que pode chamar agents) ou via o próprio Claude Code quando executa um workflow de nível superior.

Projetar um agent que tenta chamar outro agent resulta em erro de execução ou comportamento indefinido. Conhecer o limite evita arquiteturas impossíveis e sugere o caminho correto (via skill).

Agent chama skill; skill chama agent; agent não chama agent. O loop de controle fica sempre no Claude Code principal ou numa skill orquestradora.

Uma skill (arquivo `.md` de instrução) pode conter lógica que dispara múltiplos agents em sequência ou em paralelo. É o padrão correto para criar pipelines complexos sem violar a regra agents-não-chamam-agents.

Skills são o "cola" do ecossistema. Entender como uma skill dispara agents permite construir workflows de N etapas sem precisar de um agent especial de orquestração.

Skill = instrução ao Claude Code; o Claude Code executa o agent invocado; a skill define a sequência lógica; o estado intermediário pode ser passado via arquivos ou mensagens.

Quando o resultado de A é necessário para que B comece, e o resultado de B é necessário para que C comece, temos um pipeline sequencial. O maestro aguarda cada etapa antes de disparar a próxima.

Misturar sequencial com paralelo sem perceber gera condições de corrida ou resultados incorretos. Identificar dependências entre tarefas é a primeira etapa do design de qualquer pipeline.

Dependência de dados = sequencial; independência = paralelo; o maestro decide a ordem baseado nas dependências; passar output de A como input de B via mensagem ou arquivo.

Cada subagente se comunica apenas com o maestro que o invocou. Não há canal lateral entre subagente A e subagente B. Para que A "passe algo" a B, o maestro precisa intermediar.

Projetos que assumem comunicação direta entre subagentes não funcionam. Conhecer esse limite antes de projetar evita arquiteturas que parecem elegantes no papel mas são impossíveis na prática.

Maestro é o único ponto de junção; "conversas" entre subagentes são ilusão — o maestro faz a intermediação; use arquivos compartilhados quando dois agentes precisam do mesmo dado.

Desenhe (em texto ou diagrama) um pipeline de 3 etapas para o job: "buscar issues abertas → priorizar por impacto → redigir comentários de triagem". Identifique quais etapas são sequenciais, quais podem ser paralelas.

A habilidade de decompor um job em etapas com dependências claras é a base de qualquer orquestração. Errar aqui é o erro mais comum de quem começa com multiagente.

Entregável: diagrama com setas direcionadas, modelos escolhidos, pontos de handoff e mecanismo de passagem de dados (mensagem ou arquivo).

O agente que construiu um artefato carrega no contexto toda a história de decisões que o levou àquele resultado. Esse contexto induz viés de confirmação — ele tende a validar o que já decidiu.

Um revisor com contexto limpo não tem acesso ao "porquê" das decisões — ele vê apenas o resultado. Esse isolamento gera críticas mais objetivas e identifica problemas que o builder ignorou.

Contexto limpo = começa do zero; não herda a "lógica interna" do builder; recebe apenas o artefato + critérios de avaliação; produz feedback sem ancoragem nas decisões originais.

O builder recebe a tarefa e produz o artefato (código, plano, pesquisa). O reviewer recebe o artefato + critérios e produz um relatório de qualidade. São dois subagentes distintos, convocados em sequência pelo maestro.

A separação de papéis aumenta a qualidade sem aumentar a complexidade do agente individual — cada um faz uma coisa e faz bem. O maestro decide se o feedback exige nova iteração do builder.

Fluxo: maestro → builder (produz) → maestro → reviewer (critica) → maestro (decide iterar ou publicar); o reviewer não tem acesso ao processo interno do builder.

O padrão builder-reviewer funciona para qualquer tipo de artefato: código (revisor verifica bugs e estilo), plano (revisor verifica viabilidade e riscos), pesquisa (revisor verifica fontes e consistência).

Reconhecer que o mesmo padrão se aplica em domínios diferentes permite reutilizar a mesma arquitetura de orquestração — só muda o critério passado ao revisor, não o pipeline.

Critérios explícitos no prompt do reviewer; domínio-específico (código: correctness, style; plano: feasibility, risk; pesquisa: sources, consistency); o revisor entrega um relatório estruturado.

`plan-roaster` e `code-reviewer` são subagentes disponíveis no ecossistema Claude Code que implementam o padrão revisor. São exemplos concretos para estudar e adaptar.

Estudar um revisor existente revela: como o critério é passado, como o output é estruturado, qual modelo usar para revisão, e como o maestro usa o resultado. É mais rápido do que projetar do zero.

Revisor recebe: artefato + critérios + escopo; produz: relatório com findings categorizados por severidade; o maestro decide agir baseado no relatório.

Após o revisor entregar o relatório, o maestro decide: os findings são críticos (nova iteração do builder) ou aceitáveis (publicar). Esse loop pode repetir 2–3 vezes antes de um critério de parada.

Sem critério de parada, o loop pode rodar indefinidamente. Definir "quando é bom o suficiente" antes de executar é tão importante quanto projetar os agentes.

Critério de parada: zero findings críticos, ou N iterações atingidas, ou deadline de custo; o maestro codifica o critério; o revisor reporta severidade para facilitar a decisão.

Use o diagrama de pipeline que você criou no M3.3 como artefato. Passe-o a um revisor (pode ser você mesmo com "contexto limpo" ou um subagente code-reviewer) com critérios: viabilidade, eficiência, pontos de falha.

Revisar o próprio trabalho com um olhar externo (mesmo simulado) é a habilidade de meta-qualidade. O exercício fecha o ciclo M3.3 → M3.4: você construiu e agora avalia.

Entregável: relatório com findings (ao menos 1 melhoria identificada); refletir sobre o que mudaria no diagrama do M3.3 após a revisão.

`ultracode` (anteriormente chamado "workflow") é o gatilho que instrui o Claude Code a operar em modo de alta escala: ele decompõe o job em dezenas de tarefas paralelas e dispara subagentes para cada uma.

Ativar `ultracode` para jobs pequenos desperdiça orçamento. Saber o que o gatilho faz por baixo permite usá-lo cirurgicamente — apenas quando a escala justifica.

Modo de planejamento automático + paralelização agressiva; o Claude Code estima o número de subagentes antes de executar; o usuário pode confirmar ou cancelar; custo estimado visível antes do commit.

Caso real documentado em que um único job disparou 41 subagentes em paralelo para refatorar um repositório grande. O resultado foi entregue em frações do tempo que levaria sequencialmente.

O caso concreto ancora o conceito: não é teoria. Mostra o que é possível, qual foi o custo real, e quais foram os acertos e problemas encontrados na execução em alta escala.

41 subagentes Haiku; maestro Sonnet; tarefa: refatorar 80+ arquivos; custo estimado: ~$8 na execução; tempo total: ~6 min vs ~2h sequencial; cobertura de testes mantida.

Sessões com dezenas de subagentes consomem tokens rapidamente. Limites de taxa da API (rate limits) e limites de sessão do Claude Code podem interromper um workflow no meio.

Não planejar o orçamento antes de um ultracode leva a jobs incompletos e custo desperdiçado. Entender os limites permite dimensionar o job corretamente — ou dividi-lo em lotes menores.

Rate limits por minuto e por dia; limite de sessão do Claude Code (tokens por janela); estratégia de batching: dividir em grupos de 10–20 subagentes para respeitar os limites.

Checklist prático: 10+ arquivos a modificar, tasks genuinamente paralelas (sem dependências entre si), output esperado que causaria truncamento num contexto único, refatoração de larga escala, análise em paralelo de múltiplos módulos.

A checklist evita a decisão por intuição. Com ela, você chega a "sim/não para workflow" em 30 segundos, antes de rodar qualquer coisa.

Qualquer "sim" forte na checklist aponta para workflow; sinal vermelho: tarefa pequena, contexto compartilhado necessário, resultados interdependentes; dúvida = não use workflow.

Em workflows de 40+ subagentes, falhas parciais são esperadas. O maestro precisa detectar quais subtarefas falharam e decidir: retentar, ignorar ou abortar o job inteiro.

Jobs sem estratégia de recuperação falham completamente quando qualquer subagente falha. Projetar o tratamento de falha antes da execução reduz o custo de retrabalho e aumenta a robustez.

Log de resultados por subagente; identificar falhos por id; estratégia "retry once, then skip"; o maestro consolida com marcação de incomplete onde necessário.

Dados 3 cenários (A: refatorar 1 arquivo; B: analisar 100 PRs fechados; C: escrever testes para 15 módulos), aplique a checklist e responda: workflow ou não? Justifique cada decisão.

A prática da decisão binária com justificativa é a habilidade-chave do módulo. Respostas sem justificativa não contam — o raciocínio é o entregável, não o sim/não.

Gabarito: A = não (único arquivo); B = sim (100 tarefas paralelas independentes); C = sim (15 módulos separáveis); o módulo completo tem análise detalhada de cada caso.

N subagentes rodando ao mesmo tempo, cada um com sua própria tarefa isolada, sem dependência entre si. O maestro dispara todos e aguarda todos terminarem para consolidar.

É o padrão mais eficiente para tarefas uniformes em larga escala: analisar N arquivos, buscar N documentos, gerar N rascunhos. Identificar quando as tarefas são genuinamente independentes é o pré-requisito.

Independência total: nenhum subagente precisa do resultado de outro; o maestro sincroniza no final; custo = N × custo individual; speedup = N× (limitado pelo rate limit).

Etapas A → B → C onde o output de cada etapa é o input da próxima. O maestro executa um de cada vez, aguardando cada resultado antes de prosseguir.

Para tarefas com dependências de dados, o pipeline é o único padrão correto. Forçar paralelismo onde há dependência gera erros ou resultados inconsistentes — reconhecer dependências é essencial.

Latência total = soma das latências individuais; não há speedup por paralelismo; cada etapa pode usar um modelo diferente (ex: Haiku coleta, Sonnet sintetiza, Opus decide).

1 entrada → N subagentes paralelos → 1 resultado agregado. O maestro dispara N workers com partes diferentes do problema, aguarda todos, e passa os N resultados a um agregador que sintetiza o resultado final.

Fan-out é o padrão do ultracode. Entender a estrutura "dispatcher → workers → aggregator" permite projetar qualquer workflow de alta escala e entender o que o Claude Code faz por baixo quando você usa ultracode.

Dispatcher: maestro que parte a entrada; workers: Haiku/Sonnet em paralelo; aggregator: agente separado (Sonnet/Opus) que consolida; resultado final: único, coerente, completo.

Agent teams são configurações onde múltiplos agentes compartilham contexto e se comunicam diretamente — diferente dos subagentes clássicos com topologia estrela. Custam mais por manter múltiplos contextos abertos.

Saber a diferença evita confundir as duas arquiteturas. Agent teams são raros no Claude Code e geralmente mais caros e complexos. Para a maioria dos casos, subagentes com maestro central são mais eficientes.

Subagentes: topologia estrela, maestro central, contextos isolados, mais barato. Agent teams: grafo de comunicação, contextos parcialmente compartilhados, mais caro, menos comum.

Heurística prática: se o job envolve 10+ arquivos separáveis OU produziria um output que truncaria num único contexto, use fan-out ou paralelo. Caso contrário, pipeline sequencial ou agente único.

Ter uma heurística numérica evita a análise detalhada para cada job. "10 arquivos" é o threshold prático derivado de experiência real — abaixo disso, a overhead do multiagente geralmente não compensa.

10 arquivos = ~threshold de overhead; "parede de output" = resultado que causaria > 50% do contexto; ambos são sinalizadores, não regras absolutas; o julgamento final é do operador.

Dados 3 problemas (A: traduzir 30 arquivos Markdown; B: gerar release notes a partir de 50 commits analisados em ordem; C: revisar código + propor refatoração + implementar), escolha a topologia e justifique.

O exercício fecha a trilha: você aplica o vocabulário de topologias a problemas reais. Gabarito: A = paralelo independente; B = fan-out + pipeline (coleta paralela, síntese sequencial); C = pipeline (3 etapas dependentes).

Entregável: tabela problema × topologia × justificativa × modelos escolhidos. O módulo completo inclui implementação de referência para cada caso.