Nota: tente resistir a tentação de resumir esse documento. O resumo dará a ideia geral mas deixará de fora muitas informações úteis. Uns 10 minutos são suficientes para a leitura.
O NOVO MOMENTO
Estamos em 2026, e nunca foi tão divertido desenvolver software. Atuo na área há mais de 30 anos, e parece que nunca a endorfina esteve tão relacionada com o desenvolvimento de software. Ano passado foi marcado pela massificação dos agentes de inteligência artificial que geram código. O desenvolvimento de software nunca mais será como antes de 2025. Junto às mudanças vieram as promessas. "Em 12 meses não vão mais existir programadores". "Em 6 meses todos códigos serão gerados por inteligência artificial". Só discurso comercial de vendedores desesperados em tentar dar alguma importância a seus produtos para atrair investidores.
A verdade é que desenvolver software agora envolve muito mais planejamento e verificação do que digitação de código. Código é uma parte do processo, uma parte grande, muitas vezes chata. E essa parte agora pode ser ágil e rápida. Então a fricção de fazer algo complexo ficou muito menor. Mas fazer software bem feito continua exigindo planejamento e verificação, e o software continua sendo de responsabilidade dos desenvolvedores, nesse ponto nada mudou.
Em abril de 2025, Dario Amodei, presidente da Anthropic, dona do modelo Claude, postou em seu blog um texto chamado The Urgency of Interpretability [https://www.darioamodei.com/post/the-urgency-of-interpretability], onde ele diz literalmente: "nós não entendemos como funcionam as nossas próprias criações de inteligência artificial". Achei fantástico, fiquei empolgado ao ler. E se tratando de redes neurais, isso é até compreensível, são pesos, temperatura durante a inferência e probabilidades. Mas o meu sentimento ao ler foi de que ao não entender exatamente como os modelos funcionam, significa não ter limite, significa que tudo é possível e não sabemos até onde podemos ir. Isso também significa o caos.
E é aqui que estamos. O código todo vai ser gerado por inteligência artificial, certo, mas como isso vai funcionar exatamente? Ninguém sabe. Qual é o melhor processo para gerar o melhor código? Ninguém sabe. Como eu garanto que o resultado final será confiável, seguro, manutenível, escalável, eficiente, e alinhado com a intenção inicial? Pois é, ninguém sabe. Por enquanto pelo menos.
O que pretendo mostrar aqui é o método cross-agent que desenvolvi com base nas minhas pesquisas e testes. Não vi pessoas falando sobre isso, e acredito que organizar essas ideias pode ajudar muita gente a melhorar o resultado final dos seus trabalhos.
O MÉTODO CROSS-AGENT
Os modelos generativos se tornaram muito bons em gerar códigos e sistemas prontos. A internet está cheia de exemplos de excelentes resultados gerados a partir de apenas um prompt. As falhas do ano passado se tornam cada vez mais raras. E os "copy-paste" de erros quase não existem mais. É realmente incrível ver os agentes gerarem o código, rodarem o build sozinhos, encontrarem os erros, e corrigirem até ficar tudo correto. Eles são excelentes mesmo, mas não são perfeitos (por enquanto pelo menos).
Por mais que o Claude Code gere o código correto, compilável e funcional, por mais que o GPT Codex faça todas alterações nos sistemas que preciso e o resultado seja o que eu pedi, sempre, sempre ficam pontas soltas.
Os problemas em códigos mais comuns na minha experiência, são falhas de segurança. Endpoints que ficaram abertos e nunca poderiam estar disponíveis na internet. Dados que são retornados pra tela sem necessidade e entregando mais do que deveriam. E veja bem, todos esses problemas não fazem o sistema parar de funcionar ou funcionar errado, usando o sistema, tudo funciona, e aqui é onde está o problema. Sistemas gerados por inteligência artificial estão fazendo os vazamentos de dados aumentarem exponencialmente. Isso precisa ser evitado.
Essa foi minha motivação para buscar soluções inexploradas, e resultou numa descoberta interessante. Quando um modelo está em modo de geração de código, todo processo da rede neural está focado em gerar um bom código, que resulte no que foi pedido. Como eu disse, isso os modelos estão fazendo bem, só não é o suficiente. Mas quando os modelos entram em modo de avaliação, eles conseguem ir muito além, muito além de gerar o código. Percebi que a análise crítica de códigos consegue ser muito mais assertiva que a geração dos códigos. Quando um modelo de linguagem faz a análise crítica de algo pronto, ele consegue ter uma "visão mais ampla", e parece não se preocupar com o próximo token, mas sim se preocupar com os tokens que faltam, ou que estão onde não deveriam existir.
Assim é possível gerar códigos mais seguros, com menos falhas críticas e fazer o desenvolvimento ser muito mais prático, aproveitando realmente a geração de código por inteligência artificial para agilizar o resultado final. O método cross-agent é a geração de artefatos do processo e códigos por um modelo de linguagem, e a avaliação crítica por outro modelo de linguagem. Sempre, SEMPRE, tem correções a serem feitas, não importa o modelo que gerou o código. Sempre tem erros, sempre tem brechas de segurança.
Eu propositalmente digo artefatos. Não estou falando apenas de verificar os códigos. O Claude Code e o GPT Codex tem ótimas ferramentas de code review. Mas não estou falando só de code review. Tão importante quanto a revisão do código é a revisão do planejamento. Talvez a revisão do planejamento seja até mais importante para atingir um resultado de qualidade.
Muito importante também destacar que, a validação cross-agent não elimina a necessidade do code review humano. O code review continua necessário e faz parte do desenvolvimento de software de qualidade. O problema é quando o agente de inteligência artificial fica trabalhando por 1 hora e 20 minutos e tem 15 mil linhas de código geradas. Você quer mesmo fazer code review em um arquivo de interface de 1.500 linhas?
O code review me permitiu, a um tempo atrás, descobrir que uma aplicação que eu estava testando a geração de código, só validava o login no endpoint /login. E todos outros endpoints da área logada poderiam ser chamados sem credenciais retornando todos os dados. Nesse ponto o método cross-agent poderia ter me avisado logo no início e me poupado tempo. Quando pedi uma nova funcionalidade para o Claude Code, que me entregou corretamente, e o GPT Codex rapidamente me avisou que os endpoints novos estavam em um controller sem o Authenticated, é sobre isso que estou falando.
Essa é a ideia geral do método cross-agent, gerar o artefato em um modelo, e usar o modo de análise crítica de um segundo modelo para correções e melhorias. A seguir vou entrar mais a fundo nos passos do desenvolvimento, e como eu uso o método cross-agent para fazer os modelos trabalharem por mais de uma hora e entregar o resultado esperado, desenvolvendo software de qualidade com as melhores vantagens dos modelos de inteligência artificial.
Não faz parte do escopo falar sobre governança, onde será executado, como fazer deploy, passos para o pipeline, nem mesmo metodologia de testes. Estou falando de geração de código de qualidade, e o foco é esse. Você é um desenvolvedor de software e já deve entender esses outros conceitos (ou pode pedir pra uma inteligência artificial te ajudar nisso).
COMO EU COMEÇO
Indo direto ao ponto: iniciar um projeto nunca será pelo prompt da inteligência artificial. Eu nunca vou dar uma página em branco para o modelo fazer o que quiser. Sempre vou guiar da maneira mais clara e restrita possível. Iniciar um projeto hoje é igual a anos atrás, mas com a vantagem de ser fácil resolver dúvidas porque existe a inteligência artificial para nos ajudar.
Então, vou usar a inteligência artificial para tirar dúvidas, buscar opções, entender novos conceitos, e a partir daí, eu vou criar a base do projeto. Eu vou escolher onde vai ser executado o projeto. Hoje existem uma infinidade de frameworks e linguagens, e novas opções surgem todos os dias. É preciso ter conhecimento e entender as escolhas. Eu escolho, e eu crio o projeto inicial, até ver o projeto rodando vazio nada é gerado por inteligência artificial.
Além do framework e todos detalhes para inicio do projeto, um ponto que geralmente eu demoro mais tempo no início, é entender como será feita a segurança da aplicação. Bearer token, sessão stateful, HMAC, passkeys, MFA, são diversas opções que fazem parte da segurança do software e precisam ser definidas antes de iniciar o projeto. É necessário entender essa parte e fazer as escolhas certas no início para o software ter qualidade e segurança no final.
O próximo passo é iniciar os documentos com as definições e regras do software. Geralmente o AGENTS.md, que será um documento vivo e alterado a todo momento durante o desenvolvimento do software. O que é preciso colocar dentro desse documento:
- O propósito do software
- As decisões de arquitetura
- Recursos disponíveis para o sistema (banco de dados e etc)
- Explicação dos frameworks escolhidos
- Links para documentação online
- Instruções para geração do código
- Como fazer build, executar e testar o software
- Explicar o que não fazer (tão importante quanto o que fazer)
Nesse ponto entenda o tamanho da janela de contexto. Atualmente existem modelos com janela de contexto de até 2 milhões de tokens. Nunca use esse contexto todo. Pesquisas indicam que, mesmo um modelo que suporta 1 milhão de tokens, a partir de 500 mil tokens a qualidade das respostas cai muito. Sempre inicie novas conversas e tente se manter bem abaixo de 500 mil tokens por implementação.
O tamanho da janela de contexto é importante porque precisamos controlar o tamanho dos arquivos para incluir nos prompts. O AGENTS.md precisa ter todas informações para o modelo saber como gerar o código de qualidade, mas esse arquivo não pode ser gigante porque acaba ocupando espaço demais na janela de contexto. O arquivo AGENTS.md precisa ter as informações corretas e precisas para estar em todos os prompts, de maneira genérica. São informações que precisam ser enviadas sempre. Não inclua no AGENTS.md exemplo de códigos, regras de desenvolvimento específicas, ou como implementar recursos específicos.
Instruções para geração do código
As instruções devem ser a parte mais viva do documento AGENTS.md e deve ser alterada sempre que for preciso, geralmente quando o modelo gera códigos indesejados. Esse é um ponto importante: ao ver a geração de código indesejado, não solicite a correção do código. Melhore as instruções para geração e peça para a inteligência artificial corrigir conforme instruções. Isso garante que as próximas gerações sejam corretas.
O método cross-agent aproveita o benefício do modelo entrar em modo análise crítica para avaliar algo que já está pronto, e essa mesma técnica pode ser usada em relação aos prompts (que chega pronto para o modelo). Pedir para o modelo avaliar o próprio prompt faz com que ele tenha uma visão mais ampla do que está sendo pedido e pode avaliar melhor as instruções, além de sugerir melhorias que nem mesmo foram solicitadas. Por isso a primeira instrução que eu sempre uso é algo como:
Seja crítico diante de qualquer prompt ou comando. Se algo parecer incompleto, incorreto, arriscado ou claramente melhorável, você deve dizer isso explicitamente, explicar o motivo e sugerir uma alternativa melhor.
Documentos específicos
Os modelos de linguagens adoram criar arquivos de documentação do que fizeram. Por isso, a segunda instrução que eu geralmente uso é: "não crie arquivos de documentação a menos que sejam claramente solicitados". Além disso gosto de adicionar nas instruções: "não escreva comentários nos códigos a menos que seja para explicar porque algo está sendo feito, mas nunca comente o que está sendo feito".
Esses arquivos de documentação gerados automaticamente, geralmente são inúteis, nunca mais serão lidos e acabam confundindo quando se precisa de informação (além de encher a janela de contexto). Por isso você deve controlar a documentação que está sendo gerada.
Por outro lado, é importante ter arquivos de documentação que expliquem melhor o projeto, e arquivos que explicam como será feita a implementação de funcionalidades. Esses arquivos, nem sempre irão para os prompts, mas apenas quando precisar. Um arquivo geral com descrição detalhada de todos diretórios e o que cada pacote faz, será muito bem utilizado quando for solicitada uma análise do projeto como um todo.
A partir daí, são necessários apenas documentos de funcionalidades que serão geradas no decorrer do desenvolvimento com a inteligência artificial.
COLOCANDO A INTELIGÊNCIA ARTIFICAL PARA TRABALHAR
Até aqui, a inteligência artificial pode fazer um grande trabalho como consultora, resolvendo dúvidas e ajudando nas tomadas de decisões, mas não deve ter gerado nada ainda. E a técnica mais importante para conseguir um resultado de qualidade, é nunca começar por um prompt de geração de código, e sempre fazendo o planejamento do que é necessário antes. Todas as ferramentas nesse momento já oferecem a função de planejamento. Use esse recurso.
Então, primeiro deve ser feito o planejamento. O objetivo do planejamento é simples: na hora da implementação, passar a maior quantidade de informações possíveis para a inteligência artificial, e garantir que ela não tenha dúvidas e faça exatamente o que precisamos. Entenda o modo de planejamento como a inteligência artificial te ajudando a construir um prompt que será usado por ela mesmo. Aqui também é possível usar o recurso de Skills das ferramentas, muito provavelmente para o que você irá desenvolver já existe uma Skill pra ajudar.
O planejamento deve ser iterações com várias mensagens trocadas entre o desenvolvedor e o agente. Eu gosto de começar com:
Entenda esse projeto em @AGENTS.md
Isso irá garantir a leitura que o modelo irá ler as regras, já que algumas ferramentas ignoram o AGENTS.md, e depois sigo com algo como:
Planeje a implementação do recurso tal, que será usado para tal coisa, inclua testes de tal maneira, planeje pensando em tal uso com tal contexto.
Veja bem, esse primeiro prompt para iniciar o planejamento pode ser bem vago. Talvez ele sendo vago irá te ajudar a refinar depois, porque a inteligência artificial pode te trazer ideias que você não estava pensando. E como é só o planejamento, nada será feito, são só ideias. É um brainstorm para depois ser refinado.
Com isso, o modelo irá gerar um plano de implementação. E então começa a parte legal: você irá ler o plano todo, e começar a refinar: "não use serviços dessa forma, prefira de tal maneira", "Use um banco A em vez de B", "Use a biblioteca X do javascript em vez da Y". São exemplos. A cada correção, a inteligência artificial vai refinando o plano e mostrando o plano atualizado. Exija que o plano tenha detalhamento a nível de classe, banco de dados ou o que for necessário.
E esse, pra mim, é o processo mais importante no desenvolvimento de software na era da inteligência artificial. Um plano bem feito vai fazer você se preocupar menos com a implementação e principalmente vai te dar certeza de que foi feito da maneira correta. Demore horas no planejamento. Demore dias. O importante é ter o plano bem feito.
Quando você achar que o refinamento está pronto, e não conseguir mais pensar em melhorias, chegou a hora de colocar o método cross-agent em ação. Peça para a inteligência artificial gerar um arquivo, sem nenhuma implementação. Abra outro modelo de linguagem, no mesmo projeto e peça a análise crítica:
Entenda esse projeto em @AGENTS.md. Em anexo está o plano de implementação de tal coisa. Leia, entenda, e faça uma análise crítica do planejamento. Procure pontos críticos de atenção, itens mandatórios faltando e falhas de segurança. Pense profundamente e seja criterioso. Se precisar busque informações online. Não implemente nada e gere um relatório no final. Plano @PLANO_IMPLEMENTACAO.md”
Um prompt parecido com esse, em um modelo de inteligência artificial diferente do que foi usado para gerar o plano, será extremamente útil, e muito provavelmente (pela minha experiência) ele irá dizer algo como:
O plano é bom, bem completo, foca em todos aspectos importantes, mas precisa ser melhorado nos seguintes pontos
Esse processo gera uma lista de melhorias e validações de segurança sobre o plano original. Na minha experiência, o segundo modelo nunca deixou de apontar pontos de melhoria. E são sugestões, você pode pedir para o segundo modelo melhorar o plano ou não. Sua escolha.
A partir daí entram novamente as iterações, "melhore conforme sua sugestão tal ponto". "Tal ponto melhore o plano como sua sugestão, mas fazendo diferente". E assim por diante. Refine, refine de novo, até achar que está bom.
Tente não deixar nenhuma ponta solta para a inteligência artificial decidir o que fazer. Quando você não diz exatamente o que precisa ser feito, a inteligência artificial preenche esse espaço com o que ela acha correto. Pode ser que funcione da primeira vez, mas ninguém garante que funcionará da próxima. É a piada de que os sistemas gerados por inteligência artificial, geralmente começam com muito mais do que precisa e o refinamento é retirando recursos desnecessários. Não deixe isso acontecer.
IMPLEMENTANDO
Agora que você tem um plano sólido, completo e seguro, você está pronto para pedir a geração do código. Com um plano bem completo, a implementação nem precisa ser com o melhor modelo, vale o teste e isso poderá economizar dinheiro. Com o documento do plano em mãos, só digite no seu modelo preferido:
Entenda o projeto em @AGENTS.md. Implemente o plano @PLANO_IMPLEMENTACAO.md
Só isso, "simples assim". Dependendo do tamanho da implementação, a inteligência artificial pode terminar rápido ou levar horas. Depois de implementado, gosto de testar se funcionou antes de fazer o code review, para ter o gostinho de: "implementou com um prompt de 2 linhas. :)"
Geralmente, falta algum detalhe nesse ponto. Uma configuração, uma API Key, uma migration que não está perfeita. Mas são pequenos detalhes. O que aprendi é que essa é a melhor experiência possível para o desenvolvimento de software com inteligência artificial atualmente.
Caso alguma implementação saia errada, você deve avaliar se é algo que deve ser mudado no AGENTS.md, ou deve ser mudado no plano, ou é algo que um simples prompt irá corrigir. Geralmente quanto mais genérico for o problema, mais vale a pena avaliar. O critério deve ser: esse erro pode acontecer de novo? Se sim, deve ir para um documento mais genérico.
O Code review
Como eu disse, eu faço code review da maior parte do código gerado. E onde tem segurança envolvida meu olhar é bem criterioso. Você deve fazer isso também, afinal, é o seu trabalho: entregar código de qualidade, não importa se foi digitado ou gerado por inteligência artificial. Se algo der errado quando o software estiver em produção, é sua responsabilidade.
Mas alguns itens eu realmente não me importo tanto, principalmente se tratando de telas. E nesse caso, use o método cross-agent novamente. Você sempre tem a opção de voltar no modelo alternativo, e pedir:
Entenda o projeto em @AGENTS.md.
Foi feita a implementação do @PLANO_IMPLEMENTACAO.md. Está pronto e funcionando. Faça uma análise crítica dos códigos da implementação procurando pontos de atenção e falhas de segurança.
Seja criterioso, procurando implementação de conveniência no lugar de implementações corretas.
Você pode pedir para a inteligência artificial agir como um consultor de segurança, para focar mais nesse ponto. Pode pedir para buscar informações online e atualizadas sobre implementações e escolhas feitas para ter uma validação extra sobre suas escolhas.
Um grande problema de códigos gerados são as implementações de conveniência. A inteligência artificial gera um código que funciona, você testa e funciona, mas ele está repleto de IFs desnecessários, com lógica repetida, tendo o dobro de linhas que deveria ter por arquivo. Estamos falando de qualidade do código. Talvez nunca ninguém irá mexer nesse código, porque as alterações serão feitas por uma inteligência artificial também, mas código ruim, é custo de execução. Se preocupe com isso.
A DOCUMENTAÇÃO PARA A INTELIGÊNCIA ARTIFICIAL
Depois de um recurso implementado corretamente, é muito comum existirem outros recursos no software que precisam de implementação parecida. O mais simples são cadastros, geralmente os softwares tem vários deles, e você vai querer implementações parecidas, com funcionamento parecido. Então deve ser gerada a documentação da implementação. Isso não é o plano de implementação, é uma radiografia do que foi feito, incluindo a lógica que foi implementada, detalhes dos recursos e trechos de código. Você deve pedir para a inteligência artificial gerar essa documentação, "incluindo tudo que será necessário para replicar a funcionalidade em uma implementação futura."
Outra documentação necessária, que eu uso é a documentação do projeto como um todo. É uma documentação mais detalhada que o AGENTS.md com detalhes gerais, mais profundos. Se existem projetos de sistemas com diversos projetos menores que fazem parte de algo maior, então o melhor é detalhar dentro de um documento único para quando a inteligência artificial for fazer uma análise geral, eu incluo esse arquivo no contexto para dar essa visão geral para a análise.
O que incluo nessa documentação mais genérica de detalhada:
- Mais detalhes da arquitetura
- Diretórios físicos
- Funcionamento das telas
- Contratos de API
- Modelo de dados
- Padrões de erro / validação
- Regras de codificação
CONCLUINDO
Os modelos generativos ainda vão evoluir muito, não temos ideia real do que está por vir. Parece que estamos no início de uma grande revolução. É preciso estar sempre se atualizando com as novidades, e ao mesmo tempo ignorar o ruído, e ignorar os vendedores alarmistas. Usar inteligência artificial em 2026 para desenvolver software comercial não é mais opcional, é a única via, não existem alternativas. A nós, desenvolvedores da velha guarda e novos que estão começando, só nos resta ser eternos aprendizes.
Bons estudos
Marcelo Martins
marcelomartins@gmail.com
https://minhainternet.com/marcelomartins
Top comments (0)