Guida

Cosa mettere in AGENTS.md e CLAUDE.md?

Cosa mettere in AGENTS.md e CLAUDE.md secondo i benchmark sugli agenti: comandi utili, vincoli operativi, trappole costose e cosa lasciare fuori.

Un file di istruzioni del repository può facilmente diventare un README compresso, un saggio sull’architettura e un elenco di ammirevoli principi di ingegneria. L’agente riceve poi tutto quel materiale a ogni attività, anche quando gran parte è irrilevante.

I risultati recenti dei benchmark suggeriscono per questi file un compito più ristretto. Usa AGENTS.md e CLAUDE.md come brevi manuali operativi: comandi esatti, operazioni costose, passaggi di verifica, confini e fatti difficili da dedurre dal codice. Non aspettarti che una descrizione più lunga del progetto fornisca un giudizio ingegneristico che il modello non ha già.

Risposta rapida

Metti un fatto nel file di istruzioni principale quando valgono tutte e tre queste condizioni:

  1. Si applica alla maggior parte del lavoro in quell’ambito.
  2. L’agente non può scoprirlo dal repository in modo rapido e affidabile.
  3. Seguirlo cambia un’azione o un controllo osservabile.

Buoni esempi sono:

  • pnpm test --filter api è il comando di test rapido per le modifiche all’API.
  • La suite di integrazione completa richiede 25 minuti e va eseguita una volta sola, dopo che i test mirati sono passati.
  • I file sotto generated/ vanno modificati tramite pnpm generate.
  • Aggiungere una dipendenza di produzione o modificare una migrazione del database richiede una conferma.
  • Una modifica non è completa finché il controllo dei tipi e il test mirato pertinente non passano.

Lascia fuori affermazioni generiche come «scrivi codice pulito», elenchi di pacchetti copiati e descrizioni che l’agente può ottenere leggendo il manifest e l’albero dei sorgenti. Usa il prompt dell’attività per i requisiti una tantum, una skill per una procedura su richiesta e test, hook o CI per le regole che vanno fatte rispettare in modo meccanico.

AGENTS.md e CLAUDE.md sono simili, ma non identici

Entrambi i file forniscono istruzioni persistenti per il repository, ma le regole su come vengono trovati e su quale ambito coprono dipendono dall’agente che li legge.

AGENTS.md di Codex CLAUDE.md di Claude Code
File principale del progetto AGENTS.md CLAUDE.md o .claude/CLAUDE.md
Impostazioni personali ~/.codex/AGENTS.md ~/.claude/CLAUDE.md
Indicazioni più specifiche AGENTS.md annidato o AGENTS.override.md CLAUDE.md annidato o .claude/rules/ limitato a percorsi specifici
Come si combinano i file Catena dalla radice alla directory di lavoro; i file più vicini si applicano dopo I file nelle directory superiori si caricano all’avvio; quelli annidati quando Claude lavora in quel sottoalbero
Indicazioni attuali sulla dimensione Limite predefinito di 32 KiB per la ricerca combinata Anthropic consiglia meno di 200 righe per file

Codex costruisce la sua catena di istruzioni una volta per ogni esecuzione o sessione TUI avviata. Controlla le indicazioni globali, poi percorre le directory dalla radice del progetto fino alla directory di lavoro corrente. Un file più vicino compare più avanti nel prompt combinato e quindi prevale sulle indicazioni più generali. L’ordine esatto di ricerca e il comportamento di override sono descritti nella documentazione di Codex su AGENTS.md.

Claude Code tratta CLAUDE.md come contesto, non come una configurazione imposta. La sua documentazione consiglia istruzioni specifiche e concise e spiega che file grandi o contraddittori ne riducono il rispetto. Vedi How Claude remembers your project.

Se un team usa entrambi gli agenti, tieni le istruzioni condivise in AGENTS.md e importale da un piccolo CLAUDE.md:

@AGENTS.md

## Claude Code only

- Use the path-scoped rule in `.claude/rules/frontend.md` for UI changes.

Anthropic documenta esplicitamente questo schema di importazione. Anche un link simbolico può funzionare, ma l’importazione lascia spazio a una piccola quantità di indicazioni specifiche per Claude ed è più portabile su Windows.

Cosa ha verificato l’ultimo studio su due agenti

Il preprint di luglio 2026 Do Context Files Help Coding Agents? ha trasformato pull request già integrate di tre repository Python (PDM, firebase-admin-python e opshin) in 17 attività di coding. La descrizione della PR faceva da prompt, mentre i test introdotti dalla PR reale restavano nascosti e servivano a giudicare l’implementazione dell’agente.

Claude Code e Codex hanno lavorato ciascuno in tre condizioni:

  • nessuno: nessun file di contesto del repository;
  • sempre attivo: l’intero AGENTS.md veniva inserito in ogni turno;
  • selettivo: l’agente riceveva un suggerimento e poteva leggere, quando serviva, file wiki organizzati per argomento.

Dopo tre ripetizioni, 288 esecuzioni avevano risultati di correttezza validi:

Strategia Claude Code Codex
Nessun contesto 53,3% 58,8%
Sempre attivo 55,6% 56,9%
Selettivo 55,6% 52,9%

Le differenze non erano statisticamente significative. Nella revisione manuale degli autori, i casi mancati di poco fallivano per la progettazione della funzionalità, la scelta del pattern o collegamenti errati tra i componenti, non per la mancanza di un fatto sul repository contenuto nel vero AGENTS.md. Aggiungere o riorganizzare quel contesto non ha trasformato quei fallimenti in successi.

Questo risultato non dimostra che i file di istruzioni non migliorino mai la correttezza. Il campione comprende solo tre repository Python e 15–17 attività per agente. L’analisi della potenza statistica dell’articolo stima che per rilevare un effetto di 10 punti percentuali servirebbero circa 120–200 attività. Lo studio ha inoltre testato un’iniezione più forte e artificiale, anziché lasciare semplicemente un file nella sua posizione naturale nel workspace: Claude lo riceveva aggiunto in coda al prompt di sistema, mentre per Codex il testo veniva anteposto al prompt dell’utente.

La condizione selettiva ha un ulteriore limite. La sua wiki corrispondeva all’AGENTS.md originale solo per opshin; gli altri due repository hanno ricevuto wiki generate più ampie, lunghe circa 10 e 18 volte tanto. Il recupero selettivo, quindi, non è un confronto pulito dello stesso contenuto fornito in modo diverso.

Il risultato utile era operativo

L’AGENTS.md di opshin dice che la suite di test completa richiede più di 20 minuti. Senza quell’avvertimento, Claude ha eseguito l’intera suite in media 3,67 volte per cella. Con il contesto sempre attivo l’ha eseguita 2,44 volte; con il contesto selettivo, 1,67. Il tempo medio di esecuzione è sceso da 2689 secondi a 2066 e 2032 secondi, una riduzione di circa il 24%, senza un corrispondente miglioramento della correttezza.

È una buona evidenza a favore di un tipo concreto di istruzione: dire all’agente quanto costa un’azione e dargli una strada corretta più economica. Non è una prova generale di esecuzione più rapida. L’analisi era esplorativa, riguardava Claude su un solo repository e, con cinque attività, aveva una potenza statistica insufficiente. La durata per Codex è rimasta invariata, e un altro repository si è mosso leggermente nella direzione opposta.

La conclusione prudente è:

Un file di istruzioni del repository può migliorare il modo in cui un agente lavora anche quando non migliora ciò che l’agente riesce a risolvere.

Le evidenze più ampie sono contrastanti

Due studi precedenti del 2026 sono arrivati a risultati diversi sull’efficienza:

  • On the Impact of AGENTS.md Files ha esaminato 10 repository e 124 pull request. La presenza di AGENTS.md era associata a un tempo di esecuzione mediano inferiore del 28,64% e al 16,58% di token di output in meno, con un comportamento di completamento paragonabile.
  • Evaluating AGENTS.md ha testato file generati e file scritti dagli sviluppatori su diversi agenti e modelli. Non ha rilevato un miglioramento generale nel successo delle attività e ha misurato in media un costo di inferenza superiore di oltre il 20%, anche se gli agenti seguivano effettivamente le istruzioni non standard.

Il nuovo studio su due agenti suggerisce che meccanismi di iniezione diversi e una difficoltà delle attività che varia da agente ad agente potrebbero spiegare la contraddizione. È un’ipotesi, non una riconciliazione definitiva. Alla luce dei tre articoli, la pratica più difendibile è valutare un file in base al comportamento che cambia, invece di dare per scontato che più contesto sia meglio.

Cosa mettere in un file di contesto utile

Comandi esatti e la strada rapida

Fornisci comandi pronti da eseguire, con la directory di lavoro corretta e i flag utili. Distingui il controllo mirato dalla suite finale più costosa:

## Verification

- API change: run `pnpm test --filter api` first.
- Type check: run `pnpm typecheck` after changing TypeScript.
- Full suite: `pnpm test`; takes about 18 minutes, so run it once after focused tests pass.

«Esegui i test» aggiunge poco. Indicare il comando giusto, il suo costo e l’ordine elimina le congetture.

Confini con una motivazione o un’alternativa sicura

Annota le aree non ovvie che l’agente non deve modificare direttamente:

## Boundaries

- Do not edit `src/generated/`; change the schema and run `pnpm generate`.
- Ask before adding a production dependency.
- Do not rewrite an existing migration; add a new migration instead.

Una strada sicura è più utile di un semplice divieto.

Invarianti specifiche del repository

Includi le convenzioni importanti, sorprendenti e non imposte in modo meccanico. Per esempio, una regola insolita per la mappatura degli errori, un requisito di compatibilità che i test non coprono, o quell’unico servizio che deve usare un comando diverso.

Metti i fatti specifici di un servizio in un file di istruzioni annidato o in una regola limitata a un percorso. Caricare i dettagli del frontend in ogni attività sul backend consuma contesto e aumenta la probabilità di conflitti.

