Chaotische Codebasis umstrukturieren, ohne die Produktion zu gefährden

Was eine chaotische Codebasis-Struktur wirklich bedeutet

Eine chaotische Codebasis-Struktur ist nicht einfach „viele Dateien“. Sie entsteht, wenn das Layout nicht mehr widerspiegelt, wie das Produkt funktioniert. Sie wissen nicht mehr, wohin eine Änderung gehört, und jede Änderung fühlt sich riskant an.

In echten Repositories zeigt sich das häufig durch vermischte Verantwortlichkeiten: UI-Code spricht direkt mit der Datenbank, Auth-Prüfungen sind über Seiten verstreut, und „utils“-Ordner enthalten stillschweigend einen Großteil der Geschäftslogik. Ein weiteres häufiges Krankheitssymptom sind zirkuläre Imports (A importiert B, B importiert A). Sie können merkwürdiges Laufzeitverhalten erzeugen und Leute zu Hacks treiben, nur damit die App startet.

Benennung ist das leisere Problem. Sie sehen drei verschiedene Namen für dasselbe Ding (userService, users.service, user_manager) oder Ordner, die nichts aussagen (misc, temp, old2). Leute duplizieren Code, weil sie den richtigen Ort nicht finden, und das Chaos wächst.

Sie spüren Strukturprobleme im Tagesgeschäft mehr als in Architekturskizzen:

• Kleine Änderungen dauern Stunden, weil Sie Abhängigkeiten im ganzen Repo jagen.
• Bugs wiederholen sich, weil Fixes an einer Stelle landen, während das tatsächliche Verhalten woanders steckt.
• Releases sind beängstigend, weil eine „winzige“ Änderung etwas Unabhängiges kaputtmachen kann.

Eine Bereinigung lohnt sich, wenn die Struktur der Hauptgrund ist, dass Sie langsam sind oder vermeidbare Bugs entstehen. Wenn das Produkt stabil ist, Änderungen selten sind und das Team das aktuelle Layout versteht, kann ein großer Refactor warten. Oft ist die beste Taktik „touch it, tidy it“: verbessern Sie die Struktur nur dort, wo Sie ohnehin eine Funktion oder einen Bug ändern.

„Nicht alles kaputtmachen“ bedeutet, dass das Verhalten gleich bleibt, während sich die Struktur ändert. Nutzer sollten nichts merken. Der Gewinn ist sichereres Arbeiten: kleinere Diffs, klarere Grenzen und weniger Überraschungen bei Tests und Releases.

Ziele und Guardrails setzen, bevor Sie den Code anfassen

Refactors laufen schneller, wenn Sie eine Frage beantworten können: Was wollen wir verbessern? Wählen Sie ein primäres Ziel, z. B. schnellere Änderungen, weniger Bugs oder einfacheres Onboarding. Wenn Sie versuchen, alles auf einmal zu beheben, verbringen Sie eine Woche damit, Dateien zu verschieben, ohne das System tatsächlich leichter wartbar zu machen.

Schreiben Sie anschließend auf, was stabil bleiben muss. Stabilität ist nicht nur „Tests laufen“. Es ist der reale Vertrag Ihrer App mit Nutzern und anderen Systemen.

Einigen Sie sich vor dem ersten Commit auf Guardrails:

• Nicht verhandelbar: öffentliche APIs, Datenbankschema, Routen und zentrale UI-Flows, die sich nicht ändern dürfen.
• Scope: was in den Rahmen fällt und was vorerst tabu ist.
• Timebox: ein klares Limit (z. B. 2–3 Tage), bevor Sie neu bewerten.
• Beweis: welche Prüfungen grün sein müssen (Tests, Lint, Build sowie ein kurzer Smoke-Test).
• Done heißt: „diese Ordner sind bereinigt und dokumentiert“, nicht „das ganze Repo ist perfekt“.

