Registri delle Decisioni per lo Sviluppo Software Guidato dall'IA

Le registrazioni delle decisioni sono lo strato di memoria mancante nello sviluppo software assistito da AI. Esse catturano non solo ciò che è stato costruito, ma il perché — e questa distinzione diventa critica quando gli strumenti AI scrivono il tuo codice.

Le registrazioni delle decisioni sono lo strato di memoria mancante

La programmazione guidata da AI cambia l’economia dello sviluppo software rendendo il codice più economico da generare, più facile da refattorizzare e più veloce da scartare. Questo è utile. È anche pericoloso, perché quando il codice diventa più facile da produrre, la risorsa scarsa non è più la digitazione — la risorsa scarsa è il giudizio.

Perché il team ha scelto PostgreSQL invece di DynamoDB? Perché il prodotto richiede una revisione umana prima di inviare email generate dall’AI? Perché l’interfaccia mostra i suggerimenti in un pannello laterale invece di applicarli direttamente? Perché un approccio più semplice è stato respinto sei mesi fa? Il codice può mostrare cosa esiste, ma raramente spiega perché esiste.

Le registrazioni delle decisioni risolvono questo problema fornendo un documento breve, sottoposto a controllo versione, che cattura una scelta importante, il contesto dietro di essa, le alternative considerate e le conseguenze che il team ha accettato. In una codebase assistita da AI, queste registrazioni diventano più della semplice documentazione — diventano una memoria di progetto durevole che sia gli umani che gli agenti di coding AI possono leggere prima di apportare modifiche future. La regola operativa pratica è semplice: mantenere le registrazioni delle decisioni come file Markdown nel repository, revisionarle come codice e permettere agli strumenti AI futuri di leggerle prima di proporre o implementare modifiche.

Cosa sono le registrazioni delle decisioni?

Una registrazione delle decisioni è un documento scritto di una decisione significativa, strutturata per rispondere a quattro domande di base: cosa abbiamo deciso, perché l’abbiamo deciso, quali alternative abbiamo considerato e quali conseguenze abbiamo accettato? La forma più comune è l’Architecture Decision Record, abbreviato in ADR. Gli ADR sono ampiamente utilizzati per documentare le decisioni tecniche, e lo stesso modello può essere esteso oltre l’architettura al lavoro sul prodotto e sul design.

Per la programmazione guidata da AI, tre tipi sono particolarmente utili:

Insieme, ADR, PDR e DDR descrivono non solo la struttura del sistema, ma anche l’intento del prodotto e il ragionamento dietro l’esperienza utente. Questa combinazione è importante perché gli agenti AI possono leggere il codice, ma il codice da solo non contiene abbastanza contesto per prendere buone decisioni. Le registrazioni delle decisioni forniscono ai sistemi AI una fonte di intento del progetto revisionata, durevole e approvata dagli umani.

Architecture Decision Records (Registrazioni delle Decisioni Architetturali)

Le Architecture Decision Records catturano decisioni tecniche e strutturali. Usa un ADR quando una decisione influenza la forma del sistema — i suoi confini, le dipendenze, il modello operativo o la manutenibilità a lungo termine.

Gli esempi di decisioni meritevoli di essere registrate come ADR includono:

• La scelta di PostgreSQL come database principale
• L’uso di un’architettura guidata dagli eventi per l’elaborazione in background
• Mantenere l’applicazione come un monolite modulare
• L’introduzione di una coda di messaggi
• La scelta di REST invece di GraphQL
• L’uso del rendering lato server per l’applicazione web
• Richiedere che tutti i lavori in background siano idempotenti
• L’adozione di un modello specifico di autenticazione e autorizzazione

Un ADR non è un documento completo di architettura — è intenzionalmente piccolo, registrando una decisione importante in un momento specifico del tempo. Un buon ADR previene l’amnesia architetturale: senza di esso, i contributori futuri potrebbero riscoprire gli stessi compromessi, riaprire vecchie discussioni o accidentalmente annullare vincoli importanti.

Nella programmazione guidata da AI, gli ADR hanno ancora più peso. Gli strumenti AI sono spesso abili nell’ottimizzazione locale e potrebbero proporre una modifica tecnicamente plausibile che viola un vincolo architetturale più ampio. Un ADR fornisce all’AI un confine chiaro: “Questo è come questo sistema dovrebbe essere strutturato.”

Product Decision Records (Registrazioni delle Decisioni di Prodotto)

