Durante décadas, comentar código dividiu opiniões. De um lado, quem defendia que bom código se explica sozinho e que comentário é dívida a envelhecer. De outro, quem via na documentação um favor ao colega e ao próprio autor do futuro. Esse debate mudou de figura quando o colega passou a ser um agente de IA. Hoje, quando um modelo abre o seu repositório para implementar uma tarefa, ele lê o README, os comentários, as docstrings e os arquivos de instrução antes de tocar em qualquer linha. A documentação virou o contexto que alimenta a máquina.
A ironia é que os modelos de fronteira já operam com janelas de contexto acima de um milhão de tokens, e ainda assim o gargalo não desapareceu. Ter espaço para ler tudo não resolve o problema de saber o que ler, por que aquilo importa e como se conecta à tarefa. É aí que a documentação deixa de ser enfeite e vira mapa. Um código bem descrito não é mais educado, é mais legível para o agente, e isso se traduz diretamente na qualidade do que ele devolve.
Este texto é continuação natural de uma ideia que explorei ao falar de Spec-Driven Development. Se a especificação é o que e o porquê definidos antes do código, a documentação e os comentários são o porquê que vive dentro do código, a camada que o agente consulta enquanto executa. Uma prepara o terreno, a outra sustenta o caminho.
O contexto virou o gargalo
A capacidade de entender e navegar uma base de código grande é o limite que define os agentes de programação atuais. Janela enorme de contexto ajuda, mas base real não se resolve despejando todos os arquivos no prompt. O caminho que funciona é o oposto, externalizar o contexto para o sistema de arquivos e deixar o agente ler de forma seletiva o que precisa, quando precisa. Documentação estruturada, comentários que explicam decisões e um plano escrito em disco cumprem esse papel de índice. Eles dizem ao agente onde olhar e por que aquilo é relevante, poupando a leitura cega de milhares de linhas.
Do comentário à base de conhecimento
Na prática, os sistemas modernos que dão inteligência de repositório a um agente extraem estrutura do código com ferramentas como o tree-sitter, e nessa extração entram classes, funções, grafos de chamada, docstrings e comentários de racional. Ou seja, o comentário que explica por que uma decisão foi tomada não é ruído, é dado indexável que ajuda o agente a raciocinar. O código sozinho raramente basta. Faltam a ele os artefatos que explicam arquitetura, padrões e operação, exatamente o que um bom comentário e uma boa documentação carregam. A estrutura da documentação afeta de forma mensurável a acurácia das respostas do agente, e essa relação já aparece em estudos com centenas de desenvolvedores.
AGENTS.md e a convenção que emergiu
Do lado das convenções, um padrão se firmou depressa. O arquivo AGENTS.md, colocado na raiz do repositório, reúne o contexto que o agente precisa para trabalhar bem: comandos de build com as flags certas, procedimento de testes, regras de estilo que fogem do padrão e restrições de arquitetura. Sua compatibilidade é ampla, com dezenas de agentes que o leem, do Codex ao Claude Code, passando por Copilot, Cursor e Gemini CLI, e dezenas de milhares de repositórios já o adotaram. Ao lado dele convivem variações como o CLAUDE.md e o arquivo de regras do Cursor, além do llms.txt, que oferece a sites de documentação um índice pensado para consumo por IA.
O que muda na prática
As boas práticas convergem para um princípio conhecido de quem já mantinha documentação séria. Menos é mais. Um arquivo focado de cinquenta linhas supera um manual de mil, porque o modelo tem capacidade limitada de seguir instrução e ignora o excesso. Mantenha uma única fonte de verdade e faça os arquivos específicos apontarem para ela, em vez de duplicar. Prefira o que foi escrito à mão, onde cada linha resolve um problema real que você já enfrentou. E, no código, comente o porquê, não o o quê. A assinatura da função já diz o que ela faz. O comentário valioso é o que registra a decisão, a restrição e o motivo, o tipo de contexto que nenhum modelo adivinha sozinho.
A documentação parou de ser um favor ao seu eu do futuro e virou infraestrutura para os seus agentes. A lição espelha a do desenvolvimento guiado por especificação. A alavanca está em tornar a intenção explícita, seja antes do código na forma de spec, seja dentro dele na forma de comentário e documento. Onde a intenção está registrada, humano e agente compartilham o mesmo mapa. Onde ela vive apenas na cabeça de quem escreveu, cada um segue um palpite diferente.
A maturidade, de novo, não vem de escrever mais, e sim de escrever o que importa. Documentar o racional, manter uma fonte de verdade e podar o excesso rende mais do que encher o repositório de texto que ninguém lê, nem pessoa nem máquina. Ao preparar uma base para trabalhar com agentes, uso o Claude para revisar um AGENTS.md, apontar onde falta racional nos comentários e transformar conhecimento espalhado em contexto que o próprio agente vai consumir depois. A pergunta que sobra é direta: quando o próximo agente abrir o seu código, ele vai encontrar um mapa ou um labirinto? Para conversas sobre engenharia, IA aplicada e arquitetura de software, acompanhe o Canal Nexa e a Seleção Vip.
