Duas afirmações, as duas erradas, as duas comuns.

"É autocomplete chique."

"Ele entende meu codebase."

Nenhuma sobrevive a dez minutos vendo um trabalhar. O que tem ali é mais chato e mais útil que as duas.

Um agente de código é um loop em volta de um modelo que consegue chamar ferramentas. O modelo não vê seu repositório; ele vê a saída das chamadas que decidiu fazer. A cada turno ele decide ler um arquivo, rodar uma busca, editar algo ou executar um comando, e o resultado volta como texto no contexto dele. Repete até achar que terminou. Esse é o mecanismo inteiro. Tudo que parece compreensão é o resultado acumulado de ter lido as coisas certas — e tudo que parece alucinação é o que acontece quando ele age sobre o que não leu.

Deixa eu traçar um caso real.

Uma mudança real, passo a passo

Este blog não tinha sitemap.xml, nem dado estruturado, nem llms.txt — nada que permitisse a um crawler ou a um modelo enumerar os posts. Adicionar tudo isso é um bom caso de teste: mexe num script de build, gera arquivos novos e não dá pra verificar no olho.

O que o loop fez de verdade:

1. read   CLAUDE.md              → aprendeu "nenhuma dependência npm, nunca"
2. glob   content/articles/**    → achou 21 posts × 2 idiomas
3. read   build_blog.js:1-120    → achou PUBLISH_ENTRIES, o parser
4. grep   "ld+json|canonical"    → 0 resultados, confirmando o buraco
5. read   build_blog.js:330-590  → achou pageShell, buildTranslationMap
   ─── planeja ───
6. edit   build_blog.js          → adicionou um param `head` ao pageShell
7. edit   build_blog.js          → adicionou os emissores de sitemap/feed/llms
8. bash   node build_blog.js     → "Built 42 articles"
9. bash   <parseia todo JSON-LD> → 87 blocos, 0 inválidos
10. bash  python3 -c "minidom.parse(...)" → XML bem-formado

Os passos 1 a 5 são a parte que o pessoal subestima. Metade do trabalho é leitura, e a leitura é o que determina se os passos 6 e 7 produzem algo que encaixa no codebase ou algo que só compila. O passo 1 sozinho mudou a implementação inteira: sem o CLAUDE.md dizendo "nenhuma dependência npm", o movimento óbvio é npm install feed sitemap e o build inteiro deixa de ser hermético.

Os passos 8 a 10 são a outra metade que subestimam. Um agente que não consegue verificar o próprio trabalho é uma forma muito rápida de produzir lixo plausível. O parse de XML no passo 10 vale mais que qualquer quantidade de confiança no passo 7.

Onde ele errou

O passo 9 revelou uma coisa não planejada. Parseando o JSON-LD gerado, apareceu um título assim:

The \"exactly once\" myth

O parser de frontmatter tirava as aspas externas mas nunca desescapava o \" de dentro. Esse bug estava no ar em toda página do site, dentro da tag <title>, havia meses. Ninguém tinha notado — nem o autor, nem nenhum leitor.

Não foi achado por perspicácia. Foi achado porque um passo de verificação obrigou uma máquina a ler uma saída que um humano só tinha batido o olho. Essa é a versão honesta do que essas ferramentas fazem bem: não é serem mais espertas, é toparem conferir de verdade.

E o modo de falha que vale nomear: mais cedo na mesma sessão, o agente tinha escrito um plano afirmando que o site não tinha "canonical URL em lugar nenhum", quando existia um dentro do stub de redirect do /blog/index.html. Ele tinha feito o grep, visto o resultado e arredondado. Pequeno, inofensivo, e exatamente o formato de erro que se deve esperar: resumo confiante correndo um pouco à frente do que foi realmente lido.

Ler, planejar, editar, verificar

        ┌─────────────────────────────────────┐
        ↓                                     │
      LER ──→ PLANEJAR ──→ EDITAR ──→ VERIFICAR
       │                                  │
   a parte que                      a parte que
   deixa correto                    deixa confiável

As duas pontas desse loop é onde mora a qualidade, e são as duas que você consegue influenciar de fora. Você não deixa o modelo mais esperto. Você muda, e muito, o que ele lê e o que ele tem que provar.

O que ele lê é definido pelo seu repositório. Um CLAUDE.md declarando as restrições que não estão visíveis no código ("nenhuma dependência npm", "blog/ é gerado, nunca edite à mão") faz mais pela qualidade da saída que qualquer forma de escrever o prompt. São exatamente os fatos que não dá pra inferir dos arquivos — o que os torna exatamente os fatos que vale escrever.

O que ele tem que provar é definido pelas suas instruções. "Adiciona um sitemap" convida a um sitemap plausível. "Adiciona um sitemap, depois parseia com um parser XML de verdade e confirma que toda URL resolve pra um arquivo" convida a um correto. A segunda pegou dois bugs nesta sessão.

No que ele é realmente ruim

Vale ser específico, já que o marketing não é:

  • Qualquer coisa que dependa de estado de runtime. Ele lê sua migration; ele não sabe que sua tabela em produção tem 2,3 bilhões de linhas e um índice que não cabe na memória.
  • Qualquer coisa que dependa de história. Um codebase de quinze anos é cheio de código que parece errado e é estrutural. O motivo mora numa decisão de 2013 de alguém que saiu da empresa.
  • Saber quando a resposta é "apaga isso". Ele vai estender fielmente uma abstração ruim, bem, pra sempre.
  • Julgar a própria confiança. Ele relata no mesmo tom se verificou ou se inferiu. Essa é a coisa mais importante de internalizar.

Os erros mais comuns

  1. Tratar a saída como código revisado. É um rascunho escrito rápido. Revise como PR de alguém competente que nunca viu sua produção.
  2. Não escrever as restrições invisíveis. Toda regra que mora só na cabeça do time é uma regra que o agente vai quebrar.
  3. Pedir a mudança sem pedir a prova. Verificação é uma instrução separada, e é a que importa.
  4. Deixar rodar comando cuja falha você não enxerga. Se a saída do comando de teste não volta pro loop, o loop não está verificando nada.
  5. Presumir que ele leu o que resumiu. Prosa confiante não é evidência de chamada de ferramenta. Pergunte qual arquivo, qual linha.
  6. Dar a tarefa inteira em vez do contexto inteiro. Escopo pequeno, contexto largo — o inverso é como se produz erro confiante em escala.

Perguntas frequentes

Como um agente de código de IA funciona de verdade?

É um loop: um modelo de linguagem que chama ferramentas, rodando até decidir que a tarefa acabou. A cada turno ele escolhe uma ação — ler arquivo, buscar no codebase, editar, rodar um comando de shell — e o resultado volta pro contexto dele como texto. Ele não tem visão nenhuma do seu repositório além do que essas chamadas retornaram. É por isso que o que ele lê determina o que ele produz, e por isso que um passo de verificação que executa código de verdade é a diferença entre uma mudança plausível e uma correta.

É só autocomplete?

Não, e o que distingue é o loop de ferramentas, não o modelo. Autocomplete prevê os próximos tokens num cursor. Um agente decide rodar sua suíte de testes, lê a falha e edita outro arquivo por causa dela. O modelo por baixo é o mesmo tipo de coisa; o loop em volta é o que o torna capaz de agir e — o que mais importa — de conferir.

Ele consegue entender meu codebase?

Não do jeito que um colega que trabalhou nele por três anos entende. Ele lê qualquer coisa que você apontar, rápido e sem entediar, e não retém nenhum dos motivos. Fato que mora no código, ele acha. Fato que mora na história, no comportamento de produção ou na cabeça do time é invisível pra ele, a menos que você escreva — que é o argumento real pra manter um CLAUDE.md.

O que eu nunca devo deixar ele fazer sem supervisão?

Qualquer coisa irreversível ou voltada pra fora: dar push em produção, apagar dado, mandar mensagem, gastar dinheiro. Não porque ele erre mais ali, mas porque são os erros que você não desfaz. O portão fica antes do passo irreversível, e fica lá permanentemente — não só enquanto você ainda está aprendendo a confiar.

Mapa mental rápido

escreva as restrições invisíveis (CLAUDE.md)
  ↓
escopo pequeno na tarefa
  ↓
deixe ele ler bastante antes de editar
  ↓
exija verificação que executa, não que afirma
  ↓
revise o diff como PR de um colega rápido e sem história
  ↓
todo passo irreversível atrás de um portão humano

Conclusão

O enquadramento útil não é "vai substituir desenvolvedor". É que você agora tem um colaborador que lê exaustivamente, nunca cansa de conferir, não retém nada sobre o porquê, e relata inferência no mesmo tom confiante que fato.

Isso é um conjunto real e específico de forças e fraquezas. Construir em volta delas é engenharia comum: escreva o que não dá pra inferir, e faça ele provar o que afirma.

Este post achou um bug de meses no próprio site onde está publicado. Não por ser esperto — por ter rodado o parser.