Le Product Decision Records catturano il comportamento del prodotto, l’ambito e l’intento rivolto all’utente. Questo è meno comune rispetto agli ADR, ma è spesso altrettanto prezioso — le decisioni di prodotto sono frequentemente sparse tra ticket, strumenti di roadmap, thread di chat, note delle riunioni e memorie delle persone, rendendole facili da dimenticare per gli umani e quasi impossibili da inferire in modo affidabile per gli strumenti AI.

Usa un PDR quando una decisione influenza cosa fa il prodotto, a chi serve, cosa è intenzionalmente fuori ambito o come dovrebbe comportarsi una feature rivolta all’utente. Gli esempi includono:

• I messaggi generati dall’AI devono rimanere bozze fino a quando non vengono revisionati da un umano
• Gli utenti del tier gratuito possono creare fino a tre progetti
• I workspace eliminati sono recuperabili per 30 giorni
• La fatturazione per team è fuori ambito per la versione 1
• Gli utenti possono esportare i loro dati senza contattare il supporto
• I riassunti AI con bassa confidienza mostrano un avviso invece di essere nascosti

Un PDR è particolarmente utile quando una scelta di prodotto sembra arbitrata dal codice. Il codice potrebbe contenere un limite di tre progetti per gli utenti gratuiti e, senza un PDR, uno strumento AI potrebbe trattare quel numero come una costante magica e suggerire di cambiarlo. Con un PDR, l’AI può vedere che il limite è legato alla strategia di pricing, al costo di onboarding o al carico di supporto — e che cambiarlo richiede una decisione di prodotto deliberata, non una modifica rapida.

Design Decision Records (Registrazioni delle Decisioni di Design)

Le Design Decision Records catturano decisioni sull’esperienza utente, l’interazione, il design visivo e il design dei contenuti. Usa un DDR quando una decisione influenza come gli utenti interagiscono con il prodotto, come le informazioni sono presentate o come un principio di design dovrebbe essere applicato nel lavoro futuro.

Gli esempi di decisioni di design meritevoli di essere registrate includono:

• Usare la validazione inline invece della validazione solo al momento del submit
• Mettere i suggerimenti AI in un pannello laterale invece che direttamente nell’editor
• Usare la disclosure progressiva per le impostazioni avanzate
• Richiedere conferma prima di azioni distruttive
• Usare “Bozza” e “Pubblicato” invece di “Inattivo” e “Attivo”
• Mantenere le azioni primarie visibili sugli schermi mobili

L’intento di design è facile da perdere durante l’implementazione. Uno sviluppatore potrebbe semplificare un flusso, o un agente AI potrebbe generare un componente che tecnicamente funziona ma rompe il modello di interazione inteso. Ad esempio, un DDR potrebbe registrare: “Mostriamo i suggerimenti di scrittura AI accanto al documento, non all’interno, perché gli utenti hanno bisogno di confrontare il testo generato con la propria bozza prima di accettare le modifiche.” Questa registrazione fornisce ai contributori futuri un principio da preservare, non solo un layout da copiare.

Perché le registrazioni delle decisioni sono più importanti con l’AI

Gli strumenti di coding AI sono potenti, ma sono spesso stateless o solo parzialmente consapevoli della storia del progetto. Possono ispezionare i file, inferire pattern e generare modifiche — ma non sanno automaticamente quali decisioni sono intenzionali, quali sono accidentali e quali sono già state discusse e risolte. Questo crea diversi rischi distinti.

L’AI potrebbe riaprire dibattiti già risolti

Se il team ha già deciso di usare un monolite modulare, un agente AI potrebbe comunque proporre di estrarre un servizio perché sembra pulito in isolamento. Senza un ADR, l’AI non ha un modo durevole per sapere che il team ha già considerato e respinto quel percorso, e il risultato è uno sforzo sprecato o una regressione sottile nella coerenza del sistema.

L’AI potrebbe ottimizzare localmente e danneggiare globalmente

Una refattorizzazione generata potrebbe rendere un file più pulito violando i confini del sistema. Una modifica UI potrebbe ridurre la complessità del componente indebolendo l’esperienza utente intesa. Una modifica al prodotto potrebbe semplificare l’implementazione rompendo le assunzioni di pricing o conformità. Le registrazioni delle decisioni forniscono all’AI un quadro di riferimento più ampio prima che agisca su segnali a ambito ristretto.

L’AI potrebbe preservare il codice ma perdere l’intento

