Pular para o conteúdo principal

AGENTS.md: O manual que ensina IA a pensar no seu projeto

· 10 min para ler
Bruno Nogueira
Bruno Nogueira
Desenvolvedor de Software

Construí um projeto de médio porte em Python — uma linguagem que nunca programei profissionalmente — sem digitar uma única linha de código. Utilizei apenas modelos de IA gratuitos. E o segredo? (até parece) Um arquivo de 773 linhas chamado AGENTS.md.

Se você quiser pular a história e ir direto para a prática, vá para a seção: O que é o AGENTS.md.

O contexto: um desenvolvedor Java tentando programar em Python​

Apesar de atualmente não estar atuando profissionalmente diretamente a minha base de aprendizado é Java. Python? Conheço por cima. Nunca programei profissionalmente nela, não tenho como hobby, não sei os atalhos, não conheço as bibliotecas de cor. Mas em abril de 2026, resolvi testar algo que estava me incomodando desde 2025: a IA finalmente estava pronta para desenvolver projetos reais?

Eu já tinha tentado antes. Na virada de 2025, usei IA para criar um projeto em Java — minha própria língua. O resultado? A IA começou a errar, entrou em loop infinito, deletou uma regra de negócio inteira só para o build parar de falhar. Perdi um fim de semana inteiro para ter algo inconsistente. Fiquei decepcionado.

Mas em 2026, as ferramentas evoluíram. Li um artigo do Akita sobre como usar IA em projetos de verdade, e resolvi dar nova chance. A diferença agora? Eu não ia programar. A IA ia programar. Eu ia ser o Navegador Sênior — definindo direção, questionando decisões, corrigindo a rota. A IA seria o Piloto — escrevendo o código, testando e apresentando soluções.

Observação: Eu nunca tinha programado em Python antes disso. Não sei se isso é coragem ou loucura. Talvez um pouco dos dois.

A ferramenta: de Kilo AI para opencode AI​

Comecei utilizando o Kilo AI, VS Code e um terminal Linux com IA integrada que permite interagir diretamente com o código. O Kilo me deu o pontapé inicial — consegui configurar o projeto, o famoso comando /init, criar a estrutura básica e os primeiros endpoints. Funcionava, mas tinha uma limitação: os modelos de IA gratuitos disponíveis não estavam entregando a qualidade que eu precisava para um projeto de médio porte. E também eu estava afim de testar novas ferramentas diferente do Claude Code e de preferência com modelos gratuitos com bastante tokens diários para serem usados.

Busquei modelos gratuitos não apenas por curiosidade mas também para ver qualidade e os famosos custos que atualmente quando escreve este artigo estão consumindo em níveis altos.

Foi quando descobri o opencode AI — uma ferramenta de terminal que roda no Linux e permite conversar diretamente com a IA, que tem acesso completo à pasta do projeto. A grande sacada? Ele funciona com modelos 100% gratuitos. Sem assinatura, sem cartão de crédito, (quase) sem limite de tokens. Eu estava usando o opencode com modelos como Ling 3.0 Flash Fin Free, Nemotron 3 Ultra Free, MiMo V2.5 Free, e Big Pickle, para construir todo o projeto.

Para quem quiser saber mais, o opencode está disponível em opencode.ai. É uma ferramenta open source que roda no terminal e se conecta a diversos provedores de modelos.

A transição foi natural. O opencode me dava acesso terminal, leitura de arquivos, execução de comandos — tudo que eu precisava para controlar o fluxo de desenvolvimento. E o melhor: eu não pagava nada.

O que é o AGENTS.md​

Voltando à pergunta do título: o que é esse arquivo que "ensina a IA a pensar"?

O AGENTS.md é um arquivo Markdown colocado na raiz do projeto. Ele funciona como um manual de instruções e regras para a IA. Toda vez que uma sessão nova é iniciada, a IA lê esse arquivo e passa a entender o contexto do projeto — arquitetura, convenções, comandos, decisões de design, o que pode e o que não pode fazer.

No meu projeto, o AGENTS.md tem 773 linhas. Não é um README. Não é uma documentação para humanos. É um documento escrito para a IA interpretar e seguir. Contém:

  • Arquitetura completa do sistema
  • Padrões de código que devem ser seguidos
  • Comandos disponíveis (testes, lint, build)
  • Regras de segurança obrigatórias
  • Convenções de nomenclatura
  • O que nunca deve ser feito (como commitar sem autorização)
  • Estrutura de pastas e responsabilidades de cada módulo
Estrutura simplificada do que o AGENTS.md cobre:
├── 🚀 Comandos Essenciais (setup, testes, lint)
├── 🏗️ Arquitetura e Convenções (padrão async-first)
├── ⚙️ Características Técnicas (banco, auth, carrinho)
├── 📝 Arquivos que NÃO devem ser commitados
├── 🔧 Dicas de Desenvolvimento (10 regras práticas)
├── 📋 Mudanças Implementadas e Pendências
├── 🔒 Requisitos de Desenvolvimento Seguro
└── 📚 Referências Internas

Por que 773 linhas?​

Porque a IA precisa de contexto explícito. Ela não faz suposições inteligentes — ou melhor, faz, mas muitas vezes erra. Quando eu pedia "criar um endpoint de autenticação", a IA podia criar com SQLAlchemy síncrono, ou usar session.query() em vez de select(), ou esquecer de usar async def. Tudo errado para o padrão do projeto.

Cada vez que eu corrigia um erro desses, eu adicionava a regra no AGENTS.md. O arquivo cresceu organicamente, erro a erro, correção a correção. Era uma espécie de "diário de erros" que se transformou em manual.

Como o AGENTS.md funciona na prática​

Vou dar um exemplo concreto. No início, quando pedia à IA para criar um endpoint, ela fazia algo assim:

