Discutere l'architettura dove vive

Qualcuno nota che Billing scrive direttamente nel database del ledger, anche se l'ADR-12 dice che può farlo solo la Ledger API. Lo chiede in un thread di Slack. Due risposte, un "ottima osservazione, ci guardo", e a pranzo il thread è già scomparso dallo schermo. Un mese dopo la freccia è ancora nel diagramma, l'ADR-12 si legge ancora come se nessuno l'avesse mai messo in discussione, e la persona che aveva detto "ci guardo" è passata a un altro team. La domanda è stata posta e ha avuto risposta, in un posto che l'architettura non vede.

È questo il vuoto su cui abbiamo lavorato questa settimana. Il 18 ottobre abbiamo rilasciato sei funzionalità che portano la conversazione sull'architettura dentro il modello stesso: commenti fissati sul diagramma, @menzioni, citazioni con # e un elenco "Citato in", anteprime dei link nell'app e in Slack, il seguire e le attività. Ognuna collega una discussione all'elemento, alla decisione o alla pagina di cui parla, e tutte arrivano nella inbox che abbiamo aggiunto il 10 ottobre.

La stessa domanda, posta nel modello

Ecco di nuovo quella domanda sul ledger, passata attraverso ciò che abbiamo rilasciato. I nomi e il progetto sono esempi. Il comportamento è quello del prodotto.

Marie la fissa dove la vede. Sta rivedendo il progetto Checkout a livello di container. Preme C, il cursore diventa un mirino, e clicca sulla freccia da Billing a Ledger DB. A metà della relazione si apre un riquadro di commento, e scrive:

Billing writes to Ledger DB directly here. #ADR-12 says ledger writes
go through the Ledger API. @Sam, is this still intended?

Digitare # ha aperto un elenco degli elementi, delle decisioni e delle pagine del progetto, e ADR-12 è diventato un chip che apre la decisione. Digitare @ ha elencato le persone che possono aprire il progetto, e anche Sam, responsabile di Billing, è diventato un chip. Preme ⌘ Enter. La bolla riceve un numero, #7, e chiunque apra quella vista del diagramma la vede.

Sam viene avvisato. La sua campanella mostra che Marie lo ha menzionato, con il commento di lei come estratto. Non deve tenere d'occhio il diagramma, né il canale Slack giusto, per saperlo.

La risposta diventa un'attività. Sam risponde che è un residuo della migrazione del ledger e che lo sposterà dietro la Ledger API. Marie, che ha avviato la discussione, riceve la sua risposta nella inbox. Apre la discussione completa, clicca Attività sotto la risposta di Sam, gliela assegna, sceglie venerdì come scadenza e clicca Crea attività. Sotto la risposta compare una casella di spunta, e l'attività arriva nella scheda Da fare della inbox di Sam.

La decisione ricorda di essere stata messa in discussione. Apri l'ADR-12 e in fondo alla sua scheda espansa ora c'è il commento di Marie sotto Citato in, con il testo attorno alla citazione. Chi leggerà la decisione dopo scoprirà che il database che protegge riceveva ancora scritture, e potrà cliccare fino alla discussione.

La correzione si annuncia da sola. Sam sostituisce la freccia con una richiesta di modifica. La sua descrizione cita #ADR-12 e incolla il link alla discussione #7, che appare come scheda di anteprima sotto il testo. Tutti quelli che possono modificare il progetto vengono avvisati che è stata aperta una richiesta di modifica, come prima. Léa, del team dati della finanza, non può revisionarla, ma segue il progetto Checkout, quindi riceve anche lei una riga: una richiesta di modifica aperta in un progetto seguito notifica i follower che non possono revisionarla.

Il cerchio si chiude. Sam spunta l'attività. Marie, che l'ha creata, riceve "Sam ha completato un'attività che hai creato". Risolve la #7 e la bolla scompare dal diagramma. Quando Sam incolla il link della richiesta di modifica in #payments, il bot di Archyl lo espande con titolo, stato e progetto.

Ogni pezzo di quello scambio è collegato a qualcosa nel modello: la relazione, la decisione, il responsabile, la richiesta di modifica. Niente dipende dal fatto che qualcuno ricordi dove si trovava un thread.

Cosa fa ogni funzionalità

Commenti sul diagramma

Premi C, oppure clicca Commenta nella barra in fondo al diagramma, poi clicca dove deve stare il commento:

  • su uno spazio vuoto, la bolla resta in quel punto;
  • su un elemento, vi resta agganciata e lo segue quando si sposta, e la discussione compare anche nel pannello dei dettagli dell'elemento;
  • su una relazione, si posiziona a metà di essa.

