Änderungsprozess für Architektur, Spezifikationen und Roadmap¶
Status: verbindlich
Spezifikationsversion: 1.2.0
Stand: 2026-07-05
1. Zweck¶
Dieser Prozess schützt die fachliche und technische Wahrheit sowie die verbindliche Roadmap während der Entwicklung. Neue Ideen, Korrekturen und Prioritätsänderungen werden zuerst als nicht verbindliche Einzelvorschläge erfasst und erst nach Prüfung und dokumentierter Entscheidung übernommen.
2. Verbindliche und nicht verbindliche Bereiche¶
Verbindliche Architektur:
führende Architekturentwürfe unter docs/specification/architecture/
Verbindliche Spezifikationen:
docs/calculations/model-specification.md
führende Dokumente unter docs/specification/
maschinenlesbare Verträge nach erfolgreicher Synchronisation
Verbindliche Roadmap:
docs/roadmap/roadmap.md
Nicht verbindliche Vorschläge:
docs/changes/proposals/architecture/
docs/changes/proposals/roadmap/
docs/changes/proposals/specification/
Die Eigentümerschaft je Thema ist in docs/governance/documentation-system.md festgelegt.
3. Proposal-Kategorien und Dateinamen¶
Architektur:
docs/changes/proposals/architecture/ARCH-YYYY-NNN-<slug>.md
Roadmap:
docs/changes/proposals/roadmap/ROAD-YYYY-NNN-<slug>.md
Spezifikation:
docs/changes/proposals/specification/SPEC-YYYY-NNN-<slug>.md
Jeder unabhängige Vorschlag besitzt eine eigene Datei und eine eindeutige ID. Die nächste ID wird anhand der bereits vorhandenen Dateien derselben Kategorie bestimmt.
4. Zwei Arbeitsstufen¶
4.1 Erfassung¶
Eine neue konkrete Idee wird zunächst mit Status new erfasst. Vor der Erfassung wird nur der betroffene bestehende Architektur-, Roadmap- und Spezifikationsstand betrachtet. Vorhandene Proposals und Entscheidungen zum gleichen Thema werden ebenfalls berücksichtigt.
Diese begrenzte Kontextprüfung dient der Einordnung, der Wahl der richtigen Kategorie und der Vermeidung offensichtlicher Dubletten. Sie ist keine vollständige Vertrags-, Implementierungs- oder Regressionprüfung.
Die Erfassung verändert keine verbindliche Architektur, Roadmap, Spezifikation, kein Schema, keine Konfiguration, keine Implementierung und keinen Test.
4.2 Prüfung und Integration¶
Die vollständige Prüfung beginnt mit der beabsichtigten Bewertung, Entscheidung, Annahme, Integration oder Umsetzung eines Proposals. Erst in dieser Stufe werden alle betroffenen Verträge, Implementierungen, Tests, Versionen und Migrationsfolgen untersucht.
5. Proposal-Status¶
new
under_review
accepted
rejected
deferred
integrated
Bedeutung:
new:
erfasst, noch nicht vollständig geprüft
under_review:
wird gegen den verbindlichen Stand und die Implementierung geprüft
accepted:
fachlich oder technisch entschieden, aber noch nicht vollständig integriert
rejected:
wird nicht übernommen
deferred:
bewusst zurückgestellt
integrated:
in alle betroffenen verbindlichen Artefakte übernommen und geprüft
6. Pflichtangaben eines Proposals¶
proposal_id
title
created_at
status
category
Anlass
Ausgangsproblem
relevanter bestehender Stand
betroffene führende Dokumente
vorgeschlagene Änderung
Entscheidungsmehrwert
Auswirkungen auf Architektur, Roadmap und Spezifikation
Auswirkungen auf Formeln und KPIs
Auswirkungen auf Datenverträge und Versionen
Auswirkungen auf UI, Reporting und Speicherung
Auswirkungen auf Tests und Referenzfälle
Legacy- und Migrationsfolgen
Risiken und offene Fragen
Prüfergebnis
Entscheidung
Zieldokumente
Integrationscommit
Bei der ersten Erfassung dürfen noch nicht bekannte Prüffelder ausdrücklich als offen markiert werden.
7. Prüfung eines Proposals¶
Vor einer Annahme wird der Vorschlag geprüft gegen:
1. Governance, fachliche Wahrheit und Modellgrenzen
2. bestehende Architektur und Verantwortungsgrenzen
3. bestehende Roadmap, Abhängigkeiten und MVP-Grenzen
4. Begriffe, Feldnamen, Datenmodell und Schnittstellen
5. Schemas und Modellkonfiguration
6. aktuelle Implementierung
7. gespeicherte Snapshots und Legacy-Kompatibilität
8. Datenqualität, Rating und Reporting
9. Regressionstests und Referenzfälle
10. Versionierungsbedarf
Das Prüfergebnis nennt Widersprüche, notwendige Folgeänderungen und offene Entscheidungen ausdrücklich.
8. Übernahme eines Proposals¶
1. Status under_review
2. Prüfung gegen den bestehenden Stand
3. dokumentierte Entscheidung
4. bei Annahme Status accepted
5. Aktualisierung der führenden Zieldokumente
6. Synchronisation aller Querverweise
7. Anpassung von Schemas und Konfiguration
8. Anpassung von Implementierung und Tests
9. Aktualisierung von Reporting, Roadmap und Arbeitsstand
10. Dokumentationsbuild und Regressionen
11. Review und gegebenenfalls Browserabnahme
12. Status integrated und Eintrag des Integrationscommits
Ein accepted-Proposal ist noch keine produktive Wahrheit. Verbindlich wird die Änderung erst nach vollständiger Integration.
9. Ausnahmen ohne Proposal¶
Kein neues Proposal entsteht bei:
reinen Verständnisfragen
Recherche ohne gewünschten Projektwechsel
redaktionellen oder mechanischen Korrekturen ohne Bedeutungsänderung
Fehlerbehebungen, die ausschließlich eine bereits verbindliche Regel wiederherstellen
Eine Änderung mit fachlicher, technischer oder priorisierender Bedeutungsänderung fällt nicht unter diese Ausnahme. Bei unklarer Abgrenzung wird sie als Proposal behandelt.
10. Versionsregeln¶
redaktionelle Klarstellung ohne Vertragsänderung:
Spezifikationsversion erhöhen
Änderung von Formeln, Ratingregeln oder fachlicher Semantik:
Modellversion prüfen und gegebenenfalls erhöhen
Änderung eines Datenvertrags:
betroffene Schemaversion erhöhen
Änderung einer Datenqualitätsmethode:
Methodenversion erhöhen
Änderung der Berechnungsimplementierung:
Engine-Version erhöhen
Versionen werden nicht erhöht, ohne Manifest, Dokumentation, Fixtures und Tests synchron zu aktualisieren.
11. Fixierter Stand¶
Ein Stand gilt als fixiert, wenn:
führende Dokumente widerspruchsfrei sind
keine offene Entscheidung als verbindliche Regel formuliert ist
Querverweise konsistent sind
maschinenlesbare Verträge synchron sind
Regressionen erfolgreich sind
Dokumentationsbuild erfolgreich ist
Browserabnahme erfolgt ist, soweit UI betroffen ist
Review abgeschlossen ist
Fixiert bedeutet nicht unveränderlich. Spätere Änderungen durchlaufen erneut diesen Prozess.
12. Verbot stiller Änderungen¶
Nicht zulässig:
Änderung nur im Code
Änderung nur in UI oder Report
direkte Umsetzung eines new- oder under_review-Proposals
stille Aktualisierung alter PropertyRecords
stille Änderung von Defaults oder Schwellen
Architektur- oder Roadmap-Änderung ohne dokumentierte Entscheidung