AGENTS.md: Configura le istruzioni del tuo repository
In questa pagina
Lezione aggiornata il 3 novembre 2026 sulla base della pagina Istruzioni personalizzate con AGENTS.md: Codex legge solo i file
AGENTS.mdsituati tra la radice del progetto e la directory di lavoro corrente (più il file globale in~/.codex). Un file in una sottodirectory esterna a questo percorso non viene caricato, contrariamente a quanto implicava la versione precedente. Fonte: AGENTS.md.
Padroneggiare il file di configurazione di Codex
Hai scoperto AGENTS.md nella Lezione 3. Qui approfondiamo gli schemi avanzati: la differenza tra un file decorativo (tre righe scritte all’avvio e dimenticate) e uno che guida effettivamente il comportamento dell’agente su un progetto attivo.
La gerarchia di AGENTS.md
Codex legge questi file in modo gerarchico, dal generale allo specifico: prima il file globale nella tua cartella Codex (~/.codex/AGENTS.md, o AGENTS.override.md se esiste), poi, partendo dalla radice del progetto, i file nelle directory attraversate fino alla directory di lavoro corrente. Su un progetto strutturato, l’albero appare così:
mon-projet/
AGENTS.md → Regole globali (bassa priorità)
src/
AGENTS.md → Regole per tutto il codice sorgente
api/
AGENTS.md → Regole specifiche per le API
routes/
AGENTS.md → Regole per le rotte
components/
AGENTS.md → Regole per i componenti React
tests/
AGENTS.md → Regole per i test
Le regole si accumulano: Codex concatena i file dalla radice fino alla directory corrente; quelli più vicini a tale directory, letti per ultimi, sovrascrivono le istruzioni generali. Un punto viene spesso frainteso: vengono lette solo le directory sul percorso tra la radice e la directory corrente. Se il tuo file radice vieta any mentre tests/AGENTS.md consente asserzioni più lasche nei mock, quella tolleranza si applica solo quando Codex lavora da tests/ o da una delle sue sottodirectory; se lanciato dalla radice, non legge tests/AGENTS.md. Per una regola che deve valere ovunque, posizionala alla radice, anche se devi nominare lì l’eccezione. La revisione del codice su GitHub funziona diversamente: Codex cerca nell’intero repository i file AGENTS.md e applica le regole di revisione (## Code Review Rules) dal file più vicino al codice in questione. La concatenazione si interrompe a 32 KiB per impostazione predefinita (project_doc_max_bytes): un file troppo lungo viene troncato.
Le sezioni che compongono il file
Il contesto viene prima di tutto, perché plasma ogni decisione successiva. Un’applicazione SaaS soggetta al GDPR (General Data Protection Regulation) non si codifica come uno strumento interno per cinque persone:
## 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.
Sapendo che gestisce dati soggetti al GDPR, Codex aggiungerà le protezioni attese senza che tu debba specificarle in ogni richiesta. Seguono le convenzioni, che rispondono a una domanda: come appare qui un codice corretto?
## 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)
La sezione dei comandi è quella più spesso omessa, e la sua assenza ha un costo: senza questi comandi, Codex non può verificare il proprio lavoro e restituisce codice che non ha mai eseguito né testato.
## 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
Le regole strette formano la barriera di sicurezza. Formulate come “MAI” e “SEMPRE”, prevengono errori che costano un’intera serata di lavoro: una migrazione Prisma cancellata che dovrai ricostruire dalla produzione, un segreto committato che necessita di revoca, o un innerHTML infiltrato in un componente che apre una vulnerabilità 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
Infine, l’architettura descrive il flusso consentito tra i livelli. Senza di essa, Codex produce codice che funziona ma scavalca la tua struttura: una rotta che interroga Prisma direttamente, ad esempio, perché era il percorso più breve.
## 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 questo si aggiungono, progetto per progetto, istruzioni specifiche per ciascuna tecnologia utilizzata:
## 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
Due schemi che prevengono le sorprese
Dichiarare le variabili d’ambiente attese impedisce a Codex di inventare nomi di chiavi quando scrive uno script, o di registrare accidentalmente un valore sensibile in un trace di debug:
## 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)
Nominare le librerie preferite, e soprattutto quelle che rifiuti, risolve un fastidio ricorrente: l’agente installa una dipendenza perfettamente valida di per sé, ma che il tuo team ha scartato due anni fa dopo una brutta esperienza.
## 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)
Mantenere il file vivo
AGENTS.md evolve con il tuo codice, proprio come un test o un README. Aggiornalo non appena adotti una nuova convenzione, cambi librerie o framework, e soprattutto non appena identifichi un errore ricorrente di Codex: quest’ultimo caso segnala sempre un’istruzione mancante piuttosto che un fallimento del modello. Vale la pena tenere d’occhio un quarto innesco, più sottile: quando un nuovo sviluppatore pone una domanda a cui AGENTS.md avrebbe dovuto rispondere, quella risposta appartiene al file.
Punti chiave
- La gerarchia di
AGENTS.mdconsente istruzioni sempre più specifiche - I comandi sono critici affinché Codex verifichi il proprio lavoro
- Le regole MAI sono le più importanti per evitare errori
- Documenta le dipendenze preferite per prevenire scelte sbagliate
- Mantieni
AGENTS.mdcome codice vivente