Registri delle decisioni per lo sviluppo software guidato dall'IA

Mantieni l'intento vicino al codice.

Indice

I registrazioni di decisione costituiscono lo strato di memoria mancante nello sviluppo del software assistito dall’IA. Non catturano solo ciò che è stato costruito, ma anche il perché — una distinzione che diventa cruciale quando gli strumenti di IA sono a scrivere il tuo codice.

Registrazioni di decisione — ADR, PDR, DDR — collegare l’intento al codice

Le registrazioni di decisione sono lo strato di memoria mancante

La programmazione guidata dall’IA cambia l’economia dello sviluppo del software rendendo il codice più economico da generare, più facile da rifattorizzare 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é la squadra ha scelto PostgreSQL invece di DynamoDB? Perché il prodotto richiede la revisione umana prima di inviare e-mail generate dall’IA? Perché l’interfaccia mostra suggerimenti in un pannello laterale invece di applicarli direttamente? Perché un approccio più semplice è stato rifiutato sei mesi fa? Il codice può mostrare ciò che esiste, ma raramente spiega perché esiste.

Le registrazioni di decisione risolvono questo problema fornendo un documento breve, gestito con controllo delle versioni, che cattura una scelta importante, il contesto alla base di essa, le alternative considerate e le conseguenze accettate dalla squadra. In una base di codice assistita dall’IA, queste registrazioni diventano più della documentazione — diventano una memoria di progetto durevole che sia gli umani che gli agenti di coding dell’IA possono leggere prima di apportare modifiche future. La regola operativa pratica è semplice: mantenere le registrazioni di decisione come file Markdown nel repository, revisionarle come codice e consentire agli strumenti di IA futuri di leggerle prima di proporre o implementare modifiche.

Cosa sono le registrazioni di decisione?

Una registrazione di decisione è un documento scritto di una decisione significativa, strutturato 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 schema può essere esteso oltre l’architettura fino al lavoro di prodotto e di design.

Per la programmazione guidata dall’IA, tre tipi sono particolarmente utili:

Tipo di registrazione Cattura Esempio
ADR Decisioni di architettura e tecniche Utilizzare PostgreSQL come database principale
PDR Decisioni sul comportamento e l’ambito del prodotto Le e-mail generate dall’IA devono rimanere bozze
DDR Decisioni di design e interazione Mostrare i suggerimenti dell’IA in un pannello laterale

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

Architecture Decision Records

Gli Architecture Decision Record catturano le decisioni tecniche e strutturali. Utilizza 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 che vale la pena registrare come ADR includono:

  • Scegliere PostgreSQL come database principale
  • Utilizzare un’architettura guidata dagli eventi per l’elaborazione in background
  • Mantenere l’applicazione come monolite modulare
  • Introdurre una coda di messaggi
  • Scegliere REST invece di GraphQL
  • Utilizzare il server-side rendering per l’applicazione web
  • Richiedere che tutti i lavori in background siano idempotenti
  • Adottare un modello specifico di autenticazione e autorizzazione

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

Nella programmazione guidata dall’IA, gli ADR hanno ancora più peso. Gli strumenti di IA sono spesso abili nell’ottimizzazione locale e potrebbero proporre una modifica tecnicamente plausibile che viola un vincolo architetturale più ampio. Un ADR fornisce all’IA un confine chiaro: “Questa è la forma che questo sistema dovrebbe avere.”

Product Decision Records

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

Utilizza un PDR quando una decisione influisce su ciò che il prodotto fa, a chi serve, cosa è intenzionalmente fuori ambito o come dovrebbe comportarsi una funzione rivolta all’utente. Gli esempi includono:

  • I messaggi generati dall’IA devono rimanere bozze finché non sono revisionati da un umano
  • Gli utenti del livello gratuito possono creare fino a tre progetti
  • Gli spazi di lavoro eliminati sono recuperabili per 30 giorni
  • La fatturazione di squadra è fuori ambito per la versione 1
  • Gli utenti possono esportare i propri dati senza contattare l’assistenza
  • I riepiloghi dell’IA con bassa confidenza mostrano un’avvertenza 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 di IA potrebbe trattare quel numero come una costante magica e suggerirne la modifica. Con un PDR, l’IA può vedere che il limite è legato alla strategia di prezzo, al costo di onboarding o al carico di supporto — e che modificarlo richiede una decisione di prodotto deliberata, non una modifica rapida.

Design Decision Records