Un modello può seguire i pattern esistenti nella codebase, ma i pattern non sono la stessa cosa dei principi. A volte il codice esistente è un compromesso. A volte è transitorio. A volte esiste a causa di un vincolo esterno che non è visibile nel file. Le registrazioni delle decisioni spiegano la differenza tra “questo è come funziona” e “questo è perché è stato costruito in questo modo.”

L’AI potrebbe generare una giustificazione plausibile ma errata

L’AI può redigere registrazioni delle decisioni, ma può anche inventare spiegazioni che suonano sicure ma che non corrispondono alla decisione reale. Questo è perché la revisione umana è innegoziable: l’AI può generare la prima bozza di una registrazione, ma un umano deve verificare che descriva accuratamente la decisione reale, le alternative e le conseguenze prima che la registrazione venga unita.

Le registrazioni delle decisioni come parte di una metodologia più ampia

Le registrazioni delle decisioni non sono solo documentazione — fanno parte di un modo più ampio di lavorare che si trova all’intersezione di governance architetturale leggera, docs as code, flussi di lavoro di gestione della conoscenza potenziati da AI, scoperta del prodotto, giustificazione del design, governance AI e revisione del codice. Un modo utile per descrivere il processo più ampio è lo Sviluppo Orientato alle Decisioni.

La maggior parte dei flussi di lavoro di programmazione guidata da AI si concentra strettamente sul ciclo genera-revisiona-commit:

Questo ciclo è troppo sottile per il lavoro serio sui sistemi. Un flusso di lavoro più forte tratta il repository come un archivio di codice e intento — i diagrammi qui usano Mermaid, un formato leggero che funziona bene anche all’interno delle registrazioni delle decisioni Markdown:

Questo processo trasforma il repository in qualcosa di più di un archivio di codice. Diventa la fonte di verità per l’implementazione, l’intento e il ragionamento — un artefatto durevole che accumula valore con ogni decisione presa.

Registrazioni delle decisioni e docs as code

Le registrazioni delle decisioni funzionano meglio quando seguono i principi dei docs-as-code, il che significa che dovrebbero essere memorizzate nello stesso repository del codice, scritte in Markdown semplice, revisionate nelle pull request, versionate con Git, collegate a issue e pull request correlate e ricercabili sia dagli umani che dagli strumenti AI. Questo è molto più affidabile rispetto a memorizzare decisioni importanti nella chat, pagine wiki, presentazioni o note delle riunioni — quegli strumenti possono ancora essere utili per la discussione, ma la decisione accettata dovrebbe sempre vivere vicino al codice.

Una struttura di repository ben organizzata per le registrazioni delle decisioni potrebbe essere simile a questa:

docs/
  decisions/
    architecture/
      0001-use-postgresql-for-primary-storage.md
      0002-keep-billing-inside-the-core-app.md
    product/
      0001-ai-generated-email-requires-human-review.md
      0002-free-tier-project-limit.md
    design/
      0001-use-inline-validation.md
      0002-place-ai-suggestions-in-side-panel.md

Per progetti più piccoli, una struttura più piatta funziona ugualmente bene. L’organizzazione esatta delle cartelle è meno importante della coerenza — le registrazioni devono essere facili da trovare, facili da revisionare e facili da caricare come contesto per gli strumenti AI prima di agire sulla codebase. Per i team Go, questa struttura docs/decisions/ si integra naturalmente accanto al layout cmd/, internal/ e api/ descritto in Go Project Structure: Practices & Patterns, che consiglia docs/ come casa per le decisioni architetturali e i riferimenti API.

Un template pratico per le registrazioni delle decisioni

Un template utile per le registrazioni delle decisioni dovrebbe essere abbastanza breve da essere effettivamente utilizzato. Ecco un template Markdown pratico che include una sezione di guida AI opzionale ma preziosa:

# Decisione: Titolo breve

Stato: Proposta | Accettata | Sostituita | Deprecata
Data: AAAA-MM-GG
Tipo: Architettura | Prodotto | Design
Responsabili: Team o nomi

## Contesto

Descrivere il problema, i vincoli, gli obiettivi, le esigenze degli utenti, i fatti tecnici
e i fattori aziendali che hanno portato a questa decisione.

## Decisione

Enunciare la decisione chiaramente.

## Alternative considerate

### Opzione 1

Pro:
- ...

Contro:
- ...

## Conseguenze

Descrivere cosa diventa più facile, cosa diventa più difficile e quali rischi
o lavori di follow-up ciò crea.

## Guida AI

Quando un assistente AI lavora in questa area, dovrebbe:
- Preservare ...
- Evitare ...
- Preferire ...
- Chiedere revisione quando ...

