SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor · Aggiornato 2026-10-28

AGENTS.md annidati: struttura corretta per un monorepo

Scopri come organizzare AGENTS.md in un monorepo: regole comuni nella radice, istruzioni specifiche nei servizi e meno contesto sprecato dall'agente.

Cosa significa avere file AGENTS.md annidati in un monorepo

In un monorepo, avere file AGENTS.md annidati significa usare un file ridotto nella radice del repository e un altro file all'interno di ogni directory dei servizi. Il file nella radice contiene le poche regole valide ovunque, oltre a una mappa delle directory in cui si trovano gli altri file. Ogni file specifico di un servizio contiene i comandi e le convenzioni applicabili soltanto a quella directory. Un agente che modifica services/worker/queue.py legge quindi il file nella radice e quello del worker, senza consumare contesto per il front end che non dovrà mai toccare.

Non è necessario installare nulla. AGENTS.md è una convenzione, come chiarisce esplicitamente il progetto upstream:

AGENTS.md è semplice Markdown standard. Usa le intestazioni che preferisci; l'agente analizza semplicemente il testo che fornisci.

Per questo vale la pena imparare correttamente questa tecnica. Il formato non cambierà senza preavviso. I problemi dipendono dal posizionamento e dalla manutenzione, ed entrambi sono di tua responsabilità.

Perché un unico AGENTS.md alla radice smette di funzionare?

Un unico AGENTS.md di 600 righe alla radice di un repository che contiene un'applicazione web, un worker in background e una directory Terraform fallisce per quattro motivi distinti.

Diventa obsoleto perché nessuno ne è responsabile. L'ingegnere che rinomina uno script di test in apps/web sta modificando file sotto apps/web. Il file AGENTS.md alla radice non fa parte di quella modifica, quindi nessun revisore vede l'incongruenza. Sei settimane dopo, il file descrive una fase di build che non esiste più e chi ha introdotto la modifica ha dimenticato di averla fatta.

Consuma contesto per ogni attività. Questi file vengono caricati all'inizio della sessione, prima che l'agente sappia cosa gli verrà chiesto. La documentazione di Claude Code indica un limite preciso: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." Codex smette di unire i file di istruzioni quando la loro dimensione complessiva raggiunge 32 KiB, il valore predefinito project_doc_max_bytes. Un file alla radice che documenta quattro servizi consuma quel budget per tre di essi a ogni attività.

Le istruzioni iniziano a contraddirsi. La directory web richiede pnpm test. Il worker richiede pytest -q. Scritte nello stesso file, entrambe le regole sono corrette solo in alcuni casi, quindi l'agente deve indovinare quale applicare. La documentazione di Claude Code descrive il risultato: "if two instructions contradict each other, Claude may pick one arbitrarily." Dividere il file non esclude l'altra regola dal contesto. Claude Code concatena ogni file di istruzioni caricato invece di consentire a uno di sostituire gli altri, quindi il file alla radice è sempre presente e, quando l'agente ha aperto file sia in apps/web sia in services/worker, entrambi i file delle directory sono presenti nel contesto. Un file per directory associa ogni regola alla directory a cui si applica. Indica il nome della directory all'inizio del file, come negli esempi seguenti con # apps/web, così ogni comando specifica ancora dove è valido quando vengono caricati più file contemporaneamente. Quando una regola che sei certo di avere scritto chiaramente viene comunque ignorata, analizzare i motivi per cui un'istruzione non viene recepita è più utile che riscriverla per la quarta volta.

Si riempie di informazioni che l'agente potrebbe ricavare dal codice. Una struttura delle directory, un elenco delle dipendenze, un riepilogo delle funzioni di ogni package. Il controllo /doctor di Claude Code serve proprio a eliminare questo tipo di contenuti. "cuts content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews" e conserva "pitfalls, rationale, and conventions that differ from tool defaults." Questa frase è il test migliore che conosca per stabilire se una riga debba essere inclusa nel file.

