AGENTS.md e HUMAN.md: guida pratica per agenti AI

Che cos’è AGENTS.md

AGENTS.md è un file Markdown semplice, collocato nella directory radice di un repository, che indica a un agente di coding come lavorare sul progetto. Il sito ufficiale lo descrive come «un README per gli agenti: un punto dedicato e prevedibile in cui fornire il contesto e le istruzioni necessari agli agenti di coding basati sull’AI per lavorare sul progetto». Il formato è mantenuto dalla Agentic AI Foundation, nell’ambito della Linux Foundation, e viene letto da più di venti agenti, tra cui Codex, Cursor, Jules, Devin e GitHub Copilot (a luglio 2026).

La convenzione esiste per un motivo pratico. Una persona appena entrata nel team legge il README, prova a indovinare il comando di build e chiede aiuto se l’ipotesi è errata. Un agente non può farlo. Esegue per tentativi npm test in un progetto che usa pnpm test, rileva l’errore e prova qualcos’altro. Ogni tentativo consuma token. Scrivere una volta il comando corretto elimina questa intera categoria di errori.

Non esistono campi obbligatori. Il sito lo specifica chiaramente: «AGENTS.md è solo Markdown standard. Usa i titoli che preferisci; l’agente analizza semplicemente il testo che fornisci». Questa è l’intera specifica. Il valore non sta nel formato. Sta nel fatto che il file si trova in un percorso che ogni strumento controlla già.

Dove viene letto il file e quale file prevale

Inserisci il primo file nella radice del repository. In un monorepo puoi aggiungerne altri all'interno di ogni sottoprogetto. La regola è semplice: "gli agenti leggono automaticamente il file più vicino nella struttura delle directory, quindi prevale quello più vicino". Se due file sono in conflitto, prevale il file relativo all'elemento che stai modificando. Qualsiasi istruzione inserita nella chat ha la precedenza su entrambi.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

Vale la pena usare la struttura annidata, perché è l'unico modo per definire una regola vera in una directory e falsa in quella successiva. Una regola come "ogni endpoint valida il proprio input" deve trovarsi accanto agli endpoint. In un file nella radice viene caricata per ogni attività non correlata e non offre alcun vantaggio. Se il file nella radice contiene già una sezione per ogni servizio, suddividerlo in una struttura annidata è la soluzione. In questo modo puoi stabilire quali regole spostare ai livelli inferiori e quali mantenere nella radice.

Cosa inserire in un file AGENTS.md

Indicate ciò che un agente non può ricavare leggendo il codice. I comandi esatti per build, test e lint vengono prima, nella forma in cui li si incollerebbe in un terminale. Aggiungete il comando per eseguire un singolo test, perché un agente che sa soltanto eseguire l'intera suite la eseguirà quaranta volte. Indicate le convenzioni che differiscono dai valori predefiniti degli strumenti: l'agente conosce già questi ultimi e deve conoscere soltanto le vostre eccezioni. Aggiungete il formato dei messaggi di commit e le regole per le pull request, se ne avete.

Siate abbastanza concreti da rendere verificabile ogni indicazione. "Usare un'indentazione di 2 spazi" è un'istruzione utilizzabile, perché si può verificare se è stata rispettata. "Formattare correttamente il codice" non lo è, perché non contiene alcun elemento verificabile. Lo stesso vale per i percorsi: "I gestori API si trovano in src/api/handlers/" è più utile di "mantenere i file organizzati".

Anche le regole negative sono utili. "Non modificare mai i file in dist/: sono generati da npm run build" evita un errore specifico e, poiché ne indica la causa, consente all'agente di ricavare il caso equivalente che non avete esplicitato. Qui rientra anche una regola sull'ambito delle modifiche, perché un agente lasciato al proprio giudizio riscriverà più di quanto richiesto: una competenza ampiamente copiata non fa altro che insistere sulla modifica minima che risolve il problema.

Cosa non deve mai contenere

Non inserire mai un secret in uno di questi file. Il file viene sottoposto a commit in git, caricato nel contesto all'inizio di ogni sessione e inviato a un model provider a ogni richiesta. Una API key in AGENTS.md diventa una API key nella cronologia del repository e nei log di terze parti. Fai riferimento al secret invece di incollarlo: «la password del database si trova in .env, che è escluso da git tramite gitignore; chiedi prima di leggerlo». La disciplina più ampia è descritta in mantenere le credenziali fuori dalla portata di un agent.

