Mono-Repository

Ausgelagerte Dokumentation erzeugt Kontextverlust

Klassische Dokumentationssoftware hat ihre Stärken, aber produktnahe, architekturnahe und entwicklungsnahe Dokumentation steht dort oft außerhalb des Änderungsflusses: Code wird in Branches geändert, reviewed und getestet, während die Wiki-Seite daneben langsam veraltet. Für Menschen ist das nervig; für KI ist es Gift, weil ein Agent ohne aktuellen Repository-Kontext nicht sauber erkennen kann, ob eine Regel noch gilt, eine Abweichung bewusst ist oder eine Dokumentation schlicht vergessen wurde.

Das Mono-Repository als gemeinsamer Arbeitsraum

Ein Mono-Repository schafft eine einfache, aber mächtige Voraussetzung: zusammengehörige Dinge liegen zusammen. Backend, Frontends, Infrastruktur, Tests, Workflows und Dokumentation teilen denselben Ort und werden damit nicht als getrennte Inseln behandelt. Eine Architekturentscheidung, eine API-Änderung und die passende Dokumentation können im selben Pull Request sichtbar werden. Genau diese Nähe macht das Repository zum Arbeitsraum: Menschen reviewen nicht nur Code, und KI-Agenten sehen nicht nur Dateien, sondern Absicht, Historie und Qualitätsregeln im Zusammenhang.

Warum gerade /docs?

Ein gutes /docs-Verzeichnis ist keine Müllhalde für Markdown-Dateien. Es ist eine Landkarte des Systems. Die Ordnerstruktur entscheidet darüber, ob Menschen und KI schnell verstehen, welche Art von Wissen wo liegt. Eine Struktur kann zum Beispiel so aussehen:

Diese Beispielstruktur ist keine Dekoration. Sie trennt unterschiedliche Arten von Wissen so, dass sie nicht gegeneinander verschwimmen. Produktkontext, fachliche Regeln, Domäne, Architektur, Engineering-Regeln und konkrete Feature-Spezifikationen haben jeweils ihren eigenen Ort. Genau dadurch wird das Verzeichnis für Menschen lesbar und für KI maschinell verwertbar.

product beschreibt den Produktkontext. Dazu gehören Vision, Glossar und Accessibility-Vorgaben. Für Menschen beantwortet dieser Bereich die Frage: Wofür bauen wir das eigentlich? Für KI beantwortet er eine andere, mindestens genauso wichtige Frage: Welche Begriffe, Ziele und Nutzererwartungen darf ich nicht frei erfinden? Gerade ein Glossar ist für KI wertvoll, weil es Fachsprache stabilisiert. Wenn ein Begriff im Produkt eine konkrete Bedeutung hat, sollte die KI diese Bedeutung nicht aus Trainingsdaten erraten müssen.

requirements sammelt Anforderungen und Business-Regeln. Das ist der Bereich, der verhindert, dass Implementierung nur technisch korrekt, aber fachlich falsch ist. Eine KI kann eine Validierung sehr schnell schreiben. Ob diese Validierung zur fachlichen Regel passt, weiß sie nur, wenn die Regel auffindbar ist. Anforderungen im Repository machen fachliche Wahrheit anschlussfähig an Code, Tests und Reviews.

domain beschreibt das Domänenmodell und seine Invarianten. Das ist der Teil, den viele Teams unterschätzen. Code zeigt, was heute implementiert ist. Die Domänendokumentation erklärt, welche Begriffe, Beziehungen und Grenzen bedeutsam sind. Für KI ist das ein massiver Unterschied. Ohne Domänenkontext optimiert sie gern lokal: ein Feld hier, eine Methode dort, ein schneller Fix. Mit Domänenkontext kann sie besser erkennen, welche Änderung fachlich in den Kern greift und welche nur technische Oberfläche ist.

architecture ist das Entscheidungsarchiv. Kontext, Container, Komponenten, API-Design und Architecture Decision Records zeigen, warum das System so geschnitten ist, wie es ist. ADRs sind besonders wichtig, weil sie nicht nur das Ergebnis dokumentieren, sondern auch verworfene Optionen und akzeptierte Trade-offs. Eine KI, die ADRs lesen kann, muss alte Debatten nicht ungewollt neu starten. Sie kann erkennen: Diese Entscheidung war bewusst. Diese Grenze ist Absicht. Dieser Kompromiss hat Gründe.