I Design Decision Record catturano le decisioni di esperienza utente, interazione, visuale e di content design. Utilizza un DDR quando una decisione influisce su come gli utenti interagiscono con il prodotto, su come le informazioni vengono presentate o su come un principio di design dovrebbe essere applicato nei lavori futuri.

Gli esempi di decisioni di design che vale la pena registrare includono:

  • Utilizzare la validazione inline invece della validazione solo al momento dell’invio
  • Posizionare i suggerimenti dell’IA in un pannello laterale invece che direttamente nell’editor
  • Utilizzare la disclosure progressiva per le impostazioni avanzate
  • Richiedere conferma prima delle azioni distruttive
  • Utilizzare “Bozza” e “Pubblicata” invece di “Inattiva” e “Attiva”
  • 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 di IA potrebbe generare un componente che tecnicamente funziona ma viola il modello di interazione previsto. Ad esempio, un DDR potrebbe registrare: “Mostriamo i suggerimenti di scrittura dell’IA accanto al documento, non al suo interno, perché gli utenti devono confrontare il testo generato con la propria bozza prima di accettare le modifiche.” Questa registrazione fornisce ai contributor futuri un principio da preservare, non solo un layout da copiare.

Perché le registrazioni di decisione sono più importanti con l’IA

Gli strumenti di coding dell’IA sono potenti, ma sono spesso privi di stato o solo parzialmente consapevoli della storia del progetto. Possono ispezionare file, inferire schemi e generare modifiche — ma non sanno automaticamente quali decisioni sono intenzionali, quali sono accidentali e quali sono già state dibattute e risolte. Questo crea diversi rischi distinti.

L’IA potrebbe riaprire dibattiti già risolti

Se la squadra ha già deciso di utilizzare un monolite modulare, un agente di IA potrebbe ancora proporre l’estrazione di un servizio perché sembra pulito in isolamento. Senza un ADR, l’IA non ha un modo durevole per sapere che la squadra ha già considerato e rifiutato quel percorso e il risultato è uno sforzo sprecato o una regressione sottile nella coerenza del sistema.

L’IA potrebbe ottimizzare localmente e danneggiare globalmente

Un refactoring generato potrebbe rendere un file più pulito violando però i confini del sistema. Una modifica all’interfaccia utente potrebbe ridurre la complessità del componente indebolendo però l’esperienza utente prevista. Una modifica al prodotto potrebbe semplificare l’implementazione ma violare le ipotesi di prezzo o di conformità. Le registrazioni di decisioni forniscono all’IA un quadro di riferimento più ampio prima che agisca su segnali a ambito ristretto.

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

Un modello può seguire gli schemi esistenti nella base di codice, ma gli schemi 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 non visibile nel file. Le registrazioni di decisione spiegano la differenza tra “così funziona” e “ecco perché è stato costruito così”.

L’IA potrebbe generare motivazioni plausibili ma errate

L’IA può redigere registrazioni di decisione, ma può anche inventare spiegazioni che suonano sicure ma non corrispondono alla decisione reale. Per questo la revisione umana è imprescindibile: l’IA potrebbe generare la prima bozza di una registrazione, ma un umano deve verificare che descriva accuratamente la decisione effettiva, le alternative e le conseguenze prima che la registrazione venga integrata.

Le registrazioni di decisione come parte di una metodologia più ampia

Le registrazioni di decisione non sono solo documentazione — fanno parte di un modo di lavorare più ampio che si colloca all’intersezione tra la governance leggera dell’architettura, la documentazione come codice, i flussi di lavoro di gestione della conoscenza potenziati dall’IA, la scoperta del prodotto, le motivazioni di design, la governance dell’IA e la 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 dall’IA si concentra strettamente sul ciclo di generazione, revisione e commit:

flowchart LR A[Prompt] --> B[Generazione del codice] B --> C[Test] C --> D[Commit]

Quel ciclo è troppo sottile per lavori seri sui sistemi. Un flusso di lavoro più robusto tratta il repository come un archivio di entrambi, codice e intento — i diagrammi qui usano Mermaid, un formato leggero che funziona bene anche dentro le registrazioni di decisione in Markdown:

flowchart TB subgraph top[" "] direction LR A[Definire il problema] --> B[Identificare le decisioni esistenti] --> C[Esplorare opzioni e compromessi] --> D[Registrazione della decisione selezionata] end subgraph bottom[" "] direction LR E[Generare o modificare il codice] --> F[Revisionare il codice rispetto alle decisioni] --> G[Integrare implementazione e memoria] --> H[Usare la registrazione per guidare i lavori futuri] end D --> E

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

