Architektur-Reviews als ADR festhalten: das Warum neben dem Code

2026-10-18

Jede Codebasis hat eine Stelle, die der nächsten Person, die sie liest, falsch vorkommt. Ein Relay-Prozess, an dessen Einführung sich niemand erinnert, eine Tabelle, die jede Woche geleert wird, eine Queue, wo ein direkter Aufruf genügen würde. Die Gründe wurden vor Monaten in einem Architektur-Review laut ausgesprochen, und die Leute, die sie genannt haben, sind inzwischen in anderen Teams. Die neue Engineerin hat zwei Möglichkeiten: eine Woche herumfragen oder es „reparieren“.

Es gibt einen kürzeren Weg. Nehmen Sie das Architektur-Review auf, drücken Sie einen Hotkey, wenn eine Entscheidung, ein Trade-off oder eine verworfene Option ausgesprochen wird, und teilen Sie die Aufnahme in einen Kanal namens Architecture. Die Markierungen bleiben an den Sätzen, mit Zeit und dem Namen der sprechenden Person. Direkt nach dem Review liest ein KI-Assistent in Claude Code, Cursor oder Claude diese Markierungen über MCP und entwirft das Architecture Decision Record (ADR) für das Repository. Monate später ist die Debatte für alle, die nach dem Warum fragen, noch da.

Diese Anleitung folgt der macOS-App von Speak-Y, geprüft am 18. Oktober 2026, und richtet sich an einen Tech Lead, dessen Team Meetings bereits in einem Workspace teilt. Falls es noch keinen gibt, richten Sie zuerst einen ein.

Warum hat „Warum ist das so gebaut?“ keine Antwort?

Die Lösung wurde 2011 beschrieben. Michael Nygards Beitrag Documenting Architecture Decisions (geprüft am 18. Oktober 2026) schlägt für jede wesentliche Entscheidung ein kurzes Record vor — Titel, Kontext, Entscheidung, Status, Konsequenzen —, das im Repository neben dem Code liegt. Seine Begründung ist das Problem von oben: Wer neu in einem Projekt ist und nicht weiß, warum eine Entscheidung getroffen wurde, kann sie nur blind akzeptieren oder blind rückgängig machen. Die ADR-Community-Website nennt die Sammlung dieser Records das Entscheidungslog eines Projekts.

Auch Teams, die ADRs einführen, verlieren das Warum, und zwar an drei vorhersehbaren Stellen:

• Der Kontext wird rekonstruiert. Das Record wird nach dem Review geschrieben, aus dem Gedächtnis, von wem auch immer gerade Zeit hat. Die Randbedingungen, die die Entscheidung bestimmt haben, verblassen zuerst.
• Verworfene Optionen schrumpfen auf eine Zeile. „Wir haben CDC erwogen“ sagt nichts darüber, warum es verloren hat — und genau das braucht die nächste Person, bevor sie es erneut vorschlägt.
• Das Record wird nie geschrieben. Ein Review, das um 16 Uhr endet, konkurriert mit dem Code, der morgen fällig ist.

Eine Aufnahme bewahrt alle drei. Die Markierungen machen sie auffindbar, und ein Assistent macht daraus einen Entwurf, bevor die Details verblassen.

Einmal einrichten: drei Markierungen und ein Kanal Architecture

Die Markierungen. Speak-Y bringt einen Notiztyp mit, Moment markieren auf ⌥1. Fügen Sie unter Einstellungen → Notizen drei eigene hinzu: Klicken Sie auf Notiztyp hinzufügen, tippen Sie Decision in Name des Typs, klicken Sie auf Speichern, dann auf Hotkey festlegen und drücken Sie ⌥2. Wiederholen Sie das für Trade-off auf ⌥3 und Rejected auf ⌥4. Jede Markierung entspricht einem Abschnitt des Records:

• Decision — was das Team zu bauen beschlossen hat. Daraus wird die Entscheidung im ADR.
• Trade-off — der Preis, den das Team dafür in Kauf genommen hat. Daraus werden die Konsequenzen.
• Rejected — eine Option, die verloren hat, mit dem Grund. Daraus werden die erwogenen Alternativen.

Der Kontext ist die Diskussion rund um die Markierungen; der Assistent liest ihn aus dem Transkript. Nygards Format hat keinen eigenen Abschnitt für verworfene Optionen; die MADR-Vorlage hat einen: Considered Options.

Der Kanal. Ein öffentlicher Kanal für Architektur-Reviews namens Architecture, dem jede Engineerin und jeder Engineer beitreten kann. Wählen Sie im Menü ⋯ des Workspace New channel. Reviews sicherheitskritischer Designs — ein Threat Model, ein Authentifizierungsablauf — gehören stattdessen in einen privaten Kanal; die Abwägung steht in wer was in Meeting-Kanälen sieht.

Im Review: erst die Komponente nennen, dann die Taste drücken

Starten Sie eine Meeting-Aufnahme in Speak-Y, wenn das Review beginnt. Kein Bot tritt dem Call bei: Speak-Y nimmt das Mikrofon und den Ton des Calls auf Ihrem Mac auf und funktioniert deshalb gleich in Zoom, Google Meet, Teams oder im Besprechungsraum. Sagen Sie allen, dass das Review aufgenommen wird.

Das Transkript kennt nur, was gesagt wurde, deshalb zahlen sich drei Gewohnheiten aus:

1. Nennen Sie die Komponente, bevor Sie über sie sprechen. „Der Payment-Event-Publisher in payments-service“ macht jede folgende Markierung unter dem Namen auffindbar, nach dem eine Engineerin später suchen wird.
2. Lassen Sie den Grund aussprechen, dann drücken. Eine Markierung umfasst die letzten 15 Sekunden des Transkripts vor dem Tastendruck, also landet der Satz mit dem weil in der Markierung.
3. Markieren Sie auch die Verlierer. Eine Markierung Rejected auf „Dual Writes verlieren Events, wenn der Service zwischen den beiden abstürzt“ ist die Zeile, die dem nächsten Review eine halbe Stunde spart.

Meist nimmt der Tech Lead, der das Review leitet, auf und drückt die Tasten. Die Hotkeys funktionieren aus jeder App, das Diagramm oder der Code bleibt im Vordergrund.

Nach dem Review: Namen, Tags, To channel

Zwei Minuten im Fenster der Aufnahme, solange alles noch frisch ist:

1. Sprecher benennen. Klicken Sie auf Speaker 1, Speaker 2 und so weiter und tippen Sie die echten Namen ein. Eine Markierung ist nur so nützlich wie der Name daneben.
2. Taggen. Fügen Sie den Namen des Service und die Nummer des Records hinzu, das Sie gleich schreiben, etwa payments-service und adr-0012. Über diese Tags finden der Assistent und Ihr Team das Review.
3. Markierungen prüfen. Die Chips über dem Transkript zählen sie nach Typ: Alle Notizen · 8, Decision · 3, Trade-off · 3, Rejected · 2.
4. Teilen. Drücken Sie unter dem Transkript To channel und wählen Sie Architecture. Das Transkript mit Namen und Zeitstempeln, die KI-Zusammenfassung und die Action Items gehen in den Kanal, Ende-zu-Ende-verschlüsselt; das Audio bleibt auf Ihrem Mac.
5. Markierungen zeigen. Markierungen sind standardmäßig privat. Klicken Sie über dem Transkript auf den Chip Privat und wählen Sie In # Architecture zeigen – Kanalmitglieder sehen sie, damit die Markierungen mit der Aufnahme mitgehen.

Den ADR aus den Markierungen entwerfen

