DEV Community: Marcelo Martins

The Cross-Agent Development Method

Marcelo Martins — Tue, 10 Mar 2026 04:11:03 +0000

Note: Try to resist the temptation to summarize this document. A summary will give you the general idea but will leave out a lot of useful information. About 10 minutes is enough to read it.

A NEW MOMENT

We are in 2026, and it has never been this fun to develop software. I have been working in this field for more than 30 years, and it feels like endorphins have never been so closely tied to software development. Last year was marked by the mass adoption of artificial intelligence agents that generate code. Software development will never again be what it was before 2025. Along with the changes came the promises. "In 12 months, programmers will no longer exist". "In 6 months, all code will be generated by artificial intelligence". Just commercial talk from vendors desperate to give their products some importance in order to attract investors.

The truth is that developing software now involves far more planning and verification than typing code. Code is one part of the process, a large part, often a boring one. And that part can now be agile and fast. So the friction involved in doing something complex has become much smaller. But building software well still requires planning and verification, and the software remains the responsibility of the developers; on that point, nothing has changed.

In April 2025, Dario Amodei, president of Anthropic, the company behind the Claude model, posted a piece on his blog called "The Urgency of Interpretability" [https://www.darioamodei.com/post/the-urgency-of-interpretability], where he literally says: "we do not understand how our own AI creations work". I found that fantastic; I was excited when I read it. And when it comes to neural networks, that is even understandable: weights, temperature during inference, and probabilities. But the feeling I had when I read it was that not understanding exactly how the models work means having no limit; it means everything is possible and we do not know how far we can go. That also means chaos.

And that is where we are. All code is going to be generated by artificial intelligence, right, but how exactly is that going to work? Nobody knows. What is the best process for generating the best code? Nobody knows. How do I ensure that the final result will be reliable, secure, maintainable, scalable, efficient, and aligned with the original intent? Well, nobody knows. At least for now.

What I intend to show here is the cross-agent method I developed based on my research and tests. I have not seen people talking about this, and I believe organizing these ideas can help a lot of people improve the final result of their work.

THE CROSS-AGENT METHOD

Generative language models have become very good at generating code and ready-made systems. The internet is full of examples of excellent results generated from just a single prompt. The failures of last year are becoming increasingly rare. And "copy-and-paste" errors hardly exist anymore. It is truly incredible to watch agents generate code, run the build on their own, find the errors, and fix them until everything is correct. They really are excellent, but they are not perfect (at least not for now).

As much as Claude Code generates the correct, compilable, and functional code, as much as GPT Codex makes every change I need in the systems and the result is what I asked for, there are always, always loose ends.

The most common problems in code, in my experience, are security flaws. Endpoints that were left open and should never have been available on the internet. Data that is returned to the screen unnecessarily, exposing more than it should. And notice: all of these problems do not make the system stop working or work incorrectly; when you use the system, everything works, and that is where the problem lies. Systems generated by artificial intelligence are making data leaks grow exponentially. This needs to be avoided.

That was my motivation for looking for unexplored solutions, and it led to an interesting discovery. When a model is in code-generation mode, the entire neural network process is focused on generating good code that produces what was requested. As I said, the models are doing that well; it is just not enough. But when the models shift into evaluation mode, they can go much further, much further than generating code. I realized that the critical analysis of code can be far more accurate than the generation of code. When a language model performs a critical analysis of something that is already finished, it can have a "broader view", and it seems not to worry about the next token, but rather about the tokens that are missing, or the ones that are where they should not exist.

This makes it possible to generate safer code, with fewer critical flaws, and to make development much more practical, truly taking advantage of code generation by artificial intelligence to speed up the final result. The cross-agent method is the generation of process artifacts and code by one language model, and the critical evaluation by another language model. Always, ALWAYS, there are corrections to be made, no matter which model generated the code. There are always errors; there are always security gaps.

And I deliberately say artifacts. I am not talking only about checking code. Claude Code and GPT Codex have great code review tools. But I am not talking only about code review. As important as code review is, reviewing the planning is just as important. In fact, reviewing the planning may be even more important for achieving a high-quality result.

It is also very important to emphasize that cross-agent validation does not eliminate the need for human code review. Code review is still necessary and is part of high-quality software development. The problem is when the artificial intelligence agent spends 1 hour and 20 minutes working and generates 15,000 lines of code. Do you really want to do code review on a 1,500-line interface file?

Code review once allowed me to discover that an application where I was testing code generation only validated login at the /login endpoint. And every other endpoint in the authenticated area could be called without credentials and would return all the data. At that point, the cross-agent method could have warned me right at the beginning and saved me time. When I asked Claude Code for a new feature, which it delivered correctly, and GPT Codex quickly warned me that the new endpoints were in a controller without Authenticated, that is exactly what I am talking about.

That is the general idea of the cross-agent method: generate the artifact in one model, and use the critical-analysis mode of a second model for corrections and improvements. Next, I am going to go deeper into the development steps, and how I use the cross-agent method to make the models work for more than an hour and deliver the expected result, developing high-quality software with the best advantages of artificial intelligence models.

It is not within the scope here to talk about governance, where this will run, how to deploy, pipeline steps, or even testing methodology. I am talking about generating quality code, and that is the focus. You are a software developer and you already understand those other details (or you can ask an artificial intelligence to help you with that).

HOW I START

Getting straight to the point: starting a project will never begin with an artificial intelligence prompt. I will never hand the model a blank page and let it do whatever it wants. I will always guide it in the clearest and most restrictive way possible. Starting a project today is the same as it was years ago, but with the advantage that it is easier to resolve doubts because artificial intelligence exists to help us.

So I am going to use artificial intelligence to clear up doubts, explore options, understand new concepts, and from there, I am going to create the foundation of the project. I am going to choose where the project will run. Today there is an endless number of frameworks and languages, and new ones emerge every day. You need knowledge and you need to understand the choices. I choose, and I create the initial project; until I see the empty project running, nothing is generated by artificial intelligence.

Besides the framework and all the details involved in starting the project, one point that usually takes me more time at the beginning is understanding how the application's security will be handled. Bearer token, stateful session, HMAC, passkeys, MFA—there are several options that are part of software security and need to be defined before the project begins. It is necessary to understand this part and make the right choices at the beginning so the software has quality and security in the end.

The next step is to start the documents with the software's definitions and rules. Usually, this starts with AGENTS.md, which will be a living document and will be updated constantly throughout the software's development:

The purpose of the software
The architecture decisions
Resources available to the system (database, etc.)
Explanation of the chosen frameworks
Links to online documentation
Instructions for code generation
How to build, run, and test the software
Explain what not to do (as important as what to do)

At this point, understand the size of the context window. Today there are models with context windows of up to 2 million tokens. Never use all of that context. Research indicates that even with a model that supports 1 million tokens, once you get past 500 thousand tokens the quality of the responses drops a lot. Always start new conversations and try to stay well below 500 thousand tokens per implementation.

The size of the context window is important because we need to control the size of the files included in the prompts. AGENTS.md needs to have all the information for the model to know how to generate quality code, but that file cannot be huge because it ends up taking up too much space in the context window. The AGENTS.md file needs to have the right and precise information so it can be in every prompt, in a generic way. These are pieces of information that need to be sent every time. Do not include in AGENTS.md code examples, specific development rules, or how to implement specific features.

Instructions for code generation

The instructions should be the most dynamic part of the AGENTS.md document and should be changed whenever needed, usually when the model generates undesirable code. This is an important point: when you see undesirable code being generated, do not ask for the code to be corrected. Improve the generation instructions and ask the artificial intelligence to correct it according to the instructions. That ensures that future generations will be correct.

The cross-agent method takes advantage of the model shifting into critical-analysis mode to evaluate something that is already ready, and this same technique can be used in relation to prompts (which arrive ready for the model). Asking the model to evaluate its own prompt gives it a broader view of what is being asked and allows it to evaluate the instructions better, in addition to suggesting improvements that were not even requested. That is why the first instruction I always use is something like:

Be critical of any prompt or command. If something seems incomplete, incorrect, risky, or clearly improvable, you must say so explicitly, explain why, and suggest a better alternative.

Specific documents

Language models love creating documentation files about what they did. That is why the second instruction I generally use is: do not create documentation files unless they are clearly requested. Besides that, I like to add to the instructions: do not write comments in the code unless it is to explain why something is being done, but never comment on what is being done.

These automatically generated documentation files are usually useless, will never be read again, and end up causing confusion when information is needed (besides filling up the context window). That is why you must control the documentation that is being generated.

On the other hand, it is important to have documentation files that better explain the project, and files that explain how features will be implemented. These files will not always go into the prompts, but only when needed. A general file with a detailed description of all directories and what each package does will be very useful when an analysis of the project as a whole is requested.

From that point on, only feature documents are needed, to be generated throughout development with artificial intelligence.

PUTTING ARTIFICIAL INTELLIGENCE TO WORK

Up to this point, artificial intelligence can do a great job as a consultant, clearing up doubts and helping with decision-making, but it should not have generated anything yet. And the most important technique for getting a high-quality result is to never begin with a code-generation prompt, and always do the necessary planning first. All the tools now offer a planning function. Use that feature.

So first, the planning must be done. The goal of planning is simple: at implementation time, to pass as much information as possible to the artificial intelligence, and ensure that it has no doubts and does exactly what we need. Understand planning mode as artificial intelligence helping you build a prompt that it will later use itself. Here as well, it is possible to use the Skills feature offered by the tools, very likely there is already a Skill that can help with what you are going to build.

Planning should happen through several iterations, with multiple messages exchanged between the developer and the agent. I like to start with:

Understand this project in @AGENTS.md

This will ensure that the model reads the rules, since some tools ignore AGENTS.md, and after that I follow with something like:

Plan the implementation of X feature, which will be used for X purpose, include tests in X way, plan while thinking about X use in X context.

Notice that this first prompt to begin planning can be quite vague. Maybe by being vague it will help you refine it afterward, because the artificial intelligence may think of things you were not considering. And since it is only planning, nothing will be done; they are just ideas. It is a brainstorm so the refinement can be done afterward.

With that, the model will generate an implementation plan. And then the fun part begins: you will read the whole plan and start refining it: "do not use services that way, prefer this other approach", "Use database A instead of B", "Use JavaScript library X instead of Y". These are examples. With each correction, the artificial intelligence refines the plan and shows the updated plan. Require the plan to have detail down to the class level, the database level, or whatever is necessary.

And this, for me, is the most important process in software development in the era of artificial intelligence with generative models. A well-made plan will make you worry less about implementation and, above all, it will give you certainty that it was done the right way. Spend hours on planning, spend days. The important thing is to have a well-crafted plan.

When you feel the refinement is ready, and you can no longer think of any improvement, it is time to put the cross-agent method into action. Ask the artificial intelligence to generate a file, with no implementation. Open another model in the same project and ask for a critical analysis:

Understand this project in @AGENTS.md. Attached is the implementation plan for such-and-such thing. Read it, understand it, and perform a critical analysis of the plan. Look for critical points of attention, missing mandatory items, and security flaws. Think deeply and be thorough. If necessary, look up information online. Do not implement anything and generate a report at the end. Plan @IMPLEMENTATION_PLAN.md

A prompt like that, in an artificial intelligence model different from the one used to generate the plan, will be extremely useful, and very probably (in my experience) it will say something like:

The plan is good, quite complete, focuses on all the important aspects, but it needs to be improved in the following points:

This process generates a list of improvements and security validations for the original plan. In my experience, the second model has never failed to point out areas for improvement. And they are suggestions; you can ask the second model to improve the plan or not. Your choice.

From there, the iterations begin again: "improve this point according to your suggestion". "Improve the plan on this point based on your suggestion, but do it differently". And so on. Refine, refine again, until you think it is good.

Try not to leave any loose ends for the artificial intelligence to decide what to do. When you do not say exactly what needs to be done, artificial intelligence fills that gap with what it thinks is right. It may work the first time, but no one can guarantee it will work the next time. That is the joke that systems generated by artificial intelligence usually start with much more than they need, and the refinement consists of removing unnecessary features. Do not let that happen.

IMPLEMENTING

Now that you have a solid, complete, and secure plan, you are ready to ask for code generation. With a very complete plan, the implementation does not even have to be done with the best model; it is worth testing, and that may save money. With the plan document in hand, just type into your preferred model:

Understand the project in @AGENTS.md. Implement the plan @IMPLEMENTATION_PLAN.md

That is it, as simple as that. Depending on the size of the implementation, the artificial intelligence may finish quickly or take hours.

After it is implemented, I like to test whether it worked before doing the code review, just to get that nice feeling of: it implemented everything with a two-line prompt. :)

