Architecture Decision Records (ADR): Der vollständige Leitfaden

Jedes Softwaresystem wird durch Hunderte von Entscheidungen geformt. PostgreSQL statt MongoDB. REST statt GraphQL. Monolith statt Microservices. Event-Driven statt Request-Response. Jede Wahl schränkt zukünftige Wahlmöglichkeiten ein, und zusammen definieren sie die Architektur.

Das Problem ist, dass Entscheidungen unsichtbar sind. Code zeigt, was gebaut wurde, nicht warum es so gebaut wurde. Sechs Monate nach der Wahl von PostgreSQL erinnert sich niemand mehr, ob das Team DynamoDB in Betracht gezogen hat, was die Performance-Anforderungen waren oder warum Eventual Consistency inakzeptabel war. Die Entscheidung ist in den Code eingebacken, aber die Begründung ist verloren.

Architecture Decision Records (ADRs) lösen dieses Problem, indem sie jede wichtige Entscheidung in einem kurzen, strukturierten Dokument festhalten. Sie gehören zu den wirkungsvollsten Dokumentationspraktiken im Software Engineering -- einfach einzuführen, günstig zu pflegen und unbezahlbar, wenn man sie braucht.

Dieser Leitfaden behandelt alles von den Grundlagen bis zu fortgeschrittenen Praktiken: was ADRs sind, wie man sie schreibt, Templates die Sie noch heute übernehmen können, häufige Fallstricke und wie Sie ADRs mit modernem Tooling in Ihren Workflow integrieren.

Was ist ein Architecture Decision Record?

Ein Architecture Decision Record ist ein kurzes Dokument, das eine einzelne architektonische Entscheidung festhält. Die Betonung liegt auf einzeln und kurz:

• Einzeln: Ein ADR, eine Entscheidung. "PostgreSQL für den Order Service verwenden" ist ein ADR. "Die gesamte Datenbankstrategie festlegen" ist ein Design-Dokument, kein ADR.
• Kurz: Ein ADR sollte auf eine Seite passen. Wenn es länger ist, dokumentieren Sie wahrscheinlich mehrere Entscheidungen oder nehmen zu viel Implementierungsdetail auf.

Das Konzept wurde durch Michael Nygard in einem Blogpost von 2011 populär gemacht. Seitdem wurden ADRs von Organisationen unterschiedlichster Größe übernommen -- von Startups bis zu Regierungen. Der UK Government Digital Service, Spotify und unzählige Engineering-Teams nutzen ADRs als Standardpraxis.

Was ADRs festhalten

Jeder ADR beantwortet vier grundlegende Fragen:

1. Was war der Kontext? Welche Situation oder welches Problem hat diese Entscheidung ausgelöst?
2. Was haben wir entschieden? Welche konkrete architektonische Wahl haben wir getroffen?
3. Welche Alternativen haben wir betrachtet? Welche anderen Optionen standen zur Debatte?
4. Was sind die Konsequenzen? Welche Trade-offs, Risiken und Auswirkungen bringt diese Entscheidung mit sich?

Das ist alles. Vier Fragen. Ein gut geschriebener ADR kann alle vier auf weniger als einer Seite beantworten.

Was ADRs nicht sind

• Keine Design-Dokumente. ADRs beschreiben nicht, wie etwas implementiert wird. Sie beschreiben, warum ein bestimmter Ansatz gewählt wurde.
• Keine RFCs. RFCs (Request for Comments) sind Vorschläge zur Diskussion. ADRs dokumentieren abgeschlossene Entscheidungen (obwohl ein ADR als Vorschlag beginnen und zu "akzeptiert" übergehen kann).
• Keine Meeting-Protokolle. ADRs erfassen das Ergebnis, nicht die Diskussion, die dazu geführt hat.
• Keine umfassende Dokumentation. ADRs ergänzen Architekturdiagramme, API-Spezifikationen und Runbooks. Sie ersetzen sie nicht.

Das Standard-ADR-Template

Es existieren mehrere ADR-Templates, aber die meisten sind Variationen derselben Grundstruktur. Hier ist ein praxisnahes Template, das Vollständigkeit mit Kürze vereint:

# ADR-NNNN: [Kurzer Titel, der die Entscheidung beschreibt]

## Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]

## Datum

[YYYY-MM-DD]

## Kontext

[Beschreiben Sie die Situation. Welches Problem lösen wir? Welche
Einschränkungen gibt es? Welche Kräfte wirken? Seien Sie konkret --
nennen Sie Zahlen, Deadlines, Team-Kompetenzen und technische
Anforderungen, wo relevant.]

## Entscheidung

[Formulieren Sie die Entscheidung klar und prägnant. Verwenden Sie
die aktive Form: "Wir werden X verwenden" statt
"X sollte in Betracht gezogen werden."]

## Betrachtete Alternativen

### [Alternative 1]
- Vorteile: ...
- Nachteile: ...
- Warum abgelehnt: ...

### [Alternative 2]
- Vorteile: ...
- Nachteile: ...
- Warum abgelehnt: ...

## Konsequenzen

### Positiv
- [Was wird einfacher oder besser]

### Negativ
- [Was wird schwieriger oder schlechter]

### Risiken
- [Was könnte schiefgehen]

## Verwandte Entscheidungen

- [Links zu verwandten ADRs]

Aufschlüsselung der einzelnen Abschnitte

Status bildet den Lebenszyklus einer Entscheidung ab. Der typische Ablauf ist: Proposed -> Accepted. Wenn sich die Umstände ändern, wird ein ADR Deprecated oder Superseded by einen neueren ADR. Wichtig: ADRs sollten niemals gelöscht werden -- selbst abgelehnte Entscheidungen sind wertvoll, weil sie verhindern, dass zukünftige Teams Optionen erneut prüfen, die bereits evaluiert wurden.

Datum legt fest, wann die Entscheidung getroffen wurde. Dies liefert zeitlichen Kontext: "Wir haben diese Technologie 2024 gewählt, als unser Scale X war. Jetzt, da unser Scale 10X ist, sollten wir das überdenken."

Kontext ist der wichtigste Abschnitt. Ein gut geschriebener Kontext-Abschnitt gibt zukünftigen Lesern genug Informationen, um zu verstehen, warum diese Entscheidung zum damaligen Zeitpunkt sinnvoll war, selbst wenn sich die Umstände seitdem geändert haben. Nennen Sie konkrete Zahlen ("wir verarbeiten 50.000 Bestellungen pro Tag"), Einschränkungen ("muss PCI-DSS-konform sein") und Teamfaktoren ("drei Ingenieure haben PostgreSQL-Erfahrung, keiner hat MongoDB-Erfahrung").

Entscheidung sollte eindeutig sein. "Wir werden PostgreSQL 16 als primären Datenspeicher für den Order Service verwenden" ist gut. "Wir sollten wahrscheinlich eine relationale Datenbank in Betracht ziehen" ist kein ADR -- das ist ein Vorschlag.

Betrachtete Alternativen ist der Abschnitt, der langfristig die meiste Zeit spart. Wenn ein neuer Ingenieur fragt "warum haben wir nicht MongoDB genommen?", steht die Antwort genau hier. Wenn das Team die Entscheidung ein Jahr später überprüft, kann es sehen, was evaluiert wurde und warum es abgelehnt wurde. Ohne diesen Abschnitt führen Teams dieselben Debatten endlos erneut.

Konsequenzen steht für intellektuelle Ehrlichkeit. Jede Entscheidung hat Trade-offs. Die Nachteile anzuerkennen schafft Vertrauen und hilft zukünftigen Teams zu verstehen, wann Umstände eine Überprüfung der Entscheidung rechtfertigen könnten.

Ein vollständiges ADR-Beispiel

Hier ist ein realistischer ADR, der das Template in der Praxis demonstriert:

# ADR-0023: Apache Kafka für die Inter-Service-Kommunikation verwenden

## Status

Accepted

## Datum

2025-11-15

## Kontext

Unsere Plattform ist im letzten Jahr von 3 auf 12 Microservices
gewachsen. Services kommunizieren derzeit synchron über HTTP-REST-Aufrufe.
Dies verursacht mehrere Probleme:

- Kaskadierende Ausfälle: Wenn der Inventory Service nicht verfügbar
  ist, kann der Order Service keine Bestellungen verarbeiten, obwohl
  Bestandsprüfungen eventual sein könnten.
- Enge Kopplung: Services müssen die API-Verträge und Endpoints der
  anderen kennen.
- Performance-Engpässe: Einige Operationen lösen Ketten von 4-5
  synchronen Aufrufen aus, was die Latenz erhöht.

Wir verarbeiten ungefähr 100.000 Events pro Tag. Wir erwarten, dass
dies innerhalb von 12 Monaten auf 500.000 ansteigen wird. Das Team hat
8 Backend-Ingenieure, von denen 2 vorherige Kafka-Erfahrung haben.

## Entscheidung

Wir werden Apache Kafka als primären Mechanismus für asynchrone
Inter-Service-Kommunikation einführen. Synchrones HTTP bleibt für
Request/Response-Muster bestehen, bei denen der Aufrufer ein sofortiges
Ergebnis benötigt (z. B. Authentifizierungsprüfungen).

Wir werden Confluent Cloud als verwalteten Kafka-Anbieter verwenden,
um den operativen Aufwand zu minimieren.

## Betrachtete Alternativen

### RabbitMQ
- Vorteile: Einfacher zu betreiben, geringere Lernkurve, unterstützt
  mehrere Messaging-Patterns (Pub/Sub, Point-to-Point, Routing).
- Nachteile: Weniger geeignet für Event-Sourcing-Patterns, die wir
  einführen möchten. Schwächere Replay/Rewind-Fähigkeiten. Community-
  Momentum hat sich bei Event-Driven Architectures zu Kafka verlagert.
- Warum abgelehnt: Wir erwarten, Event Replay für Audit und Debugging
  zu benötigen. Kafkas log-basierte Architektur ist dafür besser geeignet.

### AWS SQS + SNS
- Vorteile: Vollständig verwaltet, keine Infrastruktur zu pflegen,
  enge AWS-Integration.
- Nachteile: Vendor Lock-in zu AWS. Begrenzte Garantien für
  Nachrichtenreihenfolge. Kein eingebautes Stream Processing
  (würde Kinesis oder Lambda erfordern). Höhere Kosten pro Nachricht
  bei unserem prognostizierten Volumen.
- Warum abgelehnt: Wir wollen die Abhängigkeit von AWS nicht vertiefen,
  und wir brauchen geordnete Nachrichtenzustellung für Finanzereignisse.

### Synchrones HTTP beibehalten (mit Circuit Breakern)
- Vorteile: Keine neue Infrastruktur. Team bereits vertraut. Circuit
  Breaker adressieren kaskadierende Ausfälle.
- Nachteile: Löst die enge Kopplung nicht. Latenz akkumuliert sich
  weiterhin über Aufrufketten. Circuit Breaker sind ein Pflaster,
  keine Lösung für das grundlegende Kopplungsproblem.
- Warum abgelehnt: Adressiert Symptome, nicht die Ursache.

## Konsequenzen

### Positiv
- Services werden entkoppelt: Producer müssen die Consumer nicht kennen.
- Kaskadierende Ausfälle für asynchrone Workflows eliminiert.
- Event Replay ermöglicht leistungsfähige Debugging- und Audit-Fähigkeiten.
- Grundlage für Event-Sourcing-Patterns in zukünftigen Services.

### Negativ
- Operative Komplexität steigt (Kafka Cluster, Schema Registry,
  Consumer Group Management). Durch Confluent Cloud abgemildert.
- Team braucht Schulung zu Kafka-Konzepten und -Patterns.
- Eventual Consistency ersetzt Strong Consistency für asynchrone Flows.
  Einige Workflows müssen umgestaltet werden.
- Debugging verteilter asynchroner Flows ist schwieriger als das
  Nachverfolgen synchroner HTTP-Aufrufe. Wir werden Distributed
  Tracing benötigen (siehe ADR-0024).

### Risiken
- Wenn das Nachrichtenvolumen die Confluent-Cloud-Preisstufen
  überschreitet, könnten die Kosten erheblich steigen.
  Überwachen und Alerts einrichten.
- Schema-Evolution über Services hinweg erfordert Disziplin.
  Wir planen, Avro mit Schema Registry einzuführen.

## Verwandte Entscheidungen

- ADR-0024: OpenTelemetry für Distributed Tracing einführen
- ADR-0018: Service-Kommunikationsverträge (durch diesen ADR ersetzt)

Dieser ADR umfasst etwa 400 Wörter. Er hat vielleicht 20 Minuten zum Schreiben gebraucht. Er wird über die nächsten Jahre Stunden an Meetings einsparen.

Wann man einen ADR schreiben sollte

Nicht jede technische Entscheidung braucht einen ADR. Die Wahl zwischen zwei JSON-Bibliotheken rechtfertigt keinen. Aber einige Entscheidungen brauchen definitiv einen.

Schreiben Sie einen ADR, wenn:

• Die Entscheidung die Systemstruktur betrifft. Alles, was verändert, wie Services kommunizieren, wo Daten liegen oder wie Komponenten organisiert sind.
• Die Entscheidung kostspielig rückgängig zu machen ist. Die Wahl einer Datenbank, eines Messaging-Systems oder einer Deployment-Plattform. Wenn das Rückgängigmachen dieser Entscheidung mehr als einen Sprint braucht, dokumentieren Sie, warum Sie sie getroffen haben.
• Mehrere tragfähige Optionen existieren. Wenn die Wahl offensichtlich ist, brauchen Sie keinen ADR. Wenn Sie zwischen drei Optionen debattiert haben, halten Sie die Begründung fest.
• Die Entscheidung Teamgrenzen überschreitet. Jede architektonische Entscheidung, die andere Teams betrifft, sollte dokumentiert werden, damit sie die Begründung verstehen.
• Ihr zukünftiges Ich die Wahl in Frage stellen könnte. Wenn es auch nur die Möglichkeit gibt, dass jemand (einschließlich Ihres zukünftigen Ichs) fragt "warum haben wir das gemacht?", schreiben Sie es jetzt auf.

Kein ADR nötig, wenn:

• Die Entscheidung einem etablierten Teamstandard folgt (z. B. "wir verwenden immer Go für Backend-Services" braucht keinen neuen ADR für jeden Service)
• Die Entscheidung trivial rückgängig zu machen ist (eine Variable umbenennen, einen Code-Formatter wählen)
• Die Entscheidung rein kosmetisch ist (Code-Stil, Namenskonventionen -- das gehört in einen Style Guide)

ADR-Lebenszyklus und Governance

Der Lebenszyklus

ADRs haben einen natürlichen Lebenszyklus:

1. Draft/Proposed: Jemand identifiziert eine Entscheidung, die getroffen werden muss, und schreibt einen ADR-Entwurf. Das Team diskutiert.
2. Accepted: Das Team stimmt der Entscheidung zu. Der ADR-Status ändert sich zu Accepted.
3. Active: Die Entscheidung ist in Kraft. Der ADR dient als Referenzdokumentation.
4. Superseded: Eine neue Entscheidung ersetzt diese. Der alte ADR erhält den Status "Superseded by ADR-XXXX". Der neue ADR verweist auf den alten.
5. Deprecated: Die Entscheidung ist nicht mehr relevant (vielleicht wurde das System, auf das sie sich bezog, außer Betrieb genommen).

Wichtig: Löschen Sie niemals ADRs. Selbst veraltete oder ersetzte sind wertvoll. Sie bilden eine Zeitleiste der architektonischen Entwicklung.

Nummerierung

Verwenden Sie fortlaufende Nummern: ADR-0001, ADR-0002 usw. Die Nummer bietet chronologische Ordnung und macht ADRs leicht referenzierbar in Gesprächen: "wie in ADR-42 entschieden."

Einige Teams verwenden datumsbasierte Nummerierung (ADR-2026-03-27-kafka), aber fortlaufende Nummern sind einfacher und verbreiteter.

Überprüfungsrhythmus

Setzen Sie eine vierteljährliche Erinnerung, um Ihre ADRs zu überprüfen:

• Sind akzeptierte Entscheidungen nicht mehr gültig?
• Haben sich Rahmenbedingungen geändert, die Annahmen ungültig machen?
• Gibt es Entscheidungen, die das Team informell getroffen hat und die festgehalten werden sollten?

Diese Überprüfung verhindert ADR-Verfall und hält die Sammlung aktuell.

Wo ADRs gespeichert werden sollten

Die gängigsten Ansätze, in Empfehlungsreihenfolge:

Im Code-Repository

Speichern Sie ADRs in docs/adr/ oder docs/decisions/ innerhalb Ihres Repositorys. Dies ist der beliebteste Ansatz, und das aus gutem Grund:

• ADRs werden versionskontrolliert zusammen mit dem Code, den sie beschreiben
• Sie erscheinen in Pull Requests und Code Reviews
• Sie können nicht verwaist in einem Wiki landen, das niemand besucht
• Sie sind über grep oder Suche auffindbar

Konvention: eine Markdown-Datei pro ADR, benannt mit Nummer und Slug:

docs/adr/
  0001-use-postgresql-for-orders.md
  0002-adopt-event-driven-architecture.md
  0003-monorepo-for-frontend.md

In einem dedizierten Architektur-Tool

Tools wie Archyl bieten integriertes ADR-Management mit zusätzlichen Fähigkeiten:

• ADRs direkt mit C4-Modellelementen verknüpfen (Container, Komponenten, Beziehungen)
• ADRs über alle Projekte hinweg suchen und filtern
• ADR-Status und -Lebenszyklus verfolgen
• ADRs mit Conformance Rules verbinden, die die Entscheidung durchsetzen

Der Hauptvorteil eines Architektur-Tools ist Kontext. Wenn ein Entwickler den PostgreSQL-Container in einem C4-Diagramm betrachtet, kann er zum ADR durchklicken, der erklärt, warum PostgreSQL gewählt wurde. Die Entscheidung und die Architektur sind verbunden, nicht in Silos.

In einem Wiki (nicht empfohlen)

Wikis (Confluence, Notion usw.) sind der Ort, an dem ADRs vergessen werden. Sie sind vom Code getrennt, schwer auffindbar und werden selten gepflegt. Wenn Sie ein Wiki verwenden müssen, verweisen Sie zumindest aus dem Code-Repository auf die ADRs.

ADRs in Ihren Workflow integrieren

ADRs als Teil von Pull Requests

Für bedeutende architektonische Änderungen sollten Sie einen ADR als Teil des Pull Requests verlangen. Fügen Sie einen Abschnitt zu Ihrem PR-Template hinzu:

## Architektur-Auswirkung

- [ ] Keine architektonischen Änderungen
- [ ] ADR erstellt/aktualisiert: [Link]

Dies normalisiert die ADR-Erstellung und stellt sicher, dass Entscheidungen dokumentiert werden, wenn sie getroffen werden -- nicht Wochen später, wenn der Kontext verblasst ist.

ADRs in Architektur-Reviews nutzen

Verweisen Sie bei Architektur-Reviews oder Design-Diskussionen auf bestehende ADRs. "Bevor wir das umgestalten, schauen wir nach, was ADR-15 darüber sagt, warum wir diesen Ansatz gewählt haben." Dies gibt ADRs Sichtbarkeit und stärkt die Gewohnheit, Entscheidungen zu dokumentieren.

ADRs mit Architekturdiagrammen verbinden

Hier werden ADRs wirklich mächtig. Wenn ein ADR mit einem bestimmten Element in Ihrem C4-Modell verknüpft ist, entsteht ein navigierbarer Wissensgraph:

• Klicken Sie auf den Kafka-Container in Ihrem Container-Diagramm -> sehen Sie ADR-0023, der erklärt, warum Kafka gewählt wurde
• Klicken Sie auf die PostgreSQL-Datenbank -> sehen Sie ADR-0001, der die Datenbankauswahl erklärt
• Klicken Sie auf das API Gateway -> sehen Sie ADR-0012, der erklärt, warum Kong gegenüber Custom Routing gewählt wurde

In Archyl können Sie ADRs mit jedem C4-Element verknüpfen -- Systems, Containers, Components oder Relationships. Diese Verbindung bedeutet, dass architektonische Entscheidungen keine frei schwebenden Dokumente sind; sie sind an die spezifischen Teile der Architektur verankert, die sie betreffen.

Automatisieren, was möglich ist

Mehrere Tools können die Reibung der ADR-Verwaltung reduzieren:

• adr-tools (von Nat Pryce): Ein Kommandozeilen-Tool zum Erstellen und Verwalten von ADRs in einem Repository. Führen Sie adr new "Use Kafka for messaging" aus, um einen neuen ADR aus einem Template zu generieren.
• Log4brains: Generiert eine durchsuchbare, navigierbare Website aus Ihren ADR-Markdown-Dateien.
• Archyl: Verwaltet ADRs mit Verknüpfung zu C4-Elementen, Status-Tracking und projektübergreifender Suche.

Fortgeschrittene ADR-Praktiken

Lightweight ADRs (LADRs)

Einige Teams finden selbst das Standard-Template zu umfangreich. Ein Lightweight ADR besteht aus nur drei Sätzen:

Im Kontext von [Situation],
haben wir [Entscheidung] getroffen,
um [Ziel] zu erreichen,
wobei wir [Trade-off] akzeptieren.

Beispiel:

Im Kontext der Notwendigkeit einer Inter-Service-Kommunikation,
die Service-Ausfallzeiten toleriert, haben wir uns entschieden,
Apache Kafka via Confluent Cloud zu verwenden, um Service-Entkopplung
und Event-Replay-Fähigkeit zu erreichen, wobei wir erhöhte operative
Komplexität und Eventual Consistency akzeptieren.

Dieses Format eignet sich gut für Entscheidungen, die wichtig genug sind, um dokumentiert zu werden, aber keinen vollständigen ADR rechtfertigen.

Decision Logs

Ein Decision Log ist ein einzelnes Dokument, das alle ADRs in chronologischer Reihenfolge mit einzeiligen Zusammenfassungen auflistet. Es dient als Index:

Dies gibt einen schnellen Überblick über alle Entscheidungen, ohne einzelne ADR-Dateien öffnen zu müssen.

ADRs für nicht-technische Entscheidungen

ADRs sind nicht auf Technologieentscheidungen beschränkt. Teams nutzen sie für:

• Prozessentscheidungen: "Wir werden Pair Programming für sicherheitskritischen Code durchführen"
• Organisationsentscheidungen: "Das Plattform-Team verantwortet alle Infrastruktur-Container"
• Anbieterentscheidungen: "Wir werden Datadog für Monitoring verwenden statt eine eigene Lösung zu bauen"

Wenn die Entscheidung bedeutsam und kostspielig rückgängig zu machen ist, ist ein ADR angemessen -- unabhängig davon, ob sie streng genommen "architektonisch" ist.

Häufige Fallstricke

ADRs nachträglich schreiben

Der beste Zeitpunkt, einen ADR zu schreiben, ist während des Entscheidungsprozesses. Einen Wochen später zu schreiben bedeutet, dass Sie die Nuancen vergessen haben, die Alternativen, die Sie betrachtet haben, und die Einschränkungen, die existierten. Machen Sie das ADR-Schreiben zum Teil des Entscheidungsprozesses, nicht zu einem Nachgedanken.

Zu lang machen

Wenn Ihr ADR eine Seite überschreitet, dokumentieren Sie wahrscheinlich mehrere Entscheidungen (teilen Sie sie auf) oder nehmen Implementierungsdetails auf (heben Sie die für ein Design-Dokument auf). Die Disziplin der Kürze erzwingt Klarheit.

Abgelehnte Alternativen nicht dokumentieren

Der Abschnitt "Betrachtete Alternativen" ist langfristig der wertvollste Teil eines ADR. Ohne ihn werden zukünftige Ingenieure dieselben Alternativen vorschlagen, ohne zu wissen, dass sie bereits evaluiert und abgelehnt wurden. Erklären Sie immer, was Sie nicht gewählt haben und warum.

Die Praxis aufgeben

Ein oder zwei ADRs bieten nicht viel Wert. Fünfzig ADRs, die über zwei Jahre angesammelt wurden, werden zu einer unbezahlbaren Wissensbasis. Die Versuchung, mit dem Schreiben von ADRs aufzuhören, wenn es stressig wird, ist groß. Widerstehen Sie ihr. Die 15 Minuten, die Sie für das Schreiben eines ADR aufwenden, werden später Stunden an Meetings einsparen.

Status nicht überprüfen oder aktualisieren

Eine ADR-Sammlung, bei der die Hälfte der Entscheidungen veraltet ist, ist irreführend. Planen Sie vierteljährliche Reviews ein. Markieren Sie ersetzte Entscheidungen. Halten Sie die Sammlung vertrauenswürdig.

Warum ADRs im KI-Zeitalter noch wichtiger werden

Da KI-Agenten zu aktiven Teilnehmern in der Softwareentwicklung werden, gewinnen ADRs neue Bedeutung. Ein KI-Agent, der Code schreibt, kann Ihre ADRs lesen und verstehen:

• Warum bestimmte Technologien gewählt wurden (und weiterhin verwendet werden sollten)
• Welche Alternativen abgelehnt wurden (und nicht erneut vorgeschlagen werden sollten)
• Welche Einschränkungen bestehen (Compliance-Anforderungen, Performance-Schwellenwerte)
• Welche Trade-offs akzeptiert wurden (Eventual Consistency, Anbieterabhängigkeiten)

Über Archyls MCP Server können KI-Agenten wie Claude Code auf Ihre ADRs zugreifen, bevor sie architektonische Vorschläge machen. Statt MongoDB für einen Service vorzuschlagen, bei dem Sie bereits dokumentiert haben, warum PostgreSQL gewählt wurde, respektiert der Agent die bestehende Entscheidung -- oder weist explizit darauf hin, wenn er meint, die Entscheidung sollte überprüft werden.

Das macht ADRs nicht nur zu Dokumentation für Menschen, sondern zu Leitplanken für KI.

Heute anfangen

Wenn Ihr Team noch keine ADRs verwendet, beginnen Sie mit diesen drei Schritten:

1. Wählen Sie eine kürzliche Entscheidung. Denken Sie an eine architektonische Entscheidung, die Ihr Team im letzten Monat debattiert hat. Schreiben Sie mit dem obigen Template einen ADR dafür. Das sollte 15-20 Minuten dauern.

2. Speichern Sie ihn in Ihrem Repository. Erstellen Sie ein docs/adr/-Verzeichnis und fügen Sie die Datei hinzu. Nehmen Sie sie in Ihren nächsten Pull Request auf, damit das Team sie sieht.

3. Machen Sie es zur Gewohnheit. Fügen Sie eine "Architektur-Auswirkung"-Checkbox zu Ihrem PR-Template hinzu. Besprechen Sie ADRs in Ihrem nächsten Architektur-Meeting. Die Praxis gewinnt an Momentum, sobald das Team den Wert erkennt.

Wenn das nächste Mal jemand fragt "warum haben wir das so gemacht?" -- und das wird passieren -- haben Sie die Antwort.

Erfahren Sie mehr über Architekturdokumentation: Was ist das C4-Modell? | ADR Best Practices | KI-gestützte Architektur-Discovery. Oder testen Sie Archyl kostenlos, um ADRs direkt mit Ihrem C4-Modell zu verknüpfen.