## Link

- Issue correlate:
- Pull request correlate:
- File correlati:
- Sostituisce:
- Sostituito da:

La sezione “Guida AI” è opzionale, ma per la programmazione guidata da AI è estremamente preziosa — trasforma la registrazione delle decisioni in un’istruzione durevole per i futuri agenti che lavorano nella stessa area della codebase.

Cosa appartiene in una registrazione delle decisioni?

Non ogni scelta merita una registrazione e, se ogni piccolo dettaglio di implementazione diventa una registrazione delle decisioni, il processo collassa nel rumore. Crea una registrazione delle decisioni quando una scelta è significativa e probabilmente importante in seguito.

I buoni candidati sono decisioni che:

• Influenzano più parti del sistema
• Codificano una promessa di prodotto
• Risolvono un dibattito reale
• Introducono un compromesso a lungo termine
• Dipendono da vincoli aziendali, di conformità o operativi
• Sarebbero costosi da riscoprire in seguito
• Gli strumenti AI futuri potrebbero plausibilmente interpretare male
• I contributori futuri potrebbero essere tentati di invertire casualmente

I candidati scadenti includono piccole scelte di refattorizzazione, correzioni di bug ovvie, esperimenti temporanei, decisioni di denominazione locali e dettagli di implementazione senza conseguenze durature. Una buona regola pratica è semplice: se invertire la decisione richiederebbe una discussione, registra la decisione.

Valori di stato e ciclo di vita

Le registrazioni delle decisioni dovrebbero avere un ciclo di vita per segnalare la loro posizione attuale. I valori di stato più semplici sono sufficienti.

Proposta — La decisione è in fase di considerazione ma non ancora accettata. Usala quando il team vuole discutere una decisione in una pull request prima di impegnarsi.

Accettata — La decisione è attiva e dovrebbe guidare il lavoro futuro. La maggior parte delle registrazioni delle decisioni utili passerà la maggior parte della loro vita in questo stato.

Sostituita — La decisione è stata sostituita da una registrazione più recente. Non eliminare le vecchie registrazioni; conservale per la storia e collega alla decisione più recente in modo che l’evoluzione del pensiero rimanga visibile.

Deprecata — La decisione non è più consigliata ma potrebbe ancora descrivere parti esistenti del sistema. Questo è particolarmente utile durante le migrazioni, quando i vecchi pattern esistono nella codebase accanto a approcci più recenti.

Il principio importante è che le registrazioni delle decisioni dovrebbero essere amichevoli alle aggiunte. Quando il team cambia direzione, crea una nuova registrazione e collega quella vecchia piuttosto che riscrivere la storia per far sembrare il passato più pulito.

Come l’AI dovrebbe generare registrazioni delle decisioni

L’AI può aiutare a creare registrazioni delle decisioni e questo è uno degli usi migliori dell’AI nello sviluppo software — è veloce nel redigere documenti strutturati dal contesto. Dopo una discussione, una revisione architetturale o una pull request, puoi chiedere a un assistente AI di redigere una registrazione:

Redigi una Architecture Decision Record per la decisione in questa pull request.
Includi contesto, alternative, conseguenze e guida AI.
Salvala come Markdown sotto docs/decisions/architecture.

Per il lavoro di prodotto:

Redigi una Product Decision Record che spiega perché i messaggi generati dall'AI
devono rimanere bozze fino a quando non vengono revisionati dall'utente.
Includi l'impatto sull'utente, il comportamento fuori ambito, i compromessi e la guida AI.

La registrazione generata dall’AI non dovrebbe essere fidata automaticamente, tuttavia. La revisione umana dovrebbe verificare che il contesto sia accurato, che l’AI non abbia inventato una giustificazione, che le alternative elencate siano reali, che le conseguenze siano oneste e che la guida AI corrisponda all’intento reale del team. L’AI è un assistente alla stesura — non è il proprietario della decisione.

Come l’AI dovrebbe leggere le registrazioni delle decisioni

L’altra metà della pratica è istruire l’AI a leggere le registrazioni prima di agire. Prima di chiedere a un assistente AI di implementare una modifica, includi un’istruzione come questa:

Prima di modificare questa feature, leggi docs/decisions.
Identifica eventuali Architecture, Product o Design Decision Records applicabili.
Segui le decisioni accettate. Se la tua modifica proposta entra in conflitto con una
registrazione delle decisioni, spiega il conflitto prima di modificare il codice.

Per compiti più grandi, rinforza il ruolo delle registrazioni come memoria del progetto:

Usa le registrazioni delle decisioni come memoria del progetto.
Non invertire decisioni accettate senza proporre una nuova decisione sostitutiva.
Quando generi codice, spiega quali registrazioni delle decisioni hanno influenzato l'implementazione.

Questo cambia il ruolo dell’AI da “prevedere codice plausibile” a “operare all’interno di un sistema documentato di vincoli” — un miglioramento significativo nell’affidabilità per progetti complessi o di lunga durata.

Registrazioni delle decisioni nelle pull request

Le registrazioni delle decisioni dovrebbero essere parte della normale revisione delle pull request piuttosto che un processo separato. Una semplice voce nella checklist della PR rende l’abitudine visibile:

## Checklist delle registrazioni delle decisioni

- [ ] Questa PR non introduce una decisione architetturale, di prodotto o di design significativa.
- [ ] Questa PR introduce una decisione significativa e include una nuova registrazione delle decisioni.
- [ ] Questa PR cambia una decisione precedente e include una registrazione sostitutiva.
- [ ] Le registrazioni delle decisioni esistenti rilevanti sono state considerate.
- [ ] Il codice generato dall'AI segue le registrazioni delle decisioni accettate.
- [ ] Le registrazioni delle decisioni generate dall'AI sono state revisionate da un umano.

Questa checklist è semplice, ma cambia il comportamento ricordando al team che il codice non è l’unico artefatto importante in una pull request. Rende anche naturale catturare quando una modifica generata dall’AI viola silenziosamente una decisione precedente.

Registrazioni delle decisioni e governance architetturale

La governance architetturale tradizionale spesso fallisce perché è troppo pesante, troppo lenta o troppo disconnessa dall’implementazione — comitati centrali di approvazione, documenti preliminari ingenti e processi di gatekeeping che bloccano invece di guidare. Le registrazioni delle decisioni offrono un’alternativa più leggera che si integra direttamente nel flusso di lavoro di sviluppo.

Non richiedono un comitato centrale di architettura per ogni modifica, né bloccano i team dall’apprendere e adattarsi. Invece, creano una scia di decisioni che può essere revisionata, riferita e costruita nel tempo. Questo supporta l’architettura evolutiva: l’architettura può cambiare, ma cambia con memoria piuttosto che nonostante essa. Il team può rivedere le vecchie decisioni senza dover riscoprire perché sono state prese, che è una forma di governance più sana e onesta:

• Piccole registrazioni invece di documenti giganteschi
• Revisione vicina al codice invece di teatro di approvazione separato
• Contesto storico invece di conoscenza tribale
• Compromessi espliciti invece di assunzioni nascoste

Registrazioni delle decisioni e product management

Anche il lavoro di prodotto ha bisogno di memoria decisionale e questa è un’area in cui il valore delle registrazioni delle decisioni è spesso sottovalutato. Una roadmap dice cosa potrebbe succedere. Un ticket dice cosa costruire dopo. Le analytics dicono cosa hanno fatto gli utenti. Nessuno di questi spiega completamente perché esiste un comportamento di prodotto.

Le Product Decision Records colmano questo divario e sono particolarmente utili per decisioni su pricing e packaging, modelli di permessi, limiti e quote, flussi di sicurezza e revisione AI, scelte di onboarding, definizioni dei ruoli utente, regole di collaborazione, politiche di ritenzione dei dati e confini dell’ambito delle feature. Una volta implementate, le decisioni di prodotto diventano invisibili nel codice — in seguito, qualcuno vede solo il codice e chiede: “Perché funziona in questo modo?” Un PDR fornisce la risposta in una forma che sia gli umani che gli strumenti AI possono trovare e usare.

Registrazioni delle decisioni e sistemi di design

I sistemi di design spesso documentano componenti, token e regole di utilizzo, ma raramente documentano perché il sistema funziona in quel modo. Le Design Decision Records colmano questo divario. Una libreria di componenti potrebbe dire “usa il dialogo di conferma per le azioni distruttive”, mentre un DDR spiega la giustificazione: “Richiediamo conferma per le azioni distruttive perché gli utenti spesso lavorano con dati di team condivisi e la cancellazione accidentale ha un alto costo di recupero.”

Questa giustificazione è importante oltre il componente specifico. Aiuta i futuri designer, sviluppatori e strumenti AI ad applicare il principio correttamente in nuove situazioni. Senza il DDR, un agente AI potrebbe generare un’interazione più veloce che salta la conferma perché appare più efficiente. Con il DDR, l’agente può riconoscere che preservare la proprietà di sicurezza è intenzionale e innegoziable.

