Die Architektur dort diskutieren, wo sie lebt

Jemand bemerkt, dass Billing direkt in die Ledger-Datenbank schreibt, obwohl ADR-12 sagt, dass das nur die Ledger API darf. Die Frage landet in einem Slack-Thread. Zwei Antworten, ein „guter Punkt, ich schau's mir an", und bis zum Mittag ist der Thread aus dem Blickfeld gescrollt. Einen Monat später steht der Pfeil immer noch im Diagramm, ADR-12 liest sich immer noch, als hätte ihn nie jemand infrage gestellt, und die Person, die „ich schau's mir an" gesagt hat, ist in ein anderes Team gewechselt. Die Frage wurde gestellt und beantwortet, an einem Ort, den die Architektur nicht sieht.

Diese Lücke haben wir diese Woche angegangen. Am 18. Oktober haben wir sechs Features ausgeliefert, die das Gespräch über die Architektur ins Modell selbst holen: an das Diagramm gepinnte Kommentare, @-Erwähnungen, #-Zitate mit einer „Zitiert in"-Liste, Link-Vorschauen in der App und in Slack, Folgen und Aufgaben. Jedes davon hängt eine Diskussion an das Element, die Entscheidung oder die Seite, um die es geht, und alle melden sich im Posteingang, den wir am 10. Oktober eingeführt haben.

Dieselbe Frage, im Modell gestellt

Hier noch einmal die Ledger-Frage, diesmal mit dem, was ausgeliefert wurde. Die Namen und das Projekt sind Beispiele. Das Verhalten ist das des Produkts.

Marie pinnt sie dort, wo sie sie sieht. Sie prüft das Checkout-Projekt auf Container-Ebene. Sie drückt C, der Cursor wird zum Fadenkreuz, und sie klickt auf den Pfeil von Billing zu Ledger DB. Auf halber Länge der Beziehung öffnet sich ein Kommentarfeld, und sie schreibt:

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

Das Tippen von # hat eine Liste der Elemente, Entscheidungen und Seiten des Projekts geöffnet, und ADR-12 wurde zu einem Chip, der die Entscheidung öffnet. Das Tippen von @ hat die Personen aufgelistet, die das Projekt öffnen können, und Sam, dem Billing gehört, wurde ebenfalls zu einem Chip. Sie drückt ⌘ Enter. Die Blase bekommt eine Nummer, #7, und alle, die diese Ansicht des Diagramms öffnen, sehen sie.

Sam erfährt davon. Seine Glocke zeigt, dass Marie ihn erwähnt hat, mit ihrem Kommentar als Auszug. Er muss weder das Diagramm beobachten noch im richtigen Slack-Channel sein, um es mitzubekommen.

Die Antwort wird zur Aufgabe. Sam antwortet, dass es ein Überbleibsel aus der Ledger-Migration ist und er es hinter die Ledger API verlegen wird. Marie, die die Diskussion begonnen hat, bekommt seine Antwort in ihren Posteingang. Sie öffnet die vollständige Diskussion, klickt unter Sams Antwort auf Aufgabe, weist sie ihm zu, wählt Freitag als Fälligkeitsdatum und klickt auf Aufgabe erstellen. Unter der Antwort erscheint eine Checkbox, und die Aufgabe landet im Tab Zu erledigen von Sams Posteingang.

Die Entscheidung erinnert sich, dass sie infrage gestellt wurde. Öffne ADR-12, und unten auf der aufgeklappten Karte steht jetzt Maries Kommentar unter Zitiert in, mit dem Text rund um das Zitat. Wer die Entscheidung als Nächstes liest, erfährt, dass in die Datenbank, die sie schützt, immer noch geschrieben wurde, und kann zur Diskussion durchklicken.

Der Fix kündigt sich selbst an. Sam ersetzt den Pfeil über einen Change Request. Dessen Beschreibung zitiert #ADR-12 und enthält den Link zu Diskussion #7, der als Vorschaukarte unter dem Text erscheint. Alle, die das Projekt bearbeiten können, erfahren wie bisher, dass ein Change Request geöffnet wurde. Léa aus dem Finance-Data-Team kann ihn nicht reviewen, aber sie folgt dem Checkout-Projekt, also bekommt auch sie eine Zeile: Ein Change Request, der in einem gefolgten Projekt geöffnet wird, benachrichtigt die Follower, die ihn nicht reviewen können.