engineering beschreibt die Arbeitsweise. Coding Guidelines, Testing Strategy, Security Guidelines, Naming Conventions, Lessons, Workflows sowie Definition of Ready und Definition of Done sind keine bürokratischen Schmuckstücke. Sie sind die Betriebsanleitung für Qualität. Für Entwicklerinnen und Entwickler machen sie Erwartungen explizit. Für KI-Agenten sind sie die Regeln, nach denen Vorschläge geplant, umgesetzt und validiert werden sollen. Eine KI, die weiß, welche Tests erwartet werden, welche Sicherheitsregeln gelten und wie Fehlerbehandlung aussehen soll, liefert weniger Zufall und mehr Teamstandard.

features ist der Ort für konkrete Feature-Spezifikation. Ein gutes Feature hat eine Übersicht, Use Cases, User Stories und bei API-Änderungen eine API-Planung. Das ist perfekte Nahrung für KI-gestützte Entwicklung. Bevor ein Agent Code ändert, kann er die Feature-Dokumente lesen und daraus ableiten: Welche Akteure gibt es? Was ist der Erfolgspfad? Welche Alternativ- und Fehlerfälle sind relevant? Welche Schnittstellen sind betroffen? Dadurch wird die KI nicht nur schneller, sondern auch weniger beliebig.

tasks dokumentiert Aufgaben und Umsetzungshistorie. Nicht jede Aufgabe ist ein großes Feature. Manche Arbeiten sind technische Verbesserungen, Nachschärfungen oder Infrastrukturthemen. Wenn solche Aufgaben dokumentiert werden, entsteht ein nachvollziehbarer Verlauf. KI kann daraus lernen, welche Art von Änderungen bereits gemacht wurden und welche Muster im Team üblich sind.

todos und misc dürfen existieren, aber man sollte ehrlich mit ihnen sein. Sie sind pragmatische Sammelbereiche, nicht das Ideal. Ein misc-Ordner ist nützlich für Material, das noch keinen besseren Ort hat oder bewusst übergangsweise abgelegt wird. Aber er sollte nicht zur Ausrede werden, alles Unklare dort zu parken. Je strukturierter /docs ist, desto besser können Menschen und KI den Inhalt nutzen.

/docs ist Kontext, den KI wirklich verwenden kann

Viele Teams behandeln KI-Assistenten wie bessere Autocomplete-Werkzeuge; der eigentliche Hebel entsteht aber erst, wenn KI Aufgaben mit Systemverständnis bearbeitet. Dafür braucht sie strukturierte, aktuelle und code-nahe Informationen: Anforderungen, Domänenregeln, ADRs, API-Konventionen, Engineering-Regeln und Feature-Spezifikationen. Ein Agent kann diese Dokumente vor einer Umsetzung lesen, daraus einen Plan ableiten, Risiken markieren und während der Implementierung gegen dokumentierte Absichten prüfen. Ein versioniertes /docs-Verzeichnis ist deshalb kein Anhang, sondern ein stabiler, adressierbarer Arbeitskontext.

Workflows machen gute Gewohnheiten wiederholbar

Der Ordner docs/engineering ist deshalb so wichtig, weil dort nicht nur Regeln stehen, sondern Arbeitsabläufe. Task, Feature, Preparation, Bugfix und Documentation können jeweils einen eigenen Workflow haben, der beschreibt, was vor dem Planen geprüft wird, wann KI kritisch nachfragen soll, welche Dokumente relevant sind, wann Tests oder Builds nötig werden und was am Ende berichtet werden muss. Dadurch hängt Qualität nicht mehr davon ab, ob jemand zufällig an alle Schritte denkt.

Für das Team ist das entlastend. Neue Teammitglieder müssen nicht erraten, wie ein Bugfix anders läuft als ein Feature oder warum eine Preparation noch keinen Runtime-Code anfassen soll. Erfahrene Teammitglieder müssen weniger Prozesswissen im Kopf behalten. Und KI-Agenten bekommen einen klaren Ablauf, an dem sie sich orientieren können, statt bei jeder Aufgabe frei zu improvisieren.

Der unterschätzte Punkt ist: Workflows selbst werden damit approvable. Wenn ein Team seinen Feature-Prozess ändern will, passiert das nicht mündlich in einem Meeting und verschwindet danach im Nebel, sondern als Änderung an docs/engineering. Diese Änderung kann reviewed, kommentiert, approved und mit Historie versehen werden. So wird nicht nur Code gemeinsam verbessert, sondern auch die Art, wie das Team arbeitet.

