Wie Framework‑Konventionen den Bedarf an Dokumentation reduzieren

Was es bedeutet, wenn Konventionen Dokumentation ersetzen

Framework‑Konventionen sind die „Standardweisen“, wie ein Framework stillschweigend empfiehlt — oder sogar erwartet. Anstatt dass jedes Team seine eigene Ordnerstruktur, Benennungsregeln oder Anfrage/Antwort‑Abläufe erfindet, liefert das Framework ein gemeinsames Muster. Wenn du ihm folgst, können andere Entwickelnde vorhersagen, wo Dinge liegen und wie sie sich verhalten, ohne eine lange Erklärung lesen zu müssen.

Warum Teams überhaupt Dokumentation schreiben

Die meisten Dokumente entstehen nicht, weil Menschen gerne Docs schreiben. Sie existieren, um einige wiederkehrende Probleme zu lösen:

• Onboarding: neuen Entwicklerinnen und Entwicklern helfen zu verstehen, wo sie anfangen und wie das Projekt organisiert ist
• Konsistenz: verhindern, dass jede:r das gleiche Problem auf unterschiedliche Weise löst
• Entscheidungen festhalten: dokumentieren, warum ein bestimmter Ansatz gewählt wurde (oft nach Abwägungen)

Konventionen lösen besonders die ersten beiden Punkte gut. Wenn „wo packen wir X hin“ und „wie nennen wir Y“ bereits vom Framework entschieden sind, gibt es weniger zu erklären und weniger zu diskutieren.

Konventionen reduzieren Dokumentation — sie löschen sie nicht aus

„Konventionen ersetzen Dokumentation“ heißt nicht, dass ein Projekt völlig dokumentationsfrei wird. Es bedeutet, dass ein großer Teil der grundlegenden Anleitung von Fließtext in vorhersehbare Struktur wandert. Statt ein Wiki lesen zu müssen, um zu lernen, wo Controller liegen, schließt du daraus, weil das Framework Controller an einem bestimmten Ort erwartet (und Tools, Generatoren und Beispiele verstärken das).

Das Ergebnis ist weniger Dokumentation über das Offensichtliche und mehr Fokus auf das, was wirklich projektspezifisch dokumentiert werden muss: Geschäftsregeln, ungewöhnliche Architekturentscheidungen und beabsichtigte Ausnahmen.

Was du aus diesem Artikel mitnimmst

Dieser Artikel richtet sich an Entwickler:innen, Tech‑Leads und produktorientierte Teams, die klarere Codebasen und schnelleres Onboarding ohne ein ausuferndes Dokumentationsportal wollen.

Du lernst, wie Framework‑Konventionen "implizite Dokumentation" erzeugen, welche Dinge Konventionen typischerweise standardisieren, wo Konventionen aufhören zu helfen und was trotzdem explizit dokumentiert werden sollte — damit die Klarheit steigt, während die Menge der Docs sinkt.

Warum Konventionen funktionieren: geteilte Defaults schlagen lange Erklärungen

„Convention over configuration“ bedeutet, dass ein Framework sinnvolle Entscheidungen für dich trifft — vorausgesetzt, du hältst dich an die vereinbarten Regeln. Anstatt Seiten voller Setup‑Anweisungen zu schreiben (und zu lesen), verlassen sich Teams auf geteilte Defaults, die jede:r wiedererkennt.

Eine einfache Analogie

Stell dir vor, du fährst in einem Land, in dem alle zustimmen, rechts zu fahren, bei Rot anzuhalten und standardisierte Schilder zu beachten.

Du könntest ein detailliertes Handbuch für jede Kreuzung schreiben („Wenn du ein rotes Achteck siehst, halte an; wenn die Ampel grün ist, fahr…“), aber du brauchst das nicht — weil die Konvention bereits bekannt und konsistent angewendet wird.

Framework‑Konventionen funktionieren genauso: sie verwandeln „wie wir hier Dinge tun“ in vorhersehbares Verhalten.

