Scrittore di Architecture Decision Record
Lo Scrittore di Architecture Decision Record produce un ADR ben strutturato che cattura il contesto completo dietro una decisione tecnica, valuta le alternative con compromessi espliciti e documenta le conseguenze per i futuri membri del team. Segue il formato ADR ampiamente adottato (titolo, stato, contesto, decisione, conseguenze) aggiungendo profondità che trasforma un documento burocratico in un riferimento storico realmente utile.
Software architect, senior engineer, tech lead e engineering manager usano questo template quando prendono decisioni tecniche significative: scegliere un database, adottare un framework, definire una strategia API, selezionare un modello di deploy o stabilire una convenzione di codice. È particolarmente utile per team distribuiti dove le decisioni vengono prese in modo asincrono e il ragionamento deve essere catturato per chi non era presente.
Il prompt va oltre un template vuoto richiedendo di articolare le forze che guidano la decisione (vincoli tecnici, requisiti di business, competenze del team, pressione sulle tempistiche) e di valutare ogni opzione rispetto a queste forze. Questo confronto strutturato previene il caso tipico in cui un ADR dice "abbiamo scelto X" senza spiegare perché X ha battuto le alternative. La sezione conseguenze separa esplicitamente risultati positivi, compromessi negativi e rischi, dando ai futuri lettori il quadro completo per capire se il ragionamento originale è ancora valido.
This prompt is just the starting point
Score it with AI, optimize it with one click, track versions, and build your prompt library.
The Prompt
Scrivi un Architecture Decision Record (ADR) basato sui seguenti input: **Titolo della Decisione**: [TITOLO BREVE E DESCRITTIVO, es. "Usare PostgreSQL come datastore primario", "Adottare architettura event-driven per l'elaborazione ordini", "Migrare da REST a GraphQL per l'API pubblica"] **Stato**: [proposed / accepted / deprecated / superseded by ADR-XXX] **Contesto e Descrizione del Problema**: [DESCRIVI LA SITUAZIONE CHE RICHIEDE UNA DECISIONE. Includi: - Quale sistema o componente è coinvolto - Quale problema o opportunità ha innescato questa decisione - Eventuali vincoli rilevanti (budget, tempistiche, competenze del team, requisiti di conformità) - Stato attuale (cosa esiste oggi, se qualcosa)] **Opzioni Considerate**: 1. [OPZIONE 1: Nome e breve descrizione] 2. [OPZIONE 2: Nome e breve descrizione] 3. [OPZIONE 3: Nome e breve descrizione] [Aggiungi altre se applicabile. Includi l'opzione "non fare nulla" se rilevante.] **Fattori Decisionali** (le forze che contano di più per questa decisione): - [es. "Deve gestire 10.000 connessioni simultanee"] - [es. "Il team ha esperienza approfondita in Python ma nessuna in Go"] - [es. "Deve essere conforme SOC 2"] - [es. "Budget limitato a 500 $/mese per l'infrastruttura"] Scrivi l'ADR con queste sezioni: 1. **Titolo**: ADR-[NUMERO]: [TITOLO DELLA DECISIONE] 2. **Stato**: [Come indicato sopra] 3. **Data**: [DATA DI OGGI] 4. **Contesto**: Espandi la descrizione del problema in 2-3 paragrafi che diano a un lettore senza contesto precedente tutto ciò che serve per capire perché questa decisione era necessaria. Includi il panorama tecnico, i driver di business e i vincoli. 5. **Fattori Decisionali**: Elenca ogni fattore come elemento numerato e prioritizzato con una breve spiegazione di perché conta. 6. **Opzioni Considerate**: Per ogni opzione, fornisci: - Una descrizione di 2-3 frasi su come funzionerebbe - **Pro**: 3-5 vantaggi specifici, collegati ai fattori decisionali - **Contro**: 3-5 svantaggi specifici, collegati ai fattori decisionali - **Impegno stimato**: Stima approssimativa dello sforzo di implementazione (piccolo / medio / grande) - **Livello di rischio**: (basso / medio / alto) con una giustificazione in una frase 7. **Decisione**: Dichiara l'opzione scelta chiaramente in una frase. Poi spiega in 2-3 paragrafi perché questa opzione è stata selezionata rispetto alle alternative, facendo riferimento a fattori decisionali e compromessi specifici. 8. **Conseguenze**: - **Positive**: Cosa migliora grazie a questa decisione - **Negative**: Quali compromessi il team accetta - **Rischi**: Cosa potrebbe andare storto e quali mitigazioni sono previste - **Azioni successive**: Task specifici necessari per implementare questa decisione (con responsabili, se noti) 9. **Riferimenti**: Link o citazioni a documentazione rilevante, benchmark o ADR precedenti.
Usage Tips
- Scrivi il contesto per chi entrerà nel team fra sei mesi: L'errore più comune negli ADR è dare per scontato che il lettore abbia lo stesso contesto di chi ha preso la decisione. Includi dettagli che oggi sembrano ovvi ma che non lo saranno in futuro.
- Includi l'opzione "non fare nulla": Valutare esplicitamente lo status quo ti costringe ad articolare perché il cambiamento è necessario e stabilisce una baseline per confrontare le alternative.
- Sii onesto sui contro dell'opzione scelta: Un ADR che elenca solo aspetti positivi per l'opzione selezionata perde credibilità. I futuri lettori si fideranno di più del documento se riconosce apertamente i compromessi e spiega perché erano accettabili.
- Collega i fattori decisionali ai risultati di business: "Deve gestire 10.000 connessioni simultanee" è più forte se accompagnato da "perché le proiezioni di crescita del Q3 mostrano un raddoppio del traffico di picco." Questo aiuta i futuri lettori a valutare se i vincoli originali sono ancora validi.
- Conserva gli ADR nel repository, non in un wiki: Gli ADR sono più utili quando vivono accanto al codice che descrivono. Usa una directory
/docs/adr/nel tuo repository così sono versionati, ricercabili e scoperti naturalmente durante la code review.
Get more from this prompt
Save it, score it with AI, optimize it, and track every version. Free to start.