L'agente legge il file nella root oppure soltanto quello più vicino?

È su questo punto che la maggior parte delle persone interpreta male il modello, quindi vale la pena citare la convenzione upstream invece di parafrasarla:

Inserisci un altro AGENTS.md in ogni package. Gli agenti leggono automaticamente il file più vicino nella struttura delle directory, quindi quello più vicino ha la precedenza e ogni subproject può includere istruzioni personalizzate.

E in caso di conflitti:

Vince l'AGENTS.md più vicino al file modificato; i prompt espliciti dell'utente nella chat hanno la precedenza su tutto.

Per molti, l'espressione "ha la precedenza" significa che "il file nella root viene ignorato". Non è così. Negli strumenti che implementano questa convenzione, vengono letti tutti i file dal repository root fino alla working directory e il loro contenuto viene unito. Il file più vicino ha la precedenza soltanto quando due file indicano istruzioni diverse sullo stesso argomento.

Codex descrive esplicitamente il meccanismo: "Codex concatena i file dalla root verso il basso, separandoli con righe vuote. I file più vicini alla directory corrente sostituiscono le indicazioni precedenti." Claude Code percorre lo stesso path. All'avvio della sessione legge "ogni AGENTS.md e .claude/AGENTS.md nella working directory e nelle directory superiori", e la documentazione descrive chiaramente il modello di caricamento: "Tutti i file individuati vengono concatenati nel contesto invece di sostituirsi a vicenda." Le directory sotto la working directory si comportano in modo diverso: Claude Code carica AGENTS.md di una subdirectory su richiesta, "quando Claude apre un file al suo interno con lo strumento Read."

Ne derivano due conseguenze pratiche. Il file nella root è un prefisso di ogni sessione nel repository, quindi considera ogni sua riga come una riga per cui paghi cento volte alla settimana. Un file specifico per directory non ha alcun costo finché l'agente non apre un file in quella directory: il dettaglio è quindi economico e va collocato lì.

Questo comportamento è stato verificato sulla documentazione di Codex e Claude Code il 27 ottobre 2026. Gli strumenti implementano la convenzione in modo leggermente diverso e possono cambiare, quindi verifica le regole di caricamento dell'agente utilizzato dal tuo team.

Una struttura completa per un repository con tre servizi

repo/
  AGENTS.md                   rules true everywhere, plus the map
  apps/web/AGENTS.md          TypeScript client, Vite, Vitest
  services/worker/AGENTS.md   Python queue consumer, pytest
  infra/AGENTS.md             Terraform and the deploy scripts

Il file nella directory radice è volutamente breve. Indica dove cercare e contiene solo le regole valide in ogni directory.

# AGENTS.md

This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.

- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts

## Rules for the whole repository