Le registrazioni di decisione e la documentazione come codice

Le registrazioni di decisione funzionano meglio quando seguono i principi della documentazione come codice, il che significa che dovrebbero essere archiviate nello stesso repository del codice, scritte in Markdown semplice, revisionate nelle pull request, versionate con Git, collegate a problemi e pull request correlate e ricercabili sia da umani che da strumenti di IA. Questo è molto più affidabile che conservare decisioni importanti in chat, pagine wiki, presentazioni o note di riunione — quegli strumenti possono ancora essere utili per la discussione, ma la decisione accettata dovrebbe sempre vivere vicino al codice. Mantenere specifiche, test e codice in sincronia nello sviluppo con IA estende questa stessa abitudine di “collegarla alla registrazione” in un modello di tracciabilità completo che collega gli ID delle decisioni di requisiti e design ai test e alle pull request.

Una struttura di repository ben organizzata per le registrazioni di decisione 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 altrettanto bene. L’esatta organizzazione delle cartelle conta meno della coerenza — le registrazioni devono essere facili da trovare, facili da revisionare e facili per gli strumenti di IA da caricare come contesto prima di agire sulla base di codice. Per le squadre Go, questa struttura docs/decisions/ si integra naturalmente accanto al layout cmd/, internal/ e api/ descritto in Struttura del progetto Go: pratiche e modelli, che consiglia docs/ come sede per le decisioni di architettura e i riferimenti dell’API.

Un template pratico per le registrazioni di decisione

Un template di registrazione di decisione utile dovrebbe essere abbastanza breve da essere effettivamente usato dalle persone. Ecco un template Markdown pratico che include una sezione di guida per l’IA opzionale ma preziosa:

# Decisione: Titolo breve

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

## Contesto

Descrivere il problema, i vincoli, gli obiettivi, i bisogni 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 questa crea.

## Guida per l'IA

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

## Collegamenti

- Problemi correlati:
- Pull request correlate:
- File correlati:
- Sostituisce:
- Sostituita da:

La sezione “Guida per l’IA” è opzionale, ma per la programmazione guidata dall’IA è estremamente preziosa — trasforma la registrazione di decisione in un’istruzione durevole per gli agenti futuri che lavorano nella stessa area della base di codice.

Cosa appartiene a una registrazione di decisione?

Non ogni scelta merita una registrazione e, se ogni piccolo dettaglio di implementazione diventa una registrazione di decisione, il processo collassa in rumore. Crea una registrazione di decisione quando una scelta è significativa e probabilmente avrà importanza in seguito.

Buoni candidati sono decisioni che:

  • Influiscono su più parti del sistema
  • Codificano una promessa del 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 di IA futuri potrebbero plausibilmente sbagliare
  • I contributor futuri potrebbero essere tentati di rovesciarle casualmente

Cattivi candidati includono piccole scelte di refactoring, ovvie correzioni di bug, esperimenti temporanei, decisioni di denominazione locale e dettagli di implementazione senza conseguenze durevoli. Una buona regola empirica è semplice: se rovesciare la decisione richiederà una discussione, registra la decisione.

Valori di stato e ciclo di vita

Le registrazioni di decisione dovrebbero avere un ciclo di vita per segnalare il loro stato attuale. I valori di stato più semplici sono sufficienti.

Proposta — La decisione è in fase di considerazione ma non ancora accettata. Usalo quando la squadra vuole discutere una decisione in una pull request prima di impegnarsi.

Accettata — La decisione è attiva e dovrebbe guidare i lavori futuri. La maggior parte delle registrazioni di decisione utili passerà la maggior parte della sua vita in questo stato.

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

Obsoleta — La decisione non è più raccomandata ma può ancora descrivere parti esistenti del sistema. Questo è particolarmente utile durante le migrazioni, quando i vecchi schemi esistono nella base di codice accanto a approcci più nuovi.

Il principio importante è che le registrazioni di decisione dovrebbero essere favorevoli all’aggiunta. Quando la squadra cambia direzione, crea una nuova registrazione e collega quella vecchia invece di riscrivere la storia per far sembrare il passato più pulito.

Come l’IA dovrebbe generare le registrazioni di decisione

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

Redigi un Architecture Decision Record per la decisione in questa pull request.
Includi contesto, alternative, conseguenze e guida per l'IA.
Salvalo come Markdown sotto docs/decisions/architecture.

Per i lavori di prodotto:

Redigi un Product Decision Record che spieghi perché i messaggi generati dall'IA
devono rimanere bozze finché non sono revisionati dall'utente.
Includi impatto utente, comportamento fuori ambito, compromessi e guida per l'IA.

Tuttavia, la registrazione generata dall’IA non dovrebbe essere fidata automaticamente. La revisione umana dovrebbe verificare che il contesto sia accurato, che l’IA non abbia inventato motivazioni, che le alternative elencate siano reali, che le conseguenze siano oneste e che la guida per l’IA corrisponda all’intento effettivo della squadra. L’IA è un assistente di redazione — non è la proprietaria della decisione.

Come l’IA dovrebbe leggere le registrazioni di decisione

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

Prima di modificare questa funzione, leggi docs/decisions.
Identifica eventuali Architecture, Product o Design Decision Records che si applicano.
Segui le decisioni accettate. Se la modifica proposta confluisce con una registrazione
di decisione, spiega il conflitto prima di modificare il codice.

Per compiti più grandi, rafforza il ruolo delle registrazioni come memoria di progetto:

Usa le registrazioni di decisione come memoria di progetto.
Non rovesciare decisioni accettate senza proporre una nuova decisione che le sostituisca.
Quando generi codice, spiega quali registrazioni di decisione hanno influenzato l'implementazione.

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

Le registrazioni di decisione nelle pull request

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

## Checklist della registrazione di decisione

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

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

Le registrazioni di decisione e la governance dell’architettura

La tradizionale governance dell’architettura spesso fallisce perché è troppo pesante, troppo lenta o troppo scollegata dall’implementazione — comitati centrali di approvazione, documenti iniziali grandi e processi di gatekeeping che bloccano invece di guidare. Le registrazioni di decisione 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 le squadre dall’imparare e adattare. Invece, creano una traccia di decisioni che può essere revisionata, riferita e costruita nel tempo. Questo supporta l’architettura evolutiva: l’architettura può cambiare, ma cambia con memoria e non nonostante essa. La squadra può riesaminare vecchie decisioni senza dover riscoprire perché sono state fatte, il che è una forma di governance più sana e onesta:

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

Le registrazioni di decisione e la gestione del prodotto

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

I Product Decision Record colmano quel vuoto e sono particolarmente utili per decisioni di prezzo e imballaggio, modelli di autorizzazione, limiti e quote, flussi di sicurezza e revisione dell’IA, scelte di onboarding, definizioni di ruolo utente, regole di collaborazione, politiche di retention dei dati e confini dell’ambito delle funzioni. Una volta implementate, le decisioni di prodotto diventano invisibili nel codice — più tardi, qualcuno vede solo il codice e chiede: “Perché funziona così?” Un PDR fornisce la risposta in una forma che sia gli umani che gli strumenti di IA possono trovare e usare.

Le registrazioni di decisione e i 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. I Design Decision Record colmano questo vuoto. Una libreria di componenti potrebbe dire “usa il dialogo di conferma per le azioni distruttive”, mentre un DDR spiega la motivazione: “Richiediamo la conferma per le azioni distruttive perché gli utenti spesso lavorano con dati di squadra condivisi e l’eliminazione accidentale ha un alto costo di recupero.”

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

Come le registrazioni di decisione supportano lo sviluppo basato su specifiche

Lo sviluppo basato su specifiche spiega cosa il sistema dovrebbe fare. Le registrazioni di decisione spiegano perché la squadra ha scelto quella direzione e la distinzione è significativa per il lavoro assistito dall’IA.

Una specifica di funzione può dire che le e-mail generate dall’IA devono essere salvate come bozze. Un Product Decision Record spiega perché l’invio automatico è stato rifiutato, quali rischi sono stati considerati e quali modifiche future richiederebbero una nuova decisione. Una specifica di design potrebbe descrivere un’interfaccia a pannello laterale, mentre il DDR corrispondente spiega perché le modifiche inline dell’IA sono state esplicitamente rifiutate e perché preservare il controllo dell’utente è stato pesato più pesantemente della velocità del flusso di lavoro. Una specifica di architettura può definire un confine di servizio e il suo ADR spiega perché la squadra ha scelto quel confine rispetto a un’alternativa più semplice o più distribuita.

