Programando com agentes de IA sem perder o controle do código

O agente de IA não estraga o seu projeto num commit só. O estrago vem aos poucos: um PR que você aprovou sem ler direito, uma dependência que ele "resolveu" do jeito dele, uma regra do projeto que ele não conhecia. Quando você percebe, o código funciona, mas você já não sabe explicar por quê.

Uso agentes todos os dias, inclusive no código deste site. Neste post mostro as regras que me deixam ir rápido sem entregar o volante.

O risco não é código ruim, é código que você não leu

Código ruim aparece no review. O problema é o código plausível: compila, passa no lint, parece com o que você escreveria. É esse que passa batido.

Por isso eu parei de pensar em "quanto o agente consegue fazer sozinho" e passei a pensar em outra pergunta: quanto eu consigo verificar depois? A tarefa que eu não consigo revisar em dez minutos é grande demais para delegar de uma vez.

1. Contexto escrito, não contexto na sua cabeça

O agente começa cada sessão sem memória do seu projeto. Se a regra existe só na sua cabeça, ele vai quebrar essa regra, e com toda a confiança do mundo.

Aqui no site, o contexto mora num arquivo só, o AGENTS.md, lido por qualquer ferramenta (Claude Code, Copilot ou o que vier depois). Ele tem a stack, os comandos, as convenções e, principalmente, as armadilhas que já me custaram horas:

## Code conventions

- Pages, layouts and routes read posts only through `lib/content` — never call the content API directly.
- Tailwind only — no CSS-in-JS, no inline `style` props.
- Never hardcode user-visible strings; use `useTranslation`.

Known pitfalls (each one cost real debugging time):

- **Never `await app.listen()` at module top level** in the API. Vercel intercepts `listen()`,
  the promise never resolves, and every request hangs until it times out with no logs.

A regra que eu sigo: toda vez que eu corrijo o agente duas vezes na mesma coisa, a correção vira uma linha nesse arquivo. O arquivo cresce com os erros reais do projeto, não com boas práticas genéricas copiadas da internet.

2. Limites técnicos, não promessas

"Não mexa em produção" escrito no prompt é um pedido. Uma permissão negada na configuração é um limite. Prefiro o limite.

Este é um trecho real do .claude/settings.json deste repositório:

{
  "permissions": {
    "allow": ["Bash(yarn lint:check)", "Bash(yarn build)", "Bash(yarn api:test)", "Bash(git diff *)"],
    "deny": [
      "Read(./.env.local)",
      "Read(./.env.development.local)",
      "Read(./.env.production.local)"
    ]
  }
}

O que é leitura e verificação roda sem me perguntar. Os arquivos de segredo o agente nem consegue abrir. E existe uma camada pessoal, fora do git, que bloqueia escrita no banco de produção, mudança de variável de ambiente e deploy de produção. O agente prepara o comando; quem aperta o botão sou eu.

Isso não é desconfiança. É o mesmo princípio de um colega novo no time: acesso de leitura amplo, escrita em produção só com revisão.

3. Tarefas pequenas, com um jeito objetivo de verificar

Eu peço ao agente coisas que terminam em algo verificável: um teste que passa, um build que fecha, uma página que responde 200. "Melhora a arquitetura do projeto" não tem fim nem critério. "Corrige os alertas do Dependabot, rodando lint, typecheck, testes e build" tem.

Um exemplo de hoje mesmo. Pedi para corrigir os alertas de segurança do site. O agente forçou versões novas de várias dependências, e uma delas (o OpenTelemetry 2.x) quebrou o build:

TypeError: Cannot read properties of undefined (reading 'AlwaysOn')
    at async .../next-contentlayer2/dist/index-cjs.cjs:72:49
> Build failed because of webpack errors

Como o build fazia parte da tarefa, o erro apareceu antes do PR, não em produção. O agente tirou aquela atualização, dispensou o alerta com o motivo registrado e seguiu com as outras.

# Not fixed (dismissed as tolerable risk)
- @opentelemetry/core and @opentelemetry/propagator-jaeger: the fix is 2.x only, and forcing it breaks the contentlayer build (Cannot read properties of undefined (reading 'AlwaysOn')). Build-time tracing inside contentlayer2, which has no newer release.
- braces, http-cache-semantics, sprintf-js: no patched version published; dev/build-time chains (chokidar, node-gyp, argparse).

# Verification
- yarn lint:check, site and API typechecks, yarn api:test (54 passed)
- yarn build against the production content API: contentlayer generated 9 documents, build OK
- next start: /pt, /en, /pt/curriculum, /pt/about and an English post return 200

4. Revise o diff como se fosse de um colega

Ainda no mesmo caso: depois do merge, o GitHub reabriu doze alertas que estavam marcados como corrigidos, mas nunca foram. O agente tinha confiado no status do GitHub, e eu também. Só pegamos isso porque eu pedi para conferir os alertas depois do deploy, em vez de dar o trabalho por encerrado no merge.

A lição virou regra: o agente confere o resultado na fonte, não no resumo. Versão no lockfile, não o status do alerta. Log de produção, não "o deploy passou".

Na revisão, eu leio três coisas antes de qualquer outra:

• O que mudou fora do escopo. Arquivo que eu não esperava no diff é o primeiro sinal de problema.
• O que foi removido. Agente apaga teste "que estava quebrando" com uma facilidade assustadora.
• O que foi decidido por mim. Versão maior de dependência, mudança de API pública, migração de banco: tudo isso precisa aparecer na descrição do PR, não escondido no diff.

Erros comuns

// ❌ Errado: "refatora o módulo de pagamentos e já ajusta o que achar necessário"
// ✅ Certo: "extrai o cálculo de juros para uma função pura, com testes para os 3 casos atuais"

// ❌ Errado: aprovar porque o CI passou
// ✅ Certo: aprovar porque você leu o diff e sabe explicar cada arquivo

// ❌ Errado: corrigir o agente no chat e esquecer
// ✅ Certo: corrigir duas vezes = uma linha nova no AGENTS.md

// ❌ Errado: deixar a IA gerar o texto que vai para o usuário final sem revisão
// ✅ Certo: a IA gera a parte criativa, o código desenha o que precisa estar exato

Esse último aprendi com as capas deste blog. Eu deixava uma IA desenhar a capa inteira, título incluído, e os títulos saíam com erro de digitação. Hoje a ilustração vem da IA, e o título é desenhado por um canvas, a partir do texto do post. Cada um faz o que faz bem.

Quando delegar e quando não

A coluna da direita não é "IA proibida". É onde o custo de um erro plausível é alto demais para revisar só no final.

Por onde começar

Se você usa agentes hoje sem nenhuma dessas regras, comece pequeno:

1. Crie um AGENTS.md com cinco linhas: stack, comandos de verificação e as três regras que você mais repete no code review.
2. Configure as permissões da sua ferramenta: libere lint, testes e build; bloqueie leitura de .env e qualquer comando de produção.
3. Na próxima tarefa, defina como verificar antes de pedir. Se você não sabe dizer como vai conferir o resultado, a tarefa ainda não está pronta para delegar.

O agente acelera muito. Mas a responsabilidade pelo código que vai para produção continua com o seu nome no commit. E você, já pegou o agente "resolvendo" algo do jeito dele? Me conta, quero saber qual regra entrou no seu AGENTS.md por causa disso.