Preparation und Feature: zwei Stufen statt Anforderungsnebel

Besonders stark wird das, wenn Anforderungen und Implementierung bewusst in zwei Stufen getrennt werden. Ein preparation-Workflow verändert noch kein Runtime-Verhalten, sondern bereitet ein Feature so vor, dass es später wirklich implementierbar ist: Ziel, Akteure, betroffene Apps, Erfolgspfad, Alternativpfade, Fehlerfälle, Einschränkungen, offene Fragen und bei Bedarf API-Annahmen landen strukturiert unter docs/features/<ticket>_<slug>/. Das ist die Stelle, an der ein Team die Frage beantwortet: Verstehen wir überhaupt, was gebaut werden soll?

Eine der größten Stärken dieses Preparation-Schritts ist der eingebaute grill-me-Moment der KI. Der Agent soll nicht brav mitschreiben, sondern den Plan stressen: Sind die Akteure klar? Fehlen Alternativpfade? Ist der Fehlerfall beschrieben? Ist das API nur geraten? Gibt es offene Fragen, die vor der Implementierung geklärt werden müssen? Genau dieses kontrollierte Grillen macht aus einem vagen Ticket eine belastbare Spezifikation.

Noch besser: Das Ergebnis der Preparation landet nicht heimlich irgendwo im Wiki, sondern als Pull Request im Repository. Dieser Pull Request muss reviewed und approved werden, bevor der eigentliche feature-Workflow starten darf. Das Approval ist kein bürokratischer Stempel, sondern ein fachliches und technisches Gate: Das Team bestätigt, dass die Anforderungen verstanden, dokumentiert und bereit für die Umsetzung sind.

Der feature-Workflow kommt danach. Er behandelt die vorbereitete Feature-Dokumentation als Quelle der Wahrheit und prüft vor der Umsetzung, ob sie vollständig genug ist. Erst dann geht es an Code, Tests, Validierung, Accessibility, Security, Kompatibilität und Definition of Done. Dieses zweistufige System funktioniert, weil es zwei sehr unterschiedliche Denkmodi trennt: erst Problem und Anforderungen klären, danach Lösung bauen und absichern.

Für KI ist diese Trennung Gold wert. In der Preparation-Phase kann ein Agent Lücken finden, unklare Akteure markieren, fehlende Fehlerfälle vorschlagen und API-Fragen sichtbar machen. In der Feature-Phase kann derselbe Agent die approved Anforderungen gegen den Code halten, passende Tests ableiten und erkennen, ob die Implementierung vom vorbereiteten Pfad abweicht. Das verhindert den Klassiker: Ein Ticket klingt klar, der Code wird gebaut, und erst im Review merkt jemand, dass alle etwas anderes verstanden haben.

KI kann Dokumentation nicht nur lesen, sondern pflegen

Der zweite Hebel wird oft übersehen: Wenn Dokumentation im Repository liegt, kann KI sie nicht nur konsumieren, sondern aktiv aktualisieren. Das ist ein massiver Unterschied zu ausgelagerten Wissensinseln.

Nach einer Codeänderung kann ein Agent prüfen, ob passende Dokumente betroffen sind. Ändert sich eine API, kann er die Feature- oder API-Dokumentation aktualisieren. Wird eine fachliche Regel im Code sichtbar, die noch nicht sauber beschrieben ist, kann er einen Dokumentationsvorschlag machen. Wird ein Testfall ergänzt, kann er erkennen, ob dadurch eine neue Annahme dokumentiert werden sollte.

Das bedeutet nicht, dass KI ungeprüft Dokumentation schreiben sollte. Im Gegenteil: Gerade weil Dokumentation im Repository liegt, wird sie reviewbar. Der KI-Vorschlag erscheint als Diff. Menschen können kommentieren, kürzen, korrigieren und entscheiden. Die KI nimmt den ersten Schreibaufwand ab, aber das Team behält die Verantwortung.

Dieser Workflow ist deutlich besser als das bekannte "Wir müssen die Doku noch nachziehen". Denn diese Nacharbeit passiert oft nie. Wenn KI im Pull Request direkt erkennt, welche Dokumente wahrscheinlich betroffen sind, wird Dokumentation Teil der normalen Änderung. Nicht als extra Meeting, nicht als späterer Wiki-Frühjahrsputz, sondern als Bestandteil des Codeschnitts.