Beispiel: Sie erben eine AI-generierte App, bei der Auth „meistens“ funktioniert, Routen dupliziert sind und Dateien an zufälligen Orten liegen. Ihre Guardrails könnten lauten: diese Woche ändern wir nicht den Login-Flow, Session-Cookies oder Datenbank-Tabellen. Das Ziel ist nur, Auth hinter ein Modul zu legen und die zugehörigen Dateien in einen einzigen Ordner mit konsistenten Namen zu verschieben. So haben Sie einen lieferbaren Gewinn, ohne ein neues Rätsel-Bug zu schaffen.

Wenn Sie mit anderen arbeiten, halten Sie die Guardrails schriftlich fest und holen Sie sich ein kurzes Okay. Das verhindert Debatten während des Refactors und hält Reviews auf die Ergebnisse fokussiert statt auf Meinungen.

Kurze Karte der aktuellen Struktur (30–60 Minuten)

Bevor Sie Ordner verschieben, verbringen Sie eine fokussierte Stunde damit, eine grobe Karte zu erstellen. Das reduziert Risiko, weil Sie aufhören zu raten, wo Verhalten startet und wie es sich ausbreitet.

Beginnen Sie mit Einstiegspunkten: wo das System aufwacht und zu arbeiten beginnt. Viele Apps haben mehr als einen: einen Webserver, einen geplanten Worker, einen Queue-Consumer, ein CLI-Skript und manchmal einen Migration-Runner.

Finden Sie dann den Schmerz: Dateien und Ordner, die Leute ständig anfassen. Hoher Churn bedeutet oft, dass diese Dateien zu viel tun oder alle davon abhängen.

Halten Sie während der Arbeit eine einfache Karte offen:

• 3 bis 6 Einstiegspunkte (was zuerst läuft und wie es startet)
• 5 bis 10 Dateien oder Ordner mit hohem Änderungsaufkommen
• 3 bis 5 Abhängigkeits-Hotspots (von vielen Modulen importiert)
• Ein Satz pro Top-Level-Ordner mit dessen Zweck (auch wenn er unschön ist)

Ein Abhängigkeits-Hotspot ist der Ort, an dem Refactors scheitern. Ein schneller Indikator ist eine einzelne „utils“-Datei, die Auth-Helper, Datumsformatierung, Datenbankcode und API-Aufrufe enthält. Wenn sie überall importiert wird, ist jede Änderung riskant.

Halten Sie die Karte ehrlich, nicht beschönigend. „src/helpers: zufällige Dinge, für die wir keinen besseren Ort fanden“ ist nützlich. Später können Sie diesen Satz in einen Plan überführen.

Ordnergrenzen definieren, die Kopplung reduzieren

Wenn Sie ohne Produktionsausfälle neu organisieren wollen, beginnen Sie mit klaren Grenzen. Das Ziel ist einfach: eine Änderung in einem Bereich sollte nicht viele Änderungen im Repo erzwingen.

Wählen Sie ein Ordner-Modell, das Sie in einem Satz erklären können

Wählen Sie das einfachste Modell, das zum Denken Ihres Teams passt:

• Nach Feature: alles für „billing“ lebt zusammen (UI, Logik, Daten).
• Nach Schicht: ui/, domain/, data/ sind getrennt und Features liegen darin.
• Hybrid: Feature-Ordner an der Spitze, mit ui/, domain/, data/ innerhalb jedes Features.

Alle diese Modelle können funktionieren. Wichtig ist, dass die Frage „Wohin gehört diese Datei?“ eine offensichtliche Antwort hat.

Schreiben Sie einfache Regeln, was wohin gehört

Definieren Sie Grenzen in Alltagssprache. Zum Beispiel:

• UI: Komponenten, Seiten, Formulare und Anzeige-Logik.
• Domain: Geschäftsregeln und Entscheidungen (Preisberechnung, Berechtigungsprüfungen).
• Datenzugriff: API-Clients, Datenbankabfragen und Persistenz.

Fügen Sie dann eine kurze „nicht überschreiten“-Liste hinzu, um versehentliche Kopplungen beim Refactoring zu verhindern:

• UI importiert nicht direkt vom Datenzugriff.
• Domain importiert UI nicht.
• Keine direkten DB-Aufrufe außerhalb des Datenzugriffs.
• Keine Umgebungs-Secrets außerhalb eines einzigen Config-Moduls lesen.
• Kein Feature-Ordner greift in die Interna eines anderen Features ein.