Errori ricorrenti, non ipotetici

Aggiungi una regola quando un agente ripete lo stesso errore costoso o quando una revisione individua un fatto che l’agente non poteva ragionevolmente dedurre. Rimuovi la regola quando il repository o gli strumenti la rendono obsoleta. Così il file resta ancorato ai fallimenti osservati invece di accumulare consigli speculativi.

Cosa lasciare fuori

  • Ruoli generici: «Sei un ingegnere senior» non è stato valutato direttamente da questi studi, ma non fornisce né un’azione verificabile né un fatto sul repository.
  • Ideali vaghi: «Segui SOLID» o «scrivi codice pulito» lasciano all’agente il compito di dedurre la stessa decisione di design che avrebbe preso comunque.
  • Un secondo README: descrivi solo la struttura sorprendente o quella che determina dove va collocata una modifica.
  • Inventari completi delle dipendenze: il manifest è più aggiornato e più facile da consultare per l’agente.
  • Requisiti di una singola attività: tienili nel prompt dell’attività, così non influenzano sessioni non correlate.
  • Regole che gli strumenti possono imporre: formatter, controlli dei tipi, test, hook e CI sono più efficaci della prosa per i requisiti deterministici.
  • Segreti o credenziali personali: un file di istruzioni è normale contesto del progetto, non un archivio di segreti.

Un modello di partenza compatto

# Repository instructions

## Fast path

- Install: `pnpm install --frozen-lockfile`
- Focused tests: `pnpm test --filter <changed-package>`
- Full suite: `pnpm test` (about 20 minutes; run after focused tests pass)

## Verification

- Run `pnpm typecheck` after TypeScript changes.
- Add or update a focused test when behavior changes.

## Boundaries

- Do not edit `generated/`; run `pnpm generate` from the schema.
- Ask before adding production dependencies or changing migrations.

## Known traps

- Tests under `integration/` require the local database started with `pnpm db:up`.
- Package-specific instructions live in that package's nested `AGENTS.md`.

Sostituisci ogni esempio con un fatto del repository reale. Un file accurato di dieci righe è meglio di un modello esaustivo pieno di impostazioni generiche.

Scegli il meccanismo duraturo più piccolo

Informazione Collocazione migliore
Vale per la maggior parte delle attività nel repository AGENTS.md o CLAUDE.md principale
Vale solo per un sottoalbero File di istruzioni annidato o regola limitata a un percorso
Preferenza personale valida per tutti i repository File di istruzioni a livello utente
Procedura in più passaggi necessaria per certe attività Una skill su richiesta
Requisito solo per questa attività Il prompt dell’attività
Regola che deve essere sempre applicata Test, formatter, hook, policy o CI

Per installare e mantenere le procedure su richiesta su più agenti, vedi la guida pratica a skills.sh. Un file di istruzioni non dovrebbe diventare un sostituto di tutti gli altri strumenti di controllo.

Valuta il file nel tuo repository

Le medie della ricerca non possono dirti se un’istruzione aiuta il tuo codice. Scegli un’attività ripetibile in cui l’istruzione dovrebbe cambiare il comportamento, poi esegui diverse prove con e senza di essa, usando lo stesso agente e la stessa versione del modello. Tieni traccia di:

  • risultati di test nascosti o scritti in modo indipendente;
  • esecuzioni dei test mirati e della suite completa;
  • tempo trascorso e uso di token;
  • modifiche superflue ai file e richieste di permesso;
  • se l’agente ha seguito la regola specifica.

Tieni un’istruzione quando migliora un risultato o evita uno spreco misurabile. Riscrivila o rimuovila quando viene ignorata, è duplicata, è superata o si limita ad allungare il prompt. L’obiettivo non è il file di contesto perfetto, ma un piccolo insieme di fatti sul repository che cambi il lavoro in meglio in modo affidabile.

Domande frequenti

AGENTS.md e CLAUDE.md rendono più accurati gli agenti di coding?

Non in modo affidabile, secondo la ricerca attuale. Studi recenti trovano effetti contrastanti sull’efficienza e un miglioramento generale scarso o nullo nella correttezza delle attività. Istruzioni operative concrete possono comunque ridurre comandi, tempo e token sprecati.

Claude Code può usare un file AGENTS.md esistente?

Per impostazione predefinita Claude Code non carica direttamente AGENTS.md. Inserisci @AGENTS.md in un piccolo file CLAUDE.md per importare le istruzioni condivise, poi aggiungi sotto solo le indicazioni davvero specifiche per Claude.

Quanto dovrebbe essere lungo un file AGENTS.md o CLAUDE.md?

Mantieni il file principale corto quanto il repository consente. Al momento Anthropic consiglia meno di 200 righe per ogni CLAUDE.md. Codex ha un limite predefinito di 32 KiB sull’intera catena di istruzioni combinata, ma si tratta di un tetto massimo, non di un obiettivo di scrittura.

Condividi questa guida