Come le registrazioni delle decisioni supportano lo sviluppo guidato da specifiche

Lo sviluppo guidato da specifiche spiega cosa dovrebbe fare il sistema. Le registrazioni delle decisioni spiegano perché il team ha scelto quella direzione e la distinzione è significativa per il lavoro assistito da AI.

Una specifica di feature potrebbe dire che le email generate dall’AI devono essere salvate come bozze. Una Product Decision Record spiega perché l’invio automatico è stato respinto, quali rischi sono stati considerati e quali modifiche future richiederebbero una nuova decisione. Una specifica di design potrebbe descrivere un’interazione del pannello laterale, mentre il DDR corrispondente spiega perché le modifiche AI inline sono state esplicitamente respinte e perché preservare il controllo dell’utente è stato pesato più pesantemente rispetto alla velocità del flusso di lavoro. Una specifica architetturale potrebbe definire un confine di servizio e il suo ADR spiega perché il team ha scelto quel confine rispetto a un’alternativa più semplice o più distribuita.

La specifica guida l’implementazione. La registrazione delle decisioni preserva il giudizio. Insieme, forniscono agli agenti di coding AI sia istruzioni che contesto — il “cosa” e il “perché” — che è ciò che rende la combinazione così efficace per sistemi complessi e di lunga durata.

Le registrazioni delle decisioni non sono specifiche

Le registrazioni delle decisioni sono correlate alle specifiche, ma servono a uno scopo diverso. Una specifica dice “il sistema deve fare X”, mentre una registrazione delle decisioni dice “abbiamo scelto X invece di Y a causa di questi vincoli e compromessi”. Quel “invece di Y” è la parte preziosa. Gli strumenti AI spesso generano soluzioni trovando un percorso plausibile verso il risultato richiesto, ma le registrazioni delle decisioni告诉他们 quali percorsi plausibili sono già stati esplorati, valutati e respinti — riducendo il turnover e migliorando la qualità del lavoro assistito da AI.

Le registrazioni delle decisioni non sostituiscono i test

I test verificano il comportamento; le registrazioni delle decisioni spiegano l’intento. Entrambi sono necessari e lavorano insieme. Un test può far rispettare che le email generate dall’AI devono essere salvate come bozze, mentre una Product Decision Record spiega che questo è richiesto perché gli utenti devono revisionare la comunicazione generata dall’AI prima che esca dal sistema. Il test protegge il comportamento. La registrazione delle decisioni protegge il significato. Insieme, rendono le modifiche future più sicure e prevedibili.

Le registrazioni delle decisioni non sostituiscono i commenti al codice

I commenti al codice spiegano i dettagli di implementazione locali, mentre le registrazioni delle decisioni spiegano decisioni più ampie. Usa i commenti per righe sorprendenti, casi limite, workaround e funzioni che non possono essere semplificate. Usa le registrazioni delle decisioni per spiegare perché esiste un’architettura, perché esiste un comportamento di prodotto, perché esiste un pattern di interazione e perché il team ha scelto una direzione invece di un’altra. Se la spiegazione influenza solo poche righe, un commento è lo strumento giusto. Se influenza la direzione del sistema, una registrazione delle decisioni è lo strumento giusto.

Errori comuni

Scrivere registrazioni troppo tardi

Una registrazione delle decisioni dovrebbe essere scritta quando la decisione viene presa, non mesi dopo quando tutti hanno dimenticato i compromessi. Va bene redigerne una durante una pull request. È ancora meglio redigerla prima dell’implementazione, mentre la decisione è ancora attivamente discussa e le alternative sono fresche.

Rendere le registrazioni troppo lunghe

Una registrazione delle decisioni non è un saggio. Dovrebbe essere dettagliata abbastanza da preservare il giudizio ma breve abbastanza da essere effettivamente letta. Preferisci la chiarezza alla completezza — una registrazione concisa che viene letta è molto più preziosa di una completa che viene saltata.

Registrare decisioni senza conseguenze

La sezione delle conseguenze è il cuore della registrazione. Una decisione senza conseguenze dichiarate è spesso solo una preferenza piuttosto che una decisione reale. Le buone registrazioni ammettono onestamente i compromessi, incluso cosa diventa più difficile o rischioso a causa della scelta.

Modificare le vecchie registrazioni come se la storia fosse cambiata

