Il problema: perché l’AI sbaglia sempre nello stesso punto

Chi usa Cursor, Windsurf o Claude Code per scrivere codice conosce bene la frustrazione: l’AI butta fuori un blocco di codice, tu lo incolli, lo lanci — build rotto, test rossi, dipendenze installate nel posto sbagliato. Il problema non è l’intelligenza dell’AI, è che non conosce le “regole non scritte” del tuo progetto.

AGENTS.md è un file Markdown nella root del progetto, scritto apposta per l’AI: gli dice come buildare, come testare, quali convenzioni rispettare. Il README.md è per gli umani, pieno di presentazioni, guide al contributo, storie del brand. Quando l’AI legge quel contenuto, è come un neoassunto che il primo giorno riceve un dépliant aziendale e subito deve scrivere codice — sa cosa fa l’azienda, ma non conosce il comando di build, non sa come si lanciano i test, non sa quali regole ESLint seguire. Risultato: ogni conversazione diventa un loop di correzioni — “usa pnpm, non npm”, “i test stanno in packages/web”, “non dimenticare il lint”. Ripeti la stessa cosa cento volte, il progetto resta un caos.

Nel lavoro su commissione il danno è diretto: prendi un esterno Next.js + Prisma, acceleri con Cursor, e l’AI installa con npm install mandando in pezzi la configurazione workspace di pnpm; non sa dove sta lo schema del database e genera migration che esplodono. Il cliente preme per la consegna, tu passi tre ore a debuggare codice generato dall’AI — soldi guadagnati con l’amaro in bocca.

Tre scenari classici in cui l’AI ignora le regole del progetto: ① package manager sbagliato (il progetto usa pnpm, l’AI di default fa npm install), dipendenze nel posto sbagliato, workspace fuori uso; ② test non trovati (i test stanno in packages/web, l’AI lancia pnpm test dalla root e ottiene “file di test non trovato”); ③ stile incoerente (il progetto usa ESLint + Prettier, l’AI genera codice con indentazione e virgolette sbagliate, la CI si blocca).

L’opportunità: AGENTS.md separa “documenti per umani” e “documenti per macchine”

Il progetto open source AGENTS.md su GitHub (repo github.com/agentsmd/agents.md, circa 24.000 stelle al 25-08-2026) risolve esattamente questo. L’idea è semplice: un file Markdown nella root che spiega all’AI come buildare, testare e che stile di codice seguire.

Non sostituisce il README, lo affianca. Il README serve ai contributor umani, AGENTS.md serve agli agenti AI. Ruoli separati, zero interferenze.

Stando al post originale, AGENTS.md è già adottato da decine di migliaia di progetti open source (numero da verificare) e supportato dai principali strumenti di coding AI: VS Code, Cursor, Windsurf, Aider, GitHub Copilot (confermato). Inoltre, secondo feedback della community, anche OpenAI Codex e Google Jules offrono supporto (⚠️ non verificato). Se non lo impari adesso, stai lasciando che l’AI ti parli in dialetto.

Percorso 1: scrivere a mano un AGENTS.md minimo

Costo quasi zero. Crei il file, scrivi tre sezioni e sei a posto.

Prima di tutto: gli esempi qui sotto usano pnpm (più leggero di npm e con supporto nativo ai workspace monorepo), turbo è l’orchestratore di task per monorepo, il parametro --filter limita l’esecuzione a un singolo sotto-pacchetto senza toccare il resto del repo.

Sezione 1 “Dev environment tips”: dici all’AI quale package manager usi, come saltare tra sotto-pacchetti, come crearne di nuovi. Esempio dal template ufficiale:

• pnpm dlx turbo run where <project_name> — salta diretto nella cartella del sotto-pacchetto, niente ls a ripetizione
• pnpm install --filter <project_name> — installa le dipendenze solo di un sotto-pacchetto, senza toccare l’intero monorepo
• pnpm create vite@latest <project_name> -- --template react-ts — crea un nuovo sotto-pacchetto React + Vite con TypeScript

Comandi che l’AI non indovina da sola, ma se li scrivi li esegue.

Sezione 2 “Testing instructions”: spieghi come lanciare i test, dove sta la pipeline CI, quali check sono obbligatori prima di un commit. Esempio ufficiale:

• pnpm turbo run test --filter <project_name> — lancia tutti i check del sotto-pacchetto
• pnpm vitest run -t "<test name>" — esegue solo il test che matcha quel nome
• “Fix any test or type errors until the whole suite is green” — non si molla finché non è tutto verde
• “Add or update tests for the code you change, even if nobody asked” — questa è la riga chiave: senza, l’AI salta i test ogni volta che può

