Architecture review e ADR: il perché resta accanto al codice

2026-10-18

Ogni codebase ha una parte che sembra sbagliata alla prossima persona che la legge. Un processo di relay che nessuno ricorda di aver aggiunto, una tabella che viene svuotata ogni settimana, una coda dove basterebbe una chiamata diretta. Le ragioni sono state dette ad alta voce in un'architecture review mesi fa, e chi le ha date è passato ad altri team. Il nuovo ingegnere ha due possibilità: chiedere in giro per una settimana o «sistemarlo».

C'è una strada più breve. Si registra l'architecture review, si preme una scorciatoia quando viene detta una decisione, un compromesso o un'opzione scartata, e si condivide la registrazione in un canale Architecture. Le marcature restano sulle frasi, con l'orario e il nome di chi parlava. Subito dopo la review un assistente IA in Claude Code, Cursor o Claude legge quelle marcature via MCP e scrive la bozza dell'Architecture Decision Record (ADR) per il repository. Mesi dopo il dibattito è ancora lì per chiunque chieda il perché.

Questa guida segue l'app Speak-Y per macOS, verificata il 18 ottobre 2026, ed è pensata per un tech lead il cui team condivide già le riunioni in uno spazio di lavoro. Se non lo si ha ancora, conviene prima crearne uno.

Perché «perché è fatto così?» non ha risposta?

La soluzione è stata descritta nel 2011. Il post di Michael Nygard Documenting Architecture Decisions (verificato il 18 ottobre 2026) propone un breve documento per ogni decisione significativa — titolo, contesto, decisione, stato, conseguenze — tenuto nel repository accanto al codice. Il suo ragionamento è il problema descritto sopra: chi è nuovo in un progetto e non sa perché è stata presa una decisione può solo accettarla alla cieca o ribaltarla alla cieca. Il sito della community ADR chiama la raccolta di questi documenti il registro delle decisioni di un progetto.

Anche i team che adottano gli ADR perdono il perché, in tre punti prevedibili:

• Il contesto viene ricostruito. L'ADR si scrive dopo la review, a memoria, da chi ha tempo. I vincoli che hanno guidato la decisione sono la prima cosa a sbiadire.
• Le opzioni scartate si riducono a una riga. «Abbiamo considerato CDC» non dice nulla sul perché abbia perso, ed è proprio ciò che serve alla prossima persona prima di riproporlo.
• L'ADR non viene mai scritto. Una review che finisce alle 16 compete con il codice da consegnare domani.

Una registrazione conserva tutte e tre le cose. Le marcature le rendono trovabili, e un assistente le trasforma in una bozza prima che i dettagli sbiadiscano.

Da impostare una volta: tre marcature e un canale Architecture

Le marcature. Speak-Y arriva con un solo tipo di nota, Segna il momento su ⌥1. Se ne aggiungono tre propri in Impostazioni → Note: si fa clic su Aggiungi tipo di nota, si digita Decision in Nome del tipo, si fa clic su Salva, poi su Imposta scorciatoia e si preme ⌥2. Si ripete per Trade-off su ⌥3 e Rejected su ⌥4. Ogni marcatura corrisponde a una sezione dell'ADR:

• Decision — che cosa il team ha deciso di costruire. Diventa la decisione dell'ADR.
• Trade-off — il costo che il team ha accettato in cambio. Diventa le conseguenze.
• Rejected — un'opzione che ha perso, con il motivo. Diventa le alternative considerate.

Il contesto è la discussione intorno alle marcature; l'assistente lo legge dalla trascrizione. Il formato di Nygard non ha una sezione a parte per le opzioni scartate; il modello MADR ne ha una: Considered Options.

Il canale. Un canale pubblico per le architecture review, chiamato Architecture, a cui ogni ingegnere può unirsi. Nel menu ⋯ dello spazio di lavoro si sceglie New channel. Le review di design sensibili per la sicurezza — un threat model, un flusso di autenticazione — vanno invece in un canale privato; il compromesso è trattato in chi vede che cosa nei canali delle riunioni.

Durante la review: prima il nome del componente, poi il tasto

Quando la review inizia, si avvia una registrazione di riunione in Speak-Y. Nessun bot entra nella call: Speak-Y registra il microfono e il suono della call sul proprio Mac, quindi funziona allo stesso modo su Zoom, Google Meet, Teams o in una sala riunioni. Va detto a tutti che la review viene registrata.