Le bolle sono numerate per progetto e mantengono la stessa dimensione a qualsiasi zoom. Ognuna appartiene al livello e alla vista in cui è stata posizionata, quindi un commento sul system context non compare dentro un sistema. Le bolle risolte sono nascoste; spunta Mostra risolti in modalità commento per vederle in grigio. Per il resto, una discussione fissata è una discussione normale: compare tra le discussioni del progetto, e le sue risposte notificano le persone che vi partecipano. Docs: Commenti sul diagramma.

@menzioni

Digita @ in un commento o in una risposta, nel contesto, nella decisione o nelle conseguenze di un ADR, in una pagina di documentazione, oppure nella descrizione, in un commento o in una revisione di una richiesta di modifica. L'elenco mostra le persone che possono aprire il progetto e i team che ne contengono almeno una. Menzionare un team raggiunge i suoi membri che possono aprire il progetto.

Le persone vengono avvisate una volta sola: modificare di nuovo il testo non notifica nessuno che fosse già stato menzionato. Le menzioni in un titolo non vengono rilevate, quindi scrivile nel corpo. Quando abbiamo rilasciato la inbox, le menzioni erano la prima voce della sua lista "cosa non fa ancora". Ora ci sono. Docs: Menzioni, citazioni e link.

Citazioni con # e "Citato in"

Digita # negli stessi punti per citare un sistema, un container, un component o un elemento di codice (ciascuno mostrato con il suo genitore), una decisione (elencata come ADR-3 con il suo titolo) o una pagina di documentazione. Cliccando il chip si apre ciò che cita. Un elemento si apre nel diagramma al suo livello, già selezionato.

L'altra metà è il backlink. Ogni elemento, decisione e pagina elenca dove viene citato, dal più recente, con l'estratto attorno a ogni citazione: nella sezione Citato in del pannello dei dettagli di un elemento, in fondo alla scheda espansa di una decisione, in fondo a una pagina. È la parte che un thread di Slack non può darti. La conversazione punta all'ADR, e l'ADR punta indietro.

Anteprime dei link, in Archyl e in Slack

Copia link si trova nel pannello dei dettagli di un elemento, su ogni scheda di decisione e in cima a ogni pagina di documentazione. Un link a un elemento apre l'elemento al suo livello, selezionato. Le richieste di modifica e le discussioni si condividono dalla barra degli indirizzi.

Incolla un link di Archyl in un commento, nella descrizione di una richiesta di modifica o in una revisione e comparirà come scheda sotto il testo: titolo, tipo e stato, progetto e un estratto. Vengono mostrate in anteprima fino a tre link per messaggio, e solo per le persone che possono aprire il progetto. Tutti gli altri vedono un link semplice.

In Slack, il bot ora espande i link a un progetto, un elemento, una decisione, una pagina di documentazione, una richiesta di modifica o una discussione nella stessa anteprima. Segue le regole che il bot aveva già. L'anteprima viene costruita con i permessi dell'admin che ha collegato il workspace, solo per i progetti dell'organizzazione a cui il workspace è collegato, e in un canale con ambito limitato un link a un progetto fuori ambito resta semplice. Anche un link a qualcosa che non esiste, o che il bot non può vedere, resta semplice, così un'anteprima non conferma mai che una pagina esiste. Docs: Anteprime dei link in Slack.

Seguire

Segui un elemento, una decisione o un intero progetto con la campanella nel pannello dei dettagli dell'elemento, sulla scheda della decisione o nella barra degli strumenti del diagramma. Una campanella piena significa che stai seguendo. I responsabili di un elemento lo seguono senza fare nulla, e così i membri di un team che ne è responsabile. Clicca la campanella per smettere di seguirlo e Archyl se lo ricorda, anche se resti responsabile dell'elemento.

I follower vengono avvisati quando ciò che seguono viene modificato o eliminato (la notifica elenca i campi cambiati), quando un elemento seguito riceve un commento e quando una richiesta di modifica tocca un elemento seguito. I follower di un progetto vengono avvisati anche quando si aggiunge un elemento, una decisione o una pagina. Seguire non concede accesso: se perdi l'accesso al progetto, le notifiche si fermano. Docs: Seguire.

Attività

Sotto qualsiasi commento o risposta in un progetto, clicca Attività, scegli un assegnatario tra le persone che possono aprire il progetto (tu, per impostazione predefinita), facoltativamente una scadenza, e clicca Crea attività. Un commento porta al massimo un'attività. L'attività compare sotto il suo commento con una casella di spunta, l'assegnatario e la scadenza, che diventa rossa una volta superata. Rimuovere l'attività non elimina il commento.

