ARCH-2026-003 – Schlanke Architekturentscheidungsnachweise und nachvollziehbare Ablösung¶

Status: Entwurf
Proposal-Status: under_review
Kategorie: architecture
Erstellt: 2026-07-05
Stand: 2026-07-07
Geprüfter Repository-Stand: f84c881aace65ff9aa857b43fc2de4b0a7998397

Anlass¶

Der Entscheidungsbestand enthält historisch angenommene oder zurückgestellte Architecture Decision Records, deren Detailaussagen durch spätere Spezifikationen, Verträge und Implementierungen teilweise überholt wurden.

Die Dateien besitzen uneinheitliche Statusfelder, zwei konkurrierende Nummerierungsmuster und keine einheitliche Kennzeichnung ihrer heutigen Relevanz. Dadurch können historische Aussagen fälschlich als aktuelle Architektur gelesen werden.

Bestätigte Teilentscheidung 1 – Rolle und Lifecycle¶

Am 2026-07-07 wurde Variante B bestätigt:

Der Proposal-Status bleibt der einzige Workflowstatus für Änderungen.

Architecture Decision Records sind informative historische
Entscheidungsnachweise und keine aktuelle technische Wahrheit.

Eine separate ADR wird nur für bedeutende, langfristige und
domänenübergreifende Architekturentscheidungen erzeugt, grundsätzlich
nach vollständiger Integration des zugrunde liegenden Proposals.

Bestehende ADRs bleiben historisch erhalten, erhalten jedoch eindeutige
Metadaten, eine aktuelle Relevanzbewertung und Verweise auf die heute
führenden Quellen.

Diese Teilentscheidung legt die Rolle der ADRs fest. Die konkrete Metadatenstruktur, die Klassifizierung des Altbestands und die Integrationsdetails bleiben Gegenstand weiterer Einzelentscheidungen.

Ausgangsproblem¶

Der aktuelle Bestand vermischt drei unterschiedliche Dimensionen:

Dokumentstatus
  verbindlich | verbindlicher Zielentwurf | informativ | Entwurf

Workflowstatus eines Änderungsvorschlags
  new | under_review | accepted | rejected | deferred | integrated

historisches Ergebnis und heutige Relevanz einer Entscheidung
  accepted | deferred | rejected
  current | partial | historical

Bestehende ADR-Dateien verwenden Werte wie:

Status: Angenommen
Status: Accepted
Status: Deferred

Das widerspricht dem verbindlichen Dokumentationssystem, nach dem Status: ausschließlich die normative Dokumentklasse bezeichnet.

Zusätzlich existieren gleichzeitig:

ADR-001-tech-stack.md
0001-frontend-mvp-scenario-and-reporting-architecture.md

Beide wirken wie ADR 001, besitzen jedoch keine eindeutige maschinenlesbare Decision-ID.

Relevanter bestehender Stand¶

Führende Regeln:

docs/governance/documentation-system.md
  keine parallelen Wahrheiten
  ADRs sind keine führenden Spezifikationen
  Status verwendet nur definierte Dokumentklassen

docs/governance/change-control.md
  Proposal-Status ist der verbindliche Änderungsworkflow
  accepted ist noch keine produktive Wahrheit
  erst integrated bedeutet vollständig übernommen
docs/changes/decisions/index.md
  ADRs dokumentieren historischen Kontext
  führende Spezifikationen bleiben aktuelle Wahrheit
  aktuelle Einordnung wird bereits informativ gepflegt
AGENTS.md
  berücksichtigt Entscheidungen, ordnet ihre nicht führende Rolle aber noch nicht präzise ein

Bestehender Entscheidungsbestand:

docs/changes/decisions/ADR-001-tech-stack.md
docs/changes/decisions/0001-frontend-mvp-scenario-and-reporting-architecture.md
docs/changes/decisions/0002-future-private-user-accounts-and-family-workspaces.md
docs/changes/decisions/0003-future-separate-rent-estimation-page.md
docs/changes/decisions/0004-future-batch-reporting-and-data-quality.md
docs/changes/decisions/0005-future-personal-financing-profile.md
docs/changes/decisions/0006-future-admin-data-management-and-market-rent-database.md

Nachgewiesene aktuelle Architekturabweichungen¶

1. Dokumentstatus und Entscheidungsstatus sind vermischt¶

Die bestehenden ADRs verwenden Status: für historische Entscheidungsergebnisse. Der verbindliche Dokumentstatus müsste für ADRs jedoch informativ lauten.

2. Aktuelle Relevanz steht nur im Index¶

Der Entscheidungsindex enthält bereits eine gute aktuelle Einordnung. Die einzelne ADR-Datei zeigt beim direkten Öffnen jedoch nicht zuverlässig:

welche Aussagen weiterhin gelten
welche nur teilweise gelten
welche führenden Quellen heute maßgeblich sind
welche Detailaussagen abgelöst wurden

3. Keine maschinelle Absicherung¶

Der vorhandene Spezifikationskonsistenztest prüft ADR-Dateien und ADR-Index nicht systematisch.

Nicht geprüft werden unter anderem:

eindeutige Decision-ID
zulässige Metadatenwerte
vollständiger Index
existierende Führende-Quellen-Verweise
notwendige Ablösungshinweise bei historical
nicht existierende Superseded-by-Verweise

4. Zwei Nummerierungssysteme¶

Die Dateien verwenden sowohl ADR-001-* als auch 0001-*. Eine Umbenennung würde Historie und Links unnötig verändern. Ein eindeutiges neues Metadatenfeld ist daher erforderlich.

5. MkDocs unterscheidet Relevanz nicht sichtbar¶

Aktuelle, teilweise relevante, historische und zurückgestellte Entscheidungen stehen in derselben Navigationsgruppe. Der Entscheidungsindex erklärt die Einordnung, direkte ADR-Seiten jedoch nicht.

6. Bestehendes Proposal würde einen zweiten Workflow erzeugen¶

Der ursprüngliche Vorschlag sah einen ADR-Lifecycle mit:

proposed | accepted | deferred | rejected | superseded

vor. Dieser überschneidet sich stark mit dem bereits verbindlichen Proposal-Workflow.

7. Superseded ist keine historische Entscheidungsart¶

Eine Entscheidung kann historisch accepted gewesen sein und heute historical sein. superseded beschreibt deshalb heutige Relevanz oder Ablösung, nicht das ursprüngliche Entscheidungsergebnis.

8. Zeitpunkt und Pflicht einer ADR sind unklar¶

Es ist heute nicht geregelt:

wann ein integriertes Architektur-Proposal zusätzlich eine ADR erzeugt
ob jede Architekturänderung zwingend eine ADR benötigt
ob eine ADR bereits bei accepted oder erst bei integrated entsteht

9. AGENTS.md ist missverständlich¶

docs/changes/decisions/ wird dort unter weiteren führenden Grundlagen genannt. Governance und Entscheidungsindex stellen dagegen klar, dass ADRs historische Begründungsnachweise und keine parallele Wahrheit sind.

Zielprinzip¶

Ein einziger Änderungsworkflow¶

Proposal:
new
-> under_review
-> accepted | rejected | deferred
-> Integration und Prüfung
-> integrated

Es wird kein zweiter ADR-Workflow eingeführt.

ADR als historischer Nachweis¶

Eine ADR dokumentiert:

welche bedeutende Architekturentscheidung getroffen wurde
welche Alternativen betrachtet wurden
warum die Entscheidung getroffen wurde
welche Konsequenzen akzeptiert wurden
wie die Entscheidung später eingeordnet oder abgelöst wurde

Eine ADR ist:

informativ
historisch nachvollziehbar
keine aktuelle fachliche oder technische Wahrheit
kein Ersatz für Spezifikation, Vertrag, Code oder Test

Neue ADR nur bei wesentlichen Entscheidungen¶

Eine separate ADR ist empfohlen, wenn mehrere der folgenden Kriterien erfüllt sind:

langfristige Wirkung
mehrere Komponenten oder Domänen betroffen
mehrere realistische Alternativen mit relevanten Trade-offs
schwer oder teuer rückgängig zu machen
später voraussichtlich erneut zu hinterfragen
wichtig für das Verständnis der Gesamtarchitektur

Keine automatische ADR-Pflicht besteht für:

lokale Modulzuordnung
kleine Renderer- oder Dateistrukturentscheidung
mechanischen Refactor
Korrektur zur Wiederherstellung einer bestehenden Regel
rein redaktionelle Architekturpräzisierung

Zeitpunkt einer neuen ADR¶

Neue ADRs werden grundsätzlich erst nach vollständiger Integration erstellt oder finalisiert:

under_review
  Proposal enthält Prüfung und Optionen

accepted
  Proposal enthält die getroffene Entscheidung und offene Integration

integrated
  führende Dokumente, Code und Tests sind synchron
  bei wesentlicher Entscheidung kann eine ADR als historischer Nachweis erstellt werden

Eine vorläufige ADR vor integrated ist nur zulässig, wenn sie eindeutig als Entwurf außerhalb des Entscheidungsbestands geführt wird. Für den normalen Immohai-Prozess ist dies nicht vorgesehen.

Vorgeschlagenes Metadatenmodell¶

Für bestehende und neue ADRs wird folgende Richtung vorgeschlagen:

Status: informativ
Dokumenttyp: Architecture Decision Record
Decision-ID: eindeutig
Entscheidungsergebnis: accepted | deferred | rejected
Entschieden: YYYY-MM-DD
Zuletzt-geprüft: YYYY-MM-DD
Aktuelle-Relevanz: current | partial | historical
Führende-Quellen:
  - Pfad
  - Pfad
Supersedes: optional
Superseded-by: optional
Ursprungs-Proposal: optional
Integrationsreferenz: optional

Bedeutungen¶

Entscheidungsergebnis
  beschreibt das historische Ergebnis zum Entscheidungszeitpunkt

Aktuelle-Relevanz
  current:
    Kernaussage und relevante Details weiterhin nutzbar

  partial:
    Grundentscheidung bleibt relevant, einzelne Details sind überholt

  historical:
    Entscheidung dient nur noch als historischer Kontext

Superseded-by
  verweist auf eine nachfolgende ADR oder eine dokumentierte Ersatzentscheidung

Führende-Quellen
  nennt die heute verbindlichen Dokumente des betroffenen Themas

Regel für historical¶

Bei Aktuelle-Relevanz: historical ist mindestens erforderlich:

Superseded-by
oder
klarer Ablösungshinweis mit führender Ersatzquelle

Regel für partial¶

Bei Aktuelle-Relevanz: partial ist ein sichtbarer Hinweisblock erforderlich:

welcher Grundsatz weiter gilt
welche Detailaussagen nicht mehr verwendet werden dürfen
welche führenden Quellen heute maßgeblich sind

Eindeutige Decision-IDs und Dateinamen¶

Bestehende Dateien werden nicht umbenannt.

Empfohlene eindeutige IDs für den Altbestand:

ADR-001-tech-stack
ADR-0001-frontend-mvp
ADR-0002-private-user-accounts
ADR-0003-rent-estimation-page
ADR-0004-batch-reporting-data-quality
ADR-0005-personal-financing-profile
ADR-0006-admin-market-rent-data

Für neue ADRs soll ein einheitliches Muster entschieden werden. Empfohlene Richtung:

ADR-YYYY-NNN-<slug>.md
Decision-ID: ADR-YYYY-NNN-<slug>

Die bestehenden Nummern werden nicht nachträglich in dieses Muster migriert.

Vorläufige Klassifizierung des Altbestands¶

Die endgültige Klassifizierung bleibt eine eigene Entscheidung. Nach aktuellem Audit ist folgende Richtung plausibel:

Datei	historisches Ergebnis	vorläufige Relevanz
`ADR-001-tech-stack.md`	accepted	partial
`0001-frontend-mvp-scenario-and-reporting-architecture.md`	accepted	partial
`0002-future-private-user-accounts-and-family-workspaces.md`	deferred	partial
`0003-future-separate-rent-estimation-page.md`	deferred	partial
`0004-future-batch-reporting-and-data-quality.md`	accepted	partial
`0005-future-personal-financing-profile.md`	deferred	current
`0006-future-admin-data-management-and-market-rent-database.md`	accepted	partial

Wesentliches Prüfergebnis:

Derzeit ist keine gesamte ADR eindeutig vollständig historical.
Mehrere ADRs besitzen weiterhin gültige Grundentscheidungen,
aber überholte Detailaussagen.

Eine vollständige Ablösung darf deshalb nicht allein aufgrund einzelner veralteter Details gesetzt werden.

Sichtbarer Aktualitätshinweis in jeder ADR¶

Jede ADR soll vor dem historischen Inhalt einen kompakten Hinweisblock erhalten:

Diese Datei dokumentiert eine historische Architekturentscheidung.
Die aktuelle verbindliche Architektur steht in den unter
„Führende Quellen“ genannten Dokumenten.

Aktuelle Relevanz: partial
Weiterhin gültig: ...
Nicht mehr aktuell: ...

Der historische Haupttext bleibt unverändert. Er wird nicht nachträglich auf aktuelle Feldnamen oder Module umgeschrieben.

Der Index bleibt die zentrale Übersicht und soll mindestens enthalten:

Decision-ID
Datei
Titel
historisches Ergebnis
aktuelle Relevanz
Ursprungs-Proposal optional
Nachfolger oder Ablösung optional
führende Quellen

MkDocs soll deutlich machen, dass Decisions historische Entscheidungsnachweise enthält. Eine zusätzliche Gruppierung nach current, partial und historical ist optional und darf nicht zur manuellen Doppelpflege führen.

Konsistenzprüfung¶

Geltungsbereich¶

ARCH-2026-003 umfasst:

Rolle von ADRs im Immohai-Dokumentationssystem
Metadatenmodell
historisches Entscheidungsergebnis
aktuelle Relevanz
Ablösungs- und Nachfolgerverweise
Kriterien für neue ADRs
Zeitpunkt der ADR-Erstellung
Klassifizierung des Altbestands
Entscheidungsindex
MkDocs-Kennzeichnung
Konsistenztest
Präzisierung in AGENTS.md

Nicht Teil dieses Proposals:

Änderung der inhaltlichen Architekturentscheidungen selbst
Änderung von Formeln, KPIs oder Datenverträgen
Umbenennung bestehender ADR-Dateien
Löschen historischer Entscheidungen
automatische Erzeugung von ADRs aus Proposals
allgemeine ADR-Regeln für andere Projekte

Allgemeine projektübergreifende ADR-Anleitungen gehören in das Developer Playbook.

Weitere offene Einzelentscheidungen¶

2. Exakte Metadatenfelder
   Welche Felder sind required, optional und wiederholbar?

3. Decision-ID und Dateimuster
   Welches Muster gilt für neue ADRs?

4. Kriterien für ADR-Pflicht
   Reicht eine Empfehlung oder werden verbindliche Schwellen definiert?

5. Klassifizierung des Altbestands
   Welche ADR ist current, partial oder historical?

6. Hinweisblock und Führende Quellen
   Welche Mindeststruktur erhält jede ADR?

7. Index und MkDocs
   Welche Felder zeigt der Index, ohne doppelte Wahrheit zu erzeugen?

8. Konsistenztest
   Welche Fehler blockieren CI, welche erzeugen nur Hinweise?

9. Verhältnis zu integriertem Proposal
   Welche Inhalte bleiben nur im Proposal, welche werden in eine ADR verdichtet?

Entscheidungsmehrwert¶

keine Verwechslung zwischen historischem Kontext und aktueller Wahrheit
kein zweiter Workflow neben dem Proposal-Prozess
klare und geringe Pflegekosten
eindeutige Decision-IDs trotz bestehender Dateinamen
nachvollziehbare Teilablösung ohne Umschreiben historischer Texte
klare Verbindung zwischen Proposal, Integration, ADR und Spezifikation
maschinell prüfbarer Entscheidungsbestand

Auswirkungen auf Architektur, Roadmap und Spezifikation¶

Architektur:

keine Änderung des technischen Systems
Änderung des Architekturentscheidungsprozesses und seiner Dokumentation

Roadmap:

keine Produktprioritätsänderung
einmaliger Pflegeblock für den Altbestand
kleiner dauerhafter Pflegeaufwand bei wesentlichen Architekturentscheidungen

Spezifikation:

keine fachliche Regeländerung
Governance und Dokumentationssystem werden nach Annahme präzisiert
AGENTS.md wird an die führende Governance angepasst

Auswirkungen auf Formeln, KPIs und Datenverträge¶

keine Änderung
keine Schema- oder Modellversion
keine Engine-Version

Dokumentversionen der betroffenen Governance- und Indexdateien sind bei Integration zu erhöhen.

Auswirkungen auf UI, Reporting und Speicherung¶

keine produktive Auswirkung
keine Änderung gespeicherter Daten
nur Dokumentationsnavigation und historische Einordnung betroffen

Legacy- und Migrationsfolgen¶

bestehende Dateien bleiben an ihren Pfaden
historische Haupttexte bleiben erhalten
Metadaten und Aktualitätshinweise werden ergänzt
Index wird synchronisiert
keine inhaltliche Aktualisierung alter ADRs auf heutige Architektur
keine rückwirkende Erzeugung fehlender Proposals

Risikoanalyse¶

Proposal-Aktualisierung:

niedrig

Spätere Dokumentationsintegration:

niedrig bis mittel

Produkt- und Laufzeitrisiko:

sehr niedrig

Hauptrisiken:

falsche Einstufung als current, partial oder historical
zu viele ADRs und unnötige Doppelpflege
widersprüchliche Angaben zwischen ADR und Index
gebrochene Verweise
historische Texte werden versehentlich inhaltlich umgeschrieben
zukünftige Assistenten verwenden alte Details als aktuelle Vorgabe

Diese Risiken werden durch schlanke Metadaten, führende Quellen und einen dedizierten Konsistenztest begrenzt.

Sicherungs- und Rückfallstrategie¶

Vor Integration:

aktuellen main-Commit festhalten
Dokumentationsbuild und Contract Check nachweisen
separaten Integrationsbranch verwenden
vollständige Liste aller bestehenden ADR-Pfade sichern
bestehende Links und MkDocs-Navigation prüfen

Da keine produktiven Daten oder Berechnungen betroffen sind, genügt Git als Rückfallmechanismus. Jede ADR-Datei soll in einem kleinen, einzeln prüfbaren Commit aktualisiert werden.

Empfohlene Umsetzungsstruktur nach vollständiger Annahme¶

Phase 0
  Metadaten und Klassifizierungsregeln final entscheiden

Phase 1
  Governance, AGENTS.md und Decision-Index aktualisieren
  check-decision-records.mjs einführen

Phase 2
  ADR-Dateien einzeln klassifizieren
  Metadaten und Aktualitätshinweise ergänzen

Phase 3
  MkDocs und Querverweise synchronisieren
  Dokumentationsbuild und Contract Check

Phase 4
  Proposal auf integrated setzen
  Integrationscommit dokumentieren

Prüfergebnis¶

Die ursprüngliche Problemfeststellung ist bestätigt. Der Entscheidungsbestand benötigt eine explizite aktuelle Einordnung in jeder Einzeldatei und eine maschinelle Konsistenzprüfung.

Der ursprünglich vorgeschlagene eigenständige ADR-Lifecycle wäre jedoch unnötig komplex und würde den Proposal-Prozess teilweise duplizieren.

Die schlanke Variante ist geeigneter:

Proposal steuert Änderungen.
Führende Spezifikationen definieren aktuelle Wahrheit.
ADR dokumentiert bedeutende historische Entscheidung und Ablösung.

Entscheidung¶

Teilentscheidung 1 am 2026-07-07 bestätigt:

Variante B – schlanke historische Decision Records ohne eigenen Workflow.
Der Proposal-Status bleibt der einzige Änderungsworkflow.
Neue ADRs entstehen nur für bedeutende Architekturentscheidungen,
grundsätzlich nach vollständiger Integration.

Gesamtentscheidung: offen
Proposal-Status: under_review

Zieldokumente bei späterer Annahme¶

AGENTS.md
docs/governance/documentation-system.md
docs/governance/change-control.md
docs/changes/decisions/index.md
docs/changes/decisions/*.md
scripts/check-decision-records.mjs
package.json oder Contract-Check-Einstieg
mkdocs.yml

Integrationscommit¶

offen