AGENTS.md e HUMAN.md: cosa sono e come usarli

Che cos'è AGENTS.md

AGENTS.md è un file Markdown semplice nella radice di un repository. Indica a un agente di programmazione come lavorare sul progetto. Il sito ufficiale lo descrive come "un README per gli agenti: un luogo dedicato e prevedibile in cui fornire il contesto e le istruzioni necessari agli agenti di programmazione basati sull'IA per lavorare sul progetto". Il formato è gestito dalla Agentic AI Foundation nell'ambito della Linux Foundation. Più di venti agenti lo leggono, 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 quando l'ipotesi è errata. Un agente non può chiedere. Indovina, esegue npm test in un progetto che usa pnpm test, legge 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 dichiara esplicitamente: "AGENTS.md è semplicemente Markdown standard. Usa le intestazioni che preferisci; l'agente analizza il testo fornito." Questa è l'intera specifica. Il valore non è nel formato. È nel fatto che il file si trova in un percorso che ogni strumento controlla già.

Dove va il file e quale file ha la precedenza

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 nell'albero delle directory, quindi quello più vicino ha la precedenza." 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 l'annidamento perché è l'unico modo per esprimere una regola vera in una cartella e falsa in quella successiva. Una regola come "ogni endpoint convalida il proprio input" deve trovarsi accanto agli endpoint. In un file nella radice verrebbe caricata per ogni attività non correlata e non offrirebbe alcun vantaggio.

Cosa inserire in un file AGENTS.md

Indicate ciò che un agente non può ricavare leggendo il codice. Iniziate con i comandi esatti per compilazione, test e lint, nel formato da incollare in un terminale. Aggiungete il comando per eseguire un singolo test: un agente che sa soltanto eseguire l'intera suite la eseguirà quaranta volte. Indicate le convenzioni che differiscono dai valori predefiniti degli strumenti, perché l'agente conosce già i valori predefiniti e deve sapere solo quali sono le vostre eccezioni. Aggiungete il formato dei messaggi di commit e le regole per le pull request, se esistono.

Siate abbastanza concreti da consentire la verifica di ogni affermazione. "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/, perché sono generati da npm run build" previene un errore specifico. Poiché indica la causa, consente all'agente di ricavare anche il caso equivalente che non avete descritto.

Cosa non deve mai contenere

Non inserire mai un segreto 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 provider di modelli a ogni richiesta. Una chiave API in un file AGENTS.md è una chiave API nella cronologia del repository e nei log di terze parti. Indica il segreto invece di incollarlo: «la password del database si trova in .env, che è escluso da gitignore; chiedi prima di leggerla». La disciplina più ampia è descritta in tenere le credenziali fuori dalla portata di un agente.

Ometti tutto ciò che l'agente può ricavare esaminando il progetto. Un elenco di directory incollato, una copia dell'elenco delle dipendenze o una panoramica dell'architettura che ripete i nomi delle cartelle diventano obsoleti già nella settimana successiva alla loro stesura e consumano contesto a ogni sessione. Conserva le insidie e le motivazioni. Elimina l'inventario.

CLAUDE.md è l'equivalente di Claude Code dello stesso concetto

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 vengono inserite in ~/.claude/CLAUDE.md; su Linux, un'organizzazione può distribuire un file a livello di sistema 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.

Se il repository contiene già un file AGENTS.md, non mantenerne una seconda copia. Importalo e aggiungi solo le informazioni specifiche di Claude:

@AGENTS.md

## Claude Code

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

Un symlink è sufficiente quando non devi aggiungere altro:

ln -s AGENTS.md CLAUDE.md

Il comando non visualizza nulla se l'operazione riesce. 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 scriverne una manualmente, esegui /init: il comando legge il codebase e produce un file iniziale; se CLAUDE.md esiste già, suggerisce 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 cos'altro occupa quello spazio, cosa riempie realmente la finestra di contesto di un agente lo spiega nel dettaglio.