Defaults beseitigen die Notwendigkeit, jeden Schritt zu erklären

Wenn ein Framework Defaults hat, musst du nicht jede kleine Entscheidung dokumentieren. Das Framework (und dein Team) kann Muster annehmen wie:

• wo Dateien hingehören (Controller in einem Ordner, Templates in einem anderen)
• wie Dinge benannt werden (ein User‑Modell mappt auf users‑Daten)
• wie gängige Features verbunden sind (Routing, Validierung, Umgebungssettings)

Diese gemeinsame Basis schrumpft die Dokumentation von „hier sind alle Schritte, um X einzurichten“ zu „wir folgen den Framework‑Defaults, außer wenn anders angegeben.“ Sie reduziert auch die mentale Last beim Onboarding: neue Entwickler:innen können öfter richtig raten, weil der Code dem entspricht, was sie in anderen Projekten gesehen haben.

Der Trade‑off: weniger Flexibilität, mehr Konsistenz

Konventionen sind nicht umsonst. Der Nachteil ist, dass du manchmal auf ungewöhnliche Ordnerstrukturen, individuelle Benennungen oder stark maßgeschneiderte Workflows verzichtest.

Der Vorteil ist Konsistenz: weniger Debatten, weniger Überraschungen, weniger „tribal knowledge“, an das nur alteingesessene Mitarbeitende sich erinnern. Teams bewegen sich schneller, weil sie weniger Zeit mit Erklärungen und mehr Zeit mit Bauen verbringen.

Konventionen funktionieren am besten, wenn sie weit verbreitet sind

Eine Konvention spart nur dann Dokumentation, wenn Leute sie bereits kennen — oder sie einmal lernen können und überall wiederverwenden. Deshalb sind populäre Frameworks so mächtig: die Konventionen werden breit gelehrt, vielfach genutzt und in vielen Codebasen wiederholt. Wenn dein Projekt eng an diesen geteilten Defaults bleibt, wird dein Code von Haus aus verständlich, mit deutlich weniger schriftlichen Erklärungen.

Die 5 Dinge, die Framework‑Konventionen meist standardisieren

Framework‑Konventionen sind gemeinsame Abkürzungen. Sie standardisieren die Fragen, die jedes neue Teammitglied am ersten Tag stellt: „Wohin gehört das?“ und „Wie nennen wir das?“ Wenn diese Antworten vorhersehbar sind, kannst du Seiten an Docs durch ein paar konsistente Defaults ersetzen.

1) Ordner‑ und Dateistruktur

Die meisten Frameworks treiben eine erkennbare Projektstruktur voran: ein Platz für UI, ein Platz für Routen, ein Platz für Datenzugriff, ein Platz für Tests. Diese Konsistenz ist wichtig, weil Menschen nicht mehr erst eine Anleitung lesen müssen, um „den Teil, der eine Seite rendert“ von „dem Teil, der mit der Datenbank spricht“ zu unterscheiden.

Die besten Konventionen lassen häufige Aufgaben wie Muskelgedächtnis erscheinen: neue Seite hinzufügen → du weißt schon, in welchen Ordner sie gehört.

2) Benennungsregeln

Benennungsregeln reduzieren die Notwendigkeit für Erklärungen wie „Unsere Controller sind in X und müssen in Y verdrahtet werden.“ Stattdessen implizieren Namen Rollen.

Gängige Beispiele:

• Seiten/Komponenten, die nach dem benannt sind, was sie rendern (und in vorhersehbarer Schreibweise)
• Tests, die nach der Einheit benannt sind, die sie abdecken
• Dateien, die dem Exportnamen entsprechen (damit Suchen wie erwartet funktionieren)

3) Routing und URLs

Viele Webframeworks mappen Dateien auf Routen (oder machen Routing einfach zu erschließen). Wenn du die URL aus dem Dateinamen erraten kannst — oder umgekehrt — brauchst du für jede Funktion kein eigenes Routing‑Handbuch.