Damit wird Dokumentation nicht schwerer, sondern leichter. Sie entsteht näher am Moment der Entscheidung. Sie wird konkreter, weil der Diff danebenliegt. Und sie bleibt aktueller, weil jede Änderung die Frage stellen kann: Muss /docs mitgehen?

Der Review wird ehrlicher

Ein Pull Request, der nur Code zeigt, lädt zu lokalen Diskussionen ein: Ist die Methode schön? Ist der Name passend? Ist der Test grün? Das ist wichtig, aber nicht genug. Ein Pull Request mit passender Dokumentation ermöglicht die besseren Fragen: Ist das noch dieselbe fachliche Regel? Ist die Architekturgrenze bewusst verschoben worden? Ist die User Story wirklich erfüllt? Muss eine ADR angepasst oder neu geschrieben werden?

KI kann diese Fragen vorbereiten. Sie kann Reviewende darauf hinweisen, dass ein Feature-Dokument eine andere Erwartung beschreibt. Sie kann markieren, dass eine Definition of Ready zwar für die Planung relevant war, die Umsetzung aber noch keine ausreichenden Akzeptanzkriterien sichtbar macht. Sie kann prüfen, ob die Definition of Done als Qualitätsrahmen berücksichtigt wurde. Sie kann Lessons finden, die zu einem wiederkehrenden Problem passen.

Das macht Reviews nicht automatisch perfekt. Aber es verschiebt sie in die richtige Richtung. Weg von persönlichem Bauchgefühl, hin zu expliziten, versionierten Vereinbarungen. Genau deshalb ist /docs für KI-gestützte Teams kein Beiwerk. Es ist ein Kontrollsystem gegen kollektives Vergessen.

Docker Compose macht das Monorepo ausführbar

Ein Mono-Repository hilft KI nicht nur beim Lesen. In Verbindung mit einer zentralen docker-compose.yml wird es auch ausführbar. Wenn die lokale Entwicklungsumgebung über Compose beschrieben ist, kann ein Agent erkennen, welche Services existieren, wie sie zusammenhängen und welche Befehle für Start, Stop, Logs, Tests und Builds vorgesehen sind.

Das ist ein massiver Unterschied zu Dokumentation, die irgendwo erklärt, wie man "irgendwie lokal startet". Eine KI kann aus Repository-Kontext und Compose-Konfiguration ableiten: Datenbank starten, Backend hochfahren, Frontends prüfen, Logs lesen, Tests ausführen, Builds validieren, Umgebung wieder stoppen. Sie muss nicht raten, ob es ein lokales PHP, Node, MySQL oder Mail-Setup auf dem Host gibt. Sie kann den standardisierten Pfad benutzen, den auch das Team benutzt.

Damit wird KI-gestützte Entwicklung robuster. Der Agent schreibt nicht nur Code und hofft, dass es schon passt. Er kann die Anwendung starten, Fehler im Log sehen, gezielte Tests ausführen, eine Frontend-Build-Pipeline anstoßen oder eine Compose-Konfiguration validieren. Natürlich bleibt menschliche Kontrolle wichtig, besonders bei destruktiven Befehlen oder Daten-Reset. Aber das Grundprinzip ist stark: Ein Monorepo mit docker-compose.yml gibt KI nicht nur Wissen, sondern Handlungsfähigkeit.

Onboarding wird vom Suchspiel zur geführten Tour

Neue Entwicklerinnen und Entwickler leiden selten daran, dass es gar keine Informationen gibt. Sie leiden daran, dass Informationen verstreut sind. Ein Link ins Wiki, ein veraltetes Diagramm, ein Ticket aus dem letzten Jahr, ein Kommentar im Pull Request, eine Antwort im Chat. Das Problem ist nicht Mangel, sondern Zerfaserung.

Ein strukturiertes /docs-Verzeichnis macht Onboarding planbarer. Wer das Produkt verstehen will, startet bei product. Wer fachliche Regeln sucht, geht zu requirements und domain. Wer Systemgrenzen verstehen will, liest architecture. Wer wissen will, wie gearbeitet wird, findet es in engineering. Wer ein konkretes Feature bauen oder ändern soll, schaut in features und tasks.

Mit KI wird daraus eine geführte Tour. Ein Assistent kann einem neuen Teammitglied erklären, welche Dokumente für eine Aufgabe relevant sind. Er kann Zusammenfassungen erzeugen, offene Begriffe erklären und auf Entscheidungen verweisen. Aber er kann das nur gut, wenn die Informationen im Repository liegen und sinnvoll strukturiert sind. Sonst wird Onboarding wieder zum Ratespiel, nur mit eloquenteren Antworten.

Dokumentation wird durch KI wichtiger, nicht unwichtiger

Das ist der Kern: /docs macht implizites Wissen explizit. Nicht als Archivpflicht, sondern als Arbeitsmaterial. Es hilft Menschen, besser zu entscheiden. Es hilft KI, bessere Vorschläge zu machen. Und es hilft Teams, die Lücke zwischen Absicht und Umsetzung kleiner zu halten.

Confluence kann weiterhin seinen Platz haben. Aber für lebendige Softwaredokumentation, die direkt mit Code, Reviews und KI-Agenten arbeiten soll, ist das Repository der stärkere Ort. Nicht jede Seite muss dort liegen. Aber alles, was Implementierung, Architektur, Qualität und fachliche Regeln steuert, gehört so nah wie möglich an den Code.

Die provokante Kurzfassung ist: Wenn eure KI euren Code lesen kann, aber eure Entscheidungen nicht, arbeitet sie mit halbem Gehirn. Ein Mono-Repository mit einem guten /docs-Verzeichnis gibt ihr die andere Hälfte.

GitHub Boards und Jira bleiben nützlich

Das alles bedeutet nicht, dass GitHub Boards oder Jira plötzlich überflüssig sind. Sie sind weiterhin stark, wenn es um Steuerung geht: Wer arbeitet gerade woran? Was ist geplant, in Arbeit, blockiert oder fertig? Was gehört in den nächsten Sprint? Welche Priorität hat ein Thema?

Der Fehler beginnt dort, wo solche Tools zur eigentlichen Feature-Dokumentation werden. Ein Ticket ist gut für Status, Verantwortlichkeit, Planung und Diskussion. Es ist aber ein schlechter Ort, um alle fachlichen Regeln, Use Cases, API-Annahmen, Architekturbezüge und offenen Fragen dauerhaft zu speichern. Genau diese Informationen gehören in docs/features, weil sie dort reviewbar, versioniert und direkt neben Code und Tests liegen.

In einem konkreten Arbeitsmodell können GitHub-Projektboards trotzdem die Nummern liefern, aus denen später Task- und Feature-Dokumente entstehen. Aus einem Board-Item oder Issue wird dann zum Beispiel docs/tasks/0123-example.md oder docs/features/0123-example-feature/. Das Board steuert also den Fluss, das Repository hält die Substanz.

Beispielstruktur des gesamten Repositories

Das gleiche Prinzip gilt nicht nur für /docs, sondern für das ganze Mono-Repository. Eine grobe Hauptebene kann so aussehen:

apps enthält die lauffähigen Anwendungen und zeigt auf einen Blick, welche Systemteile gemeinsam entwickelt werden. docs enthält das Wissen, das diese Systemteile erklärt und steuert. .github hält Workflows, Pull-Request-Vorlagen und Automatisierung nah am Code. docker-compose.yml beschreibt die lokale Ausführungsumgebung, und die README.md bleibt der Einstiegspunkt für Menschen und KI.

Fazit

Ein /docs-Verzeichnis ist kein nostalgischer Markdown-Fetisch. Es ist die konsequente Antwort auf moderne Softwareentwicklung. Teams arbeiten schneller, wenn Dokumentation versioniert, reviewbar und nah am Code ist. Sie arbeiten sauberer, wenn Anforderungen, Domäne, Architektur und Engineering-Regeln nicht über mehrere Tools verstreut sind. Und sie arbeiten mit KI deutlich besser, wenn der Agent nicht nur Dateien sieht, sondern Absicht.

Die Zukunft der Dokumentation ist nicht weniger Dokumentation. Sie ist bessere Dokumentation an der richtigen Stelle. Für Entwicklerteams ist diese Stelle nicht der nächste Wiki-Bereich, der langsam veraltet. Es ist das Mono-Repository. Und darin ist /docs das Arbeitsgedächtnis, das Menschen und KI gemeinsam nutzen können.