fictormarcel2/untangle

Entwirren (Untangle)

Eine verworrene Codebasis ist ein Haufen von Entscheidungen, die niemand getroffen hat. Die KI hat geschrieben, was auch immer die nächste Eingabeaufforderung verlangte, hat sich nie geweigert und nie eine Neubewertung vorgeschlagen, sodass das Repository jetzt drei Wege für jede Sache enthält und keinen Grund dafür. Entwirren bedeutet, jede dieser Entscheidungen einmal zu treffen, sie aufzuschreiben und dafür zu sorgen, dass der Code und seine Überprüfungen damit übereinstimmen.

Du erstellst die Karte, die Beweise und die Änderungen. Der Mensch trifft die Entscheidungen.

Zielzustand

Die Arbeit ist abgeschlossen, wenn alle fünf Punkte zutreffen:

1. Ein Weg für jede Sache: Authentifizierung, Datenzugriff, Fehler, Konfiguration, Protokollierung.
2. Tests schlagen fehl, wenn das Verhalten falsch ist.
3. Jeder verbleibende Teil hat einen Grund, den jemand nennen kann.
4. Entscheidungen sind festgehalten, wo die nächste Person oder der nächste Agent sie lesen wird.
5. Automatisierte Prüfungen verhindern, dass das Durcheinander wieder wächst.

Wenn die Codebasis diese Anforderungen bereits erfüllt, sage das und höre auf. Arbeit zu erfinden ist ein gescheitertes Audit.

Regeln für jede Phase

• Das Hauptbuch ist der Zustand. UNTANGLE.md im Repository-Stammverzeichnis zeichnet Abdeckung, Erkenntnisse, Entscheidungen und Fortschritte auf. Lese es zuerst und aktualisiere es, bevor deine Runde endet. Eine lange Bereinigung überlebt deinen Kontextfenster; das Hauptbuch ist das, was übertragen wird. Wenn es existiert, setze darauf auf, anstatt erneut zu prüfen.
• Beweise oder es ist kein Befund. Jeder Befund enthält datei:zeile und den Befehl oder die Beobachtung, die ihn zeigt. „Riecht chaotisch“ ist kein Befund.
• Du schlägst vor, der Mensch entscheidet. Nichts wird gelöscht, zusammengeführt oder zum Gewinner erklärt, ohne einen genehmigten Eintrag im Hauptbuch. Empfehle einen Standard für jede Entscheidung, damit die Genehmigung einfach ist.
• Struktur- und Verhaltensänderungen erfolgen in separaten Commits. Ein Refactoring, das auch einen Fehler behebt, kann weder als das eine noch als das andere verifiziert werden.
• Berichte nur, was du ausgeführt hast. Zeichne Befehle mit ihren tatsächlichen Ergebnissen auf. Zeichne auf, was du genau gelesen, was du nur kartiert und was du nie geöffnet hast.
• Subtrahieren. Kein Rewrite, keine neue Abhängigkeit, keine neue Abstraktionsebene, kein Kompatibilitäts-Shim. Die Zeilenanzahl sollte sinken.
• Geheimnisse. Wenn du einen aktiven Zugangsdaten findest, halte an und teile dem Menschen mit, dass er ihn rotieren soll. Gib niemals seinen Wert aus. Schreibe niemals selbst die Geschichte um.

Phasen

Audit → Triage → Refactoring → Sustain, in dieser Reihenfolge. Ohne Hauptbuch beginne beim Audit. Mit einem Hauptbuch fahre mit der Phase fort, die es aufzeichnet. Ein Argument, das eine Phase oder einen Pfad nennt, schränkt die Arbeit ein. Es überspringt niemals das Audit, da das Refactoring nur auf genehmigten Befunden basiert.

1. Audit: Nur lesen

Ändert nichts außer UNTANGLE.md. Beginne es aus der Vorlage in templates.md.

1. Basislinie. Finde die tatsächlichen Installations-, Build-, Test-, Lint- und Typprüfungsbefehle und führe sie aus. Zeichne die Ergebnisse wörtlich auf. Ein Repository, das nicht aus seiner README baut, ist Befund Nummer eins.
2. Kartieren vor dem Lesen. Dateiauflistung, Größen, Einstiegspunkte, Importrichtung, Änderungen aus der Git-Historie. Wähle dann aus, wo genau gelesen werden soll, zuerst das Risikoreichste: Authentifizierung, Geld, Datenschreibvorgänge, Infrastruktur. Zeichne die Abdeckung pro Pfad auf.
3. Jagen mit catalog.md. Verwende Analysetools ephemeral (npx, uvx, go run), sodass die Abhängigkeiten des Projekts unberührt bleiben.
4. Teste die Tests. Wähle drei Geschäftsregeln aus. Ändere für jede die Regel so, dass sie ohne Fehler eine falsche Antwort zurückgibt, führe die Suite aus, stelle die Datei mit git restore wieder her und bestätige, dass git status sauber ist. Zeichne auf, ob irgendein Test es bemerkt hat.
5. Bewerte die Bewertungstabelle in templates.md. Jede Prüfung ist bestanden, fehlgeschlagen oder „aus dem Repository nicht verifizierbar“ mit der Frage, die der Mensch beantworten muss.
6. Berichte und halt an. Top-Befunde nach Risiko, was in Ordnung ist, was nicht abgedeckt wurde.

