📄 O que é AGENTS.md
AGENTS.md é um arquivo de markdown na raiz do projeto que Codex, Cursor, Claude e outros agentes leem automaticamente antes de cada sessão. É o system prompt do projeto. Vive no repositório, é versionado, é compartilhado.
🔄 Como o agente carrega AGENTS.md
📌 Por que isso importa
O agente não tem memória entre sessões por padrão. Toda vez que você abre uma conversa nova, ele esquece tudo que sabia. AGENTS.md inverte isso: o conhecimento sobre o projeto vive no repo, não na cabeça da sessão. Resultado: você muda de agente, troca de modelo, abre nova janela — e o projeto continua coerente.
🏗️ Estrutura Mínima Viável
Cinco seções obrigatórias. Mais que isso vira ruído. Menos que isso vira improviso. Padronizar essas cinco evita 80% dos erros de agente em projeto.
# Objetivo
InboxAI: triagem automatica de email com IA para PMEs.
# Stack
- Next.js 15 + React 19 + TypeScript strict
- Convex (banco e funcoes)
- Tailwind CSS + shadcn/ui
- Bun como runtime e package manager
# Comandos
- `bun dev` -> sobe app em localhost:3000
- `bun test` -> roda testes (Vitest)
- `bun lint` -> ESLint + tsc --noEmit
- `bun build` -> build de producao
# Regras de Codigo
- TypeScript strict, sem `any` implicito
- Conventional commits (feat:, fix:, chore:)
- Componentes funcionais, hooks, sem class components
- Sem comentarios obvios; codigo se explica
# Definition of Done
- `bun lint` passa sem warning
- `bun test` verde
- Smoke test no Chrome desktop + mobile
- PR com Summary + Test plan💡 A regra do tamanho
AGENTS.md ideal cabe em uma tela (~80 linhas). Se passar de 200 linhas, divida por subpasta. Se passar de 500, vira folclore que ninguém lê. Concisão é parte do contrato — o agente lê isso a cada sessão.
🌳 Hierarquia: Global vs Subpasta
AGENTS.md na raiz vale para o projeto inteiro. AGENTS.md em subpasta override regras só naquela área. Codex combina os dois automaticamente — você nunca precisa repetir o que já está na raiz.
📁 Layout em monorepo InboxAI
🌍 AGENTS.md raiz
Tudo que vale em qualquer área:
- • Stack geral do projeto
- • Conventional commits
- • TypeScript strict
- • Definition of Done global
- • Quem é o cliente / o produto
📂 AGENTS.md subpasta
Só o que é específico daquela área:
- • Padrões de componente
- • Estrutura de queries do banco
- • Bibliotecas restritas àquela área
- • Comandos extras (storybook, docker)
- • Convenções de pasta
⚠️ Não duplique
A pior armadilha é repetir regras do raiz dentro do subpasta. Quando muda na raiz, fica desincronizado. Subpasta só fala o que é diferente — herança implícita resolve o resto.
📋 Anatomia de um Exemplar (InboxAI Real)
Walkthrough comentado do AGENTS.md real do projeto InboxAI da Trilha 4. Cada linha tem justificativa. Copie o padrão, adapte para seus projetos.
# InboxAI
## Objetivo
SaaS de triagem de email para PMEs brasileiras. # o quê e pra quem em uma frase
Cliente paga R$ 197/mes. Meta MRR: R$ 50k em 6 meses. # contexto comercial — o agente prioriza certo
## Stack
- Next.js 15 (App Router) + React 19 # versao explicita evita codigo legado
- Convex 1.20 (banco + functions) # nada de Prisma/Drizzle aqui
- Tailwind 4 + shadcn/ui # sem CSS Modules, sem styled-components
- Bun 1.2 (runtime) # nunca npm/yarn — agente as vezes esquece
## Comandos
- `bun dev` (porta 3000) # comando canonico, sem improvisar
- `bun test` (Vitest)
- `bun lint` (eslint + tsc)
- `bunx convex dev` (banco em paralelo) # lembrete que precisa de dois terminais
## Regras de Codigo
- TS strict; nada de `any` implicito # corta um vicio comum
- Componentes em `components/` (kebab-case) # convencao de pasta explicita
- Hooks em `hooks/use-*.ts` # prefixo obrigatorio
- Sem comentario obvio (`// somar 2 + 2`) # corta poluicao gerada por IA
## Definition of Done
- Build limpo (`bun build`)
- Lint zero warning
- Smoke test Chrome 1440px + iPhone 14
- Screenshot antes/depois no PR # prova visual de mudanca
## Nao Faca
- Adicionar libs sem aprovar comigo # controle de bundle size
- Usar `console.log` (use logger) # observabilidade real
- Commitar `.env*` # proibir explicitamente💡 Padrão "Não Faça"
A seção Não Faça é tão importante quanto a Stack. Agentes têm vícios — instalar libs aleatórias, deixar console.log, criar arquivo na raiz. Listar explicitamente o que não fazer economiza horas de revisão.
⚠️ Erros Comuns
Três vícios silenciosos. Cada um corrói a utilidade do AGENTS.md sem você perceber. Reconhecer evita que vire ruído ignorado.
❌ Errado
# Regras
- Seja util e gentil com o usuario
- Escreva codigo limpo e bonito
- Tente nao quebrar nada
- Use as melhores praticas
- Evite codigo ruimGenérico, vazio, intratável. O agente não consegue verificar nenhuma dessas regras.
✅ Certo
# Regras
- TS strict; sem `any` implicito
- Componentes em `kebab-case`
- Hooks em `hooks/use-*.ts`
- Conventional commits obrigatorio
- `bun lint` zero warning antes de PREspecífico, verificável, com nomes de arquivo e comandos exatos.
| Vício | Sintoma | Cura |
|---|---|---|
| Genérico | "Seja útil", "escreva bem" | Trocar por regra verificável com comando ou nome de arquivo. |
| Datado | Versão antiga, comando que não roda | Revisão semanal. Quando troca stack, atualiza no mesmo PR. |
| Longo | Mais de 200 linhas no raiz | Quebrar por subpasta. Manter raiz só com o universal. |
📌 Teste de utilidade
Pergunte a um colega que nunca viu o projeto: "leu o AGENTS.md, o que você não pode fazer aqui?". Se ele não consegue listar 3 coisas concretas, seu AGENTS.md está vago. Reescreva.
🌱 Living Document: Revisar a Cada Sprint
AGENTS.md não é setup once and forget. Ao notar padrão repetido, vira regra. Ao virar ruído, sai. A cada sprint, revisar e podar mantém o sinal alto.
🔁 Ciclo de Vida do AGENTS.md
💡 A regra dos 3 strikes
Toda vez que você re-explica a mesma coisa pro agente — anota mentalmente. Na terceira vez, vira linha em AGENTS.md. Antes disso, é desperdício de espaço. Depois disso, é desperdício do seu tempo.
✅ O que Aprendemos
Próximo Módulo:
2.2 — Skills: pacote de instrução durável + recursos. Como instalar da loja, como invocar manual ou automaticamente, e as 5 skills proprietárias do Master Codex.