DESIGN.md: il file dopo AGENTS.md per l’AI

Che cos’è DESIGN.md e cosa non copre AGENTS.md

DESIGN.md è un file Markdown nella directory radice del repository. Spiega a un agente di coding basato sull’AI perché il codice è strutturato in quel modo. AGENTS.md risponde a una domanda diversa: come lavorare nel repository. Specifica il comando di build, il comando per eseguire i test, il lint che deve avere esito positivo e i percorsi da non modificare. DESIGN.md documenta le decisioni già definite e ciò che si rompe quando una di queste viene annullata.

Un agente di coding, cioè uno strumento come Claude Code o Cursor che legge e modifica autonomamente il repository, opera per impostazione predefinita con grande sicurezza. Quando trova un pattern che non riconosce, tende a migliorarlo. Una cache scritta manualmente diventa Redis, un archivio dati in memoria, perché è così che appare una cache nella maggior parte del codice analizzato dal modello. AGENTS.md non impedisce questo comportamento, perché make test funziona in entrambi i casi. La regola violata non era mai stata scritta in un punto che l’agente potesse leggere.

Se non hai ancora scritto il primo file, inizia da lì. AGENTS.md e HUMAN.md che si trova accanto descrive il formato e i percorsi che ogni strumento esamina. Questo è il capitolo successivo.

Cosa contiene realmente un DESIGN.md pubblicato

Il modo più rapido per capire il formato consiste nel leggere i file che le aziende pubblicano su se stesse. Il repository official-design-md raccoglie esclusivamente questi file. La regola di inclusione è una sola riga, ed è il punto centrale della raccolta:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

Ad agosto 2026 ne elenca sette: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel e VoltAgent. Ogni file si trova a un URL pubblico stabile, quindi puoi leggerne subito uno da un terminale.

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

Entrambi sono documenti relativi a un design system. Descrivono come deve apparire un prodotto: colori, tipografia, spaziatura e animazioni. Vai oltre l'argomento specifico, perché l'aspetto utile è la struttura del testo, non il tema trattato.

Il file di Nuxt contiene circa 2.100 parole e gran parte del contenuto consiste in una regola accompagnata dalla relativa motivazione:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

Il file di Vercel è più lungo, circa 6.500 parole ad agosto 2026, e si spinge oltre. Uno dei suoi titoli è Reject generated-design reflexes. Sotto il titolo compare un elenco di ciò a cui ricorre un generatore capace quando nessuno gli ha detto di non farlo:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

Questa frase definisce il tipo di file. È un elenco scritto dei valori predefiniti che un modello sicuro di sé produce, pubblicato per impedire al modello di produrli. Ogni DESIGN.md che vale la pena aggiungere a un repository contiene questo elenco per uno specifico dominio.

Perché le aziende pubblicano il proprio DESIGN.md?

La community è arrivata per prima. awesome-design-md contiene 73 file ricavati tramite reverse engineering da siti web pubblici. Ogni file segue lo stesso formato articolato in nove sezioni. In questo modo, è possibile indicare un file a un agente e ottenere un risultato visivo simile. Questi file sono utili, ma restano ipotesi. Nessuno nelle aziende interessate li ha revisionati.

Un file pubblicato dall'azienda stessa è diverso, perché rappresenta la fonte e non un'interpretazione del risultato. Quando Vercel modifica la propria scala tipografica, anche vercel.com/design.md viene aggiornato. Una copia acquisita tramite scraping a marzo continua a insegnare al tuo agente la vecchia scala. Nulla nel repository segnala che la copia non è più aggiornata.

Sette aziende sono poche, e il repository lo dichiara apertamente: lo standard è recente e l'adozione ufficiale è in crescita. Entrambe le raccolte sono gestite da VoltAgent, un framework open source per agenti che pubblica a sua volta il proprio file. Perciò, considera l'elenco un tracker e non un censimento neutrale. Vale comunque la pena seguirlo, per via delle sette aziende incluse. Sono le aziende il cui codice front-end viene copiato più spesso da altri sviluppatori, e i loro file stanno diventando l'esempio pratico di ciò che è un DESIGN.md. Basta confrontare il percorso seguito da AGENTS.md: agents.md conta oggi oltre 60,000 progetti open source che usano questo formato, e la gestione è affidata alla Agentic AI Foundation presso la Linux Foundation. Le convenzioni per i file leggibili dagli agenti si stanno definendo rapidamente, partendo dai principali attori.