Der Kreis schließt sich. Sam hakt die Aufgabe ab. Marie, die sie erstellt hat, bekommt „Sam hat eine von Ihnen erstellte Aufgabe erledigt". Sie löst #7, und die Blase verschwindet aus dem Diagramm. Als Sam den Link zum Change Request in #payments postet, entfaltet der Archyl-Bot ihn mit Titel, Status und Projekt.

Jedes Stück dieses Austauschs hängt an etwas im Modell: an der Beziehung, der Entscheidung, dem Owner, dem Change Request. Nichts hängt davon ab, dass sich jemand erinnert, wo ein Thread war.

Was jedes Feature tut

Kommentare im Diagramm

Drücke C oder klicke in der Leiste unten im Diagramm auf Kommentieren, und klicke dann dorthin, wo der Kommentar hingehört:

  • auf eine leere Fläche: Die Blase bleibt an dieser Stelle;
  • auf ein Element: Sie wird angeheftet und folgt dem Element, wenn es verschoben wird, und die Diskussion erscheint auch im Detail-Panel des Elements;
  • auf eine Beziehung: Sie sitzt auf halber Länge der Beziehung.

Blasen werden pro Projekt nummeriert und behalten bei jedem Zoom dieselbe Größe. Jede gehört zu der Ebene und Ansicht, in der sie platziert wurde, ein Kommentar auf dem System Context taucht also nicht innerhalb eines Systems auf. Gelöste Blasen sind ausgeblendet; aktiviere im Kommentarmodus Gelöste anzeigen, um sie ausgegraut zu sehen. Ansonsten ist eine gepinnte Diskussion eine ganz normale Diskussion: Sie wird bei den Diskussionen des Projekts aufgeführt, und ihre Antworten benachrichtigen die Beteiligten. Doku: Kommentare im Diagramm.

@-Erwähnungen

Tippe @ in einem Kommentar oder einer Antwort, im Kontext, in der Entscheidung oder in den Konsequenzen eines ADR, auf einer Dokumentationsseite oder in der Beschreibung, einem Kommentar oder einem Review eines Change Requests. Die Liste zeigt die Personen, die das Projekt öffnen können, und die Teams, die mindestens eine davon enthalten. Wer ein Team erwähnt, erreicht dessen Mitglieder, die das Projekt öffnen können.

Personen werden einmal benachrichtigt: Wird der Text erneut bearbeitet, bekommt niemand eine Nachricht, der schon erwähnt wurde. Erwähnungen in einem Titel werden nicht erkannt, schreib sie also in den Text. Als wir den Posteingang ausgeliefert haben, standen Erwähnungen ganz oben auf seiner „kann es noch nicht"-Liste. Jetzt sind sie da. Doku: Erwähnungen, Zitate und Links.

#-Zitate und „Zitiert in"

Tippe # an denselben Stellen, um ein System, einen Container, eine Component oder ein Code-Element (jeweils mit seinem Parent angezeigt), eine Entscheidung (aufgeführt als ADR-3 mit Titel) oder eine Dokumentationsseite zu zitieren. Ein Klick auf den Chip öffnet, was er zitiert. Ein Element öffnet sich im Diagramm auf seiner eigenen Ebene, bereits ausgewählt.

Die andere Hälfte ist der Backlink. Jedes Element, jede Entscheidung und jede Seite listet auf, wo sie zitiert wird, die neuesten zuerst, mit dem Auszug rund um jedes Zitat: im Abschnitt Zitiert in im Detail-Panel eines Elements, unten auf der aufgeklappten Karte einer Entscheidung, unten auf einer Seite. Das ist der Teil, den dir ein Slack-Thread nicht geben kann. Das Gespräch zeigt auf den ADR, und der ADR zeigt zurück.

Link-Vorschauen, in Archyl und in Slack

Link kopieren findest du im Detail-Panel eines Elements, auf jeder Entscheidungskarte und oben auf jeder Dokumentationsseite. Ein Element-Link öffnet das Element auf seiner Ebene, ausgewählt. Change Requests und Diskussionen teilst du über die Adressleiste.

