Fan-out de agentes com git worktrees: edições paralelas sem ninguém pisar no pé de ninguém

O padrão: um pai, vários filhos com permissão de escrita

O Muse Code funciona em cima de uma regra simples: quando um trabalho se divide em várias tarefas distintas, elas se espalham automaticamente entre agentes separados. O agente pai cria um filho com permissão de escrita para cada tarefa. Você não configura nada nem ativa nenhum “modo paralelo” especial — decompor e distribuir é o comportamento padrão sempre que o trabalho é grande o suficiente para valer a pena.

A pergunta óbvia vem na sequência: se vários agentes podem escrever código ao mesmo tempo, no mesmo repositório, por que isso não termina em uma pilha de conflitos de merge e arquivos sobrescritos?

Uma sessão real de fan-out: seis tarefas em um jogo, quatro já com merge feito, duas ainda rodando — cada uma na sua própria worktree dentro de .muse/worktrees/, com o checkout principal intocado.

Worktrees: isolamento do jeito que o git gosta

Cada agente filho ganha sua própria git worktree — um checkout separado do repositório que compartilha o histórico com a sua cópia principal, mas tem diretório de trabalho e branch próprios. Dois filhos podem editar o mesmo arquivo em suas respectivas worktrees sem nunca enxergar as mudanças um do outro no meio do caminho. Estruturalmente, a colisão simplesmente não tem como acontecer.

E tem um detalhe igualmente importante: a sua cópia de trabalho continua limpa. O diretório aberto no seu editor nunca é o que um agente está modificando. Nada se move debaixo do seu cursor, nenhuma edição pela metade aparece no seu diff, e abandonar o trabalho de um agente custa o mesmo que descartar a worktree dele. As mudanças só chegam à sua branch quando o trabalho está pronto e revisado.

Por que não usar só branches? Ou containers?

Branches comuns compartilham um único diretório de trabalho — trocar de branch no meio de uma tarefa puxaria o tapete de um agente em execução. Containers completos ou clones do repositório funcionariam, mas são pesados demais: object stores duplicados, setup lento, merge desajeitado. Worktrees acertam o ponto ideal. São quase instantâneas de criar, compartilham o banco de objetos do git por baixo, e fazer o merge da branch finalizada de um filho é git comum — sem camada de sincronização customizada para você ter que confiar, sem estado proprietário para debugar.

Seis funcionalidades ao mesmo tempo, na prática

As demos de lançamento apostaram pesado nesse mecanismo: no exemplo de desenvolvimento de jogos, o Muse Code construiu seis funcionalidades do jogo simultaneamente, cada agente na sua própria worktree, e todas as branches fizeram merge limpo. Esse é o ganho prático — o tempo de relógio de uma sprint com várias funcionalidades cai para perto da duração da tarefa individual mais longa, em vez da soma de todas elas.

Experimente a receita

O fan-out de agentes é um dos três padrões para os quais a Meta publica receitas no cookbook — dividir um trabalho grande entre subagentes sem que nada colida no meio do caminho. O cookbook tem a versão executável. E como trabalho distribuído em fan-out é exatamente o tipo de coisa que você vai querer auditar depois, cada spawn de filho, cada chamada de ferramenta e cada merge fica registrado no event log — nada acontece fora do registro só porque aconteceu em paralelo.