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’IA 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à stabilite e cosa si rompe quando una di queste decisioni viene annullata.

Un agente di coding, cioè uno strumento come Claude Code o Cursor che legge e modifica autonomamente il repository, tende a procedere con sicurezza. Quando trova un pattern che non riconosce, lo migliora. Una cache scritta manualmente diventa Redis, un archivio dati in memoria, perché questo è l’aspetto che una cache ha nella maggior parte del codice analizzato dal modello. AGENTS.md non lo impedisce, perché make test ha esito positivo 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 il file HUMAN.md che si trova accanto descrive il formato e indica dove lo cerca ciascuno strumento. Quello che segue è il capitolo successivo.

Che cosa contiene realmente un DESIGN.md pubblicato

Il modo più rapido per capire il formato è 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 è l'intero scopo 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 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 di design system. Descrivono l'aspetto che dovrebbe avere 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 è lungo circa 2.100 parole e per la maggior parte contiene 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. Una delle sue intestazioni è Reject generated-design reflexes. Sotto di essa compare un elenco delle soluzioni a cui ricorre un generatore competente quando nessuno gli ha detto di non usarle:

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 versionare è quell'elenco applicato a un determinato dominio.

Perché le aziende pubblicano il proprio DESIGN.md?

La community è arrivata prima. awesome-design-md raccoglie 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 verificati.

Un file ufficiale è diverso, perché rappresenta la fonte e non un'interpretazione del risultato. Quando Vercel modifica la propria scala tipografica, vercel.com/design.md cambia insieme a essa. Una copia estratta a marzo continua a insegnare all'agente la vecchia scala. Nel repository non ci sarà alcuna indicazione che la copia è diventata obsoleta.

Sette publisher sono pochi, e il repository lo dichiara esplicitamente: 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. Per questo, è meglio considerare l'elenco un tracker e non un censimento neutrale. Vale comunque la pena seguirlo, considerando chi sono questi sette publisher. Sono le aziende di cui gli altri sviluppatori copiano più spesso il codice front-end. I loro file stanno diventando l'esempio concreto di ciò che è un DESIGN.md. Si può confrontare questo percorso con quello seguito da AGENTS.md: agents.md conta ora oltre 60.000 progetti open source che usano il formato, mentre la gestione è affidata all'Agentic AI Foundation presso la Linux Foundation. Le convenzioni per i file leggibili dagli agenti si stanno definendo rapidamente, e partono dai principali operatori del settore.

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

La maggior parte dei software eseguiti su un VPS non ha un linguaggio visivo da definire. Il file resta comunque utile, perché il meccanismo non riguarda i colori. Serve a documentare i vincoli che un editor sicuro di sé violerebbe altrimenti senza accorgersene.

Invarianti. Una frase per ciascuna, che descriva qualcosa che deve restare vero dopo ogni modifica. "Ogni scrittura passa da queue.enqueue(). Una scrittura diretta nel database salta il log di audit, che è la fonte letta dall'esportazione per la conformità." Un invariante accompagnato dalla relativa motivazione resta valido anche quando si presenta 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 c'è un daemon in meno da mantenere attivo. Rivalutare questa scelta quando sarà disponibile un secondo application server." Senza questo paragrafo, un agente incaricato di velocizzare la cache aggiunge Redis, e fa bene a farlo: non gli hai mai comunicato il vincolo. Questa è la sezione che giustifica da sola 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 usato negli 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. Indicali e specifica il costo di una modifica a ciascuno di essi. Se l'agente può anche raggiungere il web pubblico, 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 quali testi recuperati possono influenzare il codice e quali devono essere soltanto riportati tra virgolette.

Vocabolario. Se nel codice compare tenant e il team usa customer, documenta la corrispondenza. Un agente che sbaglia interpretazione produce codice leggibile che però rappresenta il concetto errato, cioè 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 intestazioni. Un file con quattro righe accurate è utile. Un file con quaranta righe ipotizzate non lo è.

Alcuni strumenti caricano ogni file Markdown nella directory principale del repository, mentre altri caricano soltanto quello indicato esplicitamente. Non dare 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 si conclude con la licenza. Tutto questo è già nel README e non spiega perché le cose siano state progettate in quel modo.

Questo comporta un doppio costo. Il primo è il contesto. Un file che l’agente legge all’inizio di ogni attività viene conteggiato a ogni attività, e una sezione di installazione duplicata consuma inutilmente una finestra di contesto di dimensioni fisse. 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 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 informazione abbia la precedenza, 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 stare tranquillamente nel README, rimuovilo da DESIGN.md. Ciò che rimane dovrebbe essere la parte che diresti ad alta voce durante una revisione del codice, quella che inizia con "ci abbiamo già provato".

Come verificare che il file venga applicato?

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

Assegna all'agente un'attività che lo 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 salterebbe il log di audit. Se apre una connessione al database ed esegue una scrittura, una delle due spiegazioni è valida: il file non viene letto oppure l'invariante è formulata in modo abbastanza vago da consentire interpretazioni.

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

Questo è particolarmente importante quando l'agente viene eseguito su un server anziché sul laptop. Un agente che lavora in una sessione di lunga durata, 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 mai sottoposto a commit viene perso nella sessione successiva. DESIGN.md è il file in cui inserire quella spiegazione, così rimane disponibile.

Inizia dalle decisioni su cui discutete

La prima versione richiede venti minuti. Apri le ultime pull request in cui un revisore ha scritto: "no, qui facciamo diversamente". Ognuno di quei commenti descrive un'invariante che non è mai stata 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 porta a un errore, non secondo una pianificazione prestabilita. Se stai ancora definendo come integrare gli agenti nel normale flusso di sviluppo, la guida 2026 per imparare a usare gli agenti AI è un buon passo successivo.

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, che fa parte della Linux Foundation. Ad agosto 2026 DESIGN.md non ha un ente responsabile né una specifica pubblicata. Ha però adottato da aziende che lo usano direttamente: 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, ricostruiti da siti pubblici. Consideralo una convenzione che puoi adottare subito ed estendere liberamente, perché nulla convalida i nomi delle sezioni.

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

Per un repository piccolo, sì. Un solo 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 build. DESIGN.md cambia quando cambia una decisione, evento più raro e con conseguenze più rilevanti. 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 tutti i file markdown nella directory root.

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

Un ADR (architecture decision record) è il documento datato di una singola decisione. Un progetto ben gestito ne accumula decine in una directory. Questa è una cronologia, e la cronologia è costosa da consultare: per capire quali decisioni sono ancora valide, un agente dovrebbe leggerle tutte. DESIGN.md descrive lo stato attuale ed è scritto per essere letto integralmente a ogni attività. Se già scrivi ADR, conserva 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 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: 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 potuto evitare. La lunghezza non è il criterio di valutazione. Ogni riga dovrebbe descrivere qualcosa che altrimenti l’agente sbaglierebbe.