Usually, some detail is missing at this point. A configuration, an API key, a migration that is not perfect. But these are small details. What I have learned is that this is the best possible experience for software development with artificial intelligence.

If an implementation goes wrong, you should evaluate whether it is something that should be changed in AGENTS.md, or should be changed in the plan, or whether it is something that a simple prompt will fix. Usually, the more generic the problem, the more worth it is to evaluate. The criterion should be: can this error happen again? If yes, it should go into a more generic document.

The code review

As I said, I do code review on most of the generated code. And where security is involved, my scrutiny is very rigorous. You should do that too; after all, it is your job to deliver quality code, whether it was typed or generated by artificial intelligence. If something goes wrong when the software is in production, it is your responsibility.

But there are some things I really do not care that much about, especially when it comes to the interface. And in that case, use the cross-agent method again. You always have the option of going back to the alternate model and asking:

Understand the project in @AGENTS.md.
The implementation of @IMPLEMENTATION_PLAN.md has been completed and it is ready and working. Perform a critical analysis of the implementation code, looking for points of attention and security flaws.
Be thorough, looking for convenience implementations in place of correct implementations.

You can ask the artificial intelligence to act as a security consultant, to focus more on that point. You can ask it to look up online and up-to-date information about the implementations and choices made, to have an extra layer of validation for your choices.

