Stefan Mogeritsch
2dc3c4154b
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.
2.3 KiB
2.3 KiB
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.mdim Root vondocs/oder indocs/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.