- The package manager is `pnpm`. `npm install` writes a second lockfile
  that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
  `schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
  in the same commit.

Il file specifico della directory contiene i dettagli e può essere lungo quanto richiede quella directory.

# apps/web

Browser client. Vite and React, TypeScript with `strict` on.

## Commands

- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.

## Conventions

- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
  because the client attaches the auth header and retries on 429.

## Traps

- `pnpm build` does not type check. Vite strips the types instead of
  checking them, so a broken type still produces a green build.
  Run `pnpm typecheck` as a separate step.

Il file del worker ha la stessa struttura, ma contenuti diversi: il comando di installazione, pytest -q, il motivo per cui il consumer deve restare idempotente e la migrazione che deve essere eseguita prima che i test abbiano esito positivo. Il file dell'infrastruttura contiene le regole che impediscono a un agente di causare danni. Non eseguire mai terraform apply. Esegui terraform plan e non fare altro, quindi indica il backend dello stato già configurato, in modo che l'agente non tenti di inizializzarne uno nuovo.

Nota cosa non compare in nessuno di questi file: una descrizione dello scopo di ciascun servizio. Questo aspetto riguarda le persone. Il progetto upstream traccia la stessa distinzione, specificando che "i file README.md sono destinati alle persone: guide rapide, descrizioni del progetto e linee guida per i contributi", mentre AGENTS.md contiene "il contesto aggiuntivo, talvolta dettagliato, di cui gli agenti di programmazione hanno bisogno: passaggi di build, test e convenzioni." La distinzione tra AGENTS.md e un README rivolto alle persone analizza questa separazione frase per frase, mentre un DESIGN.md che documenta il motivo della struttura del codice tratta il terzo file, quello che spiega le decisioni anziché i comandi.

Chi aggiorna il file quando cambia il codice?

Una sola regola, da inserire nel file root: chi modifica il codice in una directory aggiorna l'AGENTS.md di quella directory nello stesso commit.

La regola funziona per un motivo meccanico, non culturale. Il file specifico della directory si trova nella stessa diff del codice, quindi chi esamina la pull request li vede entrambi contemporaneamente. Un file root appartiene a tutti e quindi, di fatto, non appartiene a nessuno; inoltre non compare mai nella diff che qualcuno sta già esaminando.

Sostieni la regola con un controllo sulla pull request. Il controllo individua l'AGENTS.md più vicino sopra ogni file modificato, quindi segnala i casi in cui quel file non è stato modificato.

#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)

nearest_doc() {
  d=$(dirname "$1")
  while [ "$d" != "." ]; do
    if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
    d=$(dirname "$d")
  done
  echo "AGENTS.md"
}

printf '%s\n' "$changed" | while read -r f; do
  [ -n "$f" ] || continue
  case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
  doc=$(nearest_doc "$f")
  printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
  echo "note: $f changed but $doc was not updated"
done

In un branch che ha rielaborato il client API senza modificare la documentazione, l'output è simile al seguente:

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

Mantieni il controllo come avviso, non come errore. Un gate rigido insegna ad aggiungere una riga vuota al file per far passare la CI, e un file modificato solo per soddisfare un robot vale meno di nessun file. L'avviso fornisce al revisore una domanda da porre, ed è questo l'elemento che funziona davvero.

Come individuare un file AGENTS.md non più aggiornato?

Oggi puoi eseguire due controlli e, durante una sessione, osservare un sintomo.

Confronta l'età di ogni file con quella del codice che descrive. %cs stampa la data del commit come YYYY-MM-DD.

for f in $(git ls-files '*AGENTS.md'); do
  d=$(dirname "$f")
  printf '%s  doc:%s  code:%s\n' "$f" \
    "$(git log -1 --format=%cs -- "$f")" \
    "$(git log -1 --format=%cs -- "$d")"
done
apps/web/AGENTS.md          doc:2026-02-11  code:2026-08-07
services/worker/AGENTS.md   doc:2026-07-29  code:2026-08-09
infra/AGENTS.md             doc:2026-08-01  code:2026-08-01

Una data della documentazione precedente di sei mesi rispetto alla data del codice non dimostra che il file sia errato. Indica quale file leggere per primo, ed è tutto ciò che serve da un controllo che richiede un secondo.

Cerca i percorsi che non esistono più. La documentazione diventa obsoleta in un modo molto specifico: continua a descrivere codice che è stato eliminato. Ogni percorso in questi file è racchiuso tra backtick, quindi è facile estrarlo e verificarlo.

grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
  [ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
done

Leggi l'output invece di integrare questo controllo in CI. Segnala anche glob come src/**/*.ts e qualsiasi URL racchiuso tra virgolette, perché entrambi contengono una barra e nessuno dei due è un file su disco. In Claude Code v2.1.283 o versioni successive, /doctor prompt-audit esegue per te un controllo simile: cerca «riferimenti a file o comandi che non esistono» e file in contraddizione tra loro, include per impostazione predefinita i file AGENTS.md e non modifica nulla finché non chiedi di applicare le modifiche proposte.

Il sintomo durante una sessione. L'agente legge il file, prova ad aprire src/api/client.ts perché il file glielo indica e lo strumento restituisce:

No such file or directory

Quindi fa la cosa ragionevole e scrive un proprio wrapper fetch. Questo è il costo reale di un file non più aggiornato. L'agente non ignora la documentazione. La segue, raggiunge un percorso eliminato tre mesi prima e ricostruisce codice che è già presente. Una skill come Ponytail, che vincola l'agente alla modifica minima funzionante, riduce la tendenza a ricostruire il codice, ma non può trovare un helper a cui il file indirizza nel posto sbagliato.

Claude Code legge i file AGENTS.md?

Sì, a partire da Claude Code v2.1.277, e la regola esatta è importante perché da essa dipende la struttura annidata. Verificato sulla documentazione il 27 ottobre 2026: "Claude Code può leggere AGENTS.md come istruzioni del progetto, quindi un repository già configurato per altri agenti di coding funziona senza aggiungere CLAUDE.md, un import o un'impostazione." Il valore predefinito di Project instructions, claude-md-or-agents-md, legge "i tuoi file AGENTS.md quando nella directory di lavoro o sopra di essa non esistono CLAUDE.md o CLAUDE.local.md." Sono inclusi anche i file annidati: Claude legge AGENTS.md di una sottodirectory "quando apre un file al suo interno con lo strumento Read", purché "quella sottodirectory non contenga nessuno dei tre file CLAUDE.md propri". I tre file sono CLAUDE.md, .claude/CLAUDE.md e CLAUDE.local.md, quindi un CLAUDE.local.md personale in apps/web è sufficiente per impedire il caricamento di apps/web/AGENTS.md.

Questo trasforma in una trappola il vecchio consiglio di mettere un CLAUDE.md accanto a ogni AGENTS.md. Se nella directory di lavoro o sopra di essa esistono un AGENTS.md e un CLAUDE.md o CLAUDE.local.md, la documentazione afferma che Claude legge "solo i tuoi file CLAUDE.md". Anche un .claude/CLAUDE.md ha lo stesso effetto. Un singolo file complementare nella directory principale, contenente una sola riga specifica per Claude, nasconde ogni AGENTS.md presente nel percorso, e un CLAUDE.local.md personale produce lo stesso risultato. Se vuoi conservarne uno, digita /config e imposta Project instructions su claude-md-and-agents-md, che legge entrambi: prima il CLAUDE.md di ogni directory e poi il relativo AGENTS.md.

Il solo numero di versione non conferma che la configurazione abbia funzionato. Serve v2.1.277 o una versione successiva, ma prima di v2.1.281 alcune sessioni, ad esempio quelle su Amazon Bedrock o con la telemetria disabilitata, leggevano soltanto i file CLAUDE.md. In alcuni casi anche la prima sessione dopo l'aggiornamento da v2.1.276 o da una versione precedente saltava AGENTS.md: la documentazione afferma che "Claude legge AGENTS.md a partire dalla sessione successiva". Controlla quindi la sessione stessa. In una sessione interattiva Claude Code stampa una riga come no CLAUDE.md found; AGENTS.md loaded: seguita dal percorso, mentre nelle versioni attuali /memory elenca il file. Prima di v2.1.280, /memory e /context non elencavano un AGENTS.md letto direttamente da Claude; in quelle versioni chiedi quindi a Claude quali sono le sue istruzioni del progetto.

La forma con import è ancora corretta quando Claude non può leggere direttamente AGENTS.md: con una versione precedente, in una sessione anteriore a v2.1.281 su Amazon Bedrock o con la telemetria disabilitata, in una sessione in cui il plugin integrato che lo legge è disabilitato oppure in un progetto che mantiene un CLAUDE.md con Project instructions impostato su claude-md. Inserisci questo in services/worker/CLAUDE.md:

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/worker/migrations/`.