Cosa inserire in un DESIGN.md quando il progetto non ha un'interfaccia utente

La maggior parte del software eseguito su un VPS non ha un linguaggio visivo da definire. Il file è comunque utile, perché il meccanismo non ha nulla a che vedere con i colori. Serve a documentare i vincoli che un editor esperto violerebbe altrimenti senza accorgersene.

Invarianti. Una frase per ciascuna, che descriva qualcosa che deve rimanere vero dopo qualsiasi modifica. «Ogni scrittura passa da queue.enqueue(). Una scrittura diretta nel database esclude il log di audit, che è la sorgente letta dall'esportazione per la conformità.» Un'invariante accompagnata dalla relativa motivazione resiste anche a un'attività non prevista. Un'invariante priva di motivazione sembra una preferenza, e le preferenze vengono eliminate durante l'ottimizzazione.

Alternative scartate. L'opzione più ovvia e il motivo per cui è stata scartata. «Non usiamo Redis per il caching. Il servizio viene eseguito su un singolo VPS, quindi una mappa in-process è più veloce e c'è un demone in meno da mantenere attivo. Rivalutare questa scelta quando sarà presente un secondo application server.» Senza questo paragrafo, se si chiede a un agente di velocizzare la cache, l'aggiunta di Redis è una scelta corretta: non gli è stato comunicato il vincolo. Questa è la sezione che giustifica l'intero file.

Confini. I punti in cui una piccola modifica può avere un impatto esteso. Lo schema del database. Il prefisso delle route pubbliche su cui i clienti hanno già basato i propri script. Il file di configurazione letto durante il deploy prima dell'avvio dell'applicazione. La voce cron che presuppone l'esecuzione di una sola copia. Indicateli e specificate il costo di una modifica per ciascuno.

Vocabolario. Se il codice usa tenant e il team usa customer, documentate la corrispondenza. Un agente che interpreta male questo punto produce codice apparentemente corretto, ma basato su un modello errato: è il tipo di errore più difficile da individuare durante la revisione.

Un DESIGN.md che puoi copiare oggi

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

Compila le due sezioni che oggi puoi scrivere a memoria: invarianti e alternative rifiutate. Lascia il resto come semplici titoli. Un file con quattro righe verificate è utile. Un file con quaranta righe ipotizzate non lo è.

Alcuni strumenti caricano ogni file Markdown nella directory root del repository, mentre altri caricano soltanto quello indicato esplicitamente. Non dare quindi nulla per scontato. Aggiungi un riferimento ad AGENTS.md:

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

L’anti-pattern: un DESIGN.md che ripete il README

La versione errata più comune è scorrevole, ma non insegna nulla. Inizia spiegando cosa fa il progetto, elenca le funzionalità, illustra come installarlo e termina con la licenza. Tutte queste informazioni sono già nel README e nessuna spiega perché le scelte siano state fatte in quel modo.

Questo comporta un doppio costo. Il primo è il contesto. Un file che l’agent legge all’inizio di ogni attività viene pagato a ogni attività, mentre una sezione di installazione duplicata è puro sovraccarico a fronte di una finestra di contesto fissa. La gestione di questa finestra è una competenza specifica, descritta in gestire la finestra di contesto in Claude Code. In breve: tutto ciò che viene caricato automaticamente deve essere il testo con il valore più alto nel repository.

Il secondo costo è peggiore. Due copie della stessa informazione finiscono per divergere. Il README indica che il servizio è in ascolto sulla porta 8080, mentre DESIGN.md indica ancora 3000; l’agent non ha modo di stabilire quale versione sia prioritaria, quindi ne sceglie una e scrive il codice di conseguenza. Un file che a volte è errato viene consultato con la stessa fiducia riservata a un file sempre corretto.

La verifica è rapida. Se un paragrafo potrebbe stare senza problemi nel README, rimuovilo da DESIGN.md. Ciò che resta dovrebbe essere la parte che diresti ad alta voce durante una code review, quella che inizia con «ci abbiamo già provato».

Come si verifica che il file venga applicato?

Non esiste un linter per questo file. Esiste un controllo che puoi eseguire in un minuto.

Assegna all'agente un'attività che porti direttamente a un'invariante. «Aggiungi un job in background che contrassegni come scadute le righe obsolete». Un file applicato correttamente si riconosce dalla risposta prima ancora di esaminare il codice: l'agente dovrebbe dirti che il job scrive tramite queue.enqueue(), perché una scrittura diretta bypasserebbe l'audit log. Se apre una connessione al database e scrive, una delle due condizioni è vera. Il file non viene letto affatto oppure l'invariante è formulata in modo abbastanza generico da poter essere contestata.