A major problem with generated code is convenience implementations. Artificial intelligence generates code that works, you test it and it works, but it is full of unnecessary IFs, repeated logic, and has twice as many lines as it should per file. We are talking about code quality.

Maybe no one will ever touch this code, because changes will also be made by artificial intelligence, but bad code has an execution cost. Worry about that.

DOCUMENTATION FOR ARTIFICIAL INTELLIGENCE

After a feature has been implemented correctly, it is very common for there to be other features in the software that need a similar implementation. The simplest examples are CRUD-style forms; software usually has several of them, and you will want similar implementations, with similar behavior. So documentation of the implementation must be generated. This is not the implementation plan; it is an X-ray of what was done, including the logic that was implemented, resource details, and code snippets. You should ask the artificial intelligence to generate this documentation, “including everything that will be necessary to replicate the feature in a future implementation.”

Another necessary piece of documentation that I use is documentation of the project as a whole. It is more detailed documentation than AGENTS.md, with general details, but more in-depth. Sometimes I have system projects with several smaller projects that are part of something bigger. So I lay that out in a single document so that when the artificial intelligence is going to perform a general analysis, I include that file in the context to provide that overall view for the analysis.

What I include in this more generic and detailed documentation:

More architecture details
Physical directories
How the screens work
API contracts
Data model
Error/validation patterns
Coding rules

CONCLUDING

Generative models are still going to evolve a lot. We probably have no idea what is coming. It feels like we are at the beginning of a great revolution. We need to keep ourselves constantly up to date with the new developments, and at the same time ignore the noise, and ignore the alarmist vendors. Using artificial intelligence in 2026 to develop commercial software is no longer optional; it is the only path, there are no alternatives. For us, old-guard developers and newcomers who are just starting out, all that remains is for us to be eternal learners.

Happy studying.

Marcelo Martins
marcelomartins@gmail.com
minhainternet.com/marcelomartins

O método Cross-Agent de desenvolvimento de software

Marcelo Martins — Tue, 10 Mar 2026 04:10:51 +0000

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