Como Criar um Agents.md Perfeito: Template

O que e agents.md e por que voce precisa de um

Agents.md e basicamente um manual de instrucoes pro seu agente de IA. Pensa assim: quando voce contrata alguem novo no time, voce nao joga a pessoa no codigo sem explicar nada, certo? Com agente de IA e a mesma logica. Sem contexto, ele vai gerar codigo que ate funciona, mas nao segue os padroes do seu projeto.

O arquivo fica na raiz do repositorio e e lido automaticamente por ferramentas como Claude Code, Codex CLI e Gemini CLI. Cursor usa o .cursorrules mas da pra adaptar. A ideia e a mesma: dar pro agente as informacoes que ele precisa pra parar de inventar e comecar a respeitar a arquitetura do projeto.

Na pratica, um bom agents.md resolve tres problemas de uma vez: reduz alucinacao de dependencias (o agente para de sugerir bibliotecas que voce nao usa), forca convencoes de codigo (naming, estrutura de pastas, patterns) e documenta decisoes arquiteturais que nao estao obvias no codigo.

Da pra comecar com 20 linhas e ir evoluindo. Nao precisa ser perfeito de cara. O importante e ter alguma coisa la — qualquer contexto e melhor que zero contexto.

Template comentado linha a linha

Esse template funciona pra maioria dos projetos web. Copie, remova os comentarios e adapte pro seu caso. Cada secao tem um proposito claro.

# Agents.md

## Projeto
<!-- Nome e descricao em uma frase -->
App de agendamento para barbearias. Next.js 15 + Convex + Tailwind.

## Stack
<!-- Liste TUDO que o projeto usa. Seja especifico com versoes. -->
- Next.js 15.1 (App Router)
- React 19
- TypeScript 5.7 (strict mode)
- Convex (backend + banco de dados)
- Tailwind CSS 4
- Shadcn/ui (componentes)
- Zod (validacao)
- Vitest + Playwright (testes)

## Estrutura de Pastas
<!-- O agente precisa saber onde colocar cada coisa -->
src/
  app/           # rotas Next.js (App Router)
  components/    # componentes reutilizaveis
  lib/           # helpers e utilitarios
  convex/        # schema, funcoes e mutations
  data/          # JSONs estaticos

## Convencoes
<!-- Regras que o agente DEVE seguir -->
- Componentes: PascalCase, um por arquivo
- Hooks customizados: prefixo use, arquivo separado em lib/
- Nunca usar any no TypeScript
- CSS: so Tailwind, nunca CSS inline ou modules
- Imports: absolutos com @/ (alias configurado)

## Padroes de Codigo
<!-- Exemplos concretos valem mais que regras abstratas -->
- Server Components por padrao, 'use client' so quando necessario
- Validacao com Zod em todas as mutations do Convex
- Error boundaries em cada rota
- Loading states com Suspense

## O que NAO fazer
<!-- Tao importante quanto o que fazer -->
- Nao instalar dependencias sem perguntar
- Nao usar CSS-in-JS (styled-components, emotion)
- Nao criar arquivos fora da estrutura definida
- Nao usar console.log em producao

Perceba que o template tem secoes negativas — o 'O que NAO fazer'. Isso e tao importante quanto as regras positivas. Agentes de IA adoram sugerir bibliotecas populares mesmo quando voce ja tem solucao no projeto. A secao negativa corta isso na raiz.

Outro detalhe: versoes especificas. Nao escreva so 'Next.js' — escreva 'Next.js 15.1'. A diferenca entre Next 14 e 15 e gigante em termos de API. Se o agente nao sabe a versao, ele pode gerar codigo de versao antiga que nao compila.

5 exemplos reais por tipo de projeto

Template generico e bom pra comecar, mas cada tipo de projeto tem suas particularidades. Aqui vao 5 exemplos que cobrem os cenarios mais comuns.

1. Projeto Next.js com App Router

# Agents.md — SaaS Next.js

## Stack: Next.js 16 + React 19 + Convex + Tailwind 4
## Auth: Convex Auth (nao usar NextAuth)
## Deploy: Vercel (edge functions habilitadas)

