Coordenação do trabalho entre agentes de codificação
Você é o coordenador: você possui a definição da tarefa, revisa cada entrega e decide o que acontece a seguir. Cada outro agente é um trabalhador: ele recebe uma especificação, produz um artefato e para. Não há um barramento de mensagens entre fornecedores, portanto, a coordenação é baseada em turnos e mediada por arquivos:
você escreve task.md -> trabalhador executa em modo headless -> trabalhador escreve result.md ->
você lê, verifica, decide o próximo turno
Se o agent-sync estiver instalado, execute agent sync antes de delegar para que cada
trabalhador comece com a mesma memória sintetizada que você tem.
1. Escreva o diretório da tarefa
task/
task.md # a especificação (veja o contrato abaixo)
...inputs... # tudo que o trabalhador precisa; os trabalhadores não recebem nenhum outro contexto
result.md # o trabalhador escreve isso; sua existência sinaliza a conclusão
task.md é um resumo para o contratante e deve conter:
- o objetivo, em um parágrafo;
- a entrega exata (um arquivo, nomeado);
- uma definição de pronto verificável;
- a instrução para parar após escrever a entrega;
- as regras de bloqueio ou worktree da seção 2 quando o trabalhador for editar uma árvore compartilhada.
2. Escolha o modo de compartilhamento ANTES de invocar qualquer pessoa
Regra zero: dois agentes nunca devem modificar a mesma árvore de trabalho ao mesmo tempo.
| Situação | Modo |
|---|---|
| Trabalhador apenas lê (revisão, análise, segunda opinião) | Mesmo diretório, sem bloqueio |
| Edições alternadas em uma árvore | Mesmo diretório + bloqueio mkdir |
| Tentativas paralelas ou subtarefas paralelas que tocam em arquivos | Uma git worktree por trabalhador |
| Dois agentes editando uma árvore simultaneamente | Nunca; reestruture |
Bloqueio no mesmo diretório (mkdir é atômico; coloque estas instruções também em task.md):
until mkdir .agent-lock 2>/dev/null; do sleep 1; done # adquirir
echo "$(whoami):$$" > .agent-lock/owner
# ... trabalhar ...
rm -rf .agent-lock # liberar
Nunca expire automaticamente um bloqueio por idade: um trabalhador lento parece idêntico a um morto. Verifique se o processo do trabalhador está morto antes de limpar um bloqueio obsoleto.
Modo Worktree: git worktree add ../task-<worker> -b agent/<worker> por
trabalhador, trabalhadores nunca fazem push e nunca tocam nas árvores uns dos outros, o checkout
principal permanece somente leitura, e você (o coordenador) faz toda a mesclagem como
a única etapa serializada.
3. Invoque o trabalhador em modo headless
| Trabalhador | Comando |
|---|---|
| Claude Code | claude -p "Leia o task.md neste diretório e complete-o." |
| Codex CLI | codex exec --skip-git-repo-check --sandbox workspace-write "Leia o task.md neste diretório e complete-o." </dev/null |
| Gemini CLI | gemini -p "Leia o task.md neste diretório e complete-o." |
Regras aprendidas da maneira mais difícil:
- Execute o trabalhador de dentro do diretório da tarefa e limite seu acesso de escrita a ele.
- Feche o stdin (
</dev/null) para qualquer trabalhador em segundo plano ou ele pode travar esperando por entrada. - O Codex recusa diretórios não confiáveis e que não são git sem
--skip-git-repo-check.
4. Verifique, depois decida
- A palavra do trabalhador não é a entrega. Leia
result.mde verifique-o contra a definição de pronto; para código, execute os testes você mesmo. - Uma entrega ausente ou errada gera um novo turno com uma especificação mais precisa, não uma repetição da mesma.
- Você continua responsável por tudo que aceitar: revise o diff de um trabalhador como revisaria o PR de um contratante humano.
Limites
- Nunca dê a um trabalhador credenciais, direitos de implantação ou acesso a públicos reais; trabalhadores produzem artefatos, o coordenador (com o usuário) os envia.
- Nunca execute este protocolo para paralelizar edições dentro de uma árvore sem bloqueios ou worktrees, mesmo para tarefas "rápidas".
- O usuário decide qual agente atua como coordenador; não transfira a coordenação para um trabalhador.