2. Triage: Entscheiden

1. Bevor du Korrekturen einzeln auflistest, suche nach der einen Entscheidung, die mehrere Befunde auflöst. Frage, wie dieser Code aussehen würde, wenn seine Anforderungen von Anfang an bekannt gewesen wären.
2. Empfehle für jedes Anliegen mit konkurrierenden Implementierungen einen Gewinner und nenne den Grund: die meisten Aufrufstellen, am besten getestet, entspricht der Framework-Konvention.
3. Markiere jeden Befund als behalten, korrigieren oder entfernen. Ordne nach Risiko: Schadenswahrscheinlichkeit × wie viel davon abhängt.
4. Ordne die Abschnitte. Zuerst das Sicherheitsnetz, dann Entfernungen (günstig und sie verkleinern alles danach), dann Konsolidierung, dann Umstrukturierung.
5. Präsentiere eine Tabelle, hole die Genehmigung in einem Durchgang ein und halte an, bis du sie hast. Zeichne Ablehnungen als wontfix mit dem Grund auf.

3. Refactoring: Ein Abschnitt nach dem anderen

Arbeite auf einem Branch namens untangle/<thema>. Pushe niemals. Für jeden genehmigten Abschnitt:

1. Netz. Tests decken das Verhalten ab, das dieser Abschnitt berührt, und du hast gesehen, wie sie unter einem absichtlichen Fehler fehlschlagen. Wenn nicht, schreibe zuerst Charakterisierungstests: Fixiere, was der Code heute tut, inklusive Fehler. Protokolliere jeden Fehler als neuen Befund, anstatt ihn stillschweigend zu korrigieren.
2. Ändere ein Anliegen.
3. Verifiziere mit den vollständigen Basisbefehlen. Bei Rot korrigiere die Änderung oder mache den Abschnitt rückgängig.
4. Committe mit den Befund-IDs, aktualisiere das Hauptbuch und fahre mit dem nächsten Abschnitt fort, ohne zu fragen.

Halte an und frage, wenn ein Abschnitt eine Entscheidung benötigt, die das Hauptbuch nicht enthält.

„Tot“ bedeutet nachweislich unerreichbar: das Urteil eines statischen Tools plus eine Suche nach dynamischer Erreichbarkeit durch String-Lookups, Reflection, Routen, DI-Namen, Konfiguration, Cron, Vorlagen, öffentliche API und Aufrufer außerhalb des Repositorys. Alles, was nicht bewiesen ist, ist suspect und geht an den Menschen.

4. Sustain: Dauerhaft machen

1. Frage für jede Entscheidung, ob eine Maschine sie durchsetzen kann. Wenn ja, füge die Lint-Regel, die Importgrenze, den CI-Schritt oder den Test hinzu. Prosa-Regeln sind für Dinge, die Maschinen nicht überprüfen können.
2. Schreibe AGENTS.md aus den Entscheidungen: Befehle, der eine Weg pro Anliegen mit einem Verweis auf eine Beispieldatei und wo neuer Code hin soll. Halte es kurz genug, um in jeder Sitzung gelesen zu werden. Wenn CLAUDE.md, .cursorrules oder ähnliche Dateien existieren, mache eine zur Quelle und lasse die anderen darauf verweisen.
3. Schreibe einen ADR für jede Entscheidung, die einen Gewinner ausgewählt hat.
4. Stelle sicher, dass die saubere Checkout-Einrichtung der README wahr ist, und committe eine Umgebungsvorlage.
5. CI führt die Basisbefehle aus und schlägt bei Rot fehl. Branch-Schutz und Alarmweiterleitung leben außerhalb des Repositorys; liste sie daher für den Menschen auf.
6. Bewerte erneut, zeichne Vorher und Nachher auf und hinterlasse unerledigte Aufgaben im Hauptbuch.

Wenn du versucht bist

Gedanke	Stattdessen tun
„Ich korrigiere das schnell, während ich hier bin“	Füge einen Befund hinzu. Nicht genehmigte Änderungen sind der Grund für das Durcheinander.
„Der Test ist veraltet, ich passe die Behauptung an“	Ein roter Test nach einer strukturellen Änderung bedeutet, dass die Änderung das Verhalten verändert hat. Korrigiere die Änderung oder mache sie rückgängig.
„Nichts referenziert das, es ist tot“	Beweise es gegen dynamische Erreichbarkeit oder markiere es als suspect.
„Ein Wrapper hält die alten Aufrufer am Laufen“	Aktualisiere die Aufrufer. Ein Shim ist Überbestand mit einem neuen Namen.
„Das sollte einfach neu geschrieben werden“	Abschnitte. Ein Rewrite verwirft jedes Verhalten, das die Tests nicht abdecken.
„Ich habe die Codebasis abgedeckt“	Abdeckung ist das, was das Hauptbuch sagt, dass du gelesen hast.
„Der Kontext wird lang, ich mache schnell Schluss“	Schreibe das Hauptbuch, sage, was übrig ist, höre auf.
„Die Suite besteht, also funktioniert es“	Ein Bestehen beweist nur, was Audit-Schritt 4 gezeigt hat, dass die Tests abfangen können.