La specifica guida l’implementazione. La registrazione di decisione preserva il giudizio. Insieme, danno agli agenti di coding dell’IA sia istruzioni che contesto – il “cosa” e il “perché” – che è ciò che rende la combinazione così efficace per sistemi complessi e a lunga durata. Quando si adotta una toolchain basata su specifiche, confronta come ogni opzione rende visibile quel contesto; GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows analizza la portabilità, i gate di revisione e l’ancoraggio al repository tra le principali configurazioni. Per il processo in cinque fasi neutrale rispetto agli strumenti implementato da quegli strumenti, vedi Flusso di lavoro di sviluppo basato su specifiche dai requisiti al codice. La maggior parte degli strumenti SDD gestisce solo la metà “spedito” di quel loop in modo pulito; Proposte rigettate di OpenSpec: una convenzione di memoria decisionale copre l’altra metà – registrare una decisione rigettata in modo durevole abbastanza da far sì che un agente la verifichi prima di riproporre la stessa idea.

Le registrazioni di decisione non sono specifiche

Le registrazioni di decisione sono correlate alle specifiche, ma servono a uno scopo diverso. Una specifica dice “il sistema deve fare X”, mentre una registrazione di decisione dice “abbiamo scelto X invece di Y a causa di questi vincoli e compromessi.” Quella parte “invece di Y” è la parte preziosa. Gli strumenti di IA spesso generano soluzioni trovando un percorso plausibile verso l’esito richiesto, ma le registrazioni di decisione dicono loro quali percorsi plausibili sono già stati esplorati, valutati e rifiutati — riducendo il churn e migliorando la qualità del lavoro assistito dall’IA.

Le registrazioni di decisione non sono una sostituzione per i test

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

Le registrazioni di decisione non sono una sostituzione per i commenti di codice

I commenti di codice spiegano i dettagli locali di implementazione, mentre le registrazioni di decisione spiegano decisioni più ampie. Usa i commenti per righe sorprendenti, casi limite, workaround e funzioni che non possono essere semplificate. Usa le registrazioni di decisione per perché esiste un’architettura, perché esiste un comportamento di prodotto, perché esiste uno schema di interazione e perché la squadra ha scelto una direzione rispetto a un’altra. Se la spiegazione influisce solo su poche righe, un commento è lo strumento giusto. Se influisce sulla direzione del sistema, una registrazione di decisione è lo strumento giusto.

Errori comuni

Scrittura di registrazioni troppo tardi

Una registrazione di decisione dovrebbe essere scritta quando la decisione è presa, non mesi dopo quando tutti hanno dimenticato i compromessi. È bene redigerne una durante una pull request. È ancora meglio redigerla prima dell’implementazione, mentre la decisione è ancora in fase di discussione attiva e le alternative sono fresche.

Renderle registrazioni troppo lunghe

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

Registrazione di decisioni senza conseguenze

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

Modifica di 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 adattarla allo stato attuale distrugge il contesto storico che rende preziose le registrazioni di decisione. La storia è utile proprio perché mostra come il pensiero si è evoluto. Le basi di conoscenza compilate affrontano lo stesso problema con un nome diverso — Manutenzione Wiki LLM: deriva, contraddizioni e revisione lo chiama deriva decisionale e applica la stessa regola di sostituzione invece di sovrascrittura alle pagine wiki.

Lasciare che registrazioni generate dall’IA vengano integrate senza revisione

L’IA può produrre una registrazione lucida e ben strutturata che è sottilmente errata. Tratta le registrazioni di decisione generate dall’IA esattamente come il codice generato dall’IA — revisionale attentamente, verifica che la motivazione sia accurata e assicurati che la sezione sulle conseguenze rifletta ciò che la squadra ha effettivamente accettato.

Nascondere le registrazioni fuori dal repository

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

Un modello operativo leggero

Un processo di squadra pratico che aggiunge un sovraccarico minimo è simile a questo:

  1. Durante la pianificazione o l’implementazione, identificare se sta prendendo forma una decisione significativa.
  2. Chiedere a un assistente di IA di redigere un ADR, PDR o DDR basato sulla discussione.
  3. Revisionare la bozza come squadra, verificando contesto, alternative e conseguenze.
  4. Committare la registrazione come Markdown nel repository.
  5. Collegarla dal problema o dalla pull request correlata.
  6. Istruire gli strumenti di coding dell’IA a leggere le registrazioni rilevanti prima di apportare modifiche future nell’area.
  7. Sostituire 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 il giudizio importante nel momento in cui viene creato, vicino al codice dove sarà necessario.

Esempio di ADR

# Decisione: Utilizzare PostgreSQL per l'archiviazione primaria dell'applicazione

Stato: Accettata
Data: 25/06/2026
Tipo: Architettura
Responsabili: Squadra Piattaforma

