---
title: "Cosa mettere in AGENTS.md e CLAUDE.md?"
seoTitle: "AGENTS.md e CLAUDE.md: cosa aiuta davvero gli agenti"
navTitle: "AGENTS.md e CLAUDE.md"
description: "Cosa mettere in AGENTS.md e CLAUDE.md secondo i benchmark sugli agenti: comandi utili, vincoli operativi, trappole costose e cosa lasciare fuori."
slug: agents-md-claude-md-best-practices
lang: it
date: 2026-08-06
updated: 2026-08-06
author: "Chatcode"
category: guide
faq:
  - q: "AGENTS.md e CLAUDE.md rendono più accurati gli agenti di coding?"
    a: "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."
  - q: "Claude Code può usare un file AGENTS.md esistente?"
    a: "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."
  - q: "Quanto dovrebbe essere lungo un file AGENTS.md o CLAUDE.md?"
    a: "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."
---

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](https://learn.chatgpt.com/docs/agent-configuration/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](https://code.claude.com/docs/en/memory).

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

```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?](https://arxiv.org/abs/2607.27250)
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](https://arxiv.org/abs/2601.20404) 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](https://arxiv.org/abs/2602.11988) 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:

```md
## 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:

```md
## 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

```md
# 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](/articles/skills-sh-install-skills-ai-coding-agents).
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.
