Tem uma frase que eu ouço bastante de desenvolvedor mais cético: “IA gera código legado”. E eu entendo o sentimento. Quem nunca pediu uma feature pro Claude, recebeu duzentas linhas de TypeScript que rodam de primeira, e três semanas depois descobriu que o coitado do código tem três camadas de abstração que ninguém pediu, um padrão de erro inconsistente com o resto do projeto e um teste unitário que mocka exatamente a coisa que precisava ser testada?

A questão é que esse código não foi gerado pela IA. Ele foi pedido por você.

Eu venho usando agente de IA pra codar de forma séria há um bom tempo e, depois de quebrar a cara algumas vezes, cheguei numa conclusão que parece óbvia mas é desconfortável: a IA é uma máquina de amplificar critério. Se você tem critério, ela acelera a entrega de coisa boa. Se você não tem, ela acelera a entrega de coisa ruim. A velocidade é a mesma. O que muda é o que sai do outro lado.

O ponto é que existe um trabalho que precisa estar feito antes de você abrir o agente. Quando ele não está feito, o modelo escolhe sozinho. E o que ele escolhe sozinho quase sempre é o caminho mais genérico possível.

Personas antes de qualquer linha

Toda vez que eu pulo essa etapa, eu pago depois. Sem exceção.

Quando você pede pra IA construir uma feature sem dizer pra quem ela é, o modelo vai resolver o problema técnico genérico. Vai assumir que o usuário é mediano, que vai usar o produto da forma mais óbvia, que entende um pouco de tecnologia mas não muito. O resultado é um Frankenstein de UX que serve pra ninguém em específico.

Eu mantenho um arquivo de personas no projeto. Não é um documento de marketing com nome inventado e foto de banco de imagem. É um inventário curto: quem usa, qual o nível técnico, qual o contexto de uso (mobile no metrô? desktop no escritório? voz no carro?), qual a tolerância a erro, qual a frequência de uso. Quando eu peço uma feature, esse arquivo entra no contexto e o modelo passa a decidir nuances de implementação a partir disso.

Um exemplo bobo: validação de formulário. Pra uma persona que usa o sistema dez vezes por dia, validar campo por campo é fricção desnecessária, ela já sabe os erros que comete. Pra uma persona que vai usar o produto uma vez, validar tudo no submit é cruel. Sem persona definida, o modelo escolhe um padrão genérico. Com persona definida, ele escolhe o padrão certo.

Assine agora

Use case diagrams e por que UML voltou a importar

UML virou meio palavrão na última década. Mas a IA mudou o cálculo. Ela lê diagrama de caso de uso melhor do que lê descrição em linguagem natural.

Quando eu passo um caso de uso pro modelo na forma de uma lista de bullets ou um texto descritivo, ele tem que adivinhar as fronteiras: o que é ator, o que é caso, o que é extensão, o que é inclusão. Quando eu passo o mesmo conteúdo em PlantUML, com actor, usecase, extends, includes, ele para de adivinhar. A estrutura formal funciona como um esqueleto que o modelo preenche com músculo.

Não precisa ser bonito. Eu escrevo PlantUML em arquivo .puml direto no repositório, na pasta docs/, e referencio quando estou pedindo uma feature que mexe com fluxo de usuário. O modelo entende, e mais importante, eu posso voltar nele daqui a seis meses e entender o que eu queria.

Banco de dados é onde o legado realmente nasce

Código ruim você refatora numa tarde. Banco de dados mal modelado vai te assombrar por anos.

Esse é o lugar onde eu sou mais rigoroso com a IA. Antes de pedir qualquer migration, eu tenho um diagrama do banco. Pode ser dbdiagram.io, pode ser Mermaid, pode ser um SQL puro com comentários. O importante é que o modelo enxergue o estado atual antes de propor o estado futuro.

Sem isso, o agente vai gerar uma tabela users com email, password, created_at e seguir feliz. O que ele não sabe é que você já tem uma tabela accounts que faz exatamente isso, que o login do seu sistema é por OAuth e você nem armazena senha, que o created_at no resto do projeto se chama inserted_at por convenção do framework. Cada uma dessas decisões pequenas, repetida ao longo de meses, vira aquele tipo de dívida que ninguém quer pagar.

Eu trato o schema como o ativo mais valioso do projeto. Antes de qualquer prompt que envolva persistência, o diagrama atualizado vai no contexto. Sempre.

Arquivos de contexto: o que vai e o que fica de fora