Ometti tutto ciò che l'agent può ricavare osservando il repository. Un elenco di directory incollato, una copia dell'elenco delle dipendenze o una panoramica dell'architettura che ripete i nomi delle directory diventano obsoleti già nella settimana successiva alla loro stesura e, nel frattempo, consumano contesto a ogni sessione. Mantieni le insidie e le motivazioni. Elimina l'inventario. Conviene separare le motivazioni, perché un agent che non può vedere l'origine di una struttura insolita la rifattorizzerà senza segnalarlo. Questo vale anche per mantenere un DESIGN.md accanto a questo file.

CLAUDE.md è l'equivalente di AGENTS.md per Claude Code

Claude Code legge CLAUDE.md e non legge autonomamente AGENTS.md. Un file di progetto si trova in ./CLAUDE.md o ./.claude/CLAUDE.md; le preferenze personali per ogni progetto vanno in ~/.claude/CLAUDE.md; in Linux, un'organizzazione può distribuire un file a livello di macchina in /etc/claude-code/CLAUDE.md. I file individuati vengono concatenati dalla radice del filesystem fino alla directory di lavoro, quindi il file più vicino alla directory da cui hai avviato la sessione viene letto per ultimo. Ogni sessione avviata in quella directory carica lo stesso insieme di file. Questo permette di eseguire due sessioni affiancate sulla stessa macchina; inoltre queste sessioni possono passarsi il lavoro mentre sono in esecuzione.

Se il repository contiene già un file AGENTS.md, non mantenerne una seconda copia. Importalo, quindi aggiungi soltanto le istruzioni specifiche per Claude:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Un link simbolico è sufficiente quando non devi aggiungere altro:

ln -s AGENTS.md CLAUDE.md

In caso di successo, il comando non stampa nulla. Nella sessione successiva, esegui /context e verifica che CLAUDE.md compaia nella sezione File di memoria. Se non compare nell'elenco, il file non è mai stato caricato e il suo contenuto non è stato applicato. Per generare una prima bozza invece di scriverla manualmente, esegui /init: il comando legge il codebase e produce un file iniziale. Se esiste già un file CLAUDE.md, propone miglioramenti invece di sovrascriverlo.

Mantieni ogni file al di sotto di circa 200 righe. I file più lunghi consumano una parte maggiore della finestra di contesto e riducono il rispetto delle istruzioni. Se vuoi vedere quali altri contenuti competono per quello spazio, questa analisi mostra cosa riempie realmente la finestra di contesto di un agent.

Un punto merita particolare attenzione. Un file AGENTS.md contiene istruzioni, ma non è un sistema di autorizzazioni. Il contenuto arriva come normale contesto: il modello lo legge e in genere lo segue, ma nulla impedisce un'azione che lo contraddice. Quando una regola scritta da te viene ignorata senza spiegazioni e non capisci il motivo, consulta le ragioni per cui un'istruzione viene ignorata prima di riscriverla una terza volta. Per una regola che deve essere rispettata sempre, come "non eseguire mai il push su main", usa un hook o un'impostazione di autorizzazione: questi meccanismi vengono eseguiti come codice e non dipendono dal fatto che il modello scelga di rispettarla.

Strumenti che scrivono questi file al posto tuo

Due progetti presenti nell’elenco dei repository di tendenza su GitHub il 30 July 2026 mostrano la direzione che sta prendendo questa convenzione.

agent0ai/dox (1,368 stelle a July 2026) è un framework per mantenere aggiornato un albero di file AGENTS.md. Non distribuisce alcun package e non richiede alcun runtime. Si copia il contenuto del relativo AGENTS.md nel proprio AGENTS.md radice: questa è l’installazione. Per un progetto già esistente, si comunica al proprio agente:

Initialize DOX tree for this project now.

L’agente crea quindi i file AGENTS.md figlio e i relativi indici, percorre l’albero prima di modificare qualsiasi elemento e aggiorna la documentazione interessata dopo l’applicazione di una modifica. L’idea di fondo è che la documentazione mantenuta da un agente come effetto collaterale del proprio lavoro rimanga aggiornata, mentre quella modificata manualmente da una persona no.