Un aspetto merita particolare attenzione. Un file AGENTS.md contiene linee guida, non definisce un sistema di autorizzazioni. Il contenuto viene fornito come normale contesto: il modello lo legge e in genere lo segue, ma nulla impedisce un'azione che lo contraddice. Per una regola che deve essere rispettata sempre, ad esempio "non eseguire mai il push su main", usa un hook o un'impostazione di autorizzazione, perché questi vengono eseguiti come codice e non dipendono dalla decisione del modello di rispettarla.

Strumenti che scrivono questi file al posto tuo

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

agent0ai/dox (1,368 stelle a luglio 2026) è un framework per mantenere aggiornato un albero di file AGENTS.md. Non include pacchetti né un runtime. Copia il contenuto del suo file AGENTS.md nel tuo file AGENTS.md principale: questa è l'installazione. Per un progetto già esistente, indica al tuo agente:

Initialize DOX tree for this project now.

L'agente crea quindi i file AGENTS.md secondari 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 alla base è che la documentazione mantenuta da un agente come effetto collaterale del suo lavoro rimanga corretta, mentre quella aggiornata manualmente da una persona no.

HUMAN.md: lo stesso approccio applicato a te

Intuition-Lab/personal-model (1,260 stelle a luglio 2026) applica questo modello a una persona invece che a un repository. Il progetto considera HUMAN.md come l’output del sistema, non come un file da scrivere manualmente: «un modello dinamico di ciò che conta ora, di come tendi a decidere e di dove si sta spostando la tua attenzione». Viene eseguito localmente su macOS 13 o versioni successive, acquisisce l’attività dopo che hai concesso l’autorizzazione a macOS ed espone il risultato agli agenti tramite MCP (model context protocol). La procedura di installazione breve è:

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

Non 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 davvero, le decisioni già prese che non vuoi rimettere in discussione e il livello di dettaglio che vuoi ricevere nelle risposte. Evita le stesse spiegazioni ripetute che evita un file di progetto, ma a un livello superiore.

Una cautela è necessaria. HUMAN.md è un profilo di una persona, quindi è sensibile per definizione. Non inserirlo in un repository pubblico. Collocarlo in ~/.claude/CLAUDE.md oppure in un file CLAUDE.local.md escluso da gitignore nella radice del progetto; quest’ultimo viene caricato insieme al file sottoposto a commit e viene trattato nello stesso modo.

Un modello iniziale da copiare

È breve per scelta. Elimina le sezioni che non si applicano ed evita di aggiungere sezioni 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. Il segnale che indica di aggiungere una riga è quando hai digitato due volte la stessa correzione nella chat. Questa regola mantiene il file utile e impedisce che diventi un documento che nessuno legge, comprese le macchine. Quando è stabile, viaggia insieme al repository. Questo è particolarmente importante quando l'agente viene eseguito in un ambiente diverso dal tuo laptop: eseguire un agente di coding sul proprio server descrive questa configurazione.

FAQ

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

Sono la stessa idea con due nomi di file. Claude Code legge CLAUDE.md e ignora AGENTS.md se non li colleghi. Mantieni un solo file come fonte autorevole e collega l'altro a questo file, 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 AGENTS.md garantisce che l'agente lo segua?

No. Il contenuto viene fornito come contesto. Il modello lo legge e in genere lo rispetta, ma nulla impedisce un'azione che lo contraddice. Le istruzioni vaghe vengono seguite con minore affidabilità. Inoltre, se due file forniscono indicazioni opposte, l'agente sceglie arbitrariamente quale seguire. Per una regola che deve essere rispettata sempre, usa un hook o una regola di autorizzazione. Il client la applica indipendentemente dalla decisione del modello.

AGENTS.md deve essere sottoposto a commit in git?

Sì, per tutto ciò che è vero per il progetto: comandi di compilazione, struttura e convenzioni. Questo è lo scopo del file, perché gli agenti dei tuoi colleghi iniziano quindi con lo stesso contesto del tuo. Le informazioni personali o specifiche di una macchina appartengono a un file separato escluso da git, mentre le credenziali non devono trovarsi in nessuno dei due file.

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

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