Aqui é onde a maioria das pessoas erra, eu inclusive.

A tentação é jogar tudo no contexto. O codebase inteiro, toda a documentação, os tickets do Jira, os comentários do Slack. Mais contexto é melhor, certo?

Errado. Mais contexto relevante é melhor. Mais contexto qualquer é caro e atrapalha.

O que eu faço é manter arquivos de contexto temáticos e curtos. Um CONTEXT_API.md que descreve a convenção de endpoints, padrões de erro, autenticação, paginação. Um CONTEXT_FRONTEND.md com a stack, padrões de componentes, biblioteca de UI, regras de acessibilidade. Um CONTEXT_DOMAIN.md com o vocabulário do negócio, porque a IA precisa saber que “rota” no meu produto significa uma coisa muito específica e não a coisa que o Express chama de rota.

Quando vou pedir uma feature, eu seleciono quais desses arquivos vão entrar. Feature de frontend não precisa do contexto de banco. Feature de relatório não precisa do contexto de autenticação. Cada arquivo tem entre 100 e 300 linhas, é fácil de manter atualizado, e o agente recebe só o que precisa.

Isso economiza tokens, sim, mas o ganho real é outro: o modelo fica mais focado. Quando você manda quarenta arquivos pra ele, ele vai puxar referência de qualquer canto. Quando você manda quatro, ele puxa do lugar certo.

ADRs: a memória que o agente não tem

Esse aqui demorei pra absorver. Hoje é uma das coisas que mais me poupa retrabalho.

ADR é Architecture Decision Record. Um arquivo curto, geralmente Markdown, que descreve uma decisão técnica que foi tomada no projeto, o contexto em que foi tomada, as alternativas consideradas e o que pesou na escolha. Não é documentação no sentido tradicional. É um registro do “por que” das coisas.

A primeira vez que eu vi valor real foi quando o agente, três meses depois de uma decisão, sugeriu refatorar algo que tinha sido decidido com motivo. A sugestão era boa em tese, mas ignorava uma restrição de integração com um sistema externo que a gente já tinha brigado pra acomodar. Sem ADR, eu teria que reabrir a discussão, lembrar dos detalhes, talvez aceitar a refatoração e descobrir o problema de novo. Com ADR, o modelo lê, entende a restrição, e propõe uma alternativa que respeita a decisão.

O formato que eu uso é simples. Numera os arquivos sequencialmente, 0001-uso-de-jwt-vs-sessao.md, 0002-banco-postgres-vs-mongo.md. Cada um tem cinco seções curtas: contexto, decisão, alternativas, consequências, status. Status importa porque decisão antiga pode ser revogada, e você quer que o agente saiba quando uma escolha foi superada.

O ganho vai além da IA. Time novo entra no projeto e lê os ADRs em uma hora. Cofundador volta de férias e entende o que mudou. Você mesmo, daqui a um ano, lembra do raciocínio sem precisar reconstruir tudo do zero. A IA só é mais um leitor desse mesmo material, e o melhor é que ela respeita.

Testes unitários como instrumento de design, não de cobertura

Eu confesso que durante muito tempo achei que pedir teste unitário pra IA era perda de tempo. Ela escrevia teste que testava a implementação, não o comportamento. Mockava o que não devia. Cobria casos felizes e ignorava as bordas.

O que mudou foi a ordem. Eu passei a pedir o teste antes do código.

Não é TDD no sentido clássico. É mais um TDD conversacional. Eu descrevo o comportamento esperado em linguagem natural, peço pro agente escrever os testes primeiro, reviso esses testes com cuidado e só depois libero a implementação. Quando o teste está bom, o código que sai pra fazer ele passar é quase sempre bom também.

Esse passo de revisar o teste é onde mora o critério. Eu olho cada caso e pergunto: esse teste reflete uma regra de negócio real, ou é uma armadilha de implementação? Esse mock está simulando uma dependência ou está escondendo um bug? Esse asserção verifica o que o usuário se importa, ou verifica detalhe interno?

Quando você faz isso, o teste para de ser um custo e vira um documento executável do que o sistema faz. E o agente da próxima feature lê esses testes e respeita as decisões já tomadas. É assim que o projeto para de virar uma colcha de retalhos.

Quando o critério não foi aplicado, alguém paga

Recentemente peguei um projeto pra retomar. Código entregue por uma consultoria séria, rodando em produção, com usuários ativos.

