ADR-0001: ADR-Format & Prozess

Status: Proposed
Datum: 2026-05-15
Decider: Malte (mit Claude)
Verwandt: alle ADRs (Meta)
Tags: meta, process, documentation

Kontext

mvest soll alle relevanten Architektur-Entscheidungen als ADRs dokumentieren. Damit ADRs konsistent, lesbar und visuell ansprechend sind, brauchen wir ein festes Format, Konventionen für Erstellung und Status-Übergänge sowie eine klare Sprach-Wahl.

Diese ADR wurde rückwirkend geschrieben, nachdem sich das Format in ADR-0003 bis ADR-0007 und ADR-0014 in der Praxis etabliert hatte. Sie dokumentiert, was bereits gelebt wird, und macht es zur verbindlichen Norm für künftige ADRs.

Entscheidungstreiber

Visuelle Aufbereitung: ADRs sollen ansprechend sein, mit Diagrammen, Tabellen, klarer Hierarchie — nicht nur Fließtext.
Konsistenz: Wer eine ADR liest, soll sich nicht erst neu orientieren müssen.
Lesbarkeit: direkter Konsum im Browser, kein Build-Schritt nötig.
Auditierbarkeit: Status-Übergänge sind klar definiert, nicht vom Autor allein steuerbar.
Niedrige Schwelle für neue ADRs: Template + Beispiele machen das Schreiben schnell.

Betrachtete Optionen

Option A — MADR (Markdown)

Standard-Format für ADRs, bekannt und tooling-stark.

Industriestandard, Tooling vorhanden (adr-tools, log4brains).

Einfach zu diffen, GitHub-rendert nativ.

Visuell limitiert; Diagramme nur über Mermaid-Codeblocks, kein freies Styling.

Nutzer hat explizit visuell aufbereitete Doku gewünscht — Markdown wirkt schnell „langweilig".

Option B — Eigenes HTML-Format

Handgeschriebenes HTML mit zentralem Stylesheet, Mermaid via CDN, Status-Badges, Option-Cards.

Volle visuelle Kontrolle, freie Layouts (Karten, Tabellen, Diagramme).

Kein Build-Schritt — direkt über nginx als Static-Files served.

Bereits in 0003–0007/0014 erprobt, das Format funktioniert.

Mehr Schreibaufwand als Markdown.

Tooling (Linting, Diffing) weniger ausgereift als für Markdown.

Option C — Externe Tools (Confluence, Notion)

Vendor-Lock-in, schlecht versionierbar, nicht im Repo.

Nicht offline lesbar.

Entscheidung

Wir nutzen Option B: handgeschriebenes HTML in adr/ mit einem gemeinsamen Stylesheet und festen Konventionen.

Datei- und Verzeichnis-Konventionen

Verzeichnis: adr/ im Repo-Root.
Dateiname: NNNN-kebab-case-titel.html — vierstellige Nummer, mit Bindestrichen kleingeschriebener Titel. Beispiel: 0006-tool-architektur-mcp.html.
Nummerierung: aufsteigend, fortlaufend, lückenfrei. ADR-0001 ist diese hier. Auch zurückgezogene oder superseded ADRs behalten ihre Nummer (Datei bleibt mit aktualisiertem Status erhalten).
Assets: Gemeinsames Stylesheet unter adr/assets/style.css. Pro-ADR-spezifische Assets (Bilder, SVGs) unter adr/assets/<adr-id>/.
Index: adr/index.html listet alle ADRs mit Status und Datum.
Template: adr/template.html als Kopiervorlage für neue ADRs.

Pflicht-Struktur einer ADR