Verbinden Sie Ihren Assistenten einmal mit dem Speak-Y MCP-Server: Öffnen Sie KI-Assistenten verbinden im Kontomenü unten in der Seitenleiste oder Einstellungen → Integrationen und klicken Sie neben Claude, ChatGPT oder Cursor auf Verbinden. Für Claude richtet ein Klick sowohl Claude Desktop als auch Claude Code ein. Der Server ist in jedem Tarif kostenlos.

Fragen Sie dann im Repository:

Entwirf ADR 0012 aus dem payments-service-Review mit dem Tag adr-0012: Kontext, Entscheidung, Konsequenzen und verworfene Optionen. Gib zu jedem Punkt an, wer ihn wann gesagt hat.

Der Assistent findet das Review über seinen Tag und liest es. Neben dem Transkript übergibt Speak-Y ihm die Markierungen als Liste — jede mit ihrem Offset in der Aufnahme, ihrem Typ, der sprechenden Person und den ersten Wörtern des Satzes —, sodass der Entwurf mit drei Entscheidungen, drei in Kauf genommenen Kosten und zwei verworfenen Optionen zurückkommt, jeweils mit Name und Zeit. In Cursor fragt der Assistent vor jedem Tool-Aufruf nach, sofern Sie das nicht ändern.

Bearbeiten Sie den Entwurf, bevor Sie ihn committen. Drei Felder gehören Ihnen, nicht dem Assistenten:

• Status. Proposed oder accepted ist eine Entscheidung des Teams, nichts, was ein Transkript verraten kann.
• Verantwortliche Person. Wer im nächsten Quartal Fragen dazu beantwortet.
• Der Verweis zurück. Schreiben Sie hinein, wo die Debatte liegt — Kanal, Datum und Tag —, damit die nächste Leserin die Argumentation nachvollziehen kann. Die Aufnahme ist im Kanal Ende-zu-Ende-verschlüsselt, der Verweis funktioniert also für Teammitglieder im Workspace, nicht für die Öffentlichkeit.

Monate später: Die neue Engineerin fragt nach dem Warum

Der ADR im Repository beantwortet auf einer Seite das Was. Wenn das nicht genügt, ist die Debatte einen Schritt entfernt.

In der App. Teammitglieder, die Sie einladen, treten in jedem Tarif kostenlos bei. Wer neu in den Workspace kommt, sieht den öffentlichen Kanal Architecture mit seiner Historie. Öffnen Sie ihn, klicken Sie in der Kopfzeile des Kanals auf die Lupe und tippen Sie den Namen der Komponente ein, etwa outbox. Die Suche liest die Transkripte aller Reviews im Kanal und zeigt die passenden Zeilen mit ihren Zeiten.

Im Editor. In Cursor oder Claude Code, mit geöffnetem Code:

Warum schreibt payments-service Events in eine outbox-Tabelle, statt direkt in Kafka zu publizieren? Was wurde verworfen?

Der Assistent durchsucht die Aufnahmen, die die Person sehen darf, findet das Review und antwortet daraus: die Entscheidung, wer gegen Dual Writes argumentiert hat und warum, und was das Team im Gegenzug in Kauf genommen hat. Dasselbe Muster für Code-Fragen allgemein steht in Meeting-Kontext für Voice Coding in Cursor.

Was eine Review-Aufnahme nicht ersetzt

Die Aufnahme bewahrt die Argumentation. Vier Dinge liegen weiterhin woanders:

• Das Diagramm. Whiteboards, Folien und Sequenzdiagramme sind nicht in der Aufnahme. Verlinken Sie sie im ADR.
• Der endgültige Status. Eine Markierung Decision hält fest, dass der Raum zugestimmt hat; ob die Entscheidung später abgelöst wurde, steht in den Records des Repositorys.
• Entscheidungen im Chat. Eine Wahl, die in einem Pull-Request-Thread getroffen wurde, hat das Review nie erreicht. Schreiben Sie sie direkt in den ADR.
• Der Code selbst. Widersprechen sich Code und ADR, läuft der Code. Aktualisieren Sie das Record oder den Code — die Aufnahme sagt Ihnen nur, was beabsichtigt war.