A primeira semana de leitura revelou um problema que não era um bug, era estrutural. Uma das entidades centrais do negócio tinha sido modelada no nível errado. Estava presa ao usuário, quando na verdade pertencia à organização. Funcionava, porque na operação inicial era um usuário por organização e ninguém tinha encarado o caso de mais de um.

Acontece que o roadmap do produto pedia evolução pra um modelo onde cada organização teria vários usuários, papéis diferentes, permissões por papel. E essa evolução, com a modelagem do jeito que estava, era cirurgia de coração aberto. Não é uma migration de uma tarde. É reescrever fluxo, reprocessar dado, mexer em integrações já contratadas, e fazer tudo isso sem derrubar quem já está usando.

A consultoria não fez nada que um bom desenvolvedor não faria. Entregou o que foi pedido, o código está organizado, os testes existem. O que faltou foi o passo anterior. Faltou alguém perguntar quem é o ator central de cada fluxo, faltou diagrama de caso de uso que tornasse óbvio onde aquela responsabilidade deveria viver, faltou ADR justificando a decisão. Faltou, basicamente, o trabalho que eu venho descrevendo o post inteiro.

E aqui mora a parte que poucos founders querem ouvir. Quem contrata desenvolvimento de software, seja consultoria, seja time interno, seja freelancer, tem que ter visão de processo. Tem que exigir os artefatos como parte do entregável, no mesmo nível do código. Persona documentada, casos de uso desenhados, diagrama de banco atualizado, ADR das decisões que afetam o produto a longo prazo. Sem isso, o que você compra é um repositório que roda hoje. Não é um produto que dura cinco anos.

Essa documentação não é zelo de arquiteto, é seguro contra dívida cara. A diferença entre pagar pra fazer certo no início e pagar pra desfazer depois costuma ser de uma ordem de magnitude. Às vezes mais.

Vamos pagar essa dívida no projeto que recebemos. Não tem jeito. Mas estamos pagando documentando primeiro, mapeando atores, redesenhando o modelo, registrando o porquê das mudanças. Pra que da próxima vez, quando o produto for evoluir de novo, ninguém precise descobrir do zero o que cada coisa significa.

Onde a responsabilidade foi parar

Tem uma percepção comum de que usar IA pra codar é “ficar parado vendo o modelo trabalhar”. Não é a minha experiência.

O que aconteceu foi um deslocamento. O tempo que eu gastava digitando código agora eu gasto preparando contexto, revisando teste, refinando diagrama, decidindo arquitetura, recusando sugestão. O volume de digitação caiu, o volume de decisão subiu.

E com a decisão vem a responsabilidade. Documentação, persona, caso de uso, ADR. Antes eram coisas que o gestor cobrava do desenvolvedor, e o desenvolvedor entregava se sobrasse tempo. Agora são coisas que o desenvolvedor precisa fazer pra si mesmo, porque sem elas o agente entrega o caminho mais genérico possível.

Quem espera o gestor pedir já perdeu. Quando o gestor pede, o código ruim já foi pra produção, a entidade já foi modelada no nível errado, a decisão já foi tomada sem registro. A janela onde esse trabalho importa é antes do prompt, e quem está no teclado é o desenvolvedor.

Isso muda o que significa ser desenvolvedor sênior. Não é mais o cara que escreve código difícil mais rápido. É o cara que sabe parar de codar pra desenhar, mapear, documentar, registrar. Que entende que esses artefatos não são burocracia imposta de cima, são o material que separa um produto que dura de um produto descartável.

A IA não gera código legado. Ela acelera a velocidade com que você acumula código legado se você não tem nada além do prompt. O remédio não é parar de usar IA. É reconhecer que as coisas chatas que a gente terceirizava pro gestor exigir agora são parte do que significa ser desenvolvedor.

É menos sexy do que a promessa de “deixa o agente codar pra você”. Mas é o que separa um projeto que ainda vai estar de pé em dois anos de um projeto que vai ser jogado fora junto com a próxima virada de stack.

Eu vi o jQuery virar React. Vi deploy manual virar CI/CD. Vi servidor físico virar cloud virar serverless virar “não se preocupa com infra”. Vi ORM, vi container, vi micro serviço, vi gente voltando pra monolito. Quinze anos nessa área e eu já perdi a conta de quantas vezes alguém disse que uma nova abstração ia “mudar tudo.”

