Como Escalar Agentes de Codificação de IA em uma Equipe de Desenvolvimento

Um desenvolvedor com um agente de codificação é uma história de produtividade. É fácil de contar, demonstra bem e é genuinamente verdadeira.

Cinco desenvolvedores com vinte agentes é uma coisa completamente diferente. É um problema de coordenação, e problemas de coordenação não são resolvidos pela ferramenta que os criou. Esta é a parte que ninguém escreve, porque só aparece após a fase de entusiasmo: os ganhos individuais são reais, chegam imediatamente, e então, em algum momento ao redor do terceiro ou quarto desenvolvedor, a equipe começa a gastar sua nova velocidade limpando a bagunça que fez.

O que se segue é a ordem de falha. Não uma lista de melhores práticas no abstrato, mas a sequência em que as coisas realmente quebram, porque consertá-las na ordem errada desperdiça um quarto.

O que quebra primeiro: contexto compartilhado

Cada desenvolvedor que executa um agente está silenciosamente ensinando sua própria versão da base de código.

Uma pessoa diz ao seu agente que o projeto usa ações de servidor e nunca rotas de API. Outra nunca menciona isso, então seu agente escreve rotas de API. Um terceiro menciona uma vez, em uma sessão que terminou três dias atrás. Ninguém está errado, ninguém está mentindo, e o repositório agora contém três interpretações da mesma convenção. Você notará isso na fila de revisão, que é o lugar errado para notar: até lá, o código já existe.

A correção é chata e é a coisa de maior alavancagem nesta página. Coloque as convenções em um arquivo, faça o commit do arquivo.

CLAUDE.md para Claude Code, AGENTS.md para Codex e a maioria dos outros agentes CLI, e na prática muitas equipes mantêm um arquivo de contexto portátil em vez de manter dois que se afastam. O mecanismo importa mais do que o nome do arquivo: as instruções vivem no repositório, então elas chegam com um git pull em vez de chegarem através de quem quer que estivesse na sala.

O que deve estar nele:

• As convenções que um agente não pode inferir lendo o código, especialmente aquelas que a base de código atualmente viola em alguns lugares
• Os comandos: como executar os testes, a construção, o linter, e quais deles podem ser executados automaticamente
• As partes do repositório que são perigosas de tocar, e por quê
• O que a equipe não quer: a refatoração que ninguém pediu, a dependência que não deve ser adicionada, o padrão do qual estão migrando

O que não deve estar nele, e aqui é onde as equipes se queimam: qualquer coisa específica de uma máquina. Caminhos absolutos, tokens de API pessoais, portas locais, o editor preferido de alguém. No momento em que um valor específico de máquina cai em um arquivo de contexto comitado, cada outro desenvolvedor herda uma configuração que está errada para eles, e os agentes são extremamente bons em seguir instruções que não se aplicam mais.

Um teste útil antes de adicionar uma linha: se um colega puxar isso, isso ajuda ou quebra?

O que quebra segundo: dois agentes, um arquivo

Agentes não negociam. Eles não verificam se alguém mais está editando. Dois agentes apontados para o mesmo módulo irão sobrescrever um ao outro, e nenhum mencionará isso, porque do ponto de vista de cada um, o trabalho foi concluído com sucesso.

Sozinho, isso é invisível. Você executa um agente por vez, ou executa vários e eles tocam em coisas diferentes. Em uma equipe, isso se torna estrutural, e produz a pior classe de bug: trabalho que desaparece silenciosamente entre duas execuções de teste bem-sucedidas.

Dois mecanismos consertam isso, e você quer ambos.

Isolamento. Git worktrees dão a cada tarefa seu próprio checkout do repositório, então agentes paralelos fisicamente não podem colidir. Esta é a metade barata da solução e não há razão para não fazê-lo.

Propriedade. O isolamento impede a sobrescrita; não impede que duas pessoas resolvam o mesmo problema duas vezes, em dois ramos, de duas maneiras incompatíveis. Isso é resolvido no momento da atribuição, delimitando cada tarefa a um conjunto de arquivos e dizendo isso na própria tarefa. Não "melhorar o fluxo de checkout", mas "mudar a etapa de pagamento, nesses três arquivos, não toque no carrinho".

A segunda metade é a que as equipes pulam, e é a que determina se a mesclagem é uma formalidade ou uma tarde.

O que quebra terceiro: revisão

Tudo sobre revisão em escala de equipe segue de um número: quanto diff chega por hora.

Um desenvolvedor lendo cada linha funciona bem. Cinco desenvolvedores executando quatro agentes cada um geram mais diff por dia do que a equipe pode ler, e o resultado honesto não é uma revisão cuidadosa, é um teatro de aprovação. Um humano folheando um diff de novecentas linhas às 18h produz uma assinatura sem produzir conhecimento, o que é pior do que não revisar, porque fabrica uma garantia onde não há nenhuma.

A política que sobrevive não é "revisar tudo" e não é "confiar nos agentes". É mover a revisão para as duas fronteiras do trabalho: ler o plano antes que o agente comece, porque um plano errado executado perfeitamente é o modo de falha mais caro disponível, então ler o diff em proporção ao que a mudança pode quebrar. Cópia de marketing e CSS recebem uma olhada. Autenticação, pagamentos, permissões, dados pessoais e migrações são lidos linha por linha por um humano, toda vez, independentemente de quão limpo o diff pareça.

Isso merece uma conversa própria, e escrevemos separadamente sobre isso: você ainda deve revisar o código do seu agente de IA passa pelos dez sinais objetivos de que uma mudança deu errado, e a tabela de raio de explosão que as equipes podem adotar como está.

Uma adição específica da equipe. Quando vários agentes compartilham um repositório, a revisão precisa de atribuição: qual agente, qual tarefa, qual desenvolvedor. Sem isso, um diff não tem autor e a revisão se torna arqueologia. Esta é a única coisa mais útil para corrigir em sua configuração uma vez que você passe de três ou quatro agentes concorrentes.

O que quebra quarto: custo, e a conversa sobre custo

O gasto de tokens deixa de ser um detalhe pessoal no momento em que aparece em uma fatura da equipe.

A armadilha é que a fatura é mensal e agregada, então a conversa que ela produz também é mensal e agregada, o que significa que produz uma política em vez de uma correção. Alguém propõe um modelo mais barato para todos. Alguém mais propõe limitar sessões. Ambos são palpites.

A distribuição real quase nunca é uniforme. É um pequeno número de sessões de longa duração, em um ou dois projetos, com contexto que cresceu o dia todo e nunca foi redefinido. Esse é um comportamento corrigível, e você só pode consertá-lo se puder ver o gasto por sessão e por projeto em vez de por mês. Cobrimos a mecânica disso em como verificar o uso de tokens e como cortá-lo sem desacelerar.

Torne o número visível para as pessoas que o geram, antes que se torne um tópico de gestão. Um desenvolvedor que pode ver que uma sessão custou mais do que todo o seu dia anterior muda seus hábitos por conta própria, e isso não custa nada politicamente para a equipe.

O que realmente muda nos rituais da equipe

Três coisas, em nossa experiência e no que as equipes relatam.

Standup muda de status para desbloqueio. O que cada pessoa fez ontem é amplamente visível nos ramos. O que vale cinco minutos é quais agentes estão presos, e em quê.

Prompts se tornam ativos compartilhados. A instrução que obteve um bom resultado para um desenvolvedor vale mais para a equipe do que o código que produziu, e é exatamente o tipo de coisa que evapora no histórico de um terminal privado. Equipes que mantêm uma biblioteca de prompts compartilhada no repositório param de redescobrir a mesma formulação toda semana.

Especialização se move de pessoas para papéis. Uma vez que os agentes lidam com a escrita, a pergunta interessante é quem revisa o quê, e as equipes naturalmente tendem a atribuir papéis aos agentes da mesma forma que os atribuem às pessoas: um na implementação, um na revisão, um nos testes. Essa é a ideia por trás dos Agentes de Equipe, onde uma tarefa é passada de um papel de Dev para um papel de QA com o diff, os riscos e as dicas de teste anexadas, e os portões de qualidade são decididos pelo seu conjunto de testes em vez da própria opinião de um agente sobre seu trabalho.

A configuração que se mantém

Condensado, na ordem que importa:

Os quatro primeiros não custam nada além de concordância. Os últimos dois são a razão pela qual uma equipe eventualmente quer algo acima do terminal: não porque terminais são ruins, mas porque um terminal mostra um agente por vez e não dá a você uma maneira de responder "quem está executando o quê, em qual projeto, agora".

Esse é o problema AgentsRoom para equipes é construído em torno: cada agente em cada projeto em uma visão, com seu papel, seu status e seu custo anexados, e um companheiro móvel para os momentos em que a equipe não está em suas mesas. Funciona da mesma forma com Claude Code e com Codex, o que importa mais do que parece: a maioria das equipes acaba executando ambos, e uma configuração que assume um provedor se torna silenciosamente a próxima coisa que quebra.

Comece com o arquivo de contexto, no entanto. É gratuito, leva uma tarde, e remove mais atrito do que qualquer ferramenta que você possa instalar neste trimestre.