Pular para o conteúdo

O que eu aprendi

Construí software com um agente de IA. Foi isto que eu aprendi.

Trabalho com IA desde 2022, e com agentes desde que começaram a aparecer, em meados de 2025. Com eles construí projetos reais: um backend, um app mobile, um site e esta página. No começo, o agente escrevia rápido e eu revisava devagar. Com o tempo, entendi que a qualidade não dependia de escrever instruções melhores, e sim de construir um ambiente onde o código ruim não conseguisse passar.

Esta página reúne essas lições. Ela não vende nada: conta o que deu errado, o que eu mudei e por que funciona, de um jeito que se aplica a qualquer linguagem ou stack.

A ideia em uma frase

Deixe a IA escrever e faça o projeto dizer não quando algo estiver errado.

Uma arquitetura rigorosa, com testes e linters que falham quando ela quebra, transforma a velocidade do agente em código que você consegue manter.

Lição 1

Um agente esquece o seu design de uma sessão para a outra.

Escrevi as regras do projeto em um documento: qual camada pode importar qual, onde vai cada coisa, o que não pode ser tocado. O agente as lia e seguia quase todas. Mas toda sessão começa do zero, e o “quase todas” vai se acumulando.

O desvio nunca era grande. Um import que cruzava uma fronteira, lógica de negócio dentro de um controller, um teste que faltava. Cada mudança parecia razoável sozinha, e eu só percebia semanas depois, quando já havia código construído por cima.

Parei de confiar que o agente lembraria as regras e as transformei em verificações que rodam sozinhas. Se uma mudança cruza uma fronteira, o build ou um teste falha, com o nome da regra na mensagem de erro.

Distância do designRegras em um documentoO design12345SessãoRegras que rodamO designRejeitado por uma verificação12345Sessão
Com regras em um documento, pequenos desvios se acumulam. Com regras que rodam, cada um é barrado na mudança que o causa.

Um agente lê os erros com muita atenção. Um erro com nome diz exatamente qual regra ele quebrou, e ele corrige a mudança antes mesmo de eu vê-la. A regra deixa de depender de alguém lembrar dela, nem o agente nem eu.

Regras em um documento

  • O agente as lê no início e as segue na maior parte do tempo.
  • O desvio aparece semanas depois, na revisão.
  • Revisar significa caçar erros no olho.

Regras que rodam

  • São verificadas em cada mudança, sem exceção.
  • A mudança é rejeitada na hora, com o nome da regra.
  • Revisar significa decidir sobre um trabalho que já passou pelas verificações.

Lição 2

O agente sempre trabalha na mesma ordem.

Sem uma ordem fixa, o agente fazia o que parecia mais útil a cada momento. Às vezes editava arquivos quando eu só tinha feito uma pergunta. Às vezes começava a escrever sem ler como o resto estava construído, ou dava algo por concluído sem ter testado.

Para isso eu uso o Organic Driven Development: um fluxo de trabalho de sete passos que o agente segue em cada pedido, pequeno ou grande. O processo cresce com o tamanho da tarefa, em vez de aplicar a mesma formalidade a tudo.

  1. Autorizar
  2. Explorar
  3. Tirar dúvidas
  4. Classificar
  • Pequena: direto para o código

    1. Implementar
  • Grande: acompanhada primeiro

    1. Acompanhar
    2. Implementar

Fechar

Todo pedido passa pelo mesmo tronco. Classificar decide se o trabalho vai direto para o código ou é acompanhado primeiro.
  1. Autorizar

    Primeiro ele confirma se eu realmente pedi uma mudança. Uma pergunta, uma revisão ou um plano não tocam em nenhum arquivo.

    Sem este passoEdições surpresa quando eu só queria uma resposta.

  2. Explorar

    Ele lê o código existente e as regras do projeto antes de propor qualquer coisa.

    Sem este passoSoluções que funcionam, mas não se encaixam no que já existe.

  3. Tirar dúvidas

    Se a decisão é minha (produto, escopo, design), ele faz uma única pergunta objetiva e espera. Se é técnica, ele decide e segue em frente.

    Sem este passoOu uma enxurrada de perguntas mecânicas, ou decisões tomadas por mim que não cabem a ele.

  4. Classificar

    Uma tarefa é pequena se é entendida, tem o risco contido e poderia ser retomada só a partir do diff. Caso contrário, é grande.

    Sem este passoOu tudo ganha formalidade, ou nada ganha.

  5. Acompanhar

    As tarefas grandes ganham um documento que cita o meu pedido palavra por palavra, uma lista de tarefas e um registro de decisões.

    Sem este passoO trabalho se perde quando uma sessão cai, e o resultado se afasta do que eu pedi sem que ninguém perceba.

  6. Implementar

    Primeiro um teste que falha, depois o código que o faz passar. Os commits vão por unidade de trabalho, com cerca de 400 linhas no máximo.

    Sem este passoMudanças enormes, sem prova de que funcionam, impossíveis de revisar de uma vez.

  7. Fechar

    Ele informa o que passou, o que falhou e o que não conseguiu verificar.

    Sem este passo“Concluído” sem evidência, e eu encontrando a falha depois.

A ordem transforma o bom senso em hábito. Não depende de o agente “lembrar” de ter cuidado: cada passo tem um resultado concreto que eu posso verificar. E como o processo acompanha o tamanho da tarefa, uma correção de uma linha continua rápida.

Lição 3

O agente abre o pull request. Eu decido quando ele está pronto.

Quando o agente pode rodar o ciclo inteiro sozinho, escrevendo, testando e fazendo merge, a revisão vira uma formalidade. As mudanças chegavam à branch principal porque as verificações passavam, não porque alguém tinha decidido que estavam certas.

Separei “está feito” de “está pronto”. O agente trabalha em uma branch e abre o pull request, mas a integração contínua só começa quando eu adiciono um rótulo à mão. O merge exige que essa execução passe, e o agente não tem permissão para adicionar o rótulo.

  1. O agente escreve e testa localmente
  2. Ele abre o pull request
  3. Uma pessoa adiciona o rótulo
  4. A integração contínua roda
  5. Verde: pode fazer merge. Vermelho: o rótulo sai e a mudança volta para o agente

Todo merge passa por uma decisão humana explícita, e essa decisão sai barata: chego à revisão com testes, lint e arquitetura já verificados localmente. O meu trabalho deixa de ser caçar erros e passa a ser julgar se a mudança é a certa.

Lição 4

Se você não vê o que o agente está fazendo, não sabe quando intervir.

Com várias sessões abertas ao mesmo tempo, eu perdia o fio. Uma estava esperando a minha resposta havia dez minutos, outra tinha ficado sem contexto e começado a cometer erros bobos, e outra tinha terminado sem eu perceber. Para saber, eu precisava ler cada conversa.

Adicionei ao ambiente do agente mods que mostram o estado dele num relance. Eles não mudam o que o agente faz; me dão visibilidade sobre ele.

  • landingEscrevendo testes para a nova seçãoTrabalhando
  • webPergunta antes de rodar uma migraçãoPrecisa de você
  • mobileTodas as verificações passaram, branch prontaConcluído

PróximoRevise o plano da web e depois rode as verificações antes do commit.

  • Estado de cada sessão

    Trabalhando, precisa de você, concluído ou com erro. Eu só intervenho onde sou necessário.

  • Plano e tarefas

    A lista de tarefas do agente e dos subagentes que ele inicia. Consigo acompanhar um trabalho longo sem ler cada mensagem.

  • Contexto restante

    Uma barra por sessão. Quando ele acaba, eu começo uma nova sessão antes que a qualidade caia.

  • Dicas e próximo passo

    Depois de cada turno, uma nota curta sobre o que ele acabou de fazer e uma sugestão do que fazer em seguida.

Trabalhar com um agente é, acima de tudo, decidir quando intervir. Quanto antes eu vejo uma sessão travando ou se desviando, menos trabalho há para desfazer. A visibilidade transforma a supervisão em algo que cabe num relance.

Lição 5

Camadas claras mostram ao agente onde vai cada peça.

Quando o projeto não tinha uma estrutura explícita, o agente colocava o código onde fosse mais conveniente. A lógica de negócio acabava misturada com o acesso a dados e com a interface. Cada mudança tocava muitos arquivos, e ninguém, nem o agente nem eu, conseguia dizer com certeza o que ela quebraria.

Construí repositórios base com uma arquitetura rigorosa já definida: backend, mobile, web e landing. Os nomes das camadas mudam com o projeto, mas a ideia é sempre a mesma. As dependências sempre apontam para o domínio, nunca o contrário, e cada módulo ou feature fica isolado: uma feature não importa outra diretamente.

EntradaInfraestruturaAplicaçãoDomínioAs dependências apontam para dentro
A entrada e a infraestrutura ficam do lado de fora; toda dependência aponta para dentro, para o domínio.
  1. Entrada

    O que recebe o mundo de fora: uma tela, uma rota HTTP, um comando. Ela traduz e delega; não decide.

  2. Aplicação

    Os casos de uso. Ela coordena o trabalho, mas as regras não moram aqui.

  3. Domínio

    As regras de negócio. Não sabe nada de bancos de dados, frameworks ou rede.

  4. Infraestrutura

    Bancos de dados, serviços externos, arquivos. Implementa o que o domínio precisa.

Toda seta aponta para o domínio. A infraestrutura depende do domínio, e não o contrário.

Proibido: o domínio importa a infraestrutura

Para o agente, a arquitetura é um mapa: em cada mudança, ele sabe em qual camada ela vai e o que pode importar. Para mim, cada mudança fica contida e é mais fácil de revisar. E como a regra é simples (“as setas apontam para dentro”), uma ferramenta consegue verificá-la em cada build.

Lição 6

Uma regra só conta se quebrá-la quebra o build.

Eu tinha regras em três lugares diferentes: algumas só escritas, outras verificadas na minha máquina, outras só na integração contínua. As que estavam só escritas eram justamente as que o agente acabava quebrando.

Agora toda regra sobe uma escada de três degraus, e todo projeto verifica as mesmas cinco coisas, mesmo que a ferramenta exata mude com a linguagem.

  1. Escrita

    Está nas instruções do projeto, onde o agente a lê primeiro. Explica o porquê, não só o quê.

  2. Conectada

    Um linter, um teste ou um hook a verifica em toda máquina, antes de cada commit ou push.

  3. Imposta

    A integração contínua recusa o merge se ela quebrar, seja quem for o autor, pessoa ou agente.

PassouTiposCódigo que compila “por acaso” ou usa dados com o formato errado.
FalhouArquiteturaImports que cruzam camadas, ou ciclos entre módulos.
PassouLint rigorosoPadrões perigosos, como inserir dados como HTML em vez de como texto.
PassouCobertura mínimaComportamento novo sem um teste que o prove.
PassouSegredosChaves ou senhas prestes a ir para o repositório.
Uma verificação falha. O agente lê o nome da regra, move o import e roda tudo de novo.

A linha vermelha é a útil. Ela barra a mudança, diz o nome da regra, e o agente sabe o que corrigir. Um projeto onde tudo está verde porque nada é verificado não protege nada.

Lição 7

Quatro práticas que tornam a arquitetura difícil de quebrar sem querer.

Ter regras que falham é o começo. Estas quatro práticas foram as que mais me ajudaram a manter essas regras protegendo ao longo do tempo, seja quem for que escreva o código.

  • Proíba tudo por padrão e teste a proibição.

    No começo, as minhas regras de camadas listavam o que era proibido, então qualquer coisa fora da lista era permitida sem que ninguém tivesse decidido. Agora a regra proíbe todo import que não esteja explicitamente permitido, e um pequeno projeto de teste prova que cada import proibido realmente falha. Se alguém enfraquecer a regra, esse teste fica vermelho.

    Resultado Uma regra que não pode ser enfraquecida em silêncio.

  • Escreva as regras de arquitetura como testes.

    “O domínio não importa nada de fora” pode ser uma frase em um documento ou um teste que roda com o resto da suíte. O segundo roda em toda máquina e na integração contínua, e a sua mensagem de erro explica a regra melhor do que qualquer documento.

    Resultado A regra roda onde quer que os testes rodem.

  • Duas ferramentas que se sobrepõem de propósito.

    Uma verifica camada contra camada. A outra olha o grafo inteiro de dependências: ciclos, módulos órfãos, um domínio que importa algo que não deveria. Cada uma pega o que a outra deixa passar, e se uma estiver mal configurada, a outra continua lá.

    Resultado Uma ferramenta quebrada não abre uma brecha.

  • Documente qual verificação pega cada regra.

    Mantenho uma tabela “pego por” que liga cada regra de arquitetura à ferramenta que a impõe. Uma regra sem verificação se destaca na hora como a próxima a conectar.

    Resultado A próxima regra a conectar está sempre à vista.

Regras decamadasFeatureimportandofeatureTela lendo obanco dedadosGrafo dedependênciasCiclos deimportMódulosórfãosDomínioimportandoinfraestrutura
Cada ferramenta pega algo que a outra deixa passar, e as duas pegam a regra mais importante.

Lição 8

Cinco hábitos que tornam um agente seguro para usar.

Um agente que lê, escreve e roda comandos tem mais acesso do que muitas pessoas de uma equipe. Estes hábitos valem tanto para o fluxo de trabalho do agente quanto para a aplicação que ele constrói, e cada um se apoia em uma verificação, não só em uma frase.

Fora

  • Comentários e issues
  • Páginas web
  • Documentação baixada

Lido como dado, nunca como ordem

O agente

  • Lê o código
  • Roda as verificações
  • Edita em uma branch

Ler segredos: negado

Irreversível: uma pessoa decide

Uma pessoa

  • Apaga
  • Publica
  • Faz o merge
O texto de fora entra só como dado. O agente trabalha dentro das suas permissões, e tudo o que é irreversível espera por uma pessoa.
  • Texto de fora é dado, não ordem.

    Comentários, issues, descrições de pull request, páginas da web e documentação baixada informam o agente. Mas qualquer um pode escrever neles, e alguns podem tentar dar instruções a ele. A regra é que só eu dou ordens, e tudo o que um texto de fora pede é verificado antes.

    Apoiado por Instruções do projeto e revisão humana

  • O mínimo de acesso necessário.

    O agente recebe só as permissões de que a tarefa precisa. Ler segredos é negado, e qualquer coisa irreversível (apagar, publicar, fazer merge) espera por uma pessoa.

    Apoiado por Regras de permissão e listas de bloqueio

  • Fixe as suas dependências.

    Lockfiles com versões exatas e checksums, actions de integração contínua fixadas por commit e um período de espera antes de instalar uma versão recém-publicada. Um ataque à cadeia de suprimentos costuma ser descoberto em poucos dias; esperar sai barato.

    Apoiado por Instalações congeladas e limites de idade de versão

  • Segredos ficam de fora.

    Todo commit é verificado antes de ser criado e de novo na integração contínua. Os arquivos de ambiente são ignorados, exceto o de exemplo, que não guarda valores reais.

    Apoiado por Dois verificadores de segredos independentes

  • Dados são mostrados como texto.

    Nada que venha de um usuário ou de uma API é inserido como HTML. O lint rejeita essas operações, e uma política de segurança de conteúdo bloqueia qualquer script que o build não registrou.

    Apoiado por Lint e uma política de segurança de conteúdo

Lição 9

O que precisa de atenção, em um só painel.

Os problemas que não quebram o build se acumulam em silêncio: dependências que envelhecem, vulnerabilidades publicadas em bibliotecas que eu uso, tarefas que o agente deixou “para depois”, uma branch que ficou atrás da remota. Eu descobria tarde, geralmente na revisão ou quando algo já estava falhando.

Adicionei um mod que mantém o estado do projeto ao lado da conversa com o agente. Ele mostra cinco coisas.

  • Mapa do trabalho

    Cada ferramenta que o agente usa, com uma marca onde uma verificação automática disse não a ele.

  • Atualizações

    O que está desatualizado em cada ecossistema, e quão difícil será a atualização.

  • Vulnerabilidades

    Alertas de segurança conhecidos das minhas dependências, cada um com um link.

  • Pendentes

    Tarefas que o agente deixa para depois, em uma lista que eu posso limpar.

  • Status da branch

    Um aviso quando estou atrás da remota, antes de eu construir sobre código desatualizado.

O agente e eu vemos a mesma coisa. Posso pedir a ele que trate um aviso específico antes que vire um problema, em vez de encontrá-lo na revisão.

O que eu levo comigo

A IA não tirou o meu trabalho. Ela o mudou.

Deixei de escrever a maior parte do código e passei a projetar o ambiente onde ele é escrito: as camadas, as regras que falham, a ordem de trabalho, o portão antes do merge e a visibilidade sobre o que acontece. Quanto mais rigoroso é esse ambiente, mais liberdade posso dar ao agente, porque o que está errado não passa.

Se eu tivesse que guardar uma única ideia: não tente tornar o agente perfeito. Faça o projeto perceber quando ele não é.

Foto de Hernán David Figueroa

Sobre o desenvolvedor

Hernán David Figueroa

Desenvolvedor full-stack com mais de 8 anos de experiência, especializado em fintech e pagamentos seguros. Trabalho com terminais POS e funcionalidades de pagamento para Android e iOS em um gateway de pagamentos colombiano. Trabalho com IA desde 2022 e com agentes desde meados de 2025. Moro em Bogotá.

Eu escrevo e mantenho o Guardrail por conta própria. Ver meu perfil de desenvolvedor