Na maioria das vezes, não mudava. Mudava o como, mas não mudava o quê. Você continuava pegando uma demanda, entendendo o problema, escrevendo código, entregando, e voltando pro começo. O ciclo era o mesmo. As ferramentas novas, algumas boas e outras francamente inúteis, eram camadas novas em cima do mesmo trabalho.

Dessa vez é diferente. E eu não digo isso com entusiasmo. Digo com aquele desconforto de quem entende o que tá vendo.

Assine agora

O loop quebrou

Com a IA, não é mais uma abstração nova em cima do mesmo trabalho. É o trabalho em si que tá mudando. O ciclo clássico de pegar demanda, entender, desenvolver, entregar e repetir tá sendo comprimido de uma forma que não tem volta.

Eu olho pra trás e vejo quinze anos construindo uma expertise que era, no fundo, sobre traduzir problemas humanos em código. Essa tradução tá ficando cada vez mais barata. Cada vez mais rápida. Cada vez mais acessível pra quem nunca escreveu uma linha de código na vida.

Escrever código virou commodity. E quando uma coisa vira commodity, o valor migra pra outro lugar.

O que sobra quando código vira commodity

Sobra critério.

Sobra a decisão de o que construir, e não só de como construir. Sobra a habilidade de olhar pra um briefing vago e enxergar o problema real escondido lá dentro. Sobra saber quando uma entrega que “funciona” ainda está longe de estar boa. Sobra ter gosto pra reconhecer arquitetura ruim antes que ela cobre juros. Sobra saber onde a pressa pode rolar e onde ela vai destruir o produto em seis meses.

Nada disso é novo. Sempre foi o que separava o desenvolvedor sênior do júnior. A diferença é que, antes, dava pra ter uma carreira inteira sendo excelente tecnicamente sem precisar mostrar muito desse critério, porque o critério estava embutido no código entregue, e o código entregue era o ativo. Hoje o código entregue é barato. Quem não consegue tornar o critério visível vira invisível.

Por que comecei a escrever

A pergunta que ficou na minha cabeça durante meses foi essa: como é que eu mostro critério?

Currículo não mostra. Tempo de carreira não mostra. Lista de tecnologias não mostra. Repositório no GitHub mostra um pouco, mas só pra quem entende e tem paciência de ler. Critério aparece nas escolhas, nos trade-offs, no jeito de falar sobre os problemas. Aparece quando alguém te ouve por dez minutos e pensa “esse cara já passou por isso umas mil vezes”. E pra alguém pensar isso, você precisa estar falando.

Esse blog é onde eu vou falar.

Não vai ser tutorial. Tutorial todo mundo já tem em excesso, e a IA escreve melhor do que eu. Vai ser sobre como eu penso quando preciso decidir alguma coisa difícil. Sobre os critérios que eu uso pra separar entrega boa de entrega medíocre. Sobre as decisões que eu tomo antes de uma linha de código ser escrita. Sobre o que eu desligo o agente pra fazer e por quê. Sobre o que eu acho que é trabalho de gente e o que eu acho que virou trabalho de máquina.

Vai ter convicção. Vai ter coisa que eu vou escrever hoje e olhar daqui a um ano com vergonha. Tudo bem. Pensar em público é assim mesmo.

O contexto pessoal

Vou ser direto sobre o pano de fundo. Eu sou co-fundador da Germina, um startup studio. A decisão de empreender pra mim não foi por ambição clássica de carreira. Foi mais um instinto: se o valor está migrando de quem executa pra quem define, faz sentido estar do lado de quem define. Ter algo seu. Ser dono do problema, não só do código que resolve ele.

Esse blog não é a Germina, não é pitch, não é funil. Mas também não é descolado dela. As ideias que aparecem aqui são as mesmas ideias que guiam como eu construo lá. Faz sentido isso ficar claro desde o começo.

O que esperar

Texto sobre como pensar em decisões difíceis na construção de software. Sobre o que mudou no meu jeito de trabalhar com agentes de IA. Sobre os critérios que eu uso pra separar entrega boa de entrega medíocre. Pouco sobre tendências de mercado, porque o que me interessa mostrar aqui é o ofício, não o setor.

Não tenho a pretensão de fazer engenharia reversa do futuro do desenvolvedor de software. Tenho a pretensão de fazer um trabalho honesto, mostrar o critério por trás dele, e deixar registro. Se daqui a três anos eu olhar pra trás e os posts envelhecerem mal, ótimo: significa que a indústria mudou de novo, e eu mudei com ela.