[🛠] AI Orchestration #5: Redesenhei a separação entre coordenador e workers que eu havia abandonado

✨ Resumo do GPT-5.6 Sol

Um registro de como abandonei a divisão do trabalho quando as mensagens fizeram o coordenador perder o contexto e, após enfrentar o gargalo de uma única sessão, a redesenhei com relatórios em arquivos e commits exclusivos do coordenador.

Eu já havia desistido de separar o coordenador dos workers

No mês passado, conectei de verdade um coordenador a vários workers. Um objetivo era dividido em várias tarefas, e o coordenador revisava e integrava o que os workers implementavam.

A divisão do trabalho em si era rápida. Funcionalidades independentes podiam ser implementadas ao mesmo tempo, enquanto o coordenador cuidava apenas da direção geral do produto e da integração. O problema era a forma como os workers entregavam seus resultados.

Sempre que terminavam ou ficavam bloqueados, eles enviavam um relatório à sessão do coordenador. No início, isso pareceu natural. Mas, à medida que o número de workers cresceu, os relatórios se acumularam na conversa e cada nova mensagem interrompia o trabalho atual e desviava a atenção para outra tarefa.

Eu lia o resultado de teste de um worker, passava a verificar o conflito de Git index de outro e, quando tentava voltar à implementação original, chegava um terceiro relatório de conclusão. A conversa crescia rapidamente. Quanto mais a compactação se repetia, mais tempo era gasto para reconstruir o objetivo, as proibições de deploy e o estado atual do stage. Em certo ponto, o coordenador parecia menos um integrador e mais uma central de mensagens dos workers.

Por fim, abandonei a própria separação entre coordenador e workers. Cheguei a apagar por impulso a Skill de coordenação que havia criado. Pensei que fazer tudo em uma única sessão principal ao menos evitaria que o contexto fosse puxado em várias direções.

Voltar a uma única sessão mostrou por que a divisão era necessária

Porém, ao continuar um grande trabalho de produto em uma só sessão, o gargalo oposto apareceu imediatamente.

Implementação, testes, alinhamento de documentos, verificação em dispositivos físicos e preparação do Runtime precisavam ser feitos em sequência pela mesma sessão. Se uma pergunta de prioridade ou uma entrega de outra sessão surgisse no meio, eu tinha de reconstruir primeiro o estado do trabalho em andamento. Terminar uma coisa com segurança alongava o todo; atender primeiro ao urgente exigia decidir até onde encerrar a tarefa existente.

O problema não era a divisão do trabalho. Ineficiente era uma sessão segurar até tarefas independentes. Separar coordenador e workers continuava sendo a opção mais eficiente, mas reativar a estrutura em que os workers entravam diretamente na conversa atual do coordenador apenas repetiria a falha.

Desta vez, em vez de desistir da divisão, decidi remover o caminho de entrega que interrompia o contexto do coordenador.

Uma notificação de uma linha abria a mesma porta

Primeiro pensei que os workers poderiam enviar uma linha curta em vez de um relatório longo.

READY task-042: caminho do relatório

Mas o problema não era o tamanho. Assim que uma mensagem entrava na conversa do coordenador, o Codex podia tratá-la como um contexto mais recente que o trabalho em andamento. Mesmo uma única linha mantinha aberta a mesma entrada para trocar de tarefa.

Por isso os workers deixaram de enviar mensagens ao coordenador. Estados de conclusão, bloqueio e falha são gravados apenas em arquivos de relatório. O coordenador verifica o inbox somente depois de levar seu próprio trabalho a um checkpoint ou commit seguro.

A chegada de um relatório não é um evento que interrompe o trabalho atual. Ela apenas adiciona um arquivo à próxima fila de revisão.

Os Worktrees estavam limpos, mas se afastavam do estado mais recente

Depois considerei dar a cada worker um Worktree e uma Branch separados. O Git index e as alterações sem commit não se misturavam, então essa parecia a opção mais limpa.

Em projetos reais, porém, surgiu um problema maior. Várias funcionalidades continuavam tocando a mesma API, o mesmo schema e a mesma tela. Melhorias concluídas em uma sessão não apareciam de imediato nos outros Worktrees. Cada pessoa trabalhava de forma limpa, mas na integração havia uma pilha de mudanças feitas sobre estruturas antigas. O volume de retrabalho então ficava feio.

Desta vez escolhi a estrutura oposta.

Um único main Working Tree
├─ Vários workers enxergam juntos as alterações mais recentes
├─ Workers editam apenas os arquivos e hunks atribuídos
├─ Workers não fazem stage nem commit
└─ Apenas o coordenador revisa, faz stage e commit

Um Working Tree compartilhado também se emaranha rapidamente sem limites. Por padrão, cada arquivo tem um único writer; edições paralelas no mesmo arquivo só são permitidas quando os hunks estão claramente separados. Schemas compartilhados, limpeza de imports, formatters e outras mudanças que deslocam código ao redor são serializados.

Os testes de um worker também não são aceitos como evidência final. Eles podem ter sido executados junto com alterações não commitadas de outro worker. Cada worker verifica seu próprio escopo; o coordenador congela o conjunto de mudanças e executa uma vez a regressão completa e o build.

Os relatórios se tornaram contratos de revisão

Reconstruí a Skill de coordenação removida com esses princípios. A nova Skill custom-coordinate-parallel-workers contém esse fluxo.

O coordenador atribui um task id, o resultado esperado pelo usuário e os caminhos graváveis. O worker conclui implementação, verificação delimitada e limpeza de processos temporários, gera o relatório de forma atômica e para. O relatório lista os arquivos realmente alterados, resultados das verificações, sobreposições, escopo inacabado e um commit proposto.

O coordenador não relê todas as conversas. Primeiro consulta no inbox o task id, o status, o título e o resumo das verificações; depois escolhe uma tarefa para integrar. Ele confirma se o relatório corresponde ao diff real e só então faz stage e commit dos hunks exatos.

Quando um candidato a release é escolhido, um freeze impede novas mutations dos workers. Em vez de repetir testes completos enquanto mudanças continuam chegando, a documentação de current state, a regressão completa, o build e a verificação de deploy começam quando o conjunto da release para de se mover.

O relatório deixou de ser um simples diário de trabalho. Tornou-se o contrato de revisão que permite ao coordenador confiar na mudança e levá-la ao próximo estado.

Agora precisa funcionar no trabalho real

Testei as ferramentas de gestão de estado da Skill em um ambiente temporário isolado. Além da conclusão normal, passaram conflitos de caminhos graváveis, retrabalho após solicitação de mudança, rejeição do freeze durante a execução e adiamento para o próximo batch.

Ainda não operei várias sessões reais do Codex dessa forma. A próxima tarefa paralela terá de mostrar se relatórios apenas em arquivos realmente perturbam menos o contexto do coordenador e se a propriedade dos caminhos no Working Tree compartilhado é respeitada como esperado.

A conclusão é parecida com a inicial, mas a razão agora está mais clara. Coordenador e workers precisam ser separados. O que falhou não foi a divisão do trabalho, e sim empurrar cada relatório em tempo real para a conversa atual do coordenador.

A mudança que espero não é simplesmente abrir mais workers. É permitir que o coordenador preserve seu contexto até concluir o próprio trabalho. A velocidade do trabalho paralelo dependia menos do número de workers e mais de quantas vezes a pessoa que integrava os resultados era desviada.