Die Konvention setzt auch Erwartungen an dynamische Routen, verschachtelte Routen und 404‑Handhabung, sodass „wie füge ich einen neuen Endpoint hinzu?“ eine standardisierte Antwort hat.

4) Muster für Datenzugriff

Konventionen definieren oft, wo „Daten‑Code“ lebt: Modelle, Repositories, Services, Migrationen, Schema‑Dateien. Selbst wenn die App klein ist, verhindert ein vereinbarter Ort für Datenzugriff ad‑hoc‑Datenbankaufrufe, die überall in der UI verstreut sind.

5) Gängige Skripte und Befehle

Standardbefehle (run, test, build, lint, format) beseitigen Unklarheit. Eine neue Entwicklerin oder ein neuer Entwickler sollte nicht erst ein Wiki lesen müssen, um das Projekt zu starten — npm test (oder das entsprechende Äquivalent) sollte die naheliegende Wahl sein.

Wenn diese fünf Bereiche konsistent sind, beantwortet die Codebasis die meisten „wie machen wir das hier?“‑Fragen selbst.

Wie Konventionen das Repo in eine Karte verwandeln

Ein „wie alles funktioniert“‑Wiki versucht, das gesamte System in Prosa zu beschreiben. Es ist oft am Anfang nützlich, driftet dann aber aus dem Tritt, wenn Ordner verschoben, Namen geändert und neue Features hinzugefügt werden. Konventionen kehren diese Idee um: statt eine lange Erklärung zu lesen, liest du die Struktur.

Vorhersehbare Orte erleichtern die Orientierung

Wenn ein Framework (und dein Team) sich darauf einigt, wo Dinge leben, wird das Repository wie ein Straßenraster navigierbar.

Wenn du weißt, dass UI‑Komponenten in components/ gehören, Seiten‑Views in pages/ und API‑Handler in api/ liegen, fragst du nicht mehr „wo ist X?“, denn die erste Vermutung ist meist richtig. Selbst wenn nicht, ist die Suche eingeschränkt: es ist nicht irgendwo — es ist in einer kleinen Anzahl erwarteter Orte.

Namen als Wegweiser

Konventionen lassen Dateinamen und Symbole Bedeutung tragen. Eine neue Person kann Verhalten aus Lage und Benennung ableiten:

• eine Datei user.controller behandelt wahrscheinlich Request‑Logik
• eine Klasse UserService enthält vermutlich Geschäftsregeln
• ein Ordner migrations/ enthält wahrscheinlich geordnete, einmal auszuführende Datenbankänderungen

Diese Schlüsse reduzieren „erklär mir die Architektur“‑Fragen auf kleinere, beantwortbare Fragen („Darf dieser Service direkt die DB aufrufen?“), die sich leichter dokumentieren lassen.

Templates halten die Karte konsistent

Der schnellste Weg, die Karte zu verstärken, ist Scaffolding. Starter‑Templates und Generatoren erzeugen neue Features standardmäßig in der „richtigen“ Form — Ordner, Dateinamen, Boilerplate‑Verdrahtung und oft Tests.

Das ist wichtig, weil Konventionen nur helfen, wenn sie konsistent angewandt werden. Ein Template ist eine Leitplanke: es schiebt jede neue Route, Komponente oder Modul in die erwartete Struktur, sodass die Codebasis lesbar bleibt, ohne dass zusätzliche Wiki‑Seiten nötig sind.

Wenn du interne Scaffolds pflegst, verlinke sie von einer kurzen Onboarding‑Seite (zum Beispiel /docs/getting-started) und lass den Ordnerbaum den Rest erledigen.

Praxisbeispiele für „implizite Dokumentation"

Framework‑Konventionen wirken oft wie leise, eingebaute Anweisungen. Anstatt eine Seite zu schreiben, die erklärt „wo Dinge hingehören“ oder „wie man das verdrahtet“, trifft das Framework schon die Entscheidung — und dein Team lernt, die Struktur zu lesen.

Ruby on Rails: „Leg es hier hin und es funktioniert"