Le tue attività aperte sono nella scheda Da fare della inbox, prima quelle in scadenza più vicina, con un contatore sulla scheda. Il pannello dei dettagli di ogni elemento ha una sezione Da fare che elenca le attività di tutte le sue discussioni. L'assegnatario viene avvisato quando un'attività viene creata per lui o riassegnata a lui, e chi l'ha creata viene avvisato quando qualcun altro la completa. Docs: Attività.

Anche gli agenti possono taggare

Gli agenti di coding collegati tramite il server MCP scrivono nello stesso modello: aprono richieste di modifica, registrano decisioni, lasciano commenti. Finora, un agente che scriveva "@Sam, puoi confermare?" produceva testo semplice che non avvisava nessuno.

Ora il server legge ciò che scrive un agente come fanno i selettori nell'app. In un commento, un ADR, una pagina di documentazione o una richiesta di modifica:

  • @Name menziona una persona o un team, che viene avvisato nella sua inbox come per qualsiasi altra menzione. L'agente può chiamare list_mentionables per ottenere i nomi esatti.
  • #Label cita un elemento C4, una decisione (#ADR-12) o una pagina, che poi elenca il testo dell'agente sotto Citato in.

Un commento pubblicato da un agente raggiunge anche le persone che partecipano già alla discussione e i follower dell'elemento, come uno pubblicato da una persona. Ogni scrittura comunica all'agente cosa è stato collegato, così può verificare che @Sam abbia davvero raggiunto Sam.

Gli agenti possono anche rileggere i collegamenti. get_backlinks restituisce dove un elemento, una decisione o una pagina viene citato. Prima di toccare Ledger DB, un agente può trovare il commento #7 di Marie e la richiesta di modifica che citava l'ADR-12, invece di riscoprire la domanda.

Seguire senza annegare

Il seguire va contro la regola che abbiamo fissato per la inbox: contiene solo ciò che aspetta te o ciò che risponde a qualcosa che hai fatto. Un elemento seguito che cambia non aspetta te. L'abbiamo fatto entrare perché l'hai chiesto tu, cliccando la campanella o essendo responsabile dell'elemento, e abbiamo messo dei limiti a quanto rumore può fare:

  • Spostare un elemento o cambiarne lo stile non notifica nessuno.
  • Più modifiche alla stessa cosa nell'arco di un'ora producono una sola notifica, finché non l'hai letta.
  • Se segui un progetto ma non l'elemento, ricevi al massimo una notifica di ogni tipo all'ora per quel progetto. Approvare una AI discovery che crea centinaia di elementi è una riga, non centinaia.
  • Non vieni avvisato due volte. Un commento che ti menziona, o una risposta in una discussione di cui fai parte, ti raggiunge solo tramite quella notifica.
  • Non vieni mai avvisato delle tue azioni.

Se vuoi ogni modifica in tutta l'organizzazione, le notifiche via email e la pagina Cronologia restano il posto giusto.

Cosa non fa ancora

  • Solo inbox. Menzioni, follow e attività non inviano email.
  • Nessun promemoria sulle scadenze. Un'attività scaduta diventa rossa, e niente ti avvisa.
  • Nessun elenco di ciò che segui. Lo gestisci da ogni elemento, decisione o progetto. Una pagina di documentazione non si può seguire da sola; segui invece il suo progetto.
  • Le bolle restano dove le metti. Una volta posizionata, una bolla non si può spostare. La bolla di una relazione si trova nel punto medio tra i suoi due elementi, non sulla curva della linea. Le bolle sono nascoste mentre Viaggio nel Tempo è aperto.
  • Nessuna anteprima in Microsoft Teams. Solo Slack, per ora. I workspace Slack collegati prima del 18 ottobre devono essere ricollegati da Organizzazione → Bot per concedere i due nuovi permessi, links:read e links:write.
  • Gli agenti non vedono attività, follow né commenti fissati. Tramite il server MCP possono menzionare e citare, ma non ancora leggere o completare attività, seguire un elemento o fissare un commento sul diagramma.
  • Nessuna attività fuori da un progetto. Le discussioni dell'organizzazione non possono averne.

Provalo

Apri un diagramma, premi C e clicca sulla relazione su cui volevi fare una domanda da tempo. Menziona chi è responsabile dell'altra estremità e cita la decisione che dovrebbe rispettare. La documentazione copre ogni parte nel dettaglio:

Letture correlate: una inbox per ciò che aspetta te, per le regole che segue ogni notifica qui sopra, e limitare il bot per canale, per ciò che un canale Slack può mostrare in anteprima.