Grenzen und Kosten

• Länge. Geprüft auf speak-y.com am 18. Oktober 2026: Free stoppt eine Meeting-Aufnahme nach 30 Minuten, Pro (10 $ im Monat) nach 60, Pro+ (15 $) und Max (30 $) nach vier Stunden. Eine lange Design-Session braucht Pro+ oder eine Pause nach der Stunde.
• Eine aufnehmende Person. Nehmen zwei Personen dasselbe Review auf, entstehen zwei halbe Listen von Markierungen.
• Kanäle auf dem Mac. Workspaces und Kanäle gibt es in der macOS-App. Einen Workspace zu erstellen erfordert Pro oder höher; Teammitglieder treten in jedem Tarif kostenlos bei.

Kurz gesagt

Drei Notiztypen — Decision, Trade-off, Rejected — auf ⌥2, ⌥3 und ⌥4. Im Review: die Komponente nennen, den Grund aussprechen lassen, die Taste drücken. Danach: Namen, Tags, To channel → Architecture, die Markierungen zeigen. Dann eine Frage an den Assistenten im Repository, und Sie bearbeiten den ADR-Entwurf, statt ihn aus dem Gedächtnis zu schreiben. Die Teams-Seite behandelt Workspaces und Kanäle, und ein Entscheidungslog, das sich selbst führt wendet dieselbe Idee auf Produktentscheidungen an.

FAQ

Wie halte ich fest, warum eine Architekturentscheidung getroffen wurde?

Nehmen Sie das Architektur-Review in Speak-Y auf und drücken Sie einen Hotkey, sobald eine Entscheidung, ein Trade-off oder eine verworfene Option laut ausgesprochen wird. Teilen Sie die Aufnahme in einen Team-Kanal wie Architecture. Der Kanal bewahrt die Debatte mit Namen und Zeitstempeln, und ein über MCP verbundener KI-Assistent macht aus den Markierungen einen Entwurf für ein Architecture Decision Record im Repository.

Können Claude Code oder Cursor einen ADR aus einer Meeting-Aufnahme schreiben?

Einen Entwurf, ja. Mit dem Speak-Y MCP-Server verbunden, findet der Assistent das Review über seinen Tag, liest das Transkript und die Liste der Markierungen mit Typ, Zeit und Sprecher und füllt Kontext, Entscheidung, Konsequenzen und verworfene Optionen aus. Status, verantwortliche Person und endgültige Formulierung bleiben bei der Engineerin oder dem Engineer, die die Datei committen.

Wie findet eine neue Engineerin heraus, warum ein Service so gebaut ist?

Auf zwei Wegen. Öffnen Sie den Kanal Architecture in der macOS-App von Speak-Y und durchsuchen Sie ihn nach dem Namen der Komponente, oder fragen Sie einen Assistenten im Editor, etwa Cursor oder Claude Code, warum der Service tut, was er tut. Der Assistent durchsucht die Aufnahmen, die die Person sehen darf, und antwortet damit, wer was wann gesagt hat.

Nimmt Speak-Y das Whiteboard oder die Diagramme aus dem Review auf?

Nein. Speak-Y nimmt Audio auf dem Mac auf, der die Aufnahme startet: das Mikrofon und den Ton der Call-App. Diagramme, Folien und Whiteboards sind nicht in der Aufnahme. Nennen Sie die Komponente laut, bevor Sie über sie sprechen, und verlinken Sie das Diagramm im ADR.

Was kostet dieses Setup?

Der MCP-Server ist in jedem Tarif kostenlos. Einen Team-Workspace zu erstellen erfordert Pro oder höher, Teammitglieder treten in jedem Tarif kostenlos bei. Geprüft auf speak-y.com am 18. Oktober 2026: Free stoppt eine Meeting-Aufnahme nach 30 Minuten, Pro (10 $ im Monat) nach 60, Pro+ (15 $) und Max (30 $) nach vier Stunden.