DESIGN.md: il file da creare dopo AGENTS.md

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

DESIGN.md è un file Markdown nella directory principale del repository. Spiega a un agente di programmazione basato sull’IA perché il codice è strutturato in quel modo. AGENTS.md risponde a una domanda diversa: come lavorare in questo repository. Indica il comando di build, il comando di test, il lint che deve avere esito positivo e i percorsi da non modificare. DESIGN.md documenta le decisioni già consolidate e cosa si rompe quando una di queste decisioni viene annullata.

Un agente di programmazione, cioè uno strumento come Claude Code o Cursor che legge e modifica autonomamente il repository, tende ad agire con sicurezza. Quando trova un pattern che non riconosce, cerca di migliorarlo. Una cache scritta manualmente diventa Redis, un archivio dati in memoria, perché nella maggior parte del codice analizzato dal modello una cache è implementata in questo modo. AGENTS.md non impedisce questo comportamento, perché make test passa 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 HUMAN.md che si trova accanto ad esso descrive il formato e indica dove ogni strumento cerca il file. Quello che segue è il capitolo successivo.

Cosa contiene davvero un DESIGN.md pubblicato

Il modo più rapido per comprendere 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, e quella riga esprime l’intero obiettivo 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 l’aspetto che dovrebbe avere un prodotto: colori, tipografia, spaziatura e animazioni. Vai oltre l’argomento specifico, perché la parte utile è la struttura del testo, non il tema trattato.

Il file di Nuxt contiene circa 2.100 parole e la maggior parte del contenuto è costituita da 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 delle soluzioni a cui ricorre un generatore competente quando nessuno gli ha detto di evitarle:

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 valga la pena includere nel repository rappresenta quell’elenco per uno specifico dominio.

Perché le aziende pubblicano il proprio DESIGN.md?

La community è arrivata per prima. awesome-design-md raccoglie 73 file ricavati tramite reverse engineering da siti web pubblici. Ogni file usa lo stesso formato articolato in nove sezioni. In questo modo è possibile indirizzare un agente verso uno di essi e ottenere un risultato simile a quell’aspetto. Questi file sono utili, ma restano delle supposizioni. Nessuno dei dipendenti delle aziende li ha verificati.

Un file di prima parte è diverso perché è 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 all’agente la vecchia scala. Nel repository non ci sarà alcuna indicazione che la copia sia diventata obsoleta.

Sette publisher sono pochi, e il repository lo dichiara: 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 la natura dei sette publisher. Sono le aziende il cui codice front-end viene copiato più spesso dagli altri sviluppatori, e i loro file stanno diventando l’esempio concreto di ciò che è un DESIGN.md. Basta confrontare il percorso seguito da AGENTS.md: agents.md ora conta 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, e si stanno definendo a partire dai principali operatori.

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 resta comunque utile, perché il meccanismo non ha nulla a che vedere con i colori. Serve a documentare i vincoli che un editor esperto altrimenti violerebbe senza accorgersene.

Invarianti. Una frase per ciascuna, che descriva qualcosa che deve restare vero dopo qualsiasi modifica. "Ogni scrittura passa attraverso queue.enqueue(). Una scrittura diretta nel database salta il log di audit, che è la fonte utilizzata dall'esportazione per la conformità." Un invariante accompagnato dalla relativa motivazione 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 il caching. 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 quel paragrafo, a un agente incaricato di velocizzare la cache verrebbe naturale aggiungere Redis, e avrebbe ragione: non gli avete mai 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 letto dal 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. Se l'agente 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 specificare quale testo recuperato può influenzare il codice e quale deve essere soltanto riportato all'utente.

Vocabolario. Se nel codice si usa tenant e il team usa customer, documentate la corrispondenza. Un agente che fa un'ipotesi errata produce codice apparentemente corretto, ma basato sul concetto sbagliato. È il tipo di errore più difficile da individuare durante la revisione.