Füge einen Archyl-Link in einen Kommentar, eine Change-Request-Beschreibung oder ein Review ein, und er erscheint als Karte unter dem Text: Titel, Typ und Status, Projekt und ein Auszug. Bis zu drei Links pro Nachricht bekommen eine Vorschau, und nur für Personen, die das Projekt öffnen können. Alle anderen sehen einen einfachen Link.

In Slack entfaltet der Bot jetzt Links zu einem Projekt, einem Element, einer Entscheidung, einer Dokumentationsseite, einem Change Request oder einer Diskussion zur selben Vorschau. Dabei gelten die Regeln, die der Bot schon hatte. Die Vorschau wird mit den Berechtigungen des Admins erstellt, der den Workspace verbunden hat, nur für Projekte der Organisation, mit der der Workspace verbunden ist, und in einem eingeschränkten Channel bleibt ein Link zu einem Projekt außerhalb des Bereichs einfach. Ein Link zu etwas, das nicht existiert oder das der Bot nicht sehen kann, bleibt ebenfalls einfach, sodass eine Vorschau nie bestätigt, dass eine Seite existiert. Doku: Link-Vorschauen in Slack.

Folgen

Folge einem Element, einer Entscheidung oder einem ganzen Projekt mit der Glocke im Detail-Panel des Elements, auf der Entscheidungskarte oder in der Diagramm-Toolbar. Eine ausgefüllte Glocke bedeutet, dass du folgst. Die Owner eines Elements folgen ihm, ohne etwas zu tun, ebenso die Mitglieder eines Teams, dem es gehört. Klick auf die Glocke, um dich abzumelden, und Archyl merkt es sich, auch wenn dir das Element weiterhin gehört.

Follower erfahren, wenn das, dem sie folgen, geändert oder gelöscht wird (die Benachrichtigung listet die geänderten Felder auf), wenn ein gefolgtes Element einen Kommentar bekommt und wenn ein Change Request ein gefolgtes Element betrifft. Projekt-Follower erfahren außerdem, wenn ein Element, eine Entscheidung oder eine Seite hinzugefügt wird. Folgen gewährt keinen Zugriff: Verlierst du den Zugriff auf das Projekt, hören die Benachrichtigungen auf. Doku: Folgen.

Aufgaben

Klicke unter einem beliebigen Kommentar oder einer Antwort in einem Projekt auf Aufgabe, wähle eine zuständige Person unter denen, die das Projekt öffnen können (standardmäßig dich selbst), optional ein Fälligkeitsdatum, und klicke auf Aufgabe erstellen. Ein Kommentar trägt höchstens eine Aufgabe. Die Aufgabe erscheint unter ihrem Kommentar mit einer Checkbox, der zuständigen Person und dem Fälligkeitsdatum, das rot wird, sobald es verstrichen ist. Wird die Aufgabe entfernt, bleibt der Kommentar erhalten.

Deine offenen Aufgaben findest du im Tab Zu erledigen des Posteingangs, die am frühesten fälligen zuerst, mit einem Zähler auf dem Tab. Das Detail-Panel jedes Elements hat einen Abschnitt Zu erledigen, der die Aufgaben aus all seinen Diskussionen auflistet. Die zuständige Person erfährt, wenn eine Aufgabe für sie erstellt oder ihr neu zugewiesen wird, und die erstellende Person erfährt, wenn jemand anderes sie erledigt. Doku: Aufgaben.

Auch Agents können taggen

Coding-Agents, die über den MCP-Server verbunden sind, schreiben in dasselbe Modell: Sie öffnen Change Requests, halten Entscheidungen fest, hinterlassen Kommentare. Bisher ergab ein Agent, der „@Sam, kannst du das bestätigen?" schrieb, einfachen Text, der niemanden benachrichtigte.

Jetzt liest der Server, was ein Agent schreibt, so wie die Auswahllisten in der App. In einem Kommentar, einem ADR, einer Dokumentationsseite oder einem Change Request:

  • @Name erwähnt eine Person oder ein Team, die wie bei jeder anderen Erwähnung in ihrem Posteingang benachrichtigt werden. Der Agent kann list_mentionables aufrufen, um die genauen Namen zu bekommen.
  • #Label zitiert ein C4-Element, eine Entscheidung (#ADR-12) oder eine Seite, die den Text des Agents dann unter Zitiert in auflistet.

