docs: consolidate roadmaps and update architecture documentation

Replaced fragmented roadmaps with a single MASTER_ROADMAP for Q1 2026 as the authoritative source. Deprecated outdated roadmap files and updated Architect playbook to reflect new ownership and delegation responsibilities. Introduced architecture improvement proposals and added related documents for enhanced collaboration and knowledge sharing.
2026-01-16 10:42:34 +01:00
parent 4b9772ff6b
commit 2dc3c4154b
9 changed files with 259 additions and 82 deletions
@@ -0,0 +1,37 @@
+# Vorschläge zur Verbesserung der Dokumentations- und Roadmap-Struktur
+**Von:** Lead Software Architect
+**An:** Documentation & Knowledge Curator
+
+Um die Fragmentierung der Dokumentation zu vermeiden und die Zusammenarbeit der Agenten zu optimieren, schlage ich folgende Strukturverbesserungen vor:
+
+## 1. Roadmap-Hierarchie ("Single Source of Truth")
+Aktuell entstehen oft parallele Roadmaps in Unterordnern (z.B. `05_Backend/ROADMAP.md`). Das führt zu Verwirrung.
+
+**Vorschlag:**
+*   Es gibt nur **eine** `MASTER_ROADMAP.md` im Root von `docs/` oder in `docs/01_Architecture/`.
+*   Diese Roadmap ist **phasenorientiert** (nicht komponentenorientiert).
+*   Jede Phase enthält Sektionen für die jeweiligen Rollen (Backend, Frontend, DevOps, QA).
+*   Detail-Roadmaps in Unterordnern sind verboten oder müssen strikt als "Detail-Spezifikation" eines Master-Items gekennzeichnet sein.
+
+## 2. "Living Architecture" Dokumentation
+Architektur-Diagramme und Entscheidungen veralten schnell.
+
+**Vorschlag:**
+*   **ADRs (Architecture Decision Records):** Jede größere Entscheidung (z.B. "Wechsel auf SQLDelight") muss zwingend als ADR in `docs/01_Architecture/decisions/` festgehalten werden. Das Format ist strikt: *Kontext, Entscheidung, Konsequenzen*.
+*   **System-Metapher:** Wir sollten eine zentrale Metapher oder ein Glossar pflegen, das vom Domain Expert validiert wird, damit "Ping", "Meldung", "Fall" überall gleich verstanden werden.
+
+## 3. Agent-Interaktion
+Damit ich als Architect nicht "alles mache", müssen die Schnittstellen zwischen den Agenten klarer definiert sein.
+
+**Vorschlag:**
+*   **Handover-Protokolle:** Wenn ich eine Architektur-Vorgabe mache (z.B. "Nutze UUIDv7"), muss ich ein Ticket/Issue/Task in der Roadmap definieren, das der Backend Developer dann *eigenverantwortlich* umsetzt.
+*   **Review-Pflicht:** Der QA Specialist sollte explizit angefordert werden, *bevor* eine Phase als "Done" markiert wird.
+
+## 4. Build-System als Dokumentation
+Die `libs.versions.toml` ist faktisch unsere Dokumentation des Tech-Stacks.
+
+**Vorschlag:**
+*   Kommentare in der TOML-Datei sollten erklären, *warum* eine Version gewählt wurde (z.B. "# Downgrade wegen Spring Cloud Inkompatibilität"). Das habe ich bereits begonnen, sollte aber Standard werden.
+
+---
+Bitte prüfe diese Vorschläge und integriere sie in dein Playbook oder die Dokumentations-Richtlinien.