Szenario: Wenn ein Checkout-Screen den Bestellgesamtbetrag braucht, sollte er eine Domain-Funktion wie calculateTotal aufrufen. Diese Funktion kann Datenzugriff über eine kleine Schnittstelle aufrufen, nicht über rohes SQL oder einen direkten API-Client.

Bestimmen Sie abschließend Verantwortung: Nennen Sie einen Reviewer (oder eine kleine Gruppe) für jeden Bereich, damit Grenzverletzungen früh auffallen.

Benennungsregeln und kleine Regeln, die Ordnung halten

Refactors scheitern oft an einem langweiligen Grund: Leute wissen nicht, wo die nächste Datei hingehört, also wächst das Chaos weiter. Benennungsregeln klingen pedantisch, aber sie nehmen tägliche Entscheidungen weg und verhindern „nur dieses eine Mal“-Ausnahmen.

Wählen Sie Regeln, die Ihr Team tatsächlich befolgen wird. Wenn eine Regel jedes Mal eine Debatte auslöst, ist sie zu streng oder zu clever. Ziel ist Konsistenz, nicht Perfektion.

Ein paar Grundlagen:

• Datei- und Ordnernamen: wählen Sie kebab-case (user-profile.ts) oder camelCase (userProfile.ts) und bleiben Sie dabei.
• Singular vs. Plural: verwenden Sie z. B. Singular für Modul-Ordner (invoice/) und Plural nur für Sammlungen (invoices/).
• Exports: bevorzugen Sie benannte Exporte für geteilten Code; vermeiden Sie Default-Exporte, sofern kein klarer Grund besteht.
• Index-Dateien: verbieten Sie sie entweder oder begrenzen Sie sie darauf, die öffentliche API neu zu exportieren, damit Importe vorhersehbar bleiben.
• Ein Konzept pro Datei: wächst eine Datei über eine oder zwei Screens hinaus, trennen Sie sie nach Verantwortlichkeit.

Ein kleines „Goldbeispiel“-Verzeichnis hilft mehr als ein langes Dokument. Halten Sie es winzig und nahe an dem, was Sie am häufigsten bauen:

features/
  auth/
    api.ts
    routes.ts
    components/
      LoginForm.tsx
    index.ts

Wenn jemand einen neuen Auth-Screen hinzufügt, kann er das Muster kopieren, statt zu raten.

Eine leichte Regel für neuen Code hilft, dass der Refactor hält, auch wenn die Aufräumarbeit nicht abgeschlossen ist:

• Neue Dateien folgen den neuen Benennungsregeln und liegen in den neuen Ordnern.
• „Touch it, tidy it“: wenn Sie eine Datei ändern, verschieben Sie sie an den richtigen Ort oder korrigieren Sie den Namen.
• Keine neuen „Junk Drawer“ wie misc.

Wenn das schwer durchsetzbar ist, ist das meist ein Zeichen, dass die Struktur noch nicht zur Funktionsweise der App passt.

Schritt für Schritt: Sicher ein Modul extrahieren

Wählen Sie zuerst ein kleines, risikoarmes Ziel. Ein guter Starter ist ein geteilter Utility-Code, den viele Dateien importieren (Datumformatierung, Feature-Flags, Eingabevalidierung) oder ein einzelnes Feature, das größtenteils eigenständig ist. Wenn Sie versuchen, einen zentralen Domain-Bereich am ersten Tag herauszuziehen, jagen Sie Überraschungen hinterher.

Ein sicherer Refactor ändert die Form des Codes, ohne sein Verhalten zu ändern. Der Trick ist, eine Grenze zu schaffen und dann Code Stück für Stück dahinter zu verschieben.

Eine sichere Extraktions-Reihenfolge

Formulieren Sie zuerst das Versprechen des neuen Moduls in einem Satz: was es tut und was nicht. Dann:

• Verhalten hinter einer Schnittstelle einfrieren. Eine exportierte Funktion oder Klasse reicht. Lassen Sie das Innere vorerst unordentlich; die Außenseite soll einfach sein.
• In kleinen Commits verschieben. Aktualisieren Sie Importe schrittweise. Falls Sie umbenennen müssen, tun Sie das nach dem Verschieben, damit Diffs lesbar bleiben.
• Nach jedem Schritt prüfen. Starten Sie die App und die Tests. Wenn es keine Tests gibt, machen Sie eine kurze manuelle Überprüfung des betroffenen Flows.
• Alten Code zuletzt löschen. Erst wenn Sie nachweisen können, dass nichts mehr davon abhängt (Import-Suchen, Laufzeit-Logs, keine Duplikate mehr), entfernen Sie ihn.
• Ein paar fokussierte Tests an der Grenze hinzufügen. Ein Happy Path, ein Randfall und ein Fehlerfall genügen meist.

Beispiel: Sie finden drei verschiedene Dateien, die auf leicht unterschiedliche Weise beantworten „is the user logged in?“. Erstellen Sie ein authSession-Modul mit getSession() und requireUser(). Lassen Sie diese Funktionen zunächst den alten Code aufrufen. Verschieben Sie dann die Logik ins Modul, aktualisieren Sie die Aufrufer einzeln und fügen Sie 2–3 Tests hinzu, die die erwarteten Ergebnisse sichern.

Die Extraktion deckt auch versteckte Kopplungen auf: Globals, vermischte Verantwortlichkeiten, geheime Werte in zufälligen Dateien und „temporäre“ Hilfen, die dauerhaft wurden.

Wie man den Refactor mit inkrementellen PRs ausliefert

Diese Arbeit ist am sichersten, wenn Sie sie als Serie kleiner Lieferungen behandeln, nicht als einen großen Rewrite. Inkrementelle PRs halten die Blast-Radius klein. Wenn etwas kaputtgeht, finden Sie es schnell und können ohne Panik zurückrollen.

Halten Sie PRs klein und langweilig

Zielen Sie auf eine Art Änderung pro PR: verschieben Sie einen Ordner, benennen Sie eine Gruppe von Dateien um oder extrahieren Sie ein Modul. Wenn Sie denken „ich repariere hier auch gleich noch ein paar Dinge“, notieren Sie es und machen Sie es später.

Machen Sie zuerst mechanische Änderungen: Moves, Umbenennungen, Formatierungen, Importpfad-Updates. Sie sind leicht zu reviewen, weil das Verhalten gleich bleibt.

Wenn die Struktur stabil ist, kommen Verhaltensänderungen in separaten PRs (Logikfixes, Datenform-Änderungen, Fehlerbehandlung). Struktur- und Verhaltensänderungen zu mischen ist der Weg, wie Refactors in Mystery-Bugs münden.

Schreiben Sie PR-Beschreibungen, die Reviewer das Verifizieren erleichtern

Fügen Sie bei der PR hinzu:

• Was sich geändert hat (ein Satz)
• Das Risiko (was kaputtgehen könnte und wo)
• Wie zu verifizieren ist (kurzer manueller Test + automatische Checks)
• Rollback-Plan (meistens „diese PR revertieren“)

Beispiel: „Auth-bezogenen Code nach modules/auth verschoben und Importe aktualisiert. Risiko: Login-Routen-Wiring. Verifizieren: signup, login, logout, session-refresh.“

Wenn mehrere Leute arbeiten, einigen Sie sich auf eine Reihenfolge, die Konflikte vermeidet. Mergen Sie Boundary-PRs zuerst und dann die Extraktionen, die auf dem neuen Layout aufbauen. Benennen Sie Verantwortliche, damit nicht zwei Personen dieselben Hot-Change-Dateien gleichzeitig bearbeiten.

Verhalten stabil halten, während sich die Struktur ändert

Das Ziel ist langweilig: Die App soll sich für Nutzer gleich verhalten. Die meisten Refactors scheitern, weil kleine Verhaltensänderungen unbemerkt einschleichen.

