Come scrivere un file AGENTS.md per gli agenti di programmazione
Scrivi un AGENTS.md breve con comandi di installazione e test, regole e limiti, fai in modo che Claude Code e Gemini CLI lo carichino e provalo con un piccolo compito.
Un file AGENTS.md è un semplice file Markdown nella radice del repository che spiega agli agenti di programmazione come lavorare sul progetto: quali comandi eseguire, dove si trova il codice e cosa non toccare. Non ha sezioni obbligatorie. Tienilo breve, rendi verificabile ogni regola e controlla che ogni agente lo carichi.
Questa guida spiega cosa includere, offre un modello, mostra come Claude Code e Gemini CLI trovano il file e propone una prova veloce. Gli stessi passaggi valgono quando avvii gli agenti dal telefono con Mono by Reunified.
1. Decidi cosa mettere nel file
Il sito agents.md lo definisce un README per gli agenti. Includi le informazioni che servono a ogni sessione e tralascia tutto ciò che l’agente può ricavare dal codice.
| Mettilo in AGENTS.md | Lascialo fuori |
|---|---|
| Comandi di installazione, test e lint | Password, chiavi API e token |
| Dove si trova il codice principale | Un albero completo dei file o l’elenco delle dipendenze |
| Convenzioni diverse da quelle predefinite | Procedure lunghe (rimanda invece a un documento) |
| File da non modificare mai, azioni per cui chiedere prima | Preferenze personali (usa il file a livello utente del tuo agente) |
In un monorepo puoi aggiungere un AGENTS.md dentro ogni pacchetto. Ha la precedenza il file più vicino, e un’istruzione diretta nella chat prevale su di esso.
2. Parti da un modello breve
Ecco un esempio inventato per «tidy-recipes», un’app web in TypeScript che usa pnpm:
# AGENTS.md
## Overview
TypeScript web app for saving recipes. Components live in src/components.
## Setup
- `pnpm install`
## Test and lint
- `pnpm test` and `pnpm lint`
## Code style
- TypeScript only. One component per file.
## Boundaries
- Never edit db/migrations/.
- Ask before adding a dependency.
## Before you finish
- Run `pnpm test` and `pnpm lint`.
- List the files you changed and the test results.Elenca solo comandi che hai eseguito in questo repository. L’agente si fiderà anche di un comando sbagliato.
3. Scrivi regole verificabili per l’agente
Una buona regola ti permette di controllare in seguito se l’agente l’ha rispettata.
| Vaga | Concreta |
|---|---|
| Testa le tue modifiche | Esegui pnpm test e pnpm lint prima di finire |
| Tieni i file in ordine | I componenti vanno in src/components |
| Fai attenzione al database | Non modificare mai db/migrations/ |
| Riassumi il tuo lavoro | Elenca i file modificati e i risultati dei test |
Scrivi i limiti come regole «mai» e «chiedi prima», una per riga.
4. Fai leggere il file a Claude Code e Gemini CLI
Il sito agents.md elenca Codex, Gemini CLI, opencode e altri agenti che supportano il formato, ma alcuni richiedono prima un’impostazione.
Per impostazione predefinita, le versioni recenti di Claude Code leggono AGENTS.md solo se non c’è un CLAUDE.md, un .claude/CLAUDE.md o un CLAUDE.local.md nella cartella di lavoro o in una cartella superiore (vedi la sua documentazione sulla memoria). Se hai uno di questi file o una versione meno recente, importa AGENTS.md da CLAUDE.md. Il progetto tidy-recipes ha un vecchio CLAUDE.md, quindi aggiungi questa riga in cima e tieni sotto le note valide solo per Claude:
@AGENTS.md
Prefer small commits.Avvia una nuova sessione, esegui /context e controlla che CLAUDE.md compaia tra i file di memoria (Memory files). Senza un CLAUDE.md, /memory mostra invece il percorso di AGENTS.md.
Gemini CLI legge GEMINI.md per impostazione predefinita. Per aggiungere AGENTS.md, inserisci questo nel file .gemini/settings.json del progetto (vedi la sua documentazione su GEMINI.md):
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}Avvia una nuova sessione, poi esegui /memory show per vedere cosa è stato caricato. Per gli altri agenti, consulta la loro documentazione.
5. Prova il file con un piccolo compito
In una nuova sessione, assegna all’agente questo compito:
Prima elenca le regole del progetto che hai caricato e il file da cui proviene ciascuna. Poi cambia il testo del pulsante «Save recipe» in «Save» in src/components/SaveButton.tsx. Non cambiare nient’altro.
Confronta il risultato con il file:
- Ha citato AGENTS.md (o CLAUDE.md con l’importazione).
- Ha eseguito
pnpm testepnpm linte ha riportato i risultati. - Non ha toccato db/migrations/ e non ha aggiunto dipendenze.
- Ha elencato i file che ha modificato.
Verifica tu stesso la modifica con git diff (vedi come rivedere le modifiche al codice dell’IA). Se l’agente non sa citare una regola, probabilmente il file non è stato caricato, quindi torna al passaggio 4. Se ha citato una regola ma non l’ha rispettata, rendila più concreta.
6. Tienilo breve e aggiornato
La documentazione di Claude Code suggerisce di tenere CLAUDE.md sotto le 200 righe, perché i file più lunghi occupano più contesto e vengono seguiti con meno affidabilità. Punta allo stesso obiettivo con AGENTS.md. La guida alla finestra di contesto spiega cosa succede quando il contesto si riempie.
Aggiorna il file quando un agente ripete un errore, ed elimina i comandi superati e le regole in conflitto. Fanne il commit e rivedi le sue modifiche come faresti con il codice.
Il file guida l’agente, ma non impone nulla. Per bloccare un’azione, usa le impostazioni dei permessi dell’agente o rifiuta la sua richiesta (vedi la guida ai permessi degli strumenti).
In Mono, l’agente parte dalla cartella di lavoro del progetto sul tuo computer, dove cerca questi file. Puoi aprire AGENTS.md, CLAUDE.md o .gemini/settings.json nell’editor di Mono, anche dal telefono, e le modifiche si salvano da sole. Per creare il file, chiedilo all’agente o apri un terminale dalla scheda del progetto. Mono non controlla il file e non cambia quale file carica un agente. Mono non è ancora disponibile, ma puoi iscriverti alla lista d’attesa.