La trascrizione conosce solo ciò che è stato detto, quindi tre abitudini ripagano:

1. Dire il nome del componente prima di discuterne. «Il publisher degli eventi di pagamento in payments-service» rende ogni marcatura successiva trovabile con il nome che un ingegnere cercherà più avanti.
2. Lasciar dire il motivo, poi premere. Una marcatura copre gli ultimi 15 secondi della trascrizione prima del tasto, quindi la frase con il perché ci rientra.
3. Marcare anche le opzioni perdenti. Una marcatura Rejected su «le doppie scritture perdono eventi se il servizio va in crash tra l'una e l'altra» è la riga che fa risparmiare mezz'ora alla prossima review.

Di solito è il tech lead che conduce la review a registrare e premere i tasti. Le scorciatoie funzionano da qualsiasi app, con il diagramma o il codice ancora in primo piano.

Dopo la review: nomi, tag, To channel

Due minuti nella finestra della registrazione, finché è tutto fresco:

1. Dare un nome ai parlanti. Si fa clic su Speaker 1, Speaker 2 e così via, e si digitano i nomi veri. Una marcatura è utile quanto il nome che le sta accanto.
2. Assegnare i tag. Si aggiungono il nome del servizio e il numero dell'ADR che si sta per scrivere, per esempio payments-service e adr-0012. Da questi tag l'assistente e i colleghi ritrovano la review.
3. Controllare le marcature. I chip sopra la trascrizione le contano per tipo: Tutte le note · 8, Decision · 3, Trade-off · 3, Rejected · 2.
4. Condividere. Si preme To channel sotto la trascrizione e si sceglie Architecture. La trascrizione con nomi e marcatori temporali, il riepilogo IA e gli action items vanno nel canale, cifrati end-to-end; l'audio resta sul proprio Mac.
5. Mostrare le marcature. Le marcature sono private per impostazione predefinita. Si fa clic sul chip Private sopra la trascrizione e si sceglie Mostra in # Architecture — i membri del canale le vedranno, così le marcature viaggiano con la registrazione.

Scrivere la bozza dell'ADR dalle marcature

Si collega l'assistente al server MCP di Speak-Y una volta sola: si apre Connetti assistente IA nel menu dell'account in fondo alla barra laterale, oppure Impostazioni → Integrazioni, e si fa clic su Connetti accanto a Claude, ChatGPT o Cursor. Per Claude, un clic configura sia Claude Desktop sia Claude Code. Il server è gratuito con ogni piano.

Poi, nel repository, si chiede:

Scrivi la bozza dell'ADR 0012 dalla review di payments-service con il tag adr-0012: contesto, decisione, conseguenze e opzioni scartate. Indica per ogni punto chi l'ha detto e quando.

L'assistente trova la review dal tag e la legge. Insieme alla trascrizione, Speak-Y gli passa le marcature come elenco — ognuna con il suo scarto nella registrazione, il tipo, il parlante e le prime parole della frase —, così la bozza arriva con tre decisioni, tre costi accettati e due opzioni scartate, ciascuno con un nome e un orario. In Cursor l'assistente chiede conferma prima di eseguire ogni strumento, a meno che non lo si cambi.

La bozza va rivista prima del commit. Tre campi spettano all'ingegnere, non all'assistente:

• Stato. Proposto o accettato è una decisione del team, non qualcosa che una trascrizione possa dire.
• Responsabile. Chi risponderà alle domande in merito il prossimo trimestre.
• Il rimando. Si scrive dove si trova il dibattito — il canale, la data e il tag — così il prossimo lettore può ripercorrere il ragionamento. Nel canale la registrazione è cifrata end-to-end, quindi il rimando funziona per i colleghi dello spazio di lavoro, non per il pubblico.

Mesi dopo: il nuovo ingegnere chiede perché

L'ADR nel repository risponde al che cosa in una pagina. Quando non basta, il dibattito è a un passo.

Nell'app. I colleghi invitati si uniscono gratis con qualsiasi piano. Un nuovo ingegnere che entra nello spazio di lavoro vede il canale pubblico Architecture con la sua cronologia. Lo si apre, si fa clic sulla lente nell'intestazione del canale e si digita il nome del componente, per esempio outbox. La ricerca legge le trascrizioni di tutte le review del canale e mostra le righe corrispondenti con i loro orari.

Nell'editor. In Cursor o Claude Code, con il codice aperto:

Perché payments-service scrive gli eventi in una tabella outbox invece di pubblicarli direttamente su Kafka? Che cosa è stato scartato?

L'assistente cerca tra le registrazioni che l'ingegnere può vedere, trova la review e risponde a partire da essa: la decisione, chi si è opposto alle doppie scritture e perché, e che cosa il team ha accettato in cambio. Lo stesso schema per le domande sul codice in generale è in contesto delle riunioni per il voice coding in Cursor.

Ciò che la registrazione di una review non sostituisce

La registrazione conserva il ragionamento. Quattro cose stanno ancora altrove:

• Il diagramma. Lavagne, slide e diagrammi di sequenza non sono nella registrazione. Il link va messo nell'ADR.
• Lo stato finale. Una marcatura Decision registra che la stanza era d'accordo; se la decisione sia stata poi superata lo dicono gli ADR del repository.
• Le decisioni prese in chat. Una scelta fatta nel thread di una pull request non è mai arrivata alla review. Va scritta direttamente nell'ADR.
• Il codice stesso. Se codice e ADR non concordano, è il codice a girare. Si aggiorna l'ADR o il codice — la registrazione dice solo che cosa si intendeva fare.

Limiti e costi

• Durata. Verificato su speak-y.com il 18 ottobre 2026: Free ferma una registrazione di riunione a 30 minuti, Pro ($10 al mese) a 60, Pro+ ($15) e Max ($30) a quattro ore. Una lunga sessione di design richiede Pro+ o una pausa allo scadere dell'ora.
• Una sola persona che registra. Due persone che registrano la stessa review producono due mezzi elenchi di marcature.
• Canali su Mac. Spazi di lavoro e canali sono nell'app per macOS. Per creare uno spazio di lavoro serve Pro o superiore; i colleghi si uniscono gratis con qualsiasi piano.

In breve

Tre tipi di nota — Decision, Trade-off, Rejected — su ⌥2, ⌥3 e ⌥4. Durante la review: si dice il nome del componente, si lascia esprimere il motivo, si preme il tasto. Dopo: nomi, tag, To channel → Architecture, marcature visibili. Poi una domanda all'assistente nel repository, e si rivede la bozza dell'ADR invece di scriverla a memoria. La pagina Teams tratta spazi di lavoro e canali, e un registro delle decisioni che si aggiorna da solo applica la stessa idea alle decisioni di prodotto.

FAQ

Come si conserva il perché di una decisione architetturale?

Si registra l'architecture review in Speak-Y e si preme una scorciatoia quando viene detta ad alta voce una decisione, un compromesso o un'opzione scartata. Si condivide la registrazione in un canale del team come Architecture. Il canale conserva il dibattito con nomi e marcatori temporali, e un assistente IA collegato via MCP può trasformare le marcature in una bozza di Architecture Decision Record per il repository.

Claude Code o Cursor possono scrivere un ADR dalla registrazione di una riunione?

Possono scriverne una bozza. Collegato al server MCP di Speak-Y, l'assistente trova la review dal tag, legge la trascrizione e l'elenco delle marcature con tipo, orario e parlante, e compila contesto, decisione, conseguenze e opzioni scartate. Stato, responsabile e formulazione finale restano all'ingegnere che fa il commit del file.

Come scopre un nuovo ingegnere perché un servizio è costruito in un certo modo?

In due modi. Si apre il canale Architecture nell'app Speak-Y per macOS e lo si cerca per nome del componente, oppure si chiede a un assistente nell'editor, come Cursor o Claude Code, perché il servizio fa quello che fa. L'assistente cerca tra le registrazioni che l'ingegnere può vedere e risponde indicando chi ha detto cosa e quando.

Speak-Y registra la lavagna o i diagrammi mostrati durante la review?

No. Speak-Y registra l'audio dal Mac che avvia la registrazione: il microfono e il suono dell'app di chiamata. Diagrammi, slide e lavagne non sono nella registrazione. Conviene dire ad alta voce il nome del componente prima di discuterne e mettere il link al diagramma nell'ADR.

Quanto costa questa configurazione?

Il server MCP è gratuito con ogni piano. Per creare uno spazio di lavoro del team serve Pro o superiore, e i colleghi si uniscono gratis con qualsiasi piano. Verificato su speak-y.com il 18 ottobre 2026: Free ferma una registrazione di riunione a 30 minuti, Pro ($10 al mese) a 60, Pro+ ($15) e Max ($30) a quattro ore.