AGENTS.MD: O Arquivo que Fará a sua IA Parar de Errar ao Programar

O problema que todos temos (e ninguém comenta)

Com certeza já aconteceu com você: você está programando, pede ajuda à sua IA favorita e… ela solta um código que parece escrito por alguém que não conhece o seu projeto. Comentários por todo lado quando você não os quer, um naming de métodos estranho, dependências obsoletas que não são usadas desde 2019, e um monte de coisinhas que te fazem pensar “isso eu tenho que consertar, né?”.

E claro, cada vez que você pede algo novo, volta tudo ao começo: “ei, sem comentários”, “usa camelCase”, “prefiro usar esta biblioteca em vez daquela outra”. É cansativo.

Pois bem amigos, isso acabou. Hoje trago para vocês AGENTS.MD, um simples arquivo que vai revolucionar a sua forma de programar com IA.

Por que você precisa do AGENTS.MD na sua vida

Apoiar-se na inteligência artificial para programar já não é ficção científica, é uma realidade. Mas se vamos fazê-lo, vamos fazê-lo bem. Não basta perguntar coisinhas a um chat ou usar o seu editor com IA e cruzar os dedos.

Para sermos realmente eficientes precisamos aplicar as novas metodologias que vão surgindo (e sim, eu sei que em programação tudo muda a cada dois dias, mas para isso estou eu, para trazer o que é importante).

Em posts anteriores falei sobre MCPs e como espremer o Cursor ao máximo. Mas o que trago hoje é melhor que truques de um editor específico. Para mim, isto é algo básico que vai se tornar o padrão da indústria.

PS: Antes de continuar, se você vê estes posts e não está inscrito… o que está fazendo da sua vida? Aperte o botão que não custa nada e a mim me faz muito feliz 😊

O que raios é AGENTS.MD?

A premissa é simplicíssima: AGENTS.MD é como um README mas para inteligências artificiais. Basicamente, é um arquivo onde você define as instruções do seu projeto para que a IA saiba exatamente o que fazer.

Neste arquivo você pode especificar:

Como deve iniciar o projeto
Como rodar os testes
Quais dependências usar (e quais NÃO usar)
O seu estilo de programação preferido
Convenções de naming
Política de comentários
Estrutura de pastas

É como uma bíblia para a IA. Uma vez que ela lê, você já não tem que repetir as mesmas indicações uma e outra vez.

”Mas se isto já existe…”

Ok, é verdade. Muitos editores têm as suas próprias regras:

Cursor chama de “rules”
Jules (o assistente da JetBrains) tem “guidelines”
Warp usa warp.md para regras de projeto

A diferença é que AGENTS.MD não te casa com nenhum editor. É uma convenção “internacional” que qualquer agente pode ler.

Quem suporta AGENTS.MD?

A lista cresce a cada dia, mas por enquanto suportam:

Codex
Cursor
Visual Studio Code
Warp (um terminal com IA que eu recomendo)
Gemini CLI
Devin
E muitos mais…

Provavelmente quando você estiver lendo isto, a lista será ainda maior.

A vantagem frente às regras clássicas

Aqui está a chave: hoje você pode estar usando Cursor, mas amanhã talvez seja melhor Gemini CLI, ou Codex, ou o que quer que saia na semana que vem. Com AGENTS.MD você não tem que mudar nada, o novo editor detectará automaticamente as suas regras.

E isto é importante. Vocês já sabem que não gosto de depender sempre da mesma ferramenta porque as coisas mudam muito rápido neste mundinho.

Como funciona?

Nada de outro mundo. É um arquivo de texto livre onde você indica os requisitos que quer para o seu projeto. Não há formato específico, não há mínimo nem máximo. Simplesmente coloque o que achar que é útil.

Existem mais de 20.000 exemplos na internet dependendo do seu projeto, linguagem e tecnologias, mas meu conselho é que você mesmo o crie com as coisas que realmente precisa para o seu caso específico.

Um exemplo que vai te deixar de boca aberta

Para que vocês vejam a diferença, fiz um teste rápido. Pedi à IA que me criasse uma API com Python. Sem AGENTS.MD ela gerou isto:

# API básica sem estrutura
from flask import Flask

app = Flask(__name__)

@app.route('/api/data')
def get_data():
    # Comentários desnecessários
    return {"data": "example"}

Agora, criei um AGENTS.MD especificando:

A estrutura que quero
Que todas as chamadas tenham autenticação
O naming específico dos métodos
Sem comentários óbvios

Com o mesmo prompt, a diferença foi brutal. Gerou uma API completamente estruturada, com autenticação JWT, seguindo as minhas convenções e sem um único comentário desnecessário.

A importância das instruções, amigos.

Estrutura recomendada (mas não obrigatória)

Embora não haja uma estrutura obrigatória, aqui deixo um exemplo que vocês podem adaptar:

# AGENTS.md

## Project Context
- Language/runtime: Python 3.11 / Node 20
- How to run locally: `npm run dev` ou `python main.py`
- How to run tests: `npm test` ou `pytest`

## Code Style
- Naming: camelCase para variáveis, PascalCase para classes
- NO comments óbvios, apenas documentação necessária
- Formatação: Prettier/Black segundo a linguagem
- Preferir composição sobre herança
- Usar async/await quando possível

## Dependencies
- Allowed: fastapi, pydantic, sqlalchemy (últimas versões)
- AVOID: Flask (legacy), requests (usar httpx)

## Testing & Quality
- Framework: pytest com coverage mínimo 80%
- Testes unitários obrigatórios para lógica de negócio
- Lint com ruff/eslint antes de commit

## API & Security
- Auth requerido por padrão (JWT)
- Error responses: JSON padrão com status codes apropriados
- Logging: structured logging com contexto

## Git & CI
- Conventional Commits obrigatório
- CI deve passar testes e lint antes de merge
- Não commits diretos na main

IMPORTANTE: Não coloquem keys nem segredos aqui dentro, por favor. É senso comum mas nunca é demais lembrar.

O futuro é agora

Se vocês são tão preguiçosos quanto eu (que vocês são, não nos enganemos) e não querem perder tempo explicando a mesma coisa à IA toda vez, esta é a solução.

Assim como aconteceu com os MCPs, isto provavelmente se tornará um padrão da indústria. Os que nos adaptarmos cedo teremos vantagem.

Conclusão

AGENTS.MD não é mágica, é simplesmente organização e inteligência. É aproveitar a tecnologia de forma correta para não fazer o mesmo trabalho duas vezes.

Implementem nos seus projetos, adaptem às suas necessidades e, acima de tudo, compartilhem a sua experiência. Se vocês gostaram do post, deixem nos comentários e me digam que outros temas querem que eu cubra.

E lembrem-se: no mundo da programação ou você se adapta ou fica para trás. Melhor se adaptar, né?

Nos vemos no próximo post 👋

O que você achou?

Deixe sua opinião, pergunta ou sugestão. Os comentários são sincronizados com GitHub Discussions .