Scrivere istruzioni per un agente: CLAUDE.md, AGENTS.md e regole di Cursor

Quasi tutti gli strumenti di coding con AI leggono un file di istruzioni a inizio sessione: è il modo per dire all’agente come funziona il tuo progetto senza ripeterlo a ogni richiesta. I nomi cambiano, l’idea è la stessa.

Come si chiamano

• CLAUDE.md per Claude Code.
• AGENTS.md per Codex, e sempre più spesso anche per altri strumenti che adottano la stessa convenzione.
• Le regole di Cursor, nella cartella .cursor/rules (in passato un singolo .cursorrules).

Le convenzioni evolvono in fretta: controlla la documentazione dello strumento che usi. Il contenuto utile, però, resta quasi identico.

Cosa metterci

• I comandi che l’agente deve conoscere: installare, avviare, fare la build, lanciare i test e il linter.
• La struttura del repository in poche righe: dove sta il codice, dove i contenuti, cosa viene generato.
• Le convenzioni che non si deducono dal codice: nomi, stile dei commenti, librerie da preferire o da evitare.
• Cosa non toccare: file generati, cartelle di terze parti, configurazioni sensibili.
• La definizione di «fatto»: la build passa, i test passano, l’aspetto è stato controllato.
• Le regole sul flusso di lavoro, per esempio quando si può fare un commit.

Un esempio breve

# Progetto
Portfolio React + Vite. Contenuti in src/content.js, stili in src/styles.css.

## Comandi
- npm run dev   avvia il server di sviluppo
- npm run build compila e genera le pagine statiche

## Regole
- Nessuna nuova dipendenza senza chiedere.
- Testi in italiano e in inglese: aggiorna entrambi.
- Non fare commit: lo decido io.

## Fatto significa
- La build passa e la pagina è stata controllata su mobile e desktop.

Tienilo corto

Un file lungo viene letto peggio e invecchia in fretta. Scrivi solo ciò che l’agente non può ricavare da solo guardando il codice. Se una regola è ovvia leggendo tre file, non serve.

Ogni errore ripetuto diventa una riga

Il trucco più utile: quando l’agente sbaglia due volte la stessa cosa (usa la libreria sbagliata, dimentica la lingua inglese, cambia un file generato), non correggere a voce. Aggiungi una riga al file. È un investimento di dieci secondi che vale per tutte le sessioni future, e per chiunque altro lavori con quel repository.

Evita di metterci segreti, chiavi o dati dei clienti: il file è parte del repository.