Quando una decisione cambia, crea una nuova registrazione e segna quella vecchia come sostituita. Riscrivere silenziosamente una vecchia decisione per farla corrispondere allo stato attuale distrugge il contesto storico che rende preziose le registrazioni delle decisioni. La storia è utile proprio perché mostra come il pensiero si è evoluto.

Permettere che le registrazioni generate dall’AI vengano unite senza revisione

L’AI può produrre una registrazione lucida e ben strutturata che è sottilmente errata. Tratta le registrazioni delle decisioni generate dall’AI esattamente come il codice generato dall’AI — revisionale con cura, verifica che la giustificazione sia accurata e assicurati che la sezione delle conseguenze rifletta ciò che il team ha effettivamente accettato.

Nascondere le registrazioni fuori dal repository

Se le registrazioni delle decisioni vivono in un wiki separato o in un sistema di documentazione, è meno probabile che vengano aggiornate insieme alle modifiche del codice e molto meno probabile che vengano lette dagli strumenti di coding AI che caricano il contesto per un compito. Tenerle nel repository non è solo una comodità — è ciò che rende la pratica funzionante per lo sviluppo assistito da AI.

Un modello operativo leggero

Un processo di team pratico che aggiunge un overhead minimo è simile a questo:

1. Durante la pianificazione o l’implementazione, identifica se sta venendo presa una decisione significativa.
2. Chiedi a un assistente AI di redigere un ADR, PDR o DDR basato sulla discussione.
3. Revisiona la bozza come team, verificando contesto, alternative e conseguenze.
4. Commit della registrazione come Markdown nel repository.
5. Collegala dall’issue o pull request correlata.
6. Istruisci gli strumenti di coding AI a leggere le registrazioni rilevanti prima di apportare modifiche future nell’area.
7. Sostituisci le registrazioni quando le decisioni cambiano, preservando la vecchia registrazione per la storia.

Questo non richiede una nuova burocrazia o un ruolo di documentazione dedicato. Richiede una piccola abitudine: preservare un giudizio importante nel momento in cui viene creato, vicino al codice dove sarà necessario.

Esempio ADR

# Decisione: Usare PostgreSQL per lo storage principale dell'applicazione

Stato: Accettata
Data: 2026-06-25
Tipo: Architettura
Responsabili: Team Piattaforma

## Contesto

L'applicazione ha bisogno di storage relazionale durevole per account, progetti,
permessi ed eventi di audit. Il team si aspetta query di reportistica frequenti
e forti requisiti di coerenza per i controlli dei permessi.

## Decisione

Useremo PostgreSQL come database principale dell'applicazione.

## Alternative considerate

### DynamoDB

Pro:
- Scalabilità operativa
- Adatto per pattern di accesso key-value prevedibili

Contro:
- Più complesso per query relazionali
- Più difficile per la reportistica ad hoc
- Meno familiare al team attuale

### MySQL

Pro:
- Database relazionale maturo
- Modello operativo familiare

Contro:
- PostgreSQL corrisponde meglio alle esigenze del team per il supporto JSON,
  le opzioni di indicizzazione e l'esperienza esistente

## Conseguenze

PostgreSQL diventa una dipendenza operativa centrale. Il team deve gestire
le migrazioni con cura e monitorare le prestazioni delle query. In cambio,
l'applicazione ottiene un forte modellaggio relazionale, indicizzazione matura e
supporto di reportistica flessibile.

## Guida AI

Quando si modifica il codice di persistenza, preferire il modellaggio relazionale in PostgreSQL.
Non introdurre un secondo database principale senza un ADR sostitutivo.

Esempio PDR

# Decisione: Le email generate dall'AI devono rimanere bozze

Stato: Accettata
Data: 2026-06-25
Tipo: Prodotto
Responsabili: Team Prodotto

## Contesto

Il prodotto può generare risposte email usando l'AI. L'invio di email è un'azione
ad alta fiducia perché gli errori possono raggiungere clienti, partner o
team interni.

## Decisione

Le email generate dall'AI devono essere create come bozze. Un utente umano deve
revisionarle e inviarle.

## Alternative considerate

### Invio automatico

Pro:
- Flusso di lavoro più veloce
- Meno sforzo per l'utente

Contro:
- Rischio più alto di messaggi errati o inappropriati
- Minore fiducia degli utenti
- Più difficile recuperare dagli errori

### Chiedere conferma solo dopo la generazione

Pro:
- Mantiene il flusso di lavoro semplice
- Fornisce un certo controllo all'utente

Contro:
- Incoraggia ancora una revisione superficiale
- Non si adatta bene al comportamento esistente dei client email come le bozze