## Contesto

L'applicazione ha bisogno di un'archiviazione relazionale durevole per account, progetti,
autorizzazioni ed eventi di audit. La squadra si aspetta frequenti query di reporting
e requisiti di forte consistenza per i controlli di autorizzazione.

## Decisione

Utilizzeremo PostgreSQL come database principale dell'applicazione.

## Alternative considerate

### DynamoDB

Pro:
- Scalabile operativamente
- Buona aderenza per schemi di accesso chiave-valore prevedibili

Contro:
- Più complesso per query relazionali
- Più difficile per reporting ad hoc
- Meno familiare alla squadra attuale

### MySQL

Pro:
- Database relazionale maturo
- Modello operativo familiare

Contro:
- PostgreSQL si adatta meglio ai bisogni della squadra per il supporto JSON,
le opzioni di indicizzazione e l'esperienza esistente

## Conseguenze

PostgreSQL diventa una dipendenza operativa centrale. La squadra deve gestire
accuratamente le migrazioni e monitorare le prestazioni delle query. In cambio,
l'applicazione ottiene un modello relazionale forte, un'indicizzazione matura e
un supporto flessibile per il reporting.

## Guida per l'IA

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

Esempio di PDR

# Decisione: Le e-mail generate dall'IA devono rimanere bozze

Stato: Accettata
Data: 25/06/2026
Tipo: Prodotto
Responsabili: Squadra Prodotto

## Contesto

Il prodotto può generare risposte a e-mail utilizzando l'IA. L'invio di e-mail è un'azione
ad alta fiducia perché gli errori possono raggiungere clienti, partner o squadre
interne.

## Decisione

Le e-mail generate dall'IA devono essere create come bozze. Un utente umano deve
revisionarle e inviarle.

## Alternative considerate

### Invio automatico

Pro:
- Flusso di lavoro più veloce
- Meno sforzo da parte dell'utente

Contro:
- Rischio più alto di messaggi errati o inappropriati
- Fiducia dell'utente inferiore
- 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 al comportamento del client di posta esistente meglio delle 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 aggirare
l'approvazione umana senza un PDR sostitutivo accettato.

## Guida per l'IA

Quando si costruiscono funzioni di generazione di e-mail, creare bozze per impostazione predefinita.
Non aggiungere invio automatico a meno che un nuovo PDR accettato non lo permetta esplicitamente.

Esempio di DDR

# Decisione: Mostrare i suggerimenti di scrittura dell'IA in un pannello laterale

Stato: Accettata
Data: 25/06/2026
Tipo: Design
Responsabili: Squadra Design

## Contesto

Gli utenti hanno bisogno di aiuto per migliorare il contenuto scritto, ma hanno anche bisogno
di mantenere il controllo del testo finale. Le modifiche inline dell'IA possono rendere difficile
distinguere il contenuto scritto dall'utente dai suggerimenti generati.

## Decisione

I suggerimenti di scrittura dell'IA 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:
- Confonde la paternità
- 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 suggerimento e testo originale

## Conseguenze

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

## Guida per l'IA

Quando si aggiungono funzioni di assistenza alla scrittura, preservare la separazione tra
testo utente e suggerimenti dell'IA. 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 di decisione parte dello sviluppo assistito dall’IA quotidiano.

Trovare registrazioni rilevanti prima di lavorare su una funzione:

Leggi docs/decisions e identifica eventuali registrazioni di decisione accettate che si applicano
a questo compito. Riepiloga i vincoli prima di proporre modifiche al codice.

Redigere un nuovo ADR:

Redigi un Architecture Decision Record per questa decisione tecnica.
Includi contesto, decisione, alternative, conseguenze e guida per l'IA.
Tienilo conciso e specifico.

Redigere un nuovo PDR:

Redigi un Product Decision Record per questo comportamento di prodotto.
Includi impatto utente, ambito, alternative, conseguenze e guida per l'IA.

Redigere un nuovo DDR:

Redigi un Design Decision Record per questo schema di interazione.
Includi problema utente, alternative, compromessi, conseguenze e guida per l'IA.

Revisionare una pull request rispetto alle decisioni esistenti:

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

Sostituire una decisione:

Crea una nuova registrazione di decisione che sostituisca quella esistente.
Preserva la motivazione storica, spiega cosa è cambiato e collega entrambe le registrazioni.

Lettura correlata

Iscriviti

Ricevi nuovi articoli su sistemi, infrastruttura e ingegneria AI.