---
title: "Come scrivere un ADR che serva alla prossima review"
source: "https://www.matteovincenti.com/blog/come-scrivere-adr-review"
language: it
author: "Matteo Vincenti"
published: 2026-11-11
category: "Team management"
tags: ["Team management", "Qualità software", "Workflow"]
---

# Come scrivere un ADR che serva alla prossima review

Un esempio Markdown di Architecture Decision Record per motivare una scelta tecnica, verificare il rilascio e capire quando rivederla.

![Una scheda di decisione affianca lavori in coda, un dispositivo di elaborazione e una lente sul foglio prodotto.](https://cdn.sanity.io/images/xrqkwry7/production/406d128ad170d93338c14c00967eef5eda2793d6-1672x941.png?w=1400&fit=max&auto=format)

Categoria: Team management · Tag: Team management, Qualità software, Workflow

In un’applicazione immaginaria, il browser aspetta il file CSV dei report del mese. Se la generazione impiega più del tempo concesso alla richiesta, il cliente resta senza file. Il team decide di mettere il lavoro in coda e confermare subito la ricezione. Un processo separato, chiamato **worker**, prende il lavoro in attesa e genera il CSV.

La modifica funziona in staging, l’ambiente di prova. Durante la review della pull request, qualcuno controlla il piano di rilascio e scopre che manca il worker per la coda di produzione. Il team aveva già approvato l’uso della coda. L’export resta chiuso ai clienti mentre chi rivede la modifica stabilisce quale prova serve per aprirlo.

Un **Architecture Decision Record (ADR)** è un breve documento che conserva una decisione tecnica significativa, il problema che l’ha resa necessaria e le sue conseguenze. Nel caso del CSV, può indicare anche quale risultato deve vedere chi segue il rilascio prima di attivare la funzione. [Il formato ADR di Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).

## Quando scrivere un ADR

Il team poteva tenere il flusso esistente e limitare la dimensione di ogni report. Avrebbe gestito meno componenti, chiedendo però ad alcuni clienti di dividere il mese in più esportazioni. Con la coda il cliente può chiedere il mese intero, lasciare la pagina e tornare più tardi per il file. Il team deve avviare il worker, accorgersi se i lavori restano in attesa e rendere visibile l’esito.

Vale la pena scrivere un ADR quando una scelta del genere cambia un comportamento su cui gli utenti contano o introduce una responsabilità che qualcuno dovrà gestire dopo la pull request. Un dettaglio locale, comprensibile leggendo le righe cambiate, può stare nella descrizione della modifica. [Guida di Google Cloud a contesto, opzioni e decisione](https://docs.cloud.google.com/architecture/architecture-decision-records?hl=en).

## Un esempio Markdown da riusare

Scrivi il primo ADR come proposta, quando le alternative sono ancora aperte. Puoi metterlo vicino al codice, per esempio in `docs/adr/0012-esportazioni-csv.md`, e sottoporlo a review. Qui sotto c’è lo stesso documento dopo l’accettazione. I riferimenti fra parentesi quadre indicano dove collegare le evidenze del tuo progetto.

```markdown
# ADR-012 — Generare le esportazioni CSV in background

## Contesto
La generazione dei report più grandi può superare il tempo massimo
della richiesta. Il cliente deve poter scaricare un mese in un solo file.

## Alternative
- Restare sincroni e limitare i report. Meno componenti da gestire,
  ma alcuni clienti devono dividere il mese in più download.
- Accodare la generazione. Un solo file anche per i report grandi,
  con un worker da gestire e uno stato da mostrare all'utente.

## Decisione e approvazione
Accettata — [review che approva l'ADR].
Il requisito del file unico giustifica la gestione del worker.
La richiesta mette il lavoro in coda. Il worker genera il file.
L'utente ritrova l'esito nella lista delle esportazioni.

## Conseguenze
Il team che gestisce il servizio [riferimento operativo] avvia il worker
e prende in carico i lavori fermi. La lista mostra se il file è pronto
o se l'esportazione è fallita.

## Verifiche prima di aprire l'export ai clienti
- Sulla versione candidata in staging, un report fittizio di dimensione
  rappresentativa produce il CSV completo entro il tempo concordato.
- In produzione, un account di test richiede un nuovo export sullo stesso
  percorso dei clienti. La prova passa se, entro il tempo concordato, il worker previsto
  elabora quell'ID e il CSV scaricato contiene i dati attesi.
Il responsabile del rilascio registra gli esiti nel [ticket di rilascio].

## Quando riesaminare
Se i lavori urgenti aspettano più del limite concordato durante i batch
di export, verifica dove si accumula l'attesa prima di cambiare le code.
```

Nel formato Markdown Architectural Decision Records (MADR), **Confirmation** è la sezione facoltativa in cui indicare come verificare l’attuazione. Se il tuo team ha già un controllo equivalente, collegalo dall’ADR. Il documento conserva il risultato atteso. Nel ticket di rilascio registri chi ha eseguito la prova, con quale configurazione e con quale esito. [La decisione pubblica di MADR sulla sezione Confirmation](https://adr.github.io/madr/decisions/0018-use-confirmation-as-heading.html).

Per l’accettazione della scelta può bastare una convenzione di squadra. Al Government Digital Service britannico, per esempio, il documento sul ramo principale può indicare che la decisione è accettata. [Il ciclo di vita degli ADR nel Government Digital Service](https://gds-way.digital.cabinet-office.gov.uk/standards/architecture-decisions.html).

## La prova che cambia il verdetto

Nel caso del CSV servono due riscontri. In staging, usa un report fittizio delle dimensioni di quelli che facevano scadere la richiesta. Confronta il file con i dati attesi e verifica che l’esportazione si concluda entro il tempo concordato per quel caso. In produzione, prima di aprire l’export ai clienti, basta un controllo più piccolo per verificare che il percorso di rilascio funzioni.

Prima della prova in produzione, fissa un tempo massimo di attesa. Usa un account di test con tre righe fittizie note. Deve seguire lo stesso percorso previsto per i clienti. La conferma della richiesta restituisce un ID, che compare anche nella lista delle esportazioni. Annota l’ID della nuova richiesta, chiudi la pagina e torna alla lista. Cerca lo stesso ID nei log del worker previsto dal rilascio e verifica che risulti elaborato. Scarica il CSV dalla riga corrispondente e confronta mese e contenuto con i dati di partenza. Se alla scadenza manca la conferma nei log del worker previsto, il file è assente o i dati sono diversi da quelli attesi, registra ID, stato ed esito nel ticket. L’accesso ai clienti resta chiuso.

_La prova che cambia il verdetto_

| Riscontro | Che cosa dimostra | Decisione di review |
| --- | --- | --- |
| L’app conferma che la richiesta è in coda | Il sistema ha registrato il lavoro. | Verifica anche la generazione e il download. |
| In staging il report grande produce il CSV completo entro il tempo concordato | Il caso rappresentativo riesce con quella versione e quel carico di prova. | Esegui anche il controllo del percorso in produzione. |
| Il piano di rilascio non prevede un worker per la coda di produzione | Nel rilascio manca il processo che deve generare il file. | Ferma il passaggio che esporrebbe l’export ai clienti. |
| Esito atteso in produzione. Il worker previsto elabora il nuovo ID e l’account di test scarica il CSV corrispondente con i dati attesi entro il tempo concordato | Il percorso funziona per la distribuzione e i dati provati. | Registra l’esito. Apri l’accesso quando anche la verifica sul report grande è soddisfatta. |

Nel ticket, chi segue il rilascio indica ambiente, versione dell’applicazione, configurazione del worker, ID e risultato. Può usare un riferimento unico alla distribuzione se permette di risalire anche alla configurazione del worker e della coda. Se prima dell’apertura cambia una versione o una configurazione rilevante per l’export, ripete la prova sul percorso modificato.

Nella pull request puoi lasciare un commento di questo tipo.

> Il report grande passa in staging. Nel piano di produzione manca il worker delle esportazioni. Prima di aprire l’export ai clienti, chi segue il rilascio aggiunga il worker e avvii una nuova esportazione con l’account di test sul percorso previsto per i clienti. Entro il tempo concordato, verifichi nei log che il worker previsto abbia completato il lavoro, scarichi il CSV dalla riga con lo stesso ID e confronti il contenuto con i dati attesi. Registri distribuzione, ID ed esito nel ticket.

Quando il team può riservare la funzione al solo account di test, può integrare il codice e fare la prova prima di aprire l’accesso. Se il deploy rende subito disponibile l’export, ferma il deploy fino a quando la candidata può essere provata con accesso riservato e il controllo riesce. Se è il merge della pull request a far partire quel deploy, lascia aperta la pull request. Lo stesso modo di legare un verdetto a un riscontro si applica anche alla [review di una pull request a partire dal requisito](https://www.matteovincenti.com/blog/code-review-agenti-ai-pr-pronta).

## Quando riaprire la scelta

Se più avanti partono esportazioni pianificate in blocco e i lavori urgenti aspettano più del limite concordato, confronta il tempo fra accodamento e avvio durante i batch e nei periodi normali. Controlla se i worker sono occupati dai report o se i lavori competono per un’altra risorsa, come il database. Se il team decide di assegnare ai report una coda e un worker dedicati, collega il nuovo ADR all’ADR-012. La generazione resta in background. Se cambia il requisito del file unico e il team torna a generare durante la richiesta con un limite di dimensione, la nuova decisione sostituisce l’ADR-012. Indica lo stato del vecchio documento, collega il successore e lascia leggibile la motivazione originale. [Indicazioni AWS sulla conservazione dello storico](https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/best-practices.html).

Se l’ADR prevede una verifica prima dell’attivazione, usala durante la review. Nel ticket di rilascio cerca chi la esegue, la versione da provare e l’esito. Se la prova è ancora in sospeso, scrivi nella pull request quale passaggio resta fermo e quale esito lo sblocca.
