Vai al contenuto principale
Italiano— Scegli una lingua
Menu

AGENTS.md: Configura le istruzioni del tuo repository

Lezione 15 di 20 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Padroneggiare il file di configurazione di Codex
  2. La gerarchia di AGENTS.md
  3. Le sezioni che compongono il file
  4. Due schemi che prevengono le sorprese
  5. Mantenere il file vivo
  6. Punti chiave

Lezione aggiornata il 3 novembre 2026 sulla base della pagina Istruzioni personalizzate con AGENTS.md: Codex legge solo i file AGENTS.md situati 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.md consente 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.md come codice vivente