La forma con symlink è corretta quando non c'è nulla di specifico per lo strumento da aggiungere.

git ls-files '*AGENTS.md' | while read -r f; do
  ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.md

ln non stampa nulla in caso di successo, quindi controlla l'elenco: apps/web/CLAUDE.md -> AGENTS.md. Avvia quindi una sessione ed esegui /context, dove i file caricati compaiono sotto Memory files. Su Windows, per creare un symlink servono i diritti di Administrator o Developer Mode. Inoltre, Git estrae un symlink sottoposto a commit come file di testo normale se core.symlinks non è abilitato, lasciando in quel clone un CLAUDE.md di una sola riga al posto delle istruzioni. Se qualcuno clona il repository e lavora su Windows, usa l'import @AGENTS.md. Se hai configurato una delle due soluzioni prima che Claude Code leggesse autonomamente AGENTS.md, puoi lasciarla: la documentazione afferma che mantenere l'import "non fa mai leggere AGENTS.md due volte", mentre un CLAUDE.md collegato tramite symlink viene letto una sola volta.

C'è un'altra trappola da considerare. Dopo /compact, il CLAUDE.md nella directory principale del progetto viene riletto dal disco, ma i file annidati nelle sottodirectory non vengono reiniettati. Claude Code li ricarica su richiesta, la volta successiva in cui l'agente lavora con un file di quella directory. La documentazione lo specifica per i file CLAUDE.md e non descrive separatamente la compattazione per un AGENTS.md letto direttamente; è quindi ragionevole aspettarsi questo comportamento per i file annidati di entrambi i nomi. Se una regola per-directory sembra smettere di applicarsi durante una sessione lunga, di solito la causa è questa. La lettura di un file nella directory la ricarica.