Rails ist berühmt für Konvention vor Konfiguration. Ein einfaches Beispiel: wenn du einen Controller namens OrdersController erstellst, geht Rails davon aus, dass es einen passenden View‑Ordner in app/views/orders/ gibt.

Diese einzelne Konvention kann einen Teil der Dokumentation ersetzen, die sonst erklären würde:

• wo HTML‑Templates liegen sollten
• wie eine URL die richtige Controller‑Action findet
• wie der Controller das passende Template auswählt

Ergebnis: neue Teammitglieder können eine Seite hinzufügen, indem sie dem Ordner‑Pattern folgen, ohne zu fragen „wo gehört diese Datei hin?“

Django: vorhersehbare Struktur für übliche Aufgaben

Django fördert eine konsistente „App“‑Struktur. Wenn jemand eine Django‑App sieht, erwartet er/sie models.py für Datenformen, views.py für Request‑Handling und templates/ für HTML.

Man könnte eine lange Anleitung zur Projektanatomie schreiben, aber Djangos Defaults lehren das bereits. Wenn ein Teammitglied das Aussehen einer Seite ändern will, schaut es in templates/. Muss gespeicherte Daten angepasst werden, fängt es in models.py an.

Ergebnis: schnellere Fehlerbehebungen, weniger Sucherei, weniger „welche Datei kontrolliert das?“‑Nachrichten.

Next.js: Routing ohne Routing‑Handbuch

Next.js reduziert die Dokumentation, indem Routing eine direkte Spiegelung deiner Ordnerstruktur wird. Erstelle eine Datei in app/about/page.tsx (oder pages/about.tsx in älteren Setups) und du bekommst automatisch eine /about‑Seite.

Das erspart Docs, die erklären:

• wie Routen registriert werden
• wie Routen konsistent zu benennen sind
• wie man eine neue Seite hinzufügt, ohne Navigation zu brechen

Ergebnis: Onboarding ist einfacher — Leute entdecken die Form der Website durch Verzeichnisdurchsicht.

Dasselbe Prinzip, andere Ökosysteme

Rails, Django und Next.js sehen unterschiedlich aus, aber das Prinzip ist identisch: geteilte Defaults verwandeln Projektstruktur in Anweisungen. Wenn alle denselben Konventionen vertrauen, beantwortet die Codebasis viele „wie machen wir das hier?“‑Fragen von selbst — ohne ein weiteres zu wartendes Dokument.

Wenn Konventionen versagen (und Verwirrung zurückkehrt)

Framework‑Konventionen wirken „unsichtbar“, wenn sie funktionieren. Du kannst erraten, wo Dateien liegen, wie Dinge heißen und wie eine Anfrage durch die App fließt. Verwirrung kehrt zurück, wenn eine Codebasis von diesen geteilten Defaults abweicht.

Anzeichen, dass deine Konventionen erodieren

Einige Muster treten früh auf:

• zu viele benutzerdefinierte Ordner, die nicht zur üblichen Framework‑Struktur passen (z. B. neue Top‑Level‑Verzeichnisse für jede Funktion ohne klare Regeln)
• inkonsistente Benennung: ein Teil benutzt UserService, ein anderer UsersManager, ein dritter user_service
• ad‑hoc‑Muster, die von Bildschirm zu Bildschirm oder Endpoint zu Endpoint wechseln („wir haben es hier anders gehandhabt, weil…“) ohne stabile Richtlinie

Das ist nicht automatisch falsch — aber es bedeutet, dass neue Teammitglieder sich nicht mehr auf die „Karte“ des Frameworks verlassen können.

Wie „eine Ausnahme“ viele werden kann

Die meisten Zusammenbrüche von Konventionen beginnen mit einer sinnvollen lokalen Optimierung: „Dieses Feature ist besonders, also legen wir es hier hin“ oder „Diese Benennung liest sich besser.“ Das Problem ist, dass Ausnahmen ansteckend sind. Sobald die erste Ausnahme deployed ist, nutzt die nächste Entwicklerin oder der nächste Entwickler sie als Präzedenzfall:

• ein zweites Feature kopiert den benutzerdefinierten Ordner, weil er schon da ist
• ein drittes Feature passt ihn leicht an, weil der zweite nicht ganz passte
• bald hast du drei „akzeptable“ Wege, dasselbe zu tun

An diesem Punkt ist die Konvention keine Konvention mehr — sie wird zu Tribal Knowledge.

Die wirklichen Kosten: Zeit, Fehler und Meetings

Wenn Konventionen verschwimmen, verlangsamt sich das Onboarding, weil Menschen nicht mehr vorhersagen können, wo sie suchen müssen. Alltägliche Aufgaben dauern länger („Welcher dieser Ordner ist der richtige?“), Fehler häufen sich (falsches Modul verdrahten, falsches Benennungsschema verwenden, Logik duplizieren). Teams kompensieren mit mehr Synchronisationsmeetings, ausführlicheren PR‑Erklärungen und kurzen Docs, die veralten.

Eine einfache Regel für Klarheit

Passe nur an, wenn du einen klaren Grund hast — und hinterlasse eine schriftliche Notiz.

Diese Notiz kann leicht sein: ein kurzer Kommentar in der Nähe der ungewöhnlichen Struktur oder ein knapper Eintrag auf einer /docs/decisions‑Seite, der erklärt, was sich geändert hat, warum es sich lohnt und wie zukünftig vorzugehen ist.

Was du trotzdem dokumentieren musst: die Ausnahmen

Framework‑Konventionen können Seiten an Erklärungen ersetzen, aber sie nehmen nicht die Verantwortung ab. Was weiterhin dokumentiert werden muss, sind die Bereiche, in denen dein Projekt bewusst vom erwarteten Verhalten abweicht.

Dokumentiere Entscheidungen, nicht Basics

Erkläre nicht noch einmal das Standardverhalten des Frameworks. Halte stattdessen Entscheidungen fest, die den Alltag beeinflussen:

• was ihr gewählt habt (und was nicht)
• was sich geändert hat (und wann)
• warum es sich geändert hat (Trade‑offs, Einschränkungen, incidentgetriebene Fixes)

Beispiel: „Wir verwenden Feature‑Ordner unter /src/features statt Schichtenordner (/src/components, /src/services), weil Ownership zu Teams passt und Cross‑Team‑Kopplung reduziert.“ Dieser Satz verhindert Wochen langsamen Abdriftens.

Hinterlasse kurze „Ausnahmehinweise“ nahe am Code

Wenn eine Ausnahme lokal wichtig ist, setze die Notiz lokal. Ein kleines README.md im Ordner oder ein kurzer Header‑Kommentar an der Datei schlägt oft ein zentrales Wiki, das niemand liest.

Gute Kandidaten:

• ein Verzeichnis, das aus einem Grund von der üblichen Projektstruktur abweicht
• ein Modul, das in ungewöhnlicher Reihenfolge initialisiert werden muss
• eine Benennungsregel, die „falsch“ aussieht, wenn man den Constraint nicht kennt

Halte diese Hinweise kurz und handlungsorientiert: was ist anders, warum ist es anders und was ist als Nächstes zu tun.

Erstelle eine winzige „Project Rules“‑Seite

Habe eine leichte Seite (oft in /docs/project-rules.md oder im root‑README), die nur 5–10 Schlüsselentscheidungen listet, über die Leute stolpern werden:

• Benennungsregeln, die vom Framework‑Default abweichen
• die erwartete Projektstruktur (nur wo sie vom Default abweicht)
• dein „golden path“ für das Hinzufügen eines neuen Features oder Endpoints

Das ist kein vollständiges Handbuch — nur ein Satz von Leitplanken.

Quickstart: wie man läuft und testet

Auch mit Konventionen stockt das Onboarding, wenn Leute die App nicht starten können. Füge eine kurze „How to run/test“‑Sektion hinzu, die zu den Standardbefehlen und deiner tatsächlichen Einrichtung passt.