Beginnen Sie mit Smoke-Checks, die dem Produktgebrauch entsprechen. Halten Sie die Liste kurz, damit Sie sie beim Refactor wirklich ausführen:

• Signup, Login, Logout (und Passwort-Reset)
• Erstellen des Hauptobjekts der App (Order, Post, Projekt, Ticket)
• Update und Löschen dieses Objekts
• Eine Geldaktion (Checkout, Rechnung, Abo-Änderung), falls vorhanden
• Eine Nachrichtenaktion (E-Mail, Notification, Webhook), falls vorhanden

Tests sind Fallen, nicht Perfektionsprojekt. Wenn die Coverage schwach ist, schreiben Sie 2–5 hochwirksame Tests rund um die obigen Flows und hören Sie dann auf. Ein paar End-to-End- oder Integrations-Tests fangen meist mehr Refactor-Fehler als Dutzende kleine Unit-Tests.

Achten Sie auf stille Fehler. Auth kann ohne offensichtliche Fehler brechen (Cookies, Session-Storage, Redirect-Pfade). Zahlungen und E-Mails können „erfolgreich“ fehlschlagen, wenn Callbacks nicht verbunden sind oder Background-Jobs nicht laufen. Queues können Tasks verlieren, wenn Job-Namen oder Importpfade sich beim Extrahieren ändern.

Machen Sie Fehler schnell sichtbar. Stellen Sie sicher, dass Logs und Errors an einem Ort sichtbar sind und genügend Kontext enthalten (User-ID, Request-ID, Job-Name). Fügen Sie während des Refactors ein paar gezielte Logzeilen an kritischen Grenzen hinzu (Auth, Billing, ausgehende E-Mails) und entfernen Sie sie, sobald sich alles eingependelt hat.

Häufige Fallen, die Refactors entgleisen lassen

Die meisten Refactors scheitern, wenn viele kleine Änderungen sich anhäufen, bis niemand mehr weiß, was sicher ist. Achten Sie frühzeitig auf diese Fallen.

Die „es baut noch“ Falle

Dateien zu verschieben fühlt sich harmlos an, besonders wenn Tests grün sind. Wenn Sie jedoch verschieben, ohne eine öffentliche Schnittstelle zu definieren, brechen Sie Imports oder zwingen alle dazu, „nur den Pfad zu aktualisieren“ an Dutzenden Stellen.

Ein sichereres Muster ist, stabile Einstiegspunkte beizubehalten (z. B. eine index-Datei pro Modul, die die öffentliche API definiert) und interne Pfade hinter dieser Schnittstelle zu ändern.

Vermeiden Sie außerdem, als Quickfix neue Junk-Ordner zu schaffen. Ein frisches misc oder utils wird in einer Woche zum gleichen Problem. Wenn etwas kein klares Zuhause hat, ist das ein Signal, dass Ihre Grenzen unklar sind.

Versteckte Hintertüren zwischen Modulen

Ein Extrakt ist nicht abgeschlossen, sobald Dateien verschoben sind. Er ist abgeschlossen, wenn das Modul alleinstehend funktioniert.

Übliche Hintertüren sind Cross-Imports (Modul A importiert leise Modul B) und geteilte Globals (Config-Objekte, Singletons, veränderliche Caches), die Code erlauben, über Grenzen hinwegzugreifen.

Fallen, die Reviews oft ruinieren:

• Viele Dateien und Symbole gleichzeitig umbenennen, während Ordner verschoben werden
• Refactor-Arbeit mit neuen Features mischen
• Alte und neue API „vorübergehend“ lassen und die alte Pfade nie entfernen
• Eine gigantische PR, die Reviewer nur überfliegen können
• Unbeabsichtigte Verhaltensänderungen (z. B. Auth-Code verschieben und Middleware-Reihenfolge ändern)

Beispiel: Ein Team extrahiert ein auth-Modul, aber einige Screens importieren noch ein gemeinsames currentUser-Global aus dem alten Ordner. Alles sieht in Tests gut aus, bis in Produktion ein Cold-Start Module in anderer Reihenfolge lädt.

Kurze Checkliste für jede Refactor-PR

