Entscheidungssystem, das das Projektchaos beendet: Architecture Decision Record (ADR)

Das größte Problem in modernen Softwareprojekten ist oft nicht die Qualität des Codes. Die wahre Gefahr geht von einem viel heimtückischeren Ort aus: Vergessene Entscheidungen.

Die überwiegende Mehrheit der Unternehmensteams verwaltet die architektonischen Entscheidungen, die über das Schicksal des Projekts entscheiden, immer noch auf der Ebene „Wir haben beim letzten Treffen darüber gesprochen“. Wenn das Projekt jedoch wächst, sich das Team verändert und die Zeit vergeht, verschwinden diese Treffen.

Es bleiben diese nervigen Fragen:

• „Warum haben wir dieses System zu einem Microservice gemacht, wer hat entschieden?“
• „Warum haben wir uns für diese Datenbank entschieden, haben wir nach Alternativen gesucht?“
• „Haben wir dieses Problem, das wir jetzt erleben, vorhergesehen?“

Wenn Sie keine klare Antwort auf diese Fragen haben oder kein Dokument vorlegen können; Das bedeutet, dass Ihr Projekt ins technische Chaos gerät.

An diesem Punkt kommt das ADR-System (Architecture Decision Record) ins Spiel, das das Projekt vor der Abhängigkeit von Menschen bewahrt.

Was ist ADR? (Kein Dokument, architektonisches Gedächtnis)

ADR ist ein System, mit dem kritische Entscheidungen in Softwareprojekten kurz, klar und dauerhaft aufgezeichnet werden. Aber verwechseln Sie das nicht mit langweiliger technischer Dokumentation.

Bei jedem ADR handelt es sich um eine Live-Aufzeichnung, die vier grundlegende Fragen beantwortet:

1. Welche Entscheidung haben wir getroffen?
2. Warum haben wir es gekauft? (Was war der Kontext?)
3. Welche Alternativen gab es? (Was haben wir eliminiert?)
4. Was sind die Kompromisse? (Was kostet uns diese Entscheidung?)

ADR ist das „Gedächtnis“ Ihres Projekts. Der Code kann sich ändern, die Technologie kann sich ändern, sogar der CTO kann sich ändern; aber die Logik der Entscheidungen bleibt dank ADR im Projekt erhalten.

Kritischer Unterschied zwischen Aufgabe und ADR

Viele Teams machen den Fehler zu glauben, dass Jira-Tickets oder -Aufgaben „Entscheidungen“ seien. Es gibt jedoch einen großen Unterschied zwischen ihnen.* Aufgabe: „Mach das“, sagt er. Es ist handlungsorientiert.

• ADR (Entscheidung): „Warum machen wir das?“ sagt. Es ist strategieorientiert.

Lassen Sie es uns anhand eines einfachen Beispiels erklären:

• Aufgabe: „Basket-Endpunkte verbessern.“ (Diese Aufgabe wird beendet und archiviert.)
• ADR: „Sollte die Warenkorbstruktur ein separater Dienst sein oder sollte sie innerhalb der Hauptanwendung verbleiben?“ (Diese Entscheidung beeinflusst die Architektur des Projekts über Jahre hinweg.)

Aufgabe endet, ADR lebt.

Wie sieht ein ADR aus?

Das Schreiben von ADR ist keine Aufgabe, die mehrere Tage in Anspruch nimmt. Es erfordert vielmehr Klarheit. Hier ist eine einfache und effektive ADR-Vorlage:

ADR-007: Redis-Cache verwenden

Status: Akzeptiert

Kontext: Die API-Antwortzeiten nahmen zu und die Belastung der Datenbank begann zu steigen. Lesevorgänge überwiegen bei weitem die Zahl der Schreibvorgänge.

Entscheidung: Der Redis-Cache wird auf häufig gelesenen Endpunkten verwendet.

Alternativen: Datenbankindexoptimierung oder CDN-Nutzung wurden in Betracht gezogen, aber aufgrund der Notwendigkeit sofortiger Daten ausgeschlossen.

Folgen:

• (+) Die Reaktionszeit (Latenz) wird kürzer.
• (+) Datenbanklast wird abnehmen.
• (-) Die Komplexität der Cache-Löschung (Ungültigmachung) wird hinzugefügt.

Wie Sie sehen können; Es macht nicht nur die Entscheidung, sondern auch ihre Gründe und Konsequenzen deutlich.

Warum ist ADR nicht nur ein „technisches“ Thema?

Als Manager oder Projektinhaber schützt die Beantragung von ADR Ihr Projekt. Das ADR-System bietet:

• Geschwindigkeit: Die gleichen Architekturdiskussionen werden nicht bei jedem Sprint wiederholt. Die Entscheidung ist gefallen, die Reise geht weiter.
• Einfaches Onboarding: Ein neuer Entwickler könnte fragen: „Warum?“ Anstatt zu fragen „“, versteht er/sie die gesamte Geschichte des Projekts, indem er/sie die ADR-Protokolle liest.* Technisches Schuldenmanagement: Sie kommen voran, indem Sie Risiken akzeptieren (Kompromiss), nicht unbewusst.

