🎭 O Orchestrator: Cerebro do Sistema
No centro de qualquer sistema de loop engineering escalavel esta o orchestrator: a sessao de agente que le a especificacao, decide quais tarefas executar, dispara workers e valida resultados. Ele nao escreve codigo diretamente. Seu papel e raciocinar sobre o estado do projeto e tomar decisoes de alto nivel sobre o que fazer a seguir.
💬 Como Cole Medin Descreve o Orchestrator
"We send in our initial spec to the orchestrator and it has to reason about that and then figure out how many workers to spin off. And then it has to prompt them all. They each spend tokens and then the results come back."
O orchestrator funciona como um gerente de projeto automatizado. Ele recebe a spec (o que precisa ser feito), analisa o estado atual do repositorio, e decide: quantos workers preciso? Quais tarefas atribuir a cada um? Em que ordem? Quando o trabalho esta completo? Cada uma dessas decisoes custa tokens de reasoning, e e por isso que o orchestrator e uma das partes mais caras do sistema.
📋 Responsabilidades do Orchestrator
- ✓Ler a spec e entender o escopo total do trabalho
- ✓Planejar rounds: dividir o trabalho em ondas de execucao
- ✓Despachar workers: criar prompts especificos para cada worker
- ✓Validar resultados: verificar se os workers entregaram o esperado
- ✓Decidir proximo passo: lancar nova onda ou declarar conclusao
⚙ Workers: Execucao Paralela e Isolada
Workers sao sessoes de agente independentes que recebem uma tarefa especifica do orchestrator e a executam. Cada worker opera em isolamento, idealmente numa worktree propria do git, para que multiplos workers possam trabalhar em paralelo sem pisar no codigo um do outro.
"If we're having many different agents handling tasks in a loop, we need to make sure they're running in isolation so they're not stepping on each other's toes. That is how we scale our output with AI coding assistance."
✓ Worktrees para Isolamento
- ✓Cada worker opera numa copia isolada do repositorio
- ✓Sem conflitos de arquivo entre workers paralelos
- ✓Cada um pode commitar e criar branches independentes
- ✓Merge controlado pelo orchestrator ao final
⚙ Anatomia de um Worker
- 1.Recebe tarefa especifica do orchestrator
- 2.Inicia sessao de agente numa worktree
- 3.Executa: escreve codigo, roda testes, valida
- 4.Reporta resultado ao state store
💾 State Management Externo
Um dos problemas mais criticos de loops longos e o context bloat: conforme o agente acumula historico de conversacao, a janela de contexto do LLM fica sobrecarregada e a qualidade das respostas degrada. A solucao arquitetural e mover o estado para fora do LLM, usando um banco de dados externo como fonte de verdade.
"When you're just using slash loop in Claude Code, it's really just continuing in the same coding agent session. So if you loop for a while, you're going to completely bloat your context for your LLM and overwhelm it."
📊 Context Window vs State Store
✗ Sem State Externo
Todo o historico vive no context window. Apos 10-20 iteracoes, o LLM comeca a "esquecer" instrucoes iniciais, gerar codigo repetido, e perder coerencia. E como tentar memorizar um livro inteiro em vez de consultar notas.
✓ Com State Externo (Postgres/Neon)
O banco armazena: tarefas concluidas, tarefas pendentes, resultados de validacao, logs de decisao, custo acumulado. Cada nova sessao do orchestrator le apenas o estado atual, nao o historico inteiro. O context window vira cache, nao storage.
🗄 O que o State Store armazena
Runs
Historico de execucoes: spec original, rounds realizados, status geral (running, paused, completed, failed).
Events / Logs
Cada decisao do orchestrator e cada resultado de worker. Permite auditoria e debug pos-execucao.
Task State
Status de cada tarefa individual: pending, in_progress, completed, failed. O orchestrator le isso para decidir o proximo round.
Cost Tracking
Tokens consumidos por round, por worker, custo total acumulado. Permite definir budget limits.
🔄 O Fluxo Completo de um Round
Um "round" e a unidade de trabalho do sistema orchestrator-workers. Cada round segue um fluxo previsivel: o orchestrator le o estado, decide o que fazer, despacha workers, coleta resultados, e avalia se precisa de mais rounds. Esse ciclo se repete ate que o goal seja atingido ou o budget se esgote.
🏃 Passo a Passo de um Round
Orchestrator le o state store
Consulta o banco para saber: quais tarefas estao pendentes? O que os workers do round anterior entregaram? Ha erros para corrigir?
Planeja a onda de workers
Decide quantos workers disparar, quais tarefas atribuir a cada um, e monta os prompts especificos. Esse e o fan-out.
Workers executam em paralelo
Cada worker inicia numa worktree isolada, executa sua tarefa (escreve codigo, roda testes), e grava o resultado no state store.
Fan-in: orchestrator coleta resultados
Quando todos os workers terminam, o orchestrator le os resultados do state store e avalia: tudo passou? Ha falhas? Preciso re-rodar algum worker?
Decisao: proximo round ou conclusao
Se ha trabalho restante, o orchestrator planeja o proximo round. Se o goal foi atingido, declara a run como completa e reporta ao humano.
"The orchestrator spent 6,000 tokens with that initial planning and then prompting our first three workers in round number one."
🛡 Durabilidade e Resumabilidade
Loops longos inevitavelmente falham em algum ponto. A maquina pode reiniciar, a sessao do agente pode cair, a rede pode oscilar. A questao nao e se vai falhar, mas quando. Durabilidade significa que o sistema pode retomar de onde parou, sem perder o trabalho ja feito. E isso so e possivel com state management externo.
"All of the loops that we run and the different events and logs, I'm storing this here so we can always resume a workflow later on. So we're managing all of our state in an external database."
🔧 Como a Resumabilidade Funciona
Checkpoint por round
Ao final de cada round, o estado completo e gravado no banco: tarefas concluidas, resultados de workers, decisoes do orchestrator. Se o sistema cair entre rounds, basta ler o ultimo checkpoint e continuar.
Resume from last good state
O orchestrator nao precisa de historico de conversacao para retomar. Ele le o state store e sabe exatamente onde o projeto esta. Uma nova sessao de agente e tao eficaz quanto a anterior.
Cleanup de workers orfaos
Se um worker cai no meio da execucao, o orchestrator detecta (via timeout ou status no banco) e pode re-despachar a tarefa para um novo worker no proximo round.
🎯 Ponto de Reflexao
Sem durabilidade, loop engineering e um brinquedo caro. Imagine rodar um loop por 4 horas, gastar centenas de milhares de tokens, e perder tudo porque o terminal fechou. O state externo transforma um experimento fragil num sistema que pode rodar de verdade. Cole Medin construiu exatamente isso no seu dashboard: "I'm storing this here so we can always resume a workflow later on."
❓ Questionamentos
A arquitetura orchestrator-workers e elegante no papel, mas levanta questoes praticas serias. Cole Medin, apesar de construir um dashboard funcional para isso, mantem uma posicao cautelosa.
O orchestrator e um gargalo de custo?
Cada decisao do orchestrator consome tokens de reasoning. Quanto mais complexa a spec, mais tokens para planejar rounds e avaliar resultados. Cole mostrou que uma unica run de um app simples consumiu mais de 1 milhao de tokens. A pergunta e: vale a pena pagar esse preco de reasoning para cada decisao, ou um workflow deterministico (como o Archon) resolve melhor?
Quem valida o validador?
O orchestrator valida os resultados dos workers, mas o orchestrator tambem e um LLM. Se ele alucinara na validacao (aceitando resultado ruim como bom), o erro se propaga para os rounds seguintes. Sem human-in-the-loop em pontos criticos, a auto-validacao pode ser um ponto cego perigoso.
Determinismo vs. autonomia: onde esta o equilibrio?
Cole Medin prefere workflows deterministicos onde o humano define os steps. Boris Cherny prefere autonomia total com o orchestrator decidindo tudo. A verdade provavelmente esta no meio: usar o orchestrator para decisoes de roteamento e modelo para codigo, mas nao para definir o processo inteiro.
⚠ A Provocacao de Cole
Cole sintetiza sua posicao sobre dar autonomia total ao orchestrator: "We want to actually take the decision away from the coding agent as much as we can, only applying the reasoning of the LLM when we actually need it to write the code." O orchestrator deve ser o minimo necessario, nao o maximo possivel.
📋 Resumo do Modulo
Proximo Modulo:
2.1 — Vantagens Reais (Trilha 2: Vantagens vs Desvantagens)