Kleine PRs sind der Weg, Struktur neu zu organisieren, ohne die Produktion in ein Ratespiel zu verwandeln.

Bevor Sie die PR öffnen

Wenn Sie die Änderung nicht in zwei Sätzen erklären können, ist die PR wahrscheinlich zu groß.

• Beschränken Sie den Scope auf eine Grenzkorrektur, eine Umbenennungsgruppe oder einen Modul-Move.
• Listen Sie Einstiegspunkte auf, die Sie beeinflussen könnten (Routen, CLI-Commands, Background-Jobs, Importe aus anderen Paketen).
• Notieren Sie einen Rollback-Plan (meistens „diese PR revertieren“; manchmal eine Kompatibilitäts-Export-Lösung für eine Release).
• Führen Sie lokal Lint und Tests aus und notieren Sie 2–3 Smoke-Checks.
• Bestätigen Sie, dass sich das Verhalten nicht ändert, es sei denn, der PR-Titel sagt explizit, dass er es tut.

Konkretes Beispiel: Wenn Sie Auth-Helper in ein neues Modul verschieben, nennen Sie Login-Route, Token-Refresh und Middleware-Imports als Einstiegspunkte. Smoke-Checks: anmelden, abmelden, token-refresh, geschützte Seite laden.

Nachdem Sie die PR geöffnet und gemerged haben

Machen Sie einen kurzen Sanity-Check, bevor Sie zum nächsten Schritt übergehen:

• Prüfen Sie, dass Sie keine zirkulären Imports eingeführt haben (Build + Dependency-Check zeigen das meist).
• Entfernen oder benennen Sie temporäre Ordner, die beim Verschieben entstanden sind, in ihr finales Zuhause um.
• Stellen Sie sicher, dass das Team sich einig ist, wo neue Dateien jetzt hingehen (ein kurzer Kommentar in der PR reicht oft).
• Aktualisieren Sie einfache Notizen: eine kurze README im Ordner oder ein Kommentar, der den Ordnerzweck erklärt.
• Bestätigen Sie, dass die PR nicht heimlich öffentliche APIs verändert hat (Exports, Dateipfade, die andere importieren).

Nächste Schritte: Momentum halten (und wissen, wann man Hilfe holt)

Wählen Sie eine kleine, reale Funktion und nutzen Sie sie als Proof-Pfad. Wenn Sie von einem AI-generierten Prototyp starten, ist ein üblicher Anfang: Auth-Prüfungen aus UI-Komponenten ziehen, Datenzugriff in ein Modul sammeln und die UI auf Darstellung reduzieren.

Refactoren Sie zuerst einen vertikalen Slice und verschieben Sie den Rest nach hinten. Beispiel: machen Sie „Sign in -> Account laden -> Dashboard anzeigen“ langweilig und vorhersehbar. Ziehen Sie Auth-Prüfungen an einen Ort, bündeln Sie Datenzugriff in ein Modul und halten Sie die UI auf Darstellung fokussiert. Größere Debatten (große Ordnerumbenennungen, Framework-Wechsel, perfekte Domain-Modellierung) führen Sie später, wenn Sie Momentum und ein Sicherheitsnetz haben.

Erklären Sie den Plan Nicht-Technikern, indem Sie mit dem beginnen, was stabil bleibt: Bildschirme, Preislogik, Kundendaten. Erklären Sie dann, was sich intern ändert: weniger Produktionsüberraschungen, klarere Verantwortlichkeiten und sicheres Secret-Handling.

Holen Sie sich oft Hilfe, wenn der Code tief verwoben ist (alles importiert alles), Sie Sicherheitswarnungen sehen (exponierte Keys, unsichere Queries) oder Auth bereits unzuverlässig ist. Wenn Ihr Codebestand von Tools wie Lovable, Bolt, v0, Cursor oder Replit stammt und Sie mehr Zeit mit Entwirren verbringen als mit Bauen, kann FixMyMess (fixmymess.ai) ein kostenloses Audit durchführen, die riskantesten Bereiche identifizieren und die sicherste Reihenfolge zum Beheben vorschlagen, bevor Sie alles verschieben.