## Regras
- App Router only, nunca Pages Router
- Cache Components com 'use cache' + cacheLife
- generateStaticParams obrigatorio em rotas dinamicas
- Imagens: next/image com width/height explicitos
- Fonts: next/font/google, nunca link externo

2. Monorepo com Turborepo

# Agents.md — Monorepo

## Estrutura
apps/web       # Next.js frontend
apps/api       # Fastify backend
packages/ui    # componentes compartilhados
packages/utils # helpers puros
packages/db    # Drizzle ORM + migrations

## Regras
- Imports entre packages: so via alias @repo/
- Nunca importar direto de apps/ em packages/
- Testes ficam co-locados: arquivo.test.ts ao lado
- CI roda turbo run build --filter=[HEAD^1]

3. API Python com FastAPI

# Agents.md — API Python

## Stack: Python 3.12 + FastAPI + SQLAlchemy + Alembic
## Ambiente: Poetry (nao usar pip direto)
## Linter: Ruff (nao usar black ou flake8)

## Convencoes
- Type hints obrigatorios em todas as funcoes
- Pydantic models pra request/response
- Async by default, sync so com justificativa
- Tests com pytest + httpx AsyncClient
- Migrations nomeadas: YYYYMMDD_descricao.py

4. App React Native com Expo

# Agents.md — Mobile Expo

## Stack: Expo SDK 52 + React Native + TypeScript
## Navegacao: Expo Router (file-based)
## Estado: Zustand (nao usar Redux)
## UI: NativeWind (Tailwind pra RN)

## Regras
- Nao usar StyleSheet.create, so NativeWind
- Expo modules pra acesso nativo
- Deep links configurados em app.json
- Testes: Jest + React Native Testing Library

5. CLI Tool em TypeScript

# Agents.md — CLI TypeScript

## Stack: Node.js 22 + TypeScript + Commander.js
## Build: tsup (bundler)
## Package manager: pnpm

## Convencoes
- Cada comando em arquivo separado: src/commands/
- Output formatado com chalk
- Spinners com ora pra operacoes longas
- Testes com Vitest + mock do filesystem
- Bin entry point: dist/index.js

Esses exemplos sao pontos de partida. O segredo e ir adicionando regras conforme voce percebe padroes de erro do agente. Gerou import errado? Adicione regra de import. Sugeriu lib que nao usa? Adicione na lista de proibidos. O agents.md e um documento vivo.

Como testar se seu agents.md esta funcionando

Criar o arquivo e so metade do trabalho. Voce precisa validar que ele esta sendo lido e que as regras estao sendo seguidas. Da pra fazer isso de forma sistematica.

Faca esses testes toda vez que atualizar o agents.md. E rapido — 5 minutos no maximo. E o retorno e alto: cada regra bem escrita economiza horas de correcao manual ao longo da semana.

Uma dica que pouca gente fala: peca pro proprio agente revisar seu agents.md. Literalmente cole o arquivo e pergunte 'o que esta faltando aqui pra voce gerar codigo melhor neste projeto?'. A resposta costuma ser surpreendentemente util.

Erros comuns que destroem a utilidade do arquivo

Ja vi muito agents.md que existe mas nao ajuda em nada. Geralmente e por um desses motivos:

O erro mais comum de todos? Criar o arquivo uma vez e nunca mais mexer. Agents.md precisa evoluir junto com o projeto. Mudou de versao do framework? Atualiza. Adicionou nova lib? Atualiza. Percebeu padrao de erro do agente? Adiciona regra.

Trata o arquivo como parte do onboarding do projeto. Se um dev humano novo precisaria saber, o agente tambem precisa.

Compatibilidade entre ferramentas

Cada ferramenta de AI coding le um arquivo diferente por padrao. Mas da pra fazer um so servir pra todas com alguns ajustes.

A estrategia mais pratica? Mantenha o conteudo principal em um unico arquivo (agents.md ou CLAUDE.md) e gere os outros automaticamente. Da pra fazer um script simples que copia o conteudo e ajusta o formato. Assim voce nao duplica informacao e todas as ferramentas ficam sincronizadas.