Un DESIGN.md che puoi creare 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 stesso le due sezioni che puoi scrivere a memoria: invarianti e alternative rifiutate. Lascia il resto come sole intestazioni. Un file con quattro righe verificate è utile. Un file con quaranta righe basate su supposizioni non lo è. Se il repository contiene più pacchetti, un unico file nella root non sarà adatto a tutti. In questo caso si applica la stessa suddivisione per directory descritta per i file AGENTS.md annidati in un monorepo: un breve file nella root per le decisioni condivise da tutto il repository e un file più piccolo accanto a ogni pacchetto che ha esigenze proprie.

Alcuni strumenti caricano tutti i file markdown nella root del repository, mentre altri caricano soltanto quello indicato esplicitamente. Non dare quindi per scontato quale file verrà utilizzato. 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 si legge bene, ma non insegna nulla. Inizia spiegando che cosa fa il progetto, elenca le funzionalità, descrive come installarlo e si conclude 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 due costi. Il primo è il contesto. Un file che l’agente legge all’inizio di ogni attività viene conteggiato in ogni attività, mentre una sezione di installazione duplicata è puro sovraccarico all’interno di una finestra di contesto fissa. La gestione di questa finestra richiede competenze specifiche, descritte in gestire la finestra di contesto in Claude Code. In sintesi: tutto ciò che viene caricato automaticamente deve avere il valore informativo 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 sia prioritaria, 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 sempre corretto.

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

Come si verifica che il file funzioni?

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

Assegnate all'agente un'attività che porti direttamente a una regola invariabile: "Aggiungi un job in background che contrassegni le righe obsolete come scadute". Un file che svolge correttamente il suo compito lo dimostra già nella risposta, prima ancora di qualsiasi codice: l'agente dovrebbe dirvi 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 condizioni è vera: il file non viene letto oppure la regola invariabile è formulata in modo abbastanza vago da poter essere contestata.

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

Questo aspetto è particolarmente importante quando l'agente viene eseguito su un server anziché sul vostro laptop. Un agente che opera in una sessione persistente, come nella configurazione descritta in un workspace Claude Code su un VPS con tmux, non conserva la memoria della conversazione del giorno precedente. Il repository è la memoria. Tutto ciò che avete spiegato in chat e non avete mai salvato nel repository viene perso nella sessione successiva. DESIGN.md è il punto in cui inserire queste spiegazioni, in modo che rimangano disponibili.

Inizia dalle decisioni oggetto di discussione

La prima versione richiede venti minuti. Apri le ultime pull request in cui un revisore ha scritto «no, qui facciamo diversamente». Ognuno di questi commenti descrive un’invariante che non è mai stata formalizzata e indica un punto in cui un agent commetterà lo stesso errore, più rapidamente e più spesso di una persona. Aggiorna il file quando l’agent commette un errore, non secondo una pianificazione prestabilita. Se stai ancora definendo come integrare gli agent in un 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 nello stesso senso di AGENTS.md. AGENTS.md ha un sito ufficiale all'indirizzo agents.md, viene usato 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 organismo 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, mentre 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é nulla valida i nomi delle sezioni.

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ù consultabile rapidamente oppure quando noti che le due parti cambiano con frequenze diverse. AGENTS.md cambia quando cambia la build. DESIGN.md cambia quando cambia una decisione, un evento più raro e più significativo. Quando li separi, 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 cosa DESIGN.md differisce da un architecture decision record?

Un ADR (architecture decision record) è la registrazione datata di una singola decisione, e un progetto ben gestito ne accumula decine in una directory. È una cronologia, e la cronologia è costosa da caricare, perché per capire quali decisioni siano ancora valide l'agente dovrebbe leggerle tutte. DESIGN.md rappresenta lo stato corrente ed è scritto per essere letto integralmente a ogni attività. Se già scrivi ADR, mantienili entrambi. L'ADR indica che cosa è stato deciso e quando. DESIGN.md indica che cosa è valido oggi ed è il file a cui indirizzare l'agente.

Quanto dovrebbe essere lungo un DESIGN.md?

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 conta circa 2,100 parole e quello di Vercel circa 6,500. In genere, un servizio backend richiede molto meno. Inizia con una pagina e amplialo soltanto quando un agente commette un errore che una singola frase avrebbe evitato. La lunghezza non è il criterio. Ogni riga dovrebbe descrivere qualcosa che altrimenti l'agente sbaglierebbe.