DESIGN.md: il file dopo AGENTS.md

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 essere superato e i percorsi da non modificare. DESIGN.md registra le decisioni già consolidate e descrive cosa si rompe quando una di esse viene annullata.

Un agente di coding, cioè uno strumento come Claude Code o Cursor che legge e modifica autonomamente il repository, tende a operare con sicurezza. Quando trova un pattern che non riconosce, cerca di migliorarlo. Una cache scritta manualmente può diventare Redis (un archivio dati in memoria), perché nella maggior parte del codice letto dal modello una cache ha quell’aspetto. AGENTS.md non impedisce questo comportamento, perché make test va a buon fine in entrambi i casi. La regola violata non era mai stata scritta in un punto che l’agente potesse leggere.

Se non hai ancora creato il primo file, inizia da lì. AGENTS.md e il file HUMAN.md che si trova accanto descrive il formato e indica dove ogni strumento cerca questi file. Questo è il capitolo successivo.

Cosa contiene realmente un DESIGN.md pubblicato

Il modo più rapido per imparare il formato è leggere i file che le aziende pubblicano su se stesse. Il repository official-design-md tiene traccia solo di questi file. La regola di inclusione è una sola riga, e quella riga è 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.

A ottobre 2026 ne elenca undici: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel e VoltAgent. Ogni file è disponibile a un URL pubblico, nella maggior parte dei casi sul dominio del rispettivo editore e, negli altri casi, in un repository GitHub pubblico. È quindi possibile leggerne uno subito 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 l'aspetto che dovrebbe avere un prodotto: colori, tipografia, spaziatura e animazioni. È utile andare oltre l'argomento specifico, perché l'aspetto interessante è la struttura del testo, non il tema trattato.

A ottobre 27, 2026, il file di Nuxt contiene circa 2,000 parole e la maggior parte del testo è costituita da una regola accompagnata dalla relativa motivazione. Si apre specificando che il tema predefinito è la modalità scura. Elenca il verde del brand #00DC82 con una nota che indica: "Per loghi, immagini per i social e stampa. Non usare questi valori direttamente nel codice dell'interfaccia utente." Verso la fine, una sezione intitolata Reject these include:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

Il file di Vercel è più lungo, circa 6,000 parole a ottobre 2026, e si spinge un passo oltre. Uno dei suoi titoli è Reject generated-design reflexes. Sotto il titolo è presente un elenco degli elementi 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 affinché il modello smetta di produrli. Ogni DESIGN.md che vale la pena includere nel repository rappresenta quell'elenco per uno specifico dominio.

Perché le aziende pubblicano il proprio DESIGN.md?

La community è arrivata prima. awesome-design-md contiene 84 file estratti da siti web pubblici, secondo il conteggio riportato nel README al 27 ottobre 2026. Ogni file segue lo stesso formato in nove sezioni, così un agente può riceverne uno come riferimento e produrre qualcosa di simile a quell'aspetto. Questi file sono utili, ma restano supposizioni. Nessuno dei loro contenuti è stato verificato dalle aziende esaminate.

Un file ufficiale è diverso perché rappresenta la fonte, non un'interpretazione del risultato. Quando Vercel modifica la propria scala tipografica, vercel.com/design.md cambia di conseguenza. Una copia estratta a marzo continua a insegnare al tuo agente la vecchia scala, e nel repository non c'è nulla che segnali che la copia sia diventata obsoleta.

Undici editori sono ancora un numero limitato, 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 monitoraggio dell'adozione e non un censimento neutrale. Vale comunque la pena seguirlo, per le aziende che ne fanno parte. Diverse sono tra quelle il cui codice front-end viene copiato più spesso dagli altri sviluppatori, mentre le voci più recenti, Ant Design, Microsoft FAST, Juspay e Oxide Computer, sono design system su cui si basano altri team. I loro file stanno diventando l'esempio concreto di ciò che è un DESIGN.md. Basta confrontare il percorso seguito da AGENTS.md: agents.md conta ormai oltre 60,000 progetti open source che usano il formato, e la gestione è affidata alla Agentic AI Foundation presso la Linux Foundation. DESIGN.md ha iniziato a seguire lo stesso percorso. Il 21 aprile 2026, Google ha pubblicato come open source una bozza di specifica per il formato, disponibile in google-labs-code/design.md, con uno schema per i token e una CLI distribuiti con licenza Apache-2.0. A ottobre 2026 il formato è alla versione alpha ed è ancora in fase di sviluppo attivo; è gestito da Google Labs e non da una fondazione neutrale, inoltre descrive un'identità visiva, quindi non definisce nulla sugli invarianti necessari in un file per il backend. Le convenzioni per i file leggibili dagli agenti si stanno stabilizzando rapidamente, e lo fanno partendo dai principali attori.

Cosa inserire in 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 mantiene comunque la propria utilità, 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 ciascuno, che descriva qualcosa che deve rimanere vero dopo ogni modifica. "Ogni scrittura passa da queue.enqueue(). Una scrittura diretta nel database bypassa il log di audit, che è la sorgente utilizzata dall'esportazione per la conformità." Un invariante accompagnato dal motivo resiste anche a un'attività imprevista. Un invariante privo di motivazione sembra una preferenza, e le preferenze vengono eliminate durante l'ottimizzazione.