# Errado - a IA gerava isso no início
from sqlalchemy.orm import Session

def get_users(db: Session):
    return db.query(User).all()

Depois de várias correções, adicionei no AGENTS.md a seção "Padrão Async-First":

# Correto - agora a IA sempre gera isso
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession

async def get_users(session: AsyncSession):
    result = await session.execute(select(User))
    return result.scalars().all()

A mudança não foi apenas sintática. Envolveu uma filosofia de arquitetura — async-first, SQLAlchemy 2.0, sessões assíncronas, carregamento explícito de relacionamentos. Tudo documentado no AGENTS.md com exemplos do que fazer e do que não fazer.

Outro exemplo: a IA tinha o costume de criar migrations sem COMMENT ON COLUMN. A documentação de colunas é importante para manutenção. Adicionei a regra:

**Comentários em colunas**: Toda coluna nova criada em migrations deve ter 
`COMMENT ON COLUMN` explicando o objetivo, o motivo da criação e o que é 
armazenado.

A partir desse ponto, a IA passou a gerar migrations com comentários automaticamente.

O que a IA entregou (e o que eu fiz)​

Vou ser direto: eu não digitei uma linha de código Python. Toda a lógica de negócio, endpoints, modelos, schemas, testes, migrations — tudo foi gerado pela IA. Minha participação foi:

  • Definir a arquitetura no AGENTS.md
  • Criar os prompts detalhados para cada funcionalidade
  • Revisar o código gerado (cada linha)
  • Corrigir erros e adicionar regras ao AGENTS.md
  • Testar manualmente as funcionalidades
  • Tomar decisões de design quando a IA hesitava
  • Revisões periódicas a respeito de segurança

O projeto resultado em:

MétricaValor
Commits230
Arquivos Python119
Linhas de Python66.158
Arquivos HTML55
Linhas de HTML19.908
Migrações SQL5
Linhas no AGENTS.md773
Duração~4 meses (Abril–Agosto 2026)

O que o projeto é​

É uma aplicação web completa para análise estatística. Inclui:

  • API FastAPI com autenticação JWT RSA
  • Banco PostgreSQL com domínios personalizados e triggers de auditoria
  • Sistema de carrinho com pagamento via InfinitePay (Pix e Cartão)
  • Worker assíncrono para processamento de análises
  • Painel admin com dashboard, métricas e gestão de usuários
  • Frontend com Alpine.js e Jinja2 (cyberpunk minimalista)
  • Testes unitários e E2E com Playwright
  • Sistema de migrações versionado

Tudo isso construído por uma IA que eu controlava pelo terminal.

O segredo: o AGENTS.md como memória de longo prazo​

A grande sacada do AGENTS.md não é apenas documentar regras. É criar uma memória persistente para a IA. Sem ele, cada sessão nova começava do zero. A IA não lembrava das decisões anteriores, dos padrões estabelecidos, dos erros que já tinha cometido.

Com o AGENTS.md, a IA chega no projeto e já sabe:

  • "Este projeto usa async-first, nunca síncrono"
  • "Use select() em vez de session.query()"
  • "Valores monetários são Integer em centavos, nunca Float"
  • "Use with_for_update() em qualquer fluxo financeiro"
  • "Nunca commitar sem autorização explícita do usuário"
  • "Canvas com Chart.js deve ter animation: false para evitar loop infinito"

Essa última regra, aliás, veio de um bug que me custou horas. A IA gerou um gráfico Chart.js dentro de um <template x-if> do Alpine.js. O canvas era removido e re-adicionado ao DOM, e o Chart.js entrava em loop infinito tentando chamar ctx.save() em contexto nulo. Erro clássico. Depois de resolver, adicionei a regra no AGENTS.md — e a IA nunca mais cometeu esse erro.

Dicas para quem quiser replicar o modelo​

Se você quer usar IA para desenvolver projetos reais, aqui vão algumas dicas baseadas na minha experiência:

  1. Comece com o AGENTS.md antes de qualquer código. Defina arquitetura, padrões e regras. Quanto mais detalhado, melhor.

  2. Trate a IA como um aprendiz, não como um sênior. Ela precisa de instrução explícita. Não presuma que ela "sabe" o que fazer.

  3. Leia cada linha de código gerado. Não importa se são 100 ou 10.000 linhas. Leia tudo. É o único jeito de garantir qualidade.

  4. Documente os erros. Quando a IA erra, não apenas corrija — adicione a regra no AGENTS.md. Isso cria uma memória acumulativa.

  5. Use metodologia clara. Eu usei Extreme Programming (XP) com Pair Programming. Eu era o Navegador, a IA era o Piloto. Sem uma metodologia, você perde o controle.

  6. Não tenha pressa. O projeto levou 4 meses. Não é instantâneo. Mas o resultado é consistente e funcionando.

Conclusão​

O AGENTS.md não é mágica. É um arquivo de texto. Mas ele representa algo poderoso: a capacidade de transferir conhecimento humano para uma IA de forma estruturada e persistente. Cada linha desse arquivo é uma decisão que eu tomei, um erro que eu corrigi, um padrão que eu estabeleci.

O mais interessante é que o arquivo continua crescendo. Cada nova funcionalidade traz novas regras, novos aprendizados. É um documento vivo, que evolui junto com o projeto.

E o mais importante: eu não sou programador Python. Nunca fui. Mas com a IA como Piloto e eu como Navegador, consegui construir um projeto de médio porte que funciona, tem testes, tem segurança, tem documentação e tem uma arquitetura que faz sentido.

A IA não substitui o desenvolvedor. Ela amplifica o que você já sabe. E se você não sabe nada sobre a linguagem, o AGENTS.md é a ponte que conecta o seu conhecimento de domínio ao código que a IA gera.

Referências​