Sezione 3 “PR instructions”: formato del titolo del commit, lint e test obbligatori. Esempio ufficiale: Title format: [<project_name>] <Title> e “Always run pnpm lint and pnpm test before committing”.

Meno di 50 righe in totale, ma la percentuale di codice AI che passa al primo colpo sale in modo evidente (dato dalla community, numeri precisi da verificare).

Percorso 2: uso annidato nei monorepo grandi

Se lavori su progetti enterprise con struttura monorepo (più progetti correlati nello stesso repo Git, ad esempio frontend, backend e codice condiviso in sotto-cartelle separate), un singolo AGENTS.md non basta. AGENTS.md supporta l’annidamento: metti un file dedicato in ogni sotto-cartella e l’AI carica automaticamente “quello più vicino”.

Come si fa in pratica: l’AGENTS.md nella root contiene le regole globali (package manager, flusso CI, note di sicurezza), poi in packages/web/, packages/api/, packages/shared/ ne metti uno per ciascuno, con i comandi di build specifici, l’ingresso dei test, le dipendenze particolari. Esempio: il pacchetto frontend deve dire “libreria componenti shadcn, stile Tailwind, icone lucide-react”; il pacchetto backend deve dire “migration database con Prisma, route API in src/routes, autenticazione JWT”.

Quando l’AI lavora in una sotto-cartella, carica l’AGENTS.md più vicino, con priorità superiore a quello root. Nello stesso progetto, l’assistente AI del frontend e quello del backend ricevono istruzioni diverse, zero confusione.

Percorso 3: trasformalo in un vantaggio competitivo nelle commesse

Il mercato delle commesse con AI è già saturo — tutti usano Cursor, ma la qualità della consegna è altalenante. Se nella proposta scrivi “il progetto è dotato di documentazione standard AGENTS.md, lo sviluppo assistito da AI segue le convenzioni del progetto”, batti chi si limita a dire “uso l’AI per scrivere codice”.

Tattica concreta: appena preso l’incarico, spendi 30 minuti per capire la struttura del progetto del cliente e scrivi un AGENTS.md su misura. Quel file fa parte della consegna — il cliente, in futuro, potrà usare l’AI per mantenere il codice senza tribolare.

Prezza il servizio di setup AGENTS.md come voce separata (adatta i prezzi al mercato italiano): versione base 70€ (configurazione singolo file + README esplicativo), versione enterprise 400€ (annidamento monorepo + policy di sicurezza + formazione team). Cosa consegni: ① file AGENTS.md su misura ② 30 giorni di supporto via chat ③ video di formazione da 10 minuti. Adatto a: clienti che hanno già l’abbonamento Cursor/Windsurf ma non riescono a sfruttarlo. Non adatto a: clienti che lavorano ancora solo manuale, senza tool AI.

Caso studio: il fossato della compatibilità di AGENTS.md

AGENTS.md è rilasciato sotto licenza MIT (confermato dai materiali), mantenuto dalla community (struttura di governance da verificare), sito ufficiale agents.md.

La compatibilità è il suo fossato più grande: confermato che VS Code, Cursor, Windsurf, Aider e GitHub Copilot leggono AGENTS.md; secondo la community, anche OpenAI Codex, Claude Code, Gemini CLI e Google Jules offrono supporto (⚠️ non verificato). Scrivi un file e funziona con tutti gli assistenti principali — niente configurazioni separate per ogni tool.

Confronto con le alternative: .cursorrules di Cursor vale solo per Cursor, su Windsurf non funziona; CLAUDE.md di Claude Code serve solo Claude; il sistema di istruzioni di GitHub Copilot è ancora un’altra storia. La caratteristica “scrivi una volta, gira ovunque” di AGENTS.md è il motivo per cui si è diffuso così in fretta.

Costo di migrazione tra tool azzerato. Oggi usi Cursor, domani passi a Windsurf, AGENTS.md si riusa senza riscrivere nulla.

Call to action: stasera aggiungi un manuale macchina al tuo progetto

Checklist da 5 minuti: ① apri la root del progetto ② crea AGENTS.md ③ copia il template ufficiale (github.com/agentsmd/agents.md) ④ inserisci tre comandi (build, test, lint) ⑤ al prossimo task con l’AI guarda cosa succede.

Se lavori su un monorepo, stasera spendi altri 20 minuti per aggiungere una configurazione annidata a ogni sotto-pacchetto. Domani mattina scopri che il codice generato dall’AI non ha più bisogno di correzioni continue.

AGENTS.md è oggi la configurazione di coding AI con il ROI più alto — 30 minuti di setup per risparmiare ore di debug ogni mese.