Controlla anche il numero di token, perché questo file viene caricato a ogni turno. Se l'uso del contesto aumenta dopo aver aggiunto DESIGN.md e le risposte non migliorano, il file contiene prosa che l'agente conosceva già. Lettura dei contatori dei token in Claude Code mostra dove viene utilizzato quel budget.

Questo aspetto è particolarmente importante quando l'agente viene eseguito su un server invece che sul tuo laptop. Un agente che lavora in una sessione persistente, come nella configurazione descritta in un workspace di Claude Code su un VPS con tmux, non conserva memoria della conversazione del giorno precedente. Il repository è la memoria. Tutto ciò che hai spiegato nella chat e non hai sottoposto a commit viene perso nella sessione successiva. DESIGN.md è il file in cui inserire quella spiegazione, così resterà disponibile.

Inizia dalle decisioni più controverse

La prima versione richiede venti minuti. Apri le ultime pull request in cui un revisore ha scritto «no, qui lo facciamo in modo diverso». Ognuno di questi commenti descrive un’invariante mai documentata e indica un punto in cui un agent commetterà lo stesso errore, più rapidamente e più spesso di una persona. Aggiorna il file quando ti crea un problema, non secondo una pianificazione prestabilita. Se stai ancora valutando come integrare gli agent in un normale flusso di sviluppo, la guida 2026 per imparare a usare gli agent AI è un buon passo successivo.

FAQ

DESIGN.md è uno standard ufficiale?

Non nello stesso senso di AGENTS.md. AGENTS.md ha un sito dedicato, agents.md, è utilizzato da oltre 60,000 progetti open source ed è gestito dalla Agentic AI Foundation, che fa parte della Linux Foundation. Ad agosto 2026 DESIGN.md non ha un ente di riferimento né una specifica pubblicata. Ha però un’adozione diretta da parte dei produttori: sette aziende, tra cui Vercel, Nuxt, Atlassian e Resend, ne pubblicano uno a un URL pubblico; inoltre, una raccolta della community ne contiene altri 73, ricavati tramite reverse engineering da siti pubblici. Consideralo una convenzione che puoi adottare subito ed estendere liberamente, perché non esiste alcun sistema che verifichi i nomi delle sezioni.

DESIGN.md deve essere semplicemente una sezione di AGENTS.md?

Per un repository piccolo, sì. Un singolo file che l’agente legge sicuramente è preferibile a due file, se uno dei due viene ignorato. Separali quando AGENTS.md non è più consultabile rapidamente o quando noti che le due parti cambiano con frequenze diverse. AGENTS.md cambia quando cambia la procedura di build. DESIGN.md cambia quando cambia una decisione, cosa che accade meno spesso e ha un impatto maggiore. Dopo averli separati, aggiungi ad AGENTS.md una riga che indichi all’agente di leggere DESIGN.md prima di modificare il codice, perché non tutti gli strumenti caricano ogni file markdown presente nella directory root.

In che modo DESIGN.md differisce da un architecture decision record?

Un ADR (architecture decision record) è un documento datato che registra una singola decisione. Un progetto gestito correttamente ne accumula decine in una directory. Si tratta di una cronologia, e caricarla è costoso, perché l’agente dovrebbe leggerli tutti per stabilire quali informazioni siano ancora valide. DESIGN.md descrive lo stato attuale ed è scritto per essere letto integralmente a ogni attività. Se utilizzi già gli ADR, continua a mantenere entrambi. L’ADR indica che cosa è stato deciso e quando. DESIGN.md indica che cosa è vero oggi ed è il file a cui indirizzare l’agente.

Quanto deve essere lungo un DESIGN.md?

Deve essere abbastanza breve da poter essere caricato a ogni turno senza rimpianti. Gli esempi pubblicati sono lunghi perché specificano un intero linguaggio visivo: ad agosto 2026 il file di Nuxt contiene circa 2,100 parole e quello di Vercel circa 6,500. Un servizio backend di solito richiede molto meno. Inizia con una pagina e amplialo solo quando un agente commette un errore che una singola frase avrebbe evitato. La lunghezza non è il criterio di misura. Ogni riga deve descrivere qualcosa che altrimenti l’agente sbaglierebbe.