HUMAN.md, lo stesso approccio rivolto a te

Intuition-Lab/personal-model (1,260 stelle a luglio 2026) applica questo schema a una persona anziché a un repository. Il progetto considera HUMAN.md l’output del sistema, non un file scritto manualmente: «un modello dinamico di ciò che conta in questo momento, del modo in cui tendi a prendere decisioni e della direzione in cui si sposta la tua attenzione». Funziona localmente su macOS 13 o versioni successive, acquisisce le attività dopo che hai concesso l’autorizzazione a macOS ed espone il risultato agli agent tramite MCP (model context protocol). La procedura di installazione essenziale è:

uv tool install personal-model
persome onboard
persome model open --after 30

Non ti serve nulla di tutto questo per ottenere gran parte del vantaggio. Un HUMAN.md scritto manualmente contiene circa venti righe: il tuo ruolo, il fuso orario, lo stack che usi realmente, le decisioni già prese che non vuoi rimettere in discussione e la quantità di spiegazioni che desideri ricevere. Evita le stesse ripetizioni necessarie per spiegare continuamente il contesto, come fa un file di progetto, ma a un livello superiore.

Una precauzione è necessaria. HUMAN.md contiene il profilo di una persona, quindi è sensibile per definizione. Non inserirlo in un repository pubblico. Collocalo in ~/.claude/CLAUDE.md oppure in un CLAUDE.local.md escluso da Git tramite .gitignore nella directory principale del progetto; questo file viene caricato insieme al file versionato e viene trattato allo stesso modo.

Un modello iniziale da copiare

È volutamente breve. Elimina le sezioni che non si applicano e non aggiungere quelle che non puoi mantenere aggiornate.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Scrivilo, quindi correggilo direttamente nel file. Il segnale per aggiungere una riga è aver digitato due volte la stessa correzione nella chat. Questa regola mantiene il file utile e impedisce che cresca fino a diventare un documento che nessuno legge, nemmeno le macchine. Quando è stabile, il file viaggia insieme al repository. Questo è particolarmente importante quando l’agent viene eseguito in un ambiente diverso dal tuo laptop: eseguire un agent di coding sul proprio server descrive questa configurazione.

FAQ

AGENTS.md è lo stesso file di CLAUDE.md?

Si tratta dello stesso concetto con due nomi di file. Claude Code legge CLAUDE.md e ignora AGENTS.md, a meno che non li colleghi. Mantieni un solo file come fonte autorevole e collega l'altro, inserendo una riga @AGENTS.md all'inizio di CLAUDE.md oppure usando ln -s AGENTS.md CLAUDE.md. Due copie complete gestite separatamente entreranno in conflitto entro un mese.

La scrittura di un file AGENTS.md garantisce che l'agente lo segua?

No. Il contenuto viene fornito come contesto, quindi il modello lo legge e in genere lo segue, ma nulla impedisce un'azione che lo contraddica. Le istruzioni vaghe sono quelle seguite con minore affidabilità, mentre due file con indicazioni opposte lasciano l'agente libero di sceglierne uno arbitrariamente. Per una regola che deve essere applicata ogni volta, usa un hook o una regola di autorizzazione: il client le applica indipendentemente dalla decisione del modello.

AGENTS.md deve essere aggiunto a git?

Sì, per tutto ciò che è vero sul progetto: comandi di build, struttura e convenzioni. Questo è lo scopo del file, perché gli agenti dei membri del team iniziano quindi con lo stesso contesto del tuo. Tutto ciò che è personale o specifico di una macchina deve trovarsi in un file separato escluso da git, mentre le credenziali non devono essere inserite in nessuno dei due.

Che cos'è HUMAN.md e ne ho bisogno?

HUMAN.md è un profilo leggibile dalla macchina relativo a una persona, non a un progetto. Contiene il tuo ruolo, i tuoi vincoli e le decisioni già definite, così non vengono riaperte a ogni sessione. Per iniziare non serve alcun tool: venti righe scritte manualmente nel file delle istruzioni a livello utente offrono gran parte del valore. Trattalo come dati personali e non inserirlo in alcun repository che pubblichi.