Header (<header class="adr-header">):
- Navigations-Link zum Index (<nav><a href="index.html">← ADR-Index</a></nav>)
- <h1>: ADR-NNNN: Titel
- Meta-Liste (<dl class="meta">) mit Pflichtfeldern:
  - Status — als Badge
  - Datum — ISO YYYY-MM-DD, Datum der letzten Statusänderung
  - Decider — wer entschieden hat
  - Verwandt — Liste verbundener ADRs (oder „—")
  - Tags — Schlagworte für Filterbarkeit
- Optionale Meta-Felder: Supersedes, Superseded by, Deprecates.
Sektionen (<section id="..."> mit <h2>):
- Kontext — Pflicht. Warum stellt sich die Frage?
- Entscheidungstreiber — Pflicht. Welche Kriterien beeinflussen die Wahl?
- Betrachtete Optionen — Pflicht. Mindestens zwei Optionen, davon eine markiert als gewählt.
- Entscheidung — Pflicht. Welche Option und warum, plus konkrete Festlegungen.
- Konsequenzen — Pflicht. Mit Sub-Headings „Positiv", „Negativ / Trade-offs", optional „Risiken".
- Optionale Sektionen: Architektur (mit Mermaid-Diagramm), Implementierungsstatus (Tabelle), Offene Fragen / nachfolgende ADRs.
Footer (<footer class="adr-footer">) mit ADR-ID, Datum, Link zurück zum Index.

Stil- und CSS-Klassen-Konventionen

Status-Badges: <span class="status {accepted|proposed|deprecated|superseded}">
Option-Cards: <div class="options-grid"> mit Kindern <div class="option">. Die gewählte Option bekommt zusätzlich class="option chosen".
Pros/Cons innerhalb einer Option: <p class="pros"> bzw. <p class="cons">.
Callouts: <p class="callout {info|warn|success}"> für hervorgehobene Hinweise.
Tabellen: Standard-<table>, vom Stylesheet automatisch gestylt.
Mermaid-Diagramme: <div class="mermaid">, Mermaid-Init im <head> mit festgelegtem Light-Theme (siehe Template).
Code-Snippets: <pre><code>, kein Syntax-Highlighting in v1.

Status-Lifecycle

stateDiagram-v2 [*] --> Proposed: ADR geschrieben Proposed --> Accepted: Decider stimmt zu Proposed --> Verworfen: nicht weiterverfolgt Accepted --> Deprecated: Kontext obsolet Accepted --> Superseded: andere ADR ersetzt Deprecated --> [*] Superseded --> [*] Verworfen --> [*]

Status	Bedeutung	Übergang
Proposed	ADR ist geschrieben, aber noch nicht abgenommen. Entscheidung ist zur Diskussion.	Default beim Erstellen.
Accepted	Entscheidung ist getroffen und verbindlich.	Nur bei expliziter Zustimmung des Deciders ("passt", "accepted", o. ä.).
Deprecated	Entscheidung gilt nicht mehr; der Kontext ist obsolet, ohne dass eine ersetzende ADR existiert.	Manuell, mit Begründung im ADR-Body.
Superseded	Entscheidung wurde durch eine spätere ADR ersetzt.	Pflichtfeld `Superseded by: ADR-XXXX` in der Meta.

Wichtige Regel: Eine neu geschriebene ADR steht immer auf Proposed. Der Wechsel auf Accepted erfolgt erst nach expliziter Bestätigung durch den Decider — nicht durch den Autor selbst, wenn das verschiedene Personen sind. Im Falle von KI-assistierter ADR-Erstellung: die KI darf nicht eigenmächtig „Accepted" setzen.

Inhaltliche Konventionen

Sprache: Deutsch. Technische Begriffe und Eigennamen (Provider, Tools) bleiben Englisch, wo das natürlicher liest.
Stil: präzise, ohne Marketing-Sprache. Vermeide „leverage", „seamless", „best-of-breed", „state-of-the-art".
Optionen: mindestens zwei, immer mit klaren Pros & Cons. Auch verworfene Optionen verdienen Erwähnung — sie zeigen, dass die Wahl bewusst getroffen wurde.
Entscheidung: klar und ohne Wischiwaschi. „Wir wählen Option X" — kein „wir tendieren zu".
Konsequenzen: ehrlich. Auch wenn die Wahl gut begründet ist, hat sie Nachteile — die müssen drin stehen.
Verlinkung: Bezug auf andere ADRs explizit über ADR-NNNN und ggf. <a href="...">.
Diagramme: Mermaid bevorzugt (textuell, versionierbar). Externe SVGs nur, wenn Mermaid nicht ausreicht.

ADRs zurückziehen oder ersetzen

Inhaltlich falsch / nicht umgesetzt: Status auf Deprecated, Begründung im Kontext-Abschnitt ergänzt.
Durch neuere Entscheidung überholt: Status auf Superseded, Meta-Feld Superseded by: ADR-XXXX ergänzt. Die neue ADR bekommt Supersedes: ADR-YYYY.
Datei wird nicht gelöscht — der historische Pfad bleibt sichtbar.

Erstellungs-Prozess

Diskussion: Optionen und Tradeoffs werden in der Conversation oder Issue durchgesprochen.
Entwurf: ADR wird basierend auf der Diskussion geschrieben (Template als Basis).
Status: Proposed beim ersten Commit.
Review: Decider liest, gibt Feedback. Iteration falls nötig — Status bleibt Proposed.
Abnahme: Decider sagt explizit „passt" / „accepted". Status auf Accepted, Datum bei Bedarf aktualisieren, ggf. Footer-Notiz „Accepted on YYYY-MM-DD".
Pflege: bei späteren Änderungen am Kontext — Status auf Deprecated oder Superseded, je nach Lage.

Konsequenzen

Positiv

Einheitliches Erscheinungsbild aller ADRs — gut zum schnellen Querlesen.
Status-Lifecycle macht Verbindlichkeit explizit.
Format ist im Repo versioniert, ohne externes Tooling abhängig.
Direkt im Browser konsumierbar (über mvest.malte.io/adr/).

Negativ / Trade-offs

Mehr Schreibaufwand pro ADR als Markdown. Mitigation: Template + KI-Assistenz.
Keine automatische Validierung der Struktur. Mitigation: Bei Bedarf später ein Lint-Script (HTML-Struktur-Check, Pflichtfelder, eindeutige Nummer).
Format-Anpassungen erfordern Anpassungen in mehreren Files. Mitigation: zentrales Stylesheet absorbiert die meisten visuellen Änderungen.