Alternative rifiutate. L'opzione più ovvia e il motivo per cui è stata scartata. "Non usiamo Redis per la cache. Il servizio viene eseguito su un singolo VPS, quindi una mappa in-process è più veloce e richiede un daemon in meno da mantenere attivo. Rivalutare questa scelta quando sarà disponibile un secondo application server." Senza questo paragrafo, se si chiede a un agent 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 molto ampio. Lo schema del database. Il prefisso delle route pubbliche utilizzato dagli script dei clienti. Il file di configurazione che un deploy legge prima dell'avvio dell'applicazione. La voce cron che presuppone l'esecuzione di una sola copia. Elencali e specifica il costo di una modifica a ciascuno. Se l'agent può anche accedere al web aperto, ad esempio tramite un'istanza self-hosted di SearXNG configurata come backend di ricerca, anche questo è un confine da documentare, perché il file deve indicare quale testo recuperato può influenzare il codice e quale deve essere soltanto riportato all'utente.

Vocabolario. Se il codice usa tenant e il team usa customer, documenta la corrispondenza. Un agent che la interpreta in modo errato produce codice formalmente corretto ma basato su un modello sbagliato. È 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 oggi le due sezioni che sai scrivere a memoria: invarianti e alternative rifiutate, e lascia il resto come titoli. Un file con quattro righe oneste è utile. Un file con quaranta righe congetturali no. Se il repository contiene più pacchetti, un unico file nella directory radice non sarà adatto a tutti. In questo caso si applica la stessa suddivisione per directory valida per i file AGENTS.md annidati in un monorepo: un file breve nella directory radice per le decisioni condivise da tutto il repository e uno più piccolo accanto a ciascun pacchetto che ha esigenze proprie.

Alcuni strumenti caricano ogni file markdown presente nella directory radice del repository, mentre altri caricano soltanto quello indicato esplicitamente. Non dare quindi per scontato il comportamento. 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 è ben scritta, ma non insegna nulla. Inizia spiegando cosa fa il progetto, elenca le funzionalità, descrive come installarlo e termina con la licenza. Tutto questo è già nel README e nessuna di queste informazioni spiega perché le scelte siano state fatte in quel modo.

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

Il secondo costo è peggiore. Due copie della stessa informazione finiscono per divergere. Il README dice che il servizio è in ascolto sulla porta 8080, mentre DESIGN.md indica ancora la porta 3000. L'agente non ha modo di stabilire quale delle due informazioni abbia la priorità, quindi ne sceglie una e scrive il codice di conseguenza. Un file che a volte contiene informazioni errate viene consultato con la stessa fiducia riservata a un file che è sempre corretto.

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

Come si verifica che il file stia funzionando?

Non esiste un linter per questo file. È possibile eseguire un controllo in un minuto.

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

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

Questo aspetto è particolarmente importante quando l'agente viene eseguito su un server anziché 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 in chat e non hai sottoposto a commit scompare nella sessione successiva. DESIGN.md è il punto in cui inserire questa spiegazione, in modo che rimanga disponibile.

Inizia dalle decisioni che generano discussioni

La prima versione richiede venti minuti. Apri le ultime pull request in cui un reviewer ha scritto «no, qui facciamo diversamente». 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 fissa. Se stai ancora definendo come integrare gli agent nel normale flusso di sviluppo, la guida 2026 per imparare a usare gli agent AI è un buon punto di partenza.

FAQ

DESIGN.md è uno standard ufficiale?

Non nel senso in cui lo è AGENTS.md. AGENTS.md ha un sito ufficiale all'indirizzo agents.md, è utilizzato da oltre 60,000 progetti open source ed è gestito dalla Agentic AI Foundation, parte della Linux Foundation. DESIGN.md dispone di una specifica pubblicata, ma non di un organismo indipendente che ne garantisca la gestione. Google ha pubblicato come open source una bozza della specifica il 21 aprile 2026, disponibile nel repository google-labs-code/design.md con licenza Apache-2.0. A ottobre 2026 è alla versione alpha ed è ancora in fase di sviluppo attivo; descrive un'identità visiva: colori, tipografia, layout e componenti. DESIGN.md ha anche adottanti ufficiali: undici aziende e progetti, tra cui Vercel, Nuxt, Atlassian e Resend, ne pubblicano uno, mentre una raccolta della community ne contava altri 84 estratti da siti pubblici al 27 ottobre 2026. Per un file backend che definisce invarianti e alternative rifiutate, consideralo una convenzione che puoi adottare subito ed estendere liberamente, perché nessuna specifica definisce quei nomi di sezione.

DESIGN.md dovrebbe essere soltanto una sezione di AGENTS.md?

Per un repository di piccole dimensioni, sì. Un unico file che l'agente legge sicuramente è preferibile a due file, se uno dei due viene ignorato. Separali quando AGENTS.md non è più facilmente consultabile 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 più rara e più importante. Quando li separi, aggiungi una riga ad AGENTS.md per indicare all'agente di leggere DESIGN.md prima di modificare il codice, perché non tutti gli strumenti caricano ogni file markdown nella directory root.

In cosa DESIGN.md differisce da un architecture decision record?

Un ADR (architecture decision record) è la registrazione datata di una singola decisione, e un progetto sano ne accumula decine in una directory. Questo costituisce una cronologia, e la cronologia è costosa da caricare, perché l'agente dovrebbe leggerli tutti per stabilire quali siano ancora validi. DESIGN.md rappresenta lo stato attuale ed è scritto per essere letto integralmente a ogni attività. Mantienili entrambi se già scrivi ADR. 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 dovrebbe 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: a ottobre 2026 il file di Nuxt contiene circa 2,000 parole e quello di Vercel circa 6,000. Un servizio backend di solito richiede molto meno. Inizia con una pagina e allungalo solo quando un agente commette un errore che una singola frase avrebbe potuto evitare. La lunghezza non è il criterio. Ogni riga dovrebbe descrivere qualcosa che altrimenti l'agente sbaglierebbe.