Architectuurreviews vastleggen als ADR: het waarom naast de code

2026-10-18

Elke codebase heeft een deel dat er verkeerd uitziet voor de volgende die het leest. Een relay-proces waarvan niemand zich herinnert dat het is toegevoegd, een tabel die elke week wordt leeggemaakt, een queue waar een directe aanroep zou volstaan. De redenen zijn maanden geleden hardop gegeven in een architectuurreview, en de mensen die ze gaven zitten inmiddels in andere teams. De nieuwe engineer heeft twee opties: een week rondvragen, of het "repareren".

Er is een kortere weg. Neem de architectuurreview op, druk op een sneltoets wanneer een besluit, een afweging of een afgewezen optie wordt uitgesproken, en deel de opname in een kanaal Architecture. De markeringen blijven op de zinnen staan, met het tijdstip en de naam van de spreker. Direct na de review leest een AI-assistent in Claude Code, Cursor of Claude die markeringen via MCP en stelt het Architecture Decision Record (ADR) voor de repository op. Maanden later staat de discussie er nog voor iedereen die naar het waarom vraagt.

Deze gids volgt de macOS-app van Speak-Y, gecontroleerd op 18 oktober 2026, en is bedoeld voor een tech lead wiens team vergaderingen al deelt in een werkruimte. Hebt u die nog niet, richt er dan eerst een in.

Waarom heeft "waarom is dit zo gebouwd?" geen antwoord?

De oplossing is in 2011 beschreven. Michael Nygards bericht Documenting Architecture Decisions (gecontroleerd op 18 oktober 2026) stelt voor elk belangrijk besluit een kort record voor — titel, context, besluit, status, gevolgen — dat in de repository naast de code staat. Zijn redenering is het probleem hierboven: wie nieuw is in een project en niet weet waarom een besluit is genomen, kan het alleen blind accepteren of blind terugdraaien. De ADR-communitysite noemt de verzameling van deze records het besluitenlog van een project.

Ook teams die ADR's invoeren verliezen het waarom, op drie voorspelbare plekken:

• De context wordt gereconstrueerd. Het record wordt na de review geschreven, uit het hoofd, door wie er tijd voor heeft. De randvoorwaarden die het besluit bepaalden vervagen als eerste.
• Afgewezen opties krimpen tot één regel. "We hebben CDC overwogen" zegt niets over waarom het verloor, en dat is precies wat de volgende nodig heeft voordat die het opnieuw voorstelt.
• Het record wordt nooit geschreven. Een review die om 16.00 uur eindigt, concurreert met de code die morgen af moet zijn.

Een opname bewaart alle drie. De markeringen maken ze vindbaar, en een assistent maakt er een concept van voordat de details vervagen.

Eén keer instellen: drie markeringen en een kanaal Architecture

De markeringen. Speak-Y wordt geleverd met één notitietype, Moment markeren op ⌥1. Voeg er drie van uzelf aan toe in Instellingen → Notities: klik op Notitietype toevoegen, typ Decision in Naam van type, klik op Opslaan, daarna op Sneltoets instellen en druk op ⌥2. Herhaal dit voor Trade-off op ⌥3 en Rejected op ⌥4. Elke markering hoort bij een sectie van het record:

• Decision — wat het team heeft afgesproken te bouwen. Dit wordt het besluit in de ADR.
• Trade-off — de prijs die het team erbij heeft geaccepteerd. Dit worden de gevolgen.
• Rejected — een optie die verloor, met de reden. Dit worden de overwogen alternatieven.

De context is de discussie rond de markeringen; de assistent leest die uit de transcriptie. Het format van Nygard heeft geen aparte sectie voor afgewezen opties; de MADR-template wel: Considered Options.

Het kanaal. Eén openbaar kanaal voor architectuurreviews, met de naam Architecture, waar elke engineer bij kan aansluiten. Kies in het menu ⋯ van de werkruimte New channel. Reviews van beveiligingsgevoelige ontwerpen — een threat model, een authenticatieflow — gaan in plaats daarvan naar een privékanaal; de afwegingen staan in wie ziet wat in vergaderkanalen.

Tijdens de review: noem de component, druk dan op de toets

Start een vergaderopname in Speak-Y wanneer de review begint. Er neemt geen bot deel aan het gesprek: Speak-Y neemt de microfoon en het geluid van het gesprek op op uw Mac, dus het werkt hetzelfde in Zoom, Google Meet, Teams of in een vergaderruimte. Vertel iedereen dat de review wordt opgenomen.

De transcriptie kent alleen wat er is gezegd, dus drie gewoonten lonen:

1. Noem de component voordat u hem bespreekt. "De publisher van betalingsevents in payments-service" maakt elke markering daarna vindbaar op de naam waarop een engineer later zal zoeken.
2. Laat de reden uitspreken, druk dan. Een markering beslaat de laatste 15 seconden van de transcriptie vóór de toets, dus de zin met omdat erin valt binnen de markering.
3. Markeer ook de verliezers. Een markering Rejected op "dual writes verliezen events als de service tussen de twee crasht" is de regel die de volgende review een half uur bespaart.

Meestal neemt de tech lead die de review leidt op en drukt die op de toetsen. De sneltoetsen werken vanuit elke app, met het diagram of de code nog op de voorgrond.

Na de review: namen, tags, To channel

Twee minuten in het venster van de opname, zolang alles nog vers is:

1. Geef de sprekers een naam. Klik op Speaker 1, Speaker 2 enzovoort en typ de echte namen. Een markering is maar zo bruikbaar als de naam ernaast.
2. Tag de opname. Voeg de naam van de service toe en het nummer van het record dat u gaat schrijven, zoals payments-service en adr-0012. Via deze tags vinden de assistent en uw teamgenoten de review.
3. Controleer de markeringen. De chips boven de transcriptie tellen ze per type: Alle notities · 8, Decision · 3, Trade-off · 3, Rejected · 2.
4. Deel het. Druk onder de transcriptie op To channel en kies Architecture. De transcriptie met namen en tijdstempels, de AI-samenvatting en de actiepunten gaan het kanaal in, end-to-end versleuteld; de audio blijft op uw Mac.
5. Toon de markeringen. Markeringen zijn standaard privé. Klik boven de transcriptie op de chip Privé en kies Tonen in # Architecture — kanaalleden zien ze, zodat de markeringen met de opname meegaan.

Stel de ADR op uit de markeringen

Verbind uw assistent één keer met de Speak-Y MCP-server: open AI-assistent verbinden in het accountmenu onder in de zijbalk, of Instellingen → Integraties, en klik op Verbinden naast Claude, ChatGPT of Cursor. Voor Claude stelt één klik zowel Claude Desktop als Claude Code in. De server is gratis in elk abonnement.

Vraag daarna in de repository:

Stel ADR 0012 op uit de review van payments-service met de tag adr-0012: context, besluit, gevolgen en afgewezen opties. Vermeld bij elk punt wie het zei en wanneer.

De assistent vindt de review via de tag en leest hem. Naast de transcriptie geeft Speak-Y hem de markeringen als lijst — elk met de positie in de opname, het type, de spreker en de eerste woorden van de zin — zodat het concept terugkomt met drie besluiten, drie geaccepteerde kosten en twee afgewezen opties, elk met een naam en een tijdstip. In Cursor vraagt de assistent toestemming voordat hij een tool uitvoert, tenzij u dat wijzigt.

Bewerk het concept voordat u het commit. Drie velden zijn van u, niet van de assistent:

• Status. Proposed of accepted is een besluit van het team, niet iets wat een transcriptie kan vertellen.
• Eigenaar. Wie volgend kwartaal vragen erover beantwoordt.
• De verwijzing terug. Schrijf op waar de discussie staat — het kanaal, de datum en de tag — zodat de volgende lezer de redenering kan terugzien. De opname is in het kanaal end-to-end versleuteld, dus de verwijzing werkt voor teamgenoten in de werkruimte, niet voor het publiek.

Maanden later: de nieuwe engineer vraagt waarom

De ADR in de repository beantwoordt het wat op één pagina. Als dat niet genoeg is, is de discussie één stap verwijderd.

In de app. Teamgenoten die u uitnodigt, sluiten gratis aan met elk abonnement. Een nieuwe engineer die de werkruimte binnenkomt, ziet het openbare kanaal Architecture met de hele geschiedenis. Open het, klik op het vergrootglas in de kop van het kanaal en typ de naam van de component, zoals outbox. De zoekfunctie leest de transcripties van elke review in het kanaal en toont de gevonden regels met hun tijdstippen.

In de editor. In Cursor of Claude Code, met de code open:

Waarom schrijft payments-service events naar een outbox-tabel in plaats van ze direct naar Kafka te publiceren? Wat is er afgewezen?

De assistent doorzoekt de opnamen die de engineer mag zien, vindt de review en antwoordt op basis daarvan: het besluit, wie tegen dual writes was en waarom, en wat het team ervoor in ruil accepteerde. Hetzelfde patroon voor codevragen in het algemeen staat in vergadercontext voor voice coding in Cursor.

Wat een reviewopname niet vervangt

De opname bewaart de redenering. Vier dingen staan nog steeds ergens anders:

• Het diagram. Whiteboards, slides en sequentiediagrammen zitten niet in de opname. Link ze vanuit de ADR.
• De definitieve status. Een markering Decision legt vast dat de kamer akkoord ging; of het besluit later is vervangen, staat in de records van de repository.
• Besluiten in de chat. Een keuze die in een pull-requestthread is gemaakt, heeft de review nooit bereikt. Schrijf die direct in de ADR.
• De code zelf. Als de code en de ADR elkaar tegenspreken, is de code wat er draait. Werk het record of de code bij — de opname vertelt u alleen wat de bedoeling was.

Grenzen en kosten

• Lengte. Gecontroleerd op speak-y.com op 18 oktober 2026: Free stopt een vergaderopname na 30 minuten, Pro ($10 per maand) na 60, Pro+ ($15) en Max ($30) na vier uur. Een lange ontwerpsessie heeft Pro+ nodig of een pauze na het uur.
• Eén opnemer. Twee mensen die dezelfde review opnemen, maken twee halve lijsten met markeringen.
• Kanalen op de Mac. Werkruimtes en kanalen zitten in de macOS-app. Voor het aanmaken van een werkruimte is Pro of hoger nodig; teamgenoten sluiten gratis aan met elk abonnement.

In het kort

Drie notitietypen — Decision, Trade-off, Rejected — op ⌥2, ⌥3 en ⌥4. Tijdens de review: noem de component, laat de reden uitspreken, druk op de toets. Daarna: namen, tags, To channel → Architecture, de markeringen tonen. Dan één vraag aan de assistent in de repository, en u bewerkt het ADR-concept in plaats van het uit het hoofd te schrijven. De Teams-pagina behandelt werkruimtes en kanalen, en een besluitenlog dat zichzelf bijhoudt past hetzelfde idee toe op productbesluiten.

FAQ

Hoe leg ik vast waarom een architectuurbesluit is genomen?

Neem de architectuurreview op in Speak-Y en druk op een sneltoets wanneer een besluit, een afweging of een afgewezen optie hardop wordt uitgesproken. Deel de opname in een teamkanaal zoals Architecture. Het kanaal bewaart de discussie met namen en tijdstempels, en een AI-assistent die via MCP is verbonden kan van de markeringen een concept-Architecture Decision Record voor de repository maken.

Kunnen Claude Code of Cursor een ADR schrijven uit een vergaderopname?

Ze kunnen een concept schrijven. Verbonden met de Speak-Y MCP-server vindt de assistent de review via de tag, leest de transcriptie en de lijst met markeringen met type, tijdstip en spreker, en vult context, besluit, gevolgen en afgewezen opties in. De status, de eigenaar en de definitieve formulering blijven bij de engineer die het bestand commit.

Hoe komt een nieuwe engineer erachter waarom een service op een bepaalde manier is gebouwd?

Op twee manieren. Open het kanaal Architecture in de macOS-app van Speak-Y en doorzoek het op de naam van de component, of vraag een assistent in de editor, zoals Cursor of Claude Code, waarom de service doet wat hij doet. De assistent doorzoekt de opnamen die de engineer mag zien en antwoordt met wie wat wanneer zei.

Neemt Speak-Y het whiteboard of de diagrammen uit de review op?

Nee. Speak-Y neemt audio op van de Mac die de opname start: de microfoon en het geluid van de belapp. Diagrammen, slides en whiteboards zitten niet in de opname. Noem de component hardop voordat u hem bespreekt, en link het diagram vanuit de ADR.

Wat kost deze opzet?

De MCP-server is gratis in elk abonnement. Voor het aanmaken van een teamwerkruimte is Pro of hoger nodig, en teamgenoten sluiten gratis aan met elk abonnement. Gecontroleerd op speak-y.com op 18 oktober 2026: Free stopt een vergaderopname na 30 minuten, Pro ($10 per maand) na 60, en Pro+ ($15) en Max ($30) na vier uur.