## Conseguenze

Il flusso di lavoro è leggermente più lento, ma più sicuro e affidabile.
L'automazione futura può migliorare la velocità di revisione, ma non deve bypassare
l'approvazione umana senza un PDR sostitutivo.

## Guida AI

Quando si costruiscono funzionalità di generazione email, creare bozze per impostazione predefinita.
Non aggiungere l'invio automatico a meno che un nuovo PDR accettato non lo consenta esplicitamente.

Esempio DDR

# Decisione: Mostrare i suggerimenti di scrittura AI in un pannello laterale

Stato: Accettata
Data: 2026-06-25
Tipo: Design
Responsabili: Team Design

## Contesto

Gli utenti hanno bisogno di aiuto per migliorare i contenuti scritti, ma hanno anche bisogno di restare
in controllo del testo finale. Le modifiche AI inline possono rendere difficile
distinguere il contenuto scritto dall'utente dai suggerimenti generati.

## Decisione

I suggerimenti di scrittura AI appariranno in un pannello laterale. Gli utenti possono accettare,
rifiutare o copiare i suggerimenti nell'editor principale.

## Alternative considerate

### Applicare i suggerimenti inline

Pro:
- Veloce
- Sembra integrato

Contro:
- Sbiacca l'autorialità
- Rende la revisione più difficile
- Può sorprendere gli utenti

### Mostrare i suggerimenti in una modale

Pro:
- Esperienza focalizzata
- Facile da implementare

Contro:
- Interrompe il flusso di scrittura
- Più difficile confrontare il suggerimento e il testo originale

## Conseguenze

Il pannello laterale occupa più spazio sullo schermo, specialmente sugli schermi piccoli.
Tuttavia, preserva il controllo dell'utente e rende la revisione più chiara.

## Guida AI

Quando si aggiungono funzionalità di assistenza alla scrittura, preservare la separazione tra
testo utente e suggerimenti AI. Non applicare il testo generato direttamente
nel documento senza un'azione esplicita dell'utente.

Libreria di prompt suggerita

Usa questi prompt per rendere le registrazioni delle decisioni parte dello sviluppo quotidiano assistito da AI.

Trovare registrazioni rilevanti prima di lavorare su una feature:

Leggi docs/decisions e identifica eventuali registrazioni delle decisioni accettate applicabili
a questo compito. Riassumi i vincoli prima di proporre modifiche al codice.

Redigere un nuovo ADR:

Redigi una Architecture Decision Record per questa decisione tecnica.
Includi contesto, decisione, alternative, conseguenze e guida AI.
Mantienila concisa e specifica.

Redigere un nuovo PDR:

Redigi una Product Decision Record per questo comportamento di prodotto.
Includi l'impatto sull'utente, l'ambito, le alternative, le conseguenze e la guida AI.

Redigere un nuovo DDR:

Redigi una Design Decision Record per questo pattern di interazione.
Includi il problema dell'utente, le alternative, i compromessi, le conseguenze e la guida AI.

Revisionare una pull request rispetto alle decisioni esistenti:

Revisiona questa pull request rispetto alle registrazioni delle decisioni accettate in docs/decisions.
Identifica eventuali conflitti, registrazioni delle decisioni mancanti o decisioni che dovrebbero
essere sostituite.

Sostituire una decisione:

Crea una nuova registrazione delle decisioni che sostituisce quella esistente.
Preserva la giustificazione storica, spiega cosa è cambiato e collega entrambe le registrazioni.

Letture correlate

• Il formato ADR originale di Michael Nygard — il post fondante che ha avviato il movimento ADR
• Organizzazione ADR su GitHub — tooling, template e risorse della comunità per gestire le registrazioni delle decisioni
• Cos’è lo Spec-Driven Development? La Spec come Fonte di Verità — la definizione canonica di SDD che spiega come le specifiche delle feature completano le registrazioni delle decisioni: entrambe rendono l’intento durevole, a diversi livelli del sistema
• Spec-Driven Development vs Vibe Coding: Waterfall? — quando usare SDD e quando restare con flussi di lavoro più veloci e flessibili
• App Architecture in Production: Integration Patterns, Code Design, and Data Access — la home del cluster che copre integrazione, testing, accesso ai dati e pattern di documentazione software
• AI per la Gestione della Conoscenza: Flussi di Lavoro Reali che Reggono — flussi di lavoro di conoscenza potenziati da AI pratici che completano la pratica delle registrazioni delle decisioni