Wie wende ich ADR in meinen Dienstleistungen an?

In meiner Projektmanagement- und technischen Beratungsarbeit ist das ADR-Schreiben keine „lästige Pflicht“, sondern eine Lieferdisziplin.

Wenn ich mich in einem Projekt engagiere, setze ich normalerweise in den ersten 7 Tagen Folgendes um:

1. Festlegen der ADR-Protokollstruktur: Wir legen fest, wo die Entscheidungen gespeichert werden (Jira, Git, Notion usw.).
2. Aufzeichnung kritischer Entscheidungen: Wir machen eine Röntgenaufnahme der aktuellen Architektur und klären die im Nachhinein getroffenen kritischen Entscheidungen.
3. Gestaltung der Roadmap: Wir priorisieren die Bereitstellungs-Roadmap basierend auf diesen Architekturentscheidungen, nicht nur auf Funktionen.

Dies gewährleistet vollständige Transparenz zwischen dem Management und dem technischen Team. „Scope Drift“ (Scope-Erweiterung) wird verhindert und das Projekt wird dem System selbst anvertraut, nicht dem Gedächtnis einzelner Personen.

Ergebnis

Der Code ändert sich. Meetings vergehen wie im Flug. Aber Entscheidungen bilden die Grundlage Ihres Projekts.

Wenn Sie das Gefühl haben, dass in Ihrem Projekt Entscheidungen in der Luft schweben und immer wieder die gleichen Themen diskutiert werden, benötigen Sie ein „Entscheidungsgedächtnis“.

Der Ordner „Technology Stack and Architecture“ ist der natürlichste Ort, an dem diese Entscheidungen umgesetzt werden können.

---

Lassen Sie uns dieses System in 5 Schritten mithilfe der Confluence-Struktur einrichten:

Schritt 1: Erstellen Sie die „Entscheidungsbibliothek“

Öffnen wir im Screenshot eine neue Homepage im Ordner „Technology Stack and Architecture“.

• Seitenname: Architekturentscheidungsprotokoll (ADR)
• Zweck: Diese Seite ist keine eigenständige Entscheidung; Dies ist die Haupttabelle, in der alle Entscheidungen aufgelistet sind (Index). Wenn also ein neues Teammitglied hier klickt, sieht es den gesamten Verlauf des Projekts in einer Liste.#### Schritt 2: Bereiten Sie eine globale Vorlage vor Niemand mag es, jedes Mal eine Seite von Grund auf neu zu erstellen. In Confluence sollten Sie ein „Globales Template“ oder ein Template nur für diesen Space erstellen. Der Inhalt der Vorlage sollte so sein, wie wir es zuvor besprochen haben:
• Titel: ADR-XXX: [Kurztitel]
• Status: (Wir werden dies in Schritt 3 detailliert beschreiben)
• Kontext: Was ist los?
• Entscheidung: Was machen wir?
• Folgen: Kosten und Gewinne.

Schritt 3: Verwenden Sie das visuelle „Status“-Makro

Eine der größten Stärken von Confluence ist die Status-Makro-Funktion. Fügen Sie dieses Makro oben in Ihre Vorlage ein. Farben ermöglichen es dem Gehirn, die Situation innerhalb von Sekunden wahrzunehmen. Standardfarbcodes können sein:

• 🟢 AKZEPTIERT (Grün): Die Entscheidung wurde getroffen und wird umgesetzt.
• 🟡 VORGESCHLAGEN (Gelb): Zur Diskussion offen, noch nicht genehmigt.
• 🔴 ABGELEHNT (Rot): Es wurde vorgeschlagen, aber nicht akzeptiert (es zu verbergen ist auch eine Lektion).
• ⚪ VERALTET (Grau): War früher gültig, wurde aber jetzt durch eine neue Entscheidung ersetzt (z. B. ADR-009).

Schritt 4: Seitenbaum bearbeiten (Hierarchie)

Positionieren Sie jede neue ADR-Seite, die Sie erstellen (z. B. ADR-001: Redis Cache), als untergeordnete Seite der Seite „Architecture Decision Log“, die wir im ersten Schritt geöffnet haben. Die Ansicht wird so aussehen:``` 📂 Teknoloji Yığını ve Mimarisi └── 📂 Architecture Decision Log (ADR) ├── 📄 ADR-001: Redis Cache Kullanımı ├── 📄 ADR-002: Auth Provider Seçimi └── 📄 ADR-003: ...

Das ist der „magische“ Teil. 🪄 Anstatt Listen einzeln manuell zu erstellen, nutzen wir die Automatisierung von Confluence.
Fügen Sie jeder ADR-Seite (Vorlage) das Makro „Seiteneigenschaften“ hinzu und fügen Sie zusammenfassende Informationen wie Status, Entscheidungsdatum und Entscheidungsträger hinzu.
Gehen Sie zur Hauptseite (Architecture Decision Log) und fügen Sie das Makro „Page Properties Report“ hinzu.
Dieses Makro ruft diese zusammenfassenden Informationen von den Unterseiten ab und erstellt eine automatische, immer aktuelle Tabelle auf der Hauptseite.