Ein Kommentar, den ein Agent postet, erreicht auch die Personen, die schon an der Diskussion beteiligt sind, und die Follower des Elements, genau wie einer, den eine Person postet. Jeder Schreibvorgang teilt dem Agent mit, was verknüpft wurde, sodass er prüfen kann, ob @Sam wirklich bei Sam angekommen ist.

Agents können die Verweise auch zurücklesen. get_backlinks liefert, wo ein Element, eine Entscheidung oder eine Seite zitiert wird. Bevor ein Agent Ledger DB anfasst, kann er Maries Kommentar #7 und den Change Request finden, der ADR-12 zitiert hat, statt die Frage neu zu entdecken.

Folgen, ohne unterzugehen

Folgen steht im Widerspruch zu der Regel, die wir für den Posteingang aufgestellt haben: Er enthält nur, was auf dich wartet oder auf etwas antwortet, das du getan hast. Ein gefolgtes Element, das sich ändert, wartet nicht auf dich. Wir haben es trotzdem hereingelassen, weil du darum gebeten hast, indem du auf die Glocke geklickt hast oder weil dir das Element gehört, und wir haben begrenzt, wie laut es werden kann:

  • Ein Element zu verschieben oder seinen Stil zu ändern, benachrichtigt niemanden.
  • Mehrere Änderungen am selben Gegenstand innerhalb einer Stunde ergeben eine Benachrichtigung, solange du sie nicht gelesen hast.
  • Wenn du einem Projekt folgst, aber nicht dem Element, bekommst du für dieses Projekt höchstens eine Benachrichtigung jeder Art pro Stunde. Eine AI Discovery zu genehmigen, die Hunderte von Elementen anlegt, ergibt eine Zeile, nicht Hunderte.
  • Du wirst nicht zweimal benachrichtigt. Ein Kommentar, der dich erwähnt, oder eine Antwort in einer Diskussion, an der du beteiligt bist, erreicht dich nur über diese Benachrichtigung.
  • Über deine eigenen Aktionen wirst du nie benachrichtigt.

Wenn du jede Änderung in der ganzen Organisation willst, sind E-Mail-Benachrichtigungen und die Seite Verlauf weiterhin der richtige Ort dafür.

Was es noch nicht kann

  • Nur Posteingang. Erwähnungen, Folgen und Aufgaben verschicken keine E-Mails.
  • Keine Erinnerung an Fälligkeitsdaten. Eine überfällige Aufgabe wird rot, und nichts meldet sich bei dir.
  • Keine Liste dessen, dem du folgst. Du verwaltest es an jedem Element, jeder Entscheidung oder jedem Projekt. Einer Dokumentationsseite kann man nicht einzeln folgen; folge stattdessen ihrem Projekt.
  • Blasen bleiben, wo du sie hinsetzt. Einmal platziert, lässt sich eine Blase nicht verschieben. Die Blase einer Beziehung sitzt in der Mitte zwischen ihren beiden Elementen, nicht auf der Kurve der Linie. Blasen sind ausgeblendet, solange Zeitreise geöffnet ist.
  • Keine Vorschauen in Microsoft Teams. Vorerst nur Slack. Slack-Workspaces, die vor dem 18. Oktober verbunden wurden, müssen unter Organisation → Bot neu verbunden werden, um die beiden neuen Berechtigungen links:read und links:write zu erteilen.
  • Agents sehen keine Aufgaben, kein Folgen und keine Pins. Über den MCP-Server können sie erwähnen und zitieren, aber noch keine Aufgaben lesen oder erledigen, keinem Element folgen und keinen Kommentar im Diagramm pinnen.
  • Keine Aufgaben außerhalb eines Projekts. Diskussionen auf Organisationsebene können keine tragen.

Ausprobieren

Öffne ein Diagramm, drücke C und klicke auf die Beziehung, nach der du schon länger fragen wolltest. Erwähne, wem das andere Ende gehört, und zitiere die Entscheidung, der sie folgen soll. Die Doku behandelt jedes Teil im Detail:

Weiterlesen: ein Posteingang für das, was auf dich wartet, für die Regeln, denen jede der obigen Benachrichtigungen folgt, und den Bot pro Channel einschränken, für das, was ein Slack-Channel als Vorschau anzeigen darf.