MADR

Details
Vollständiger Name

Markdown Architectural Decision Records

Kernkonzepte:

Strukturiertes Template

Wohldefiniertes Format mit spezifischen Abschnitten

Standardfelder

  • Titel (kurze Nominalphrase)

  • Status (vorgeschlagen, akzeptiert, abgelehnt, veraltet, ersetzt)

  • Kontext und Problemstellung

  • Entscheidungstreiber (Kräfte, die die Entscheidung beeinflussen)

  • Betrachtete Optionen (bewertete Alternativen)

  • Entscheidungsergebnis (gewählte Option mit Begründung)

  • Vor- und Nachteile der Optionen (Trade-off-Analyse)

  • Links (verwandte Entscheidungen, Referenzen)

Markdown-Format

Nutzt Standard-Markdown für breite Kompatibilität

Klare Struktur

Detaillierter als einfache ADRs, enthält explizite Alternativen

Trade-off-Dokumentation

Erfasst explizit Vor-/Nachteile jeder Option

Versionskontrolle

Mit Code gespeichert, unveränderlich wie andere ADRs

Leichtgewichtig und dennoch umfassend

Balanciert Vollständigkeit mit Wartbarkeit

Schlüsselvertreter

Oliver Kopp, Olaf Zimmermann (und MADR-Community)

Referenz

https://adr.github.io/madr/

Wann zu verwenden:

  • Wenn mehr Struktur als bei einfachen ADRs benötigt wird

  • Projekte, die explizite Dokumentation von Alternativen erfordern

  • Teams, die Entscheidungen mit detaillierten Trade-offs rechtfertigen müssen

  • Organisationen mit Markdown-basierten Dokumentations-Workflows

  • Wenn LLM-Unterstützung zur Generierung konsistenter Entscheidungsaufzeichnungen benötigt wird

  • Ergänzung zu arc42 Abschnitt 9 (Architekturentscheidungen)

Aktueller Stand:

  • Die aktuelle Version ist MADR 4.0.0 (September 2024). Der Name änderte sich unterwegs zweimal: MADR 3.x (2022) benannte „Markdown Architectural Decision Records" in „Markdown Any Decision Records" um; 4.0 benannte zurück — das Template bleibt für beliebige Entscheidungen nutzbar

  • Der Trainingsdaten-Prior eines LLM reproduziert höchstwahrscheinlich das Format der 2.x-Ära (2018–2022, die langlebigste und meistkopierte Variante): Inline-Bullets * Status: / * Deciders: / * Date: und getrennte „Positive/Negative Consequences"-Abschnitte — statt des aktuellen YAML-Front-Matter mit decision-makers, dem zusammengelegten „Consequences"-Abschnitt und dem in 3.x/4.x eingeführten „Confirmation"-Element

  • Wenn das exakte Format zählt: dem Modell das aktuelle Template zeigen oder in den Prompt einfügen — der Ankername aktiviert zuverlässig das Konzept, aber nicht den aktuellen Feldsatz