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.
O 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
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
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.
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.
Lição 2
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.
Pequena: direto para o código
Grande: acompanhada primeiro
Fechar
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.
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.
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.
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.
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.
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.
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
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.
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
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.
PróximoRevise o plano da web e depois rode as verificações antes do commit.
Trabalhando, precisa de você, concluído ou com erro. Eu só intervenho onde sou necessário.
A lista de tarefas do agente e dos subagentes que ele inicia. Consigo acompanhar um trabalho longo sem ler cada mensagem.
Uma barra por sessão. Quando ele acaba, eu começo uma nova sessão antes que a qualidade caia.
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
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.
O que recebe o mundo de fora: uma tela, uma rota HTTP, um comando. Ela traduz e delega; não decide.
Os casos de uso. Ela coordena o trabalho, mas as regras não moram aqui.
As regras de negócio. Não sabe nada de bancos de dados, frameworks ou rede.
Bancos de dados, serviços externos, arquivos. Implementa o que o domínio precisa.
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
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.
Está nas instruções do projeto, onde o agente a lê primeiro. Explica o porquê, não só o quê.
Um linter, um teste ou um hook a verifica em toda máquina, antes de cada commit ou push.
A integração contínua recusa o merge se ela quebrar, seja quem for o autor, pessoa ou agente.
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
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.
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.
“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.
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.
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.
Lição 8
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.
Lido como dado, nunca como ordem
Ler segredos: negado
Irreversível: uma pessoa decide
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 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
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
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
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
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.
Cada ferramenta que o agente usa, com uma marca onde uma verificação automática disse não a ele.
O que está desatualizado em cada ecossistema, e quão difícil será a atualização.
Alertas de segurança conhecidos das minhas dependências, cada um com um link.
Tarefas que o agente deixa para depois, em uma lista que eu posso limpar.
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
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 é.

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