Impostazioni che indicano agli altri agenti di leggere AGENTS.md

Codex legge AGENTS.md in modo nativo. A ogni livello controlla prima AGENTS.override.md, consentendo a una directory di avere una sostituzione locale senza modificare il file condiviso. Smette di unire i contenuti quando la dimensione complessiva raggiunge 32 KiB, il valore predefinito di project_doc_max_bytes. Questo è un ulteriore motivo per mantenere piccolo il file nella directory principale.

Aider lo acquisisce tramite .aider.conf.yml con la riga read: AGENTS.md.

Gemini CLI lo acquisisce tramite .gemini/settings.json con { "context": { "fileName": "AGENTS.md" } }.

La documentazione upstream descrive una rinomina compatibile con le versioni precedenti per i repository che usano ancora il nome singolare: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

In un monorepo molto grande, l'impostazione claudeMdExcludes di Claude Code esclude i file delle directory ancestrali in base al percorso o al glob. È utile quando la directory di un altro team si trova sopra la tua. I relativi pattern si applicano anche ai file AGENTS.md letti da Claude Code.

In che modo è diverso dalla memoria dell’agente o da una skill?

Questi meccanismi possono sembrare simili, ma si comportano in modo completamente diverso quando si verificano errori. È quindi importante distinguere quale utilizzare.

AGENTS.md viene scritto da te, salvato in git, esaminato tramite una pull request ed è identico per tutti coloro che clonano il repository. La memoria dell’agente viene scritta dall’agente, salvata al di fuori del repository ed è locale a una macchina. Anche la documentazione di Claude Code traccia la stessa distinzione: CLAUDE.md contiene «Istruzioni e regole» scritte da te, mentre la memoria automatica contiene «Apprendimenti e schemi» scritti da Claude; inoltre, la directory della memoria non viene condivisa tra le macchine. La verifica è semplice. Se un’informazione deve essere valida anche per un collega che esegue un clone pulito, non può essere salvata nella memoria. Come persiste la memoria dell’agente tra le sessioni tratta questa parte del problema.

Una skill è il terzo elemento. AGENTS.md è contesto che viene caricato in ogni sessione; una skill è una procedura che viene caricata quando serve. La documentazione di Claude Code fornisce una regola utile: «Se una voce descrive una procedura composta da più passaggi o riguarda soltanto una parte del codebase, spostala in una skill o in una regola con ambito limitato a un percorso». La seconda parte della frase descrive esattamente il caso risolto da un AGENTS.md annidato. La prima parte indica invece l’uso delle skill dell’agente; quando la stessa procedura serve in più repository, è preferibile condividere la skill tra i repository invece di incollare gli stessi paragrafi in dieci file AGENTS.md diversi.

Il progetto upstream osserva che «al momento della stesura, il repository principale di OpenAI contiene 88 file AGENTS.md». Questo numero riassume l’intero argomento. Un repository di grandi dimensioni non ha bisogno di un file più grande. Ha bisogno di più file piccoli, ciascuno accanto al codice che descrive e gestito da chi ha modificato per ultimo quel codice.

FAQ

Un file AGENTS.md annidato sostituisce il file radice o si aggiunge a esso?

Si aggiunge a esso. La documentazione upstream afferma che "quello più vicino ha la precedenza", ma questa indicazione descrive ciò che accade in caso di conflitto, non quali file vengono caricati. Codex "concatena i file dalla radice verso il basso, separandoli con righe vuote" e Claude Code concatena ogni file trovato risalendo dalla directory di lavoro, invece di sovrascriverli. Il file più vicino prevale solo quando due file contengono istruzioni diverse sullo stesso argomento. Scrivete le regole condivise una sola volta nel file radice e non ripetetele in ogni directory.

Quanto deve essere grande il file AGENTS.md radice?

Deve essere abbastanza piccolo da poter essere incollato in cima a ogni richiesta nella repository senza problemi, perché è esattamente ciò che accade. La documentazione di Claude Code suggerisce di mantenere ogni file sotto le 200 righe e avverte che i file più lunghi "riducono il rispetto delle istruzioni". Per impostazione predefinita, Codex interrompe l'unione dei file di istruzioni quando la dimensione complessiva raggiunge 32 KiB. Se il file radice documenta quattro servizi, gran parte del contenuto è superflua per una singola attività. Spostate i dettagli nei file delle singole directory e lasciate un indice.

Come posso evitare che questi file diventino obsoleti?

Inserite una regola nel file radice: chi modifica il codice di una directory aggiorna AGENTS.md di quella directory nello stesso commit. Posizionare il file accanto al codice rende effettiva la regola, perché la modifica viene inclusa nella stessa pull request che una persona sta già esaminando. Aggiungete un avviso CI che associ ogni percorso modificato al file AGENTS.md più vicino sopra di esso e, periodicamente, confrontate git log -1 --format=%cs di ogni file con lo stesso comando eseguito sulla directory documentata.

Claude Code legge i file AGENTS.md?

Sì, dalla v2.1.277. In base alla documentazione verificata il 27 ottobre 2026, Claude Code legge AGENTS.md per impostazione predefinita quando nella directory di lavoro o in una directory superiore non sono presenti CLAUDE.md o CLAUDE.local.md, e legge AGENTS.md di una sottodirectory quando apre un file al suo interno con Read tool e quella sottodirectory non contiene CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md propri. Non aggiungete un CLAUDE.md accanto a ogni AGENTS.md: se ce n'è uno nella directory di lavoro o in una directory superiore, Claude legge "solo i file CLAUDE.md". Se vi serve anche un CLAUDE.md, impostate Project instructions su claude-md-and-agents-md in /config oppure inserite @AGENTS.md nella prima riga. Eseguite /memory in una sessione e verificate che il percorso AGENTS.md compaia nell'elenco.

Dove inserisco una regola che si applica solo in alcuni casi?

Non in AGENTS.md. Quel file viene caricato in ogni sessione, quindi ogni sua riga compete per l'attenzione con la richiesta che avete effettivamente digitato. Una procedura con diversi passaggi, necessaria solo occasionalmente, appartiene a una skill, che viene caricata su richiesta. Una regola che si applica a una sola directory appartiene all'AGENTS.md di quella directory. Un'informazione che l'agente può leggere direttamente dal codice, come l'albero delle directory o l'elenco delle dipendenze, non appartiene a nessuno dei due.

Questo articolo ti è stato utile?