Wenn der konventionelle Befehl npm test ist, dein Projekt aber npm run test:unit benötigt, dokumentiere das explizit.

Halte Docs über Code‑Reviews aktuell

Dokumentation bleibt korrekt, wenn sie als Teil der Änderung behandelt wird. Frage in Reviews: „Hat das eine neue Ausnahme eingeführt?“ Wenn ja, fordere die passende Notiz (lokales README, Project Rules oder root Quickstart) in demselben Pull Request an.

Konventionen durch Automatisierung durchsetzen statt durch mehr Docs

Wenn Konventionen die „geteilten Defaults“ deines Repos sind, macht Automatisierung sie real. Statt jede Entwicklerin und jeden Entwickler zu bitten, Regeln aus einem Wiki zu merken, mache die Regeln ausführbar — so erzwingt das Projekt sich selbst.

Automatisierte Checks, die Teams konsistent halten

Eine gute Einrichtung fängt Drift früh und leise ab:

• Formatierung: auto‑format beim Speichern und in CI (z. B. Prettier, gofmt, black), sodass Stildebatten verschwinden
• Lint‑Regeln: verhindern gängige Fehler und erzwingen Benennungsregeln (z. B. React‑Hooks‑Regeln, unused imports, „no default export“ falls das euer Standard ist)
• Test‑Namensgebung und Struktur: erzwinge Muster wie *.spec.ts, konsistente describe/it‑Formulierungen oder erforderliche Assertions, sodass Tests konsistent lesbar sind
• Ordnergrenzen: blockiere Imports, die deine intendierte Architektur verletzen (z. B. „Features dürfen nicht aus anderen Features importieren“ oder „UI darf keinen Servercode importieren"). Tools wie ESLint‑Regeln, TypeScript‑Path‑Beschränkungen oder Custom‑Skripte können das leisten.

Diese Checks ersetzen Abschnitte mit „bitte merkt euch…“ durch ein einfaches Ergebnis: der Code entspricht entweder der Konvention oder er tut es nicht.

Schnell scheitern: Probleme vor dem Merge finden

Automatisierung ist stark, weil sie früh scheitert:

• Probleme werden während der lokalen Entwicklung oder im Pull Request gefunden, nicht erst Wochen später
• Reviewer verbringen weniger Zeit mit Stil‑Polizei und mehr Zeit mit Produktlogik
• Neue Kolleg:innen lernen Konventionen, indem sie klare, konsistente Fehler und deren Behebung sehen

Halte Regeln minimal — und im Einklang mit dem Framework

Die besten Regelsets sind klein und unspektakulär. Starte mit den Defaults des Frameworks und füge nur hinzu, was Klarheit schützt (Benennung, Struktur, Grenzen). Jede zusätzliche Regel ist etwas, das Menschen verstehen müssen — behandle neue Checks wie Code: füge sie hinzu, wenn sie ein wiederkehrendes Problem lösen, und entferne sie, wenn sie nicht mehr helfen.

Tests als lebende Dokumentation (wenn sie für Menschen geschrieben sind)

Wenn eine Codebasis Framework‑Konventionen folgt, können Tests mehr als „beweisen, dass es funktioniert“: sie können erklären, was das System tun soll, in klarer Sprache, direkt neben der Implementierung.

Schreibe Tests, die wie eine Geschichte lesen

Eine nützliche Regel: ein Test sollte ein Verhalten end‑to‑end beschreiben. Wenn jemand nur den Testnamen überfliegen kann und das Versprechen des Systems versteht, hast du die Notwendigkeit separater Dokumentation reduziert.

Gute Tests folgen oft einem einfachen Rhythmus:

• Arrange: realistische Ausgangssituation aufbauen
• Act: eine Aktion ausführen
• Assert: das Ergebnis prüfen, das zählt

Noch besser sind Namen, die die Nutzerintention spiegeln:

• signing_in_with_valid_credentials_redirects_to_dashboard
• checkout_fails_when_shipping_address_is_missing

Diese Namen sind Dokumentation, die man nicht vergisst zu aktualisieren — weil fehlschlagende Tests die Diskussion erzwingen.

Acceptance‑Tests für User‑Flows

Acceptance‑ oder Feature‑Tests dokumentieren besonders gut wie sich das Produkt aus Nutzersicht verhält.

Beispielverhalten, das Acceptance‑Tests beschreiben können:

• ein Nutzer meldet sich an, bestätigt die E‑Mail und landet auf der Willkommensseite
• ein Admin erstellt einen Rabattcode, der an der Kasse angewendet wird

Diese Tests beantworten die Frage „Was passiert, wenn ich X tue?“ — oft das Erste, was neue Teammitglieder wissen wollen.

Unit‑Tests für Edge‑Cases und Regeln

Unit‑Tests sind ideal, wenn du „kleine, aber wichtige“ Regeln dokumentieren willst:

• Rundungsverhalten
• Validierungsregeln
• Berechtigungsprüfungen
• knifflige Randfälle (Zeitzonen, Limits, leere Zustände)

Sie sind besonders wertvoll, wenn die Regel nicht aus den Framework‑Konventionen ersichtlich ist.

Halte Fixtures und Beispieldaten klein — und aussagekräftig

Beispieldaten können ebenfalls lebende Dokumentation sein. Eine kleine, sinnvoll benannte Fixture (z. B. user_with_expired_subscription) lehrt die Domäne oft schneller als ein Absatz im Wiki.

Der Schlüssel ist Zurückhaltung: halte Fixtures minimal, lesbar und an eine Idee gebunden, damit sie vertrauenswürdige Beispiele bleiben statt ein zweites System, das gepflegt werden muss.

Starter‑Templates: der schnellste Weg, Konventionen zu verbreiten

Starter‑Templates (und die dahinterstehenden Generatoren) sind der schnellste Weg, „wie wir hier arbeiten“ in etwas zu verwandeln, dem Menschen tatsächlich folgen. Anstatt jede Teammitarbeiterin und jeden Teammitarbeiter zu bitten, sich die richtigen Ordner, Skripte und Tools zu merken, backst du diese Entscheidungen in ein Repo, das korrekt startet.

Templates, Generatoren und Starter‑Kits: verschiedene Geschwindigkeiten, gleiches Ziel

• Templates geben dir eine kopierbare Basis (z. B. „neuer Service“, „neue Frontend‑App").
• Generatoren (CLI‑Tools) können ein paar Fragen stellen und dann konsistente Dateien, Benennungen und Verdrahtung erzeugen.
• Starter‑Kits enthalten nicht nur Code‑Struktur, sondern oft CI, Linting, Testing und Deployment‑Defaults.

Alle drei reduzieren „Dokumentationsschuld“, weil die Konvention im Startpunkt kodiert ist und nicht in einem driftenden Wiki.

In der Praxis ist das auch der Punkt, an dem Tools wie Koder.ai helfen können: wenn du eine neue React‑App, ein Go‑Backend, ein PostgreSQL‑Schema oder einen Flutter‑Client aus einem Chat‑gesteuerten Workflow generierst, kannst du Teams auf einem einzigen "goldenen Pfad" halten, indem du die Standardausgabe an deine Konventionen anpasst (und dann den Quellcode ins Repo übernimmst).

Standardisiere das Setup, damit „nicht jedes Repo anders ist"

Die meiste Verwirrung beim Onboarding betrifft nicht Business‑Logik, sondern wo Dinge liegen und wie man sie startet. Ein gutes Template macht gemeinsame Aufgaben in allen Repos identisch: gleiche Skripte, gleiche Ordnernamen, gleiche Prüf‑Befehle, gleiche PR‑Erwartungen.

Wenn du nichts anderes tust, stimme ab auf:

• vorhersehbare Ordner (z. B. /src, /test, /docs nur für Ausnahmen)
• ein Weg, um zu starten/testen/lint via package‑Skripte
• eine Standard‑CI‑Pipeline, die diese Skripte bei jedem PR ausführt

Eine schlanke „Neues Projekt“‑Checkliste

Halte sie so klein, dass Teams sie nicht überspringen:

1. Ordnerstruktur und Benennungsregeln
2. Ein‑Kommando‑Setup (z. B. install + dev)
3. test, lint und format‑Skripte
4. CI, das bei jedem PR läuft
5. Basis‑README: Zweck, Voraussetzungen und die 3–5 Befehle, die Menschen brauchen

Nicht versteinern: das Template kann zum Problem werden

Das größte Risiko ist, ein altes Template zu kopieren „weil es letztes Jahr funktioniert hat“. Veraltete Dependencies, Legacy‑Skripte oder aufgegebene Muster verbreiten sich schnell, wenn sie im Starter stecken.

Behandle Templates wie Produkte: versioniere sie, überprüfe sie in regelmäßigen Abständen und aktualisiere sie, wenn sich deine Konventionen ändern. (Wenn deine Plattform Snapshots und Rollbacks unterstützt — Koder.ai tut das — nutze das, um Starter sicher zu iterieren, ohne die Basis zu brechen.)

Eine praktische Checkliste, um Docs zu reduzieren, ohne Klarheit zu verlieren

Dokumentation zu reduzieren heißt nicht, Menschen im Dunkeln zu lassen. Es heißt, den „Happy Path“ so konsistent zu machen, dass die meisten Fragen sich von selbst beantworten, und nur die wirklich ungewöhnlichen Teile aufzuschreiben.

1) Mach ein kurzes Self‑Audit (finde die echten Reibungspunkte)

Suche nach Stellen, an denen Leute wiederholt dieselben Fragen in Slack, PR‑Kommentaren, Standups oder Onboarding‑Sessions stellen. Ein paar Stichfragen:

• „Wo sollte diese Datei leben?“
• „Wie nennen wir dieses Ding?“
• „Wie füge ich eine neue Seite/Job/Endpoint hinzu?“
• „Warum funktioniert das Modul hier anders?“

Wenn du dieselbe Frage zwei Mal hörst, brauchst du wahrscheinlich weniger Prosa — du brauchst eine Konvention.

2) Entscheide: Framework‑Default übernehmen oder bewusste Abweichung dokumentieren

Für jede wiederkehrende Frage entscheide:

• Wir kämpfen gegen das Framework: kehre zu den Defaults zurück (Routing, Ordnerlayout, Benennung, Fehlerbehandlung). Defaults sind bereits vom Ökosystem „dokumentiert“.
• Wir haben einen guten Grund abzuweichen: behalte die Abweichung, mache sie aber explizit und gut sichtbar.

Eine nützliche Regel: wenn eine Abweichung keine echte Zeitersparnis bringt oder kein Risiko verhindert, ist sie es vermutlich nicht wert.

3) Erstelle eine winzige „Konventionen & Ausnahmen“‑Seite

Halte eine einzige, kurze Seite (z. B. /docs/conventions) bereit, die auflistet:

• die 5–10 Konventionen, von denen alle ausgehen sollen
• das kleine Set an Ausnahmen (mit Grund und Beispiel)

Beschränke dich auf das, was jemand in der ersten Woche braucht. Wenn die Seite wächst, ist das oft ein Zeichen, dass du die Codebasis vereinfachen solltest.

4) Setze einen Rhythmus: Überprüfe Konventionen quartalsweise

Apps entwickeln sich. Plane eine leichte Quartalsüberprüfung:

• welche neuen Muster sind aufgetaucht?
• welche Ausnahmen sind „normal“ geworden (und sollten zur Konvention werden)?
• welche Konventionen werden ignoriert (und warum)?

Fazit

Bevorzuge Framework‑Defaults, wann immer möglich, und dokumentiere nur das, was anders ist — klar, kurz und an einem Ort.