Ein strukturierter Ansatz zur Dokumentation wichtiger technischer Entscheidungen

In der schnelllebigen Welt der Softwareentwicklung werden täglich zahlreiche Entscheidungen getroffen – von der Wahl des Datenbanktyps bis hin zur Festlegung auf ein bestimmtes Framework. Viele dieser Entscheidungen haben langfristige Auswirkungen auf die Architektur und Wartbarkeit eines Systems.

Doch wie oft haben Sie sich schon gefragt: "Warum haben wir das damals eigentlich so gemacht?" oder "Welche Alternativen hatten wir in Betracht gezogen?" Oder was passiert, wenn das ursprüngliche Team das Projekt verlässt? Wenn neue Entwickler hinzukommen?

Was sind Architectural Decision Records?

ADRs sind kurze Textdokumente, die eine architektonische Entscheidung sowie ihren Kontext und ihre Konsequenzen festhalten. Sie beantworten vier wesentliche Fragen:

• Welches Problem sollte gelöst werden?
• Welche Alternativen wurden betrachtet?
• Welche Entscheidung wurde getroffen?
• Welche Konsequenzen ergeben sich daraus?

Ein typisches ADR hat folgende Struktur:

• Titel: Prägnante Beschreibung der Entscheidung
• Status: Vorgeschlagen, akzeptiert, überholt, ersetzt
• Kontext: Die Situation, die eine Entscheidung erforderlich macht
• Entscheidung: Die getroffene Entscheidung
• Konsequenzen: Auswirkungen der Entscheidung, sowohl positive als auch negative
• Alternativen: Welche anderen Optionen wurden in Betracht gezogen

Ein konkretes Beispiel

Nehmen wir an, ein Entwicklungsteam steht vor der Wahl eines Datenbanksystems für eine neues Kundenverwaltungssystem. Ein entsprechendes ADR könnte folgendermaßen aussehen:

# ADR-001: Auswahl der Datenbank für das Kundenverwaltungssystem

## Status
Akzeptiert

## Kontext
Unser neues Kundenverwaltungssystem benötigt eine Datenbank, die sowohl 
strukturierte Kundendaten als auch flexible Metadaten speichern kann. 
Das System muss bis zu 100.000 Kunden unterstützen und eine hohe 
Verfügbarkeit gewährleisten.

## Entscheidung
Wir werden PostgreSQL als primäre Datenbank verwenden.

## Begründung
- PostgreSQL bietet sowohl relationale als auch JSON-Unterstützung
- Bewährte Skalierbarkeit bis zu unserem erwarteten Datenvolumen
- Starke ACID-Eigenschaften für Datenkonsistenz
- Umfangreiche Erfahrung im Team vorhanden
- Aktive Community und langfristige Unterstützung

## Alternativen
- MongoDB: Flexibler für unstrukturierte Daten, aber weniger 
  ACID-Garantien
- MySQL: Bewährt, aber schwächere JSON-Unterstützung
- Cassandra: Bessere Skalierung, aber höhere Komplexität

## Konsequenzen
Positiv:
- Konsistente Datenintegrität
- Flexibilität durch JSON-Unterstützung
- Geringere Lernkurve für das Team

Negativ:
- Potentielle Skalierungsgrenzen bei sehr großen Datenmengen
- Vertikale Skalierung teurer als horizontale

Vorteile von ADRs

Die Verwendung von ADRs bietet zahlreiche Vorteile:

• Onboarding neuer Teammitglieder
  Neuzugänge können schnell verstehen, warum das System so aufgebaut ist, wie es ist.
  
  
• Vermeidung von wiederholten Diskussionen
  Die Begründung einer Entscheidung ist dokumentiert und kann bei erneuten Fragen konsultiert werden.
  
  
• Kollektives Wissen
  Das Wissen über Architekturentscheidungen bleibt im Team, auch wenn einzelne Personen das Unternehmen verlassen.
  
  
• Verbesserung der Entscheidungsfindung
  Der Prozess des Schreibens eines ADR hilft, Gedanken zu strukturieren und Entscheidungen gründlicher zu durchdenken.
  
  
• Historisches Archiv
  ADRs bieten eine chronologische Sicht auf die Historie und Evolution der Systemarchitektur.

ADRs mit adr-tools verwalten

Die manuelle Erstellung und Verwaltung von ADRs kann umständlich sein. Zum Glück gibt es Tools, die diesen Prozess vereinfachen. Eines der bekanntesten ist adr-tools, entwickelt von Nat Pryce.

Installation

# macOS mit Homebrew
brew install adr-tools

# Ubuntu/Debian
sudo apt-get install adr-tools

# Oder direkt von GitHub
git clone https://github.com/npryce/adr-tools.git

# ADR-Verzeichnis initialisieren
adr init doc/architecture/decisions

# Neues ADR erstellen
adr new "Auswahl des Frontend-Frameworks next.js"

# Verknüpfung zwischen ADRs erstellen
# Beispiel: ADR 3 ersetzt ADR 2, ADR 2 geändert durch ADR 3

# Bei Neuanlage eines ADRs, Verlinkung (-l TARGET:LINK:REVERSE-LINK)
adr new -l "2:ersetzt:geändert durch" "Auswahl des Frontend-Frameworks Remix"

# Bei Neuanlage eines ADRs, explizite Ablösung eines ADRs (-s SUPERCEDED)
adr new -s 2 "Auswahl des Frontend-Frameworks Laravel"

# Bei bestehenden ADRs, Verlinkung (-l SOURCE LINK TARGET REVERSE-LINK)
adr link 3 "ersetzt" 2 "geändert durch"

# Übersicht aller ADRs generieren
adr generate toc

Die oben verwendeten adr-tools Befehle kurz erklärt:

adr init [DIRECTORY] # Initialisiert ein neues ADR-Verzeichnis
adr new TITLE # Erstellt ein neues ADR
adr new -s SUPERCEDED # Erstellt ein neues ADR mit Verlinkung zum abgelöstem ADR
adr new -l TARGET:LINK:REVERSE-LINK # Erstellt ein neues ADR mit Verlinkung zu bestehenden ADRs
adr link SOURCE LINK TARGET REVERSE-LINK # Verknüpft ADRs miteinander
adr generate toc # Generiert ein Inhaltsverzeichnis aller ADRs

Das Tool kümmert sich automatisch um die Nummerierung, Statusverwaltung und Verlinkung zwischen zusammenhängenden ADRs.

Manuelle Status-Änderungen von ADRs

Der Status eines ADRs wie bspw. "Abgelehnt" kann direkt im ADR-Dokument geändert werden:

# ADR-003: Microservices-Architektur

## Status
Abgelehnt

## Grund für Ablehnung
Die Komplexität war für unser Team zu hoch. Siehe ADR-005 für die 
gewählte Alternative.

# ADR-002: REST API Design

## Status
Ersetzt durch ADR-006

## Kontext
[ursprünglicher Inhalt...]

Integration in den Entwicklungsprozess

• Onboarding
  Neue Teammitglieder lesen relevante ADRs als Teil der Einarbeitung
  
  
• Definition of Done
  Signifikante Architekturentscheidungen erfordern ein ADR
  
  
• Timing
  Wir schreiben ADRs zeitnah zur Entscheidung, solange der Kontext noch frisch ist.
  
  
• Leichtgewichtiger Prozess
  Wir halten ADRs bewusst kurz (meist unter einer Seite), um die Hürde für das Schreiben niedrig zu halten.
  
  
• Versionierung im Code-Repository
  Wir speichern ADRs im selben Repository wie den Code, idealerweise unter `docs/adr/` oder `doc/architecture/decisions/` und generieren regelmäßig Reporte für Mitglieder ausserhalb des Entwicklungsteams.
  
  
• Regelmäßige Reviews
  Wichtige architektonische Entscheidungen durchlaufen einen Review-Prozess ähnlich wie bei Code-Änderungen.
  
  
• ADRs als lebende Dokumente
  Wir kennzeichnen veraltete ADRs als "überholt" und verlinken auf neuere Entscheidungen, anstatt sie zu löschen.
  
  
• Einbeziehung des Teams
  Wichtige ADRs sollten im Team diskutiert und gemeinsam verabschiedet werden.
  
  
• Entscheidungen mit Bedeutung
  Nicht jede technische Entscheidung benötigt ein ADR – wir konzentrieren uns auf solche mit signifikanten Auswirkungen auf die Architektur.

Fazit

Architectural Decision Records sind ein einfaches, aber mächtiges Werkzeug, um Wissen über wichtige Entscheidungen in Softwareprojekten zu bewahren. Sie fördern Transparenz, verbessern die Kommunikation im Team und helfen, kostspielige Fehlentscheidungen zu vermeiden.

Der Aufwand für die Einführung von ADRs ist minimal, besonders mit Tools wie adr-tools, während der Nutzen mit der Zeit und der Projektgröße exponentiell wächst. Wenn Sie in Ihrem Team noch keine ADRs nutzen, ist jetzt der perfekte Zeitpunkt, damit zu beginnen.

Bei scalewerk.io unterstützen wir unsere Kunden nicht nur bei der Implementierung technischer Lösungen, sondern auch bei der Etablierung nachhaltiger Entwicklungspraktiken wie ADRs. Kontaktieren Sie uns gerne, wenn Sie mehr über unsere Erfahrungen erfahren möchten.