AGENTS.md: Configure as Instruções do Seu Repositório
Nesta página
Lição atualizada a 3 de novembro de 2026 com base na página Custom instructions with AGENTS.md: o Codex apenas lê ficheiros
AGENTS.mdlocalizados entre a raiz do projeto e o diretório de trabalho atual (além do ficheiro global em~/.codex). Um ficheiro num subdiretório fora deste caminho não é carregado, ao contrário do que a versão anterior implicava. Fonte: AGENTS.md.
Dominar o Ficheiro de Configuração do Codex
Já descobriu o AGENTS.md na Lição 3. Aqui, vamos mergulhar em padrões avançados — a diferença entre um ficheiro decorativo (três linhas escritas no arranque e esquecidas) e um que realmente orienta o comportamento do agente num projeto ativo.
A Hierarquia do AGENTS.md
O Codex lê estes ficheiros hierarquicamente, do geral para o específico: primeiro o ficheiro global na sua pasta Codex (~/.codex/AGENTS.md, ou AGENTS.override.md se existir) e, em seguida, a partir da raiz do projeto, os ficheiros nos diretórios percorridos até ao diretório de trabalho atual. Num projeto estruturado, a árvore parece isto:
mon-projet/
AGENTS.md → Regras globais (baixa prioridade)
src/
AGENTS.md → Regras para todo o código fonte
api/
AGENTS.md → Regras específicas para APIs
routes/
AGENTS.md → Regras para rotas
components/
AGENTS.md → Regras para componentes React
tests/
AGENTS.md → Regras para testes
As regras acumulam-se: o Codex concatena os ficheiros da raiz até ao diretório atual, sendo que os mais próximos desse diretório, lidos por último, substituem as instruções gerais. Um ponto é facilmente mal compreendido: apenas os diretórios no caminho entre a raiz e o diretório atual são lidos. Se o seu ficheiro de raiz proibir any enquanto tests/AGENTS.md permitir asserções mais flexíveis em mocks, essa tolerância aplica-se apenas quando o Codex está a trabalhar a partir de tests/ ou de um dos seus subdiretórios; se lançado a partir da raiz, não lê tests/AGENTS.md. Para uma regra que deve aplicar-se em toda a parte, coloque-a na raiz, mesmo que tenha de nomear lá a exceção. A revisão de código do GitHub funciona de forma diferente: o Codex pesquisa todo o repositório por ficheiros AGENTS.md e aplica as regras de revisão (## Code Review Rules) do ficheiro mais próximo do código em questão. A concatenação para nos 32 KiB por padrão (project_doc_max_bytes): um ficheiro demasiado longo é truncado.
As Secções que Compõem o Ficheiro
O contexto vem em primeiro lugar, pois molda todas as decisões subsequentes. Uma aplicação SaaS sujeita ao RGPD (Regulamento Geral sobre a Proteção de Dados) não é codificada da mesma forma que uma ferramenta interna para cinco pessoas:
## Context
SaaS invoice management application for French SMEs.
GDPR compliance mandatory. Data hosted in France (OVH).
Stack: Astro 6, React, Strict TypeScript, Prisma, PostgreSQL.
Authentication: Better Auth with server sessions.
Sabendo que lida com dados sujeitos ao RGPD, o Codex adicionará as proteções esperadas sem que tenha de as especificar em cada pedido. Seguem-se as convenções, que respondem a uma pergunta: como é o código correto aqui?
## Conventions
- Strict TypeScript (no any, no implicit any)
- Functional React components only
- Naming: kebab-case files, PascalCase components,
camelCase variables
- Imports: @/ for path aliases
- Validation: Zod for all user inputs
- Errors: custom error classes in src/lib/errors.ts
- Logging: use src/lib/logger.ts (no console.log)
A secção de comandos é a mais frequentemente omitida, e a sua ausência tem um custo: sem estes comandos, o Codex não consegue verificar o seu próprio trabalho e devolve código que nunca executou ou testou.
## Commands
- `npm run dev` — Development server (port 4321)
- `npm run build` — Production build
- `npm run test` — Vitest tests
- `npm run test:e2e` — Playwright tests
- `npm run lint` — ESLint + Prettier
- `npm run db:migrate` — Prisma migrations
- `npm run db:seed` — Database seed
As regras estritas formam a guarda-rail. Formuladas como “NUNCA” e “SEMPRE”, previnem erros que custam uma noite inteira a corrigir: uma migração Prisma apagada que terá de reconstruir a partir da produção, um segredo commitado que precisa de ser revogado, ou um innerHTML introduzido num componente que abre uma vulnerabilidade XSS.
## Strict Rules (NEVER break these)
- NEVER modify the Prisma schema without creating a migration
- NEVER store secrets in code (use .env)
- NEVER use innerHTML (XSS risk)
- NEVER delete an existing Prisma migration
- NEVER expose internal IDs in public URLs
- ALWAYS validate user inputs with Zod
- ALWAYS use Prisma transactions for multi-table operations
Finalmente, a arquitetura descreve o fluxo permitido entre camadas. Sem ela, o Codex produz código que funciona, mas contorna a sua estrutura — uma rota que consulta o Prisma diretamente, por exemplo, porque era o caminho mais curto.
## Architecture
Layers:
1. Routes (src/pages/) → receive requests
2. Services (src/services/) → business logic
3. Repositories (src/repositories/) → data access
Rule: Routes MUST NOT access Prisma directly.
Everything goes through a service, which goes through a repository.
A isto somam-se, projeto a projeto, instruções específicas para cada tecnologia utilizada:
## React
- Prefer Server Components by default
- Client Components only when necessary (interactivity)
- No useEffect for data fetching (use Server Actions)
- Local state with useState, global state with Zustand
## Prisma
- Relations: always include required fields explicitly
- Pagination: use cursor-based, not offset-based
- Soft delete: use deletedAt instead of DELETE
Dois Padrões que Previnem Surpresas
Declarar as variáveis de ambiente esperadas impede que o Codex invente nomes de chaves ao escrever um script, ou que registe acidentalmente um valor sensível num rasto de depuração:
## Required Environment Variables
- DATABASE_URL — PostgreSQL connection URL
- AUTH_SECRET — Secret for Better Auth (min 32 chars)
- SMTP_HOST — SMTP server for emails
- STRIPE_SECRET_KEY — Stripe API key (never log)
Nomear as suas bibliotecas preferidas e, especialmente, aquelas que recusa, resolve uma inconveniência recorrente: o agente instala uma dependência que é perfeitamente válida em si mesma, mas que a sua equipa rejeitou há dois anos após uma má experiência.
## Dependencies
If you need:
- Validation → Zod (NOT Joi, NOT Yup)
- Dates → date-fns (NOT moment, NOT dayjs)
- HTTP client → ofetch (NOT axios)
- Tests → Vitest (NOT Jest)
- E2E → Playwright (NOT Cypress)
Manter o Ficheiro Vivo
O AGENTS.md evolui com o seu código, tal como um teste ou um README. Atualize-o assim que adotar uma nova convenção, mudar de bibliotecas ou frameworks e, especialmente, assim que identificar um erro recorrente do Codex: esse último caso sinaliza sempre uma instrução em falta e não uma falha do modelo. Um quarto gatilho, mais subtil, vale a pena observar — quando um novo programador faz uma pergunta que o AGENTS.md deveria ter respondido, essa resposta pertence ao ficheiro.
Pontos-chave
- A hierarquia do
AGENTS.mdpermite instruções cada vez mais específicas - Os comandos são críticos para que o Codex verifique o seu trabalho
- As regras NUNCA são as mais importantes para evitar erros
- Documente as dependências preferidas para evitar más escolhas
- Mantenha o
AGENTS.mdcomo código vivo