A maioria de nós desenvolvedores já escreve código com IA diariamente. O que eu acredito ser mais incomum é um time inteiro usar IA de forma padronizada sem cair em dois extremos: virar muito burocrático e ninguém seguir, ou continuar cada um por si e ninguém saber se está no caminho certo.

Esse texto é sobre o meio-termo. Não é um tutorial de config (a documentação oficial faz isso melhor e mais atualizada que qualquer post), e não é um case de sucesso ou com resultados, porque acho que ninguém tem ainda. É a forma como interpretei o problema depois de estudar os materiais que a Anthropic e a Cognition publicaram sobre o assunto, lido pela lente de quem trabalha com desenvolvimento web e sistemas distribuídos.

O problema raramente é o prompt

A mudança mais importante de perspectiva é parar de pensar no agente de IA como só "o modelo" e pensar nele como modelo mais o aparato em volta. Esse aparato tem um nome na literatura, chamam de harness. São as ferramentas, as verificações, o contexto que você fornece, os limites que você impõe, o loop de feedback que corrige o modelo quando ele erra.

Quando uma sessão de IA é ruim, muitas pessoas culpam de cara o modelo ou o prompt. Porém, na minha opinião, muitas vezes o problema está no harness: faltou contexto sobre como o código funciona, não havia testes pra validar se algo quebrou, o modelo não tinha como verificar o próprio trabalho. É o mesmo raciocínio de quando um serviço se comporta mal em produção e a causa não está no código da request, mas sim na ausência de timeout, retry, de métricas que mostrariam o problema antes.

Guarde essa palavra, harness é a infraestrutura em volta da IA, e quase tudo que vamos abordar aqui é uma forma de construí-la. Vamos começar pela decisão mais prática que ela permite.

Autonomia deveria seguir verificabilidade, não dificuldade

O instinto é dar mais autonomia pra IA em tarefas fáceis e menos em tarefas difíceis. Porém acho que o eixo é outro, focado em dar mais autonomia onde o trabalho é verificável, e menos onde não é.
Um serviço com boa cobertura de testes oferece ao agente um loop de feedback objetivo, ele edita, roda o teste, vê se quebrou, corrige. Você pode delegar bastante e revisar o resultado. Já um serviço sem testes não oferece esse loop, e aí a IA pode estar acelerando na direção errada sem que ninguém perceba, porque não há nada dizendo que o comportamento mudou. Nesse caso, o uso mais valioso da IA não é gerar a feature, é gerar os testes que capturam o comportamento atual e, com isso, transformar um serviço nebuloso em algo verificável. Você paga a dívida com a própria ferramenta antes de confiar nela.

Porém a verificabilidade não cai do céu: ela é parte do harness que você constrói. A forma mais simples é um arquivo na raiz do seu repo, o famoso CLAUDE.md (se você estiver usando os produtos da Anthropic), descrevendo o projeto pro agente, como buildar, como rodar os testes, as convenções, o que não tocar. Algo nessa linha:

# nome-do-serviço
O que ele faz, em uma frase. Stack principal.

## Comandos
- Build, teste do módulo, subir local

## Convenções (inegociáveis)
- Tratamento de erro padrão, validação na borda, etc.

## Não tocar sem aprovação humana
- Migrations, contratos públicos, fluxo de pagamento

Parece algo muito simples mas não é. Esse arquivo é insumo de toda sessão futura de IA, e é também documentação de onboarding básica pra gente nova. Porém, ele precisa estar sempre atualizado porque, se não, ele não fica só inútil, como também passa a contaminar o contexto, fazendo a IA gerar código errado com confiança. Documentação deixou de ser cortesia e virou parte da configuração de execução.

O fluxo que decorre disso é o mesmo de sempre, só esclarecendo:
explorar o código antes de escrever, propor um plano e ter esse plano revisado por um humano antes de gerar a primeira linha, implementar em etapas com verificação a cada passo, revisar o diff completo. O ponto de maior alavancagem é o plano. Errar no plano custa dez vezes mais do que errar numa linha, e é o momento mais barato pra uma pessoa intervir.

Por fim, os guardrails que não dependem do julgamento do modelo. Um hook que roda formatação e compilação a cada edição transforma "confio que a IA não quebrou o build" em "o build não passa, então não avança":

# roda a cada edição; exit != 0 devolve o erro pro agente corrigir
formatar "$arquivo" && compilar || exit 2

E uma lista de negação que impede a IA de editar migrations, contratos públicos ou código de pagamento sem aprovação. Repare que isso não é o modelo "decidindo" respeitar a regra, é o modelo sendo impedido. Determinismo onde determinismo importa.

O critério não é leitura ou escrita, é independência

Existe uma tentação forte, quando se fala em múltiplos agentes, de montar uma "equipe": um agente arquiteto, um agente QA, um agente revisor, todos deliberando. Parece legal e promissor, mas o problema é que a decisão entre agentes tende a ser uma votação por maioria, não por colaboração, eles convergem pro consenso em vez de pegar os erros uns dos outros. O critério útil não é leitura contra escrita ou nível de dificuldade, é na verdade independência: o trabalho se decompõe em partes que não se conversam, ou é uma cadeia de raciocínio onde cada passo depende do anterior?

A evidência direta é de um estudo que li recentemente do Google Research (Kim et al., "Towards a Science of Scaling Agent Systems") mostrando um dado gritante:
Em tarefas separáveis, a coordenação entre agentes melhorou o desempenho em até 81%; já em tarefas estritamente sequenciais, degradou de 39% a 70%, com a complexidade quase idêntica entre os dois grupos. E o mesmo estudo mostra que modelos melhores não fazem diferença nesse caso, quanto mais capaz o agente sozinho, menos sobra pra a coordenação compensar, então a barra pra o multi-agente valer a pena sobe com o tempo, e não o contrário. O subagente serve pra isolar contexto, como você isola um processo, não para dar personalidade a papéis.

Como saber se valeu (e a métrica que mente)

Chegamos na parte que mais me incomoda no discurso atual sobre IA em times, e é onde quero ser mais direto.

A métrica que mais aparece é "percentual de código gerado por IA". Ela é sedutora porque é fácil de extrair e cresce rapidamente. E ela mede a coisa errada. Código gerado em volume não é valor entregue, pode até ser exatamente o oposto, código a mais pra revisar, manter e debugar. Otimizar por essa métrica é otimizar pra parecer produtivo.

O que importa medir é se o trabalho está saindo mais rápido sem piorar de qualidade. E aqui há uma vantagem metodológica interessante: como a adoção de IA num time é gradual e voluntária, você naturalmente tem, no mesmo período, demandas feitas com IA e demandas feitas sem. Isso é um grupo de comparação fácil de validar. Comparar "com IA" contra "sem IA" no mesmo intervalo de tempo é muito mais confiável que comparar "antes" contra "depois", porque elimina as variáveis que mudam ao longo do tempo: composição do time, fase do produto, pressão de prazo.

Para isso funcionar, basta uma marcação que diferencie as demandas que passaram pela IA das que não passaram. Com essa separação, as métricas que você provavelmente já coleta passam a contar uma história: tempo do início ao fim da demanda, quantidade entregue por período, tempo gasto em revisão, cards que geraram bugs.

Algo que eu acho que tem que ter cuidado é nunca medir velocidade sozinha. Velocidade sem qualidade é entregar problema mais rápido, repare que bati bastante nessa tecla, qualidade é muito indispensável. Toda métrica de tempo precisa estar emparelhada com uma de qualidade: quanto de retrabalho aquela demanda gerou, quantos bugs apareceram depois de ir pra produção.

O que isso é, e o que não é

Nada disso é transformação garantida. É um caminho, e um caminho que se percorre por fases.
Não tenho um número pra te vender. Tenho um jeito de raciocinar sobre o problema tratando o agente como modelo mais harness e investindo na infra, não no prompt; dê autonomia onde há verificação e construa verificação onde não há; paralelize leitura e serialize decisão; e acima de tudo, meça o que importa de forma realista. Num assunto onde sobra empolgação e falta ceticismo, talvez essa última parte seja a mais útil.