Codebase Convergence
Ein Repository verständlicher und änderbarer machen, ohne es neu zu gestalten. Bevorzuge Evidenz, eine schmale Schnittstelle und lokale Korrekturen gegenüber spekulativen Abstraktionen.
Leitplanken
- Gib vor einer mehrstufigen Änderung den Umfang, Annahmen, geschützte Inhalte und Erfolgskontrollen an.
- Lies Repository-Anweisungen, das Domänenglossar und relevante ADRs, bevor du die Architektur beurteilst. Verwende die Domänennamen des Repositorys.
- Bearbeite nur Dateien, die die Anfrage betreffen. Erhalte nicht zusammenhängende Benutzeränderungen und entferne nur Imports, Code oder Docs, die durch diese Arbeit obsolet geworden sind.
- Behandle explizit geschützte Domänentexte, Titel, Datendefinitionen und benutzerdesignierte Kopien als gesperrt. Halte sie wörtlich. Ist ihr Status unklar, nimm sie in das Entscheidungspaket auf, anstatt sie zu bearbeiten.
- Ändere keinen numerischen Wert oder seine Darstellung – Konfiguration, Schwellwert, Gleichgewicht, Rate, Grenze oder dokumentierter Wert – ohne explizite Zustimmung.
- Ändere nicht stillschweigend eine Geschäftsregel, einen Zustandsübergang, ein Interaktionsverhalten, eine öffentliche Schnittstelle oder einen visuellen Vertrag. Behandle es als Entscheidung, es sei denn, der Fix ist direkt impliziert und verhaltensbewahrend.
- Halte eine einzige Quelle der Wahrheit für jede Tatsache ein. Erstelle keine Dokumentation, die lediglich ein anderes Dokument wiederholt.
Arbeitsablauf
1. Baseline ermitteln
- Überprüfe den Arbeitsbaum und identifiziere nur den angeforderten Bereich. Notiere nicht zusammenhängende Änderungen; stelle sie nicht bereit und ändere sie nicht.
- Kartiere die relevanten Codepfade, Zustands-/Datenverantwortung, UI-Ablauf, Tests und Markdown-Dateien. Lies die Dokumente, die derzeit die Domäne und Entscheidungen definieren, vor den Dateien, die sie implementieren.
- Halte jeden Befund mit Beweisen fest: Dateien, widersprüchliche Aussagen oder Pfade, Benutzerauswirkungen und ob es sicher ist, ihn direkt zu beheben.
- Klassifiziere Befunde:
- Direkte Konvergenz: Duplizierung, veraltete Links, widersprüchlicher nicht gesperrter Text oder ein lokalisierter Implementierungs-/UI-Fehler mit verhaltensbewahrendem Fix.
- Entscheidung erforderlich: jeder numerische Wert, Regel, Verhalten, geschützter Inhalt, öffentliche Schnittstelle oder mehrdeutige Quelle der Wahrheit.
- Architekturkandidat: ein potenziell tieferes Modul oder eine Änderung, deren Naht noch nicht vereinbart ist.
2. Einmalig nach materialen Entscheidungen fragen
Schließe die Erkundung ab, bevor du Fragen stellst. Sende ein Entscheidungspaket, das jeden nicht aufgelösten Punkt enthält; tröpfle keine Fragen über mehrere Schritte.
Für jedes numerische Element gib seinen Bezeichner und Dateien, aktuelle Werte, Beweise für die Inkonsistenz, Auswirkungen und eine Empfehlung an oder sage klar, dass kein Wert vorgeschlagen wird. Bearbeite, normalisiere, verschiebe oder entferne den betroffenen numerischen Ausdruck nicht, bis der Benutzer ihn explizit genehmigt.
Füge andere materielle Unsicherheiten in das gleiche Paket ein: Status gesperrter Inhalte, Verhaltensentscheidungen, Konflikte der Zuständigkeit und Architekturentscheidungen. Fahre unterdessen mit unabhängiger direkter Konvergenz fort, während die Genehmigung aussteht.
3. Direkte Konvergenz anwenden
Halte jede Änderung chirurgisch und auf einen Befund zurückführbar.
Dokumentation
- Gib jedem Dokument eine Verantwortung. Respektiere bestehende Konventionen; ansonsten behalte das Minimum: Übersicht über den Einstiegspunkt, Architektur-/Systemkarte, Domänen- oder Produktregeln, Entscheidungen und aktuellen Stand/Arbeit.
- Führe überlappende PRDs, Pläne und Arbeitsprotokolle zusammen, indem du den autoritativen Inhalt einmal beibehältst. Verschiebe dauerhafte Begründungen in die Entscheidungsaufzeichnungen des Projekts und halte den Betriebsstatus kurz.
- Bewahre gesperrte Blöcke beim Verschieben wörtlich. Wenn eine Zusammenführung einen gesperrten Block oder einen numerischen Ausdruck verändern würde, lasse diesen Teil zur Genehmigung stehen.
- Entferne Wiederholungen, veraltete Verweise und widersprüchliche nicht gesperrte Erklärungen. Aktualisiere Links nach Verschiebungen und vermeide zusammenfassende Dokumente, die Spezifikationen duplizieren.
Code und UI
- Verfolge eine Benutzeraktion durch die Zustandsverantwortung bis zum gerenderten Ergebnis, bevor du UI-Code bearbeitest.
- Behebe konkrete Inkonsistenzen: duplizierter Präsentationszustand, nicht übereinstimmende Ereignis-/Datenamen, ungültiger bedingter Ablauf, toter Code, der durch diese Änderung entstanden ist, oder eine Komponentenverantwortung, die einen lokalen Fix blockiert.
- Halte Layout, Interaktion, Barrierefreiheit und reaktionsfähiges Verhalten stabil, es sei denn, der Benutzer genehmigt eine Produkt- oder visuelle Änderung.
- Bevorzuge einen klaren Eigentümer eines Zustandsübergangs und eine kanonische Darstellung von Daten. Führe keine Abstraktion, Konfiguration oder Fehlerbehandlung ohne einen nachgewiesenen Bedarf ein.
4. Architekturkandidaten separat bewerten
Verwende diese Begriffe konsistent:
- Modul: eine Einheit mit Schnittstelle und Implementierung.
- Schnittstelle: alles, was Aufrufer wissen müssen, einschließlich Invarianten und Fehlermodi.
- Naht: wo Verhalten geändert werden kann, ohne Aufrufer zu bearbeiten.
- Tiefe: Hebelwirkung aus substanziellem Verhalten hinter einer schmalen Schnittstelle; Lokalität: zusammenhängendes Wissen und Änderungen bleiben zusammen.
Wende den Löschtest an: Wenn das Löschen eines Moduls seine Komplexität lediglich in die Aufrufer verschiebt, rechtfertigt es seinen Bestand; wenn Komplexität verschwindet, ist es wahrscheinlich flach. Erzeuge keine Naht für nur einen Adapter.
Für einen Kandidaten, der eine Schnittstelle, ein Verhalten oder eine Verantwortung ändert, implementiere ihn nicht sofort. Erstelle einen prägnanten, in sich geschlossenen HTML-Bericht im temporären Verzeichnis des Betriebssystems nur, wenn ein visueller Vergleich hilfreich ist. Füge Dateien, Beweise, Vorher-/Nachher-Diagramm, erwartete Lokalität und Hebelwirkung, ggf. ADR-Konflikt und Empfehlungsstärke hinzu. Bitte den Benutzer, einen Kandidaten auszuwählen, bevor du die Schnittstelle entwirfst.
5. Verifizieren und übergeben
- Überprüfe das endgültige Diff auf Umfang, Erhalt gesperrter Inhalte, doppelte Quellen der Wahrheit und unbeabsichtigte Wert- oder Verhaltensänderungen.
- Führe den vorhandenen Formatierer, Linter, Typprüfung, Tests, Build und UI-Überprüfung aus. Füge keine Tools oder breiten Testsuiten ausschließlich für diese Aufgabe hinzu. Unterscheide bereits vorhandene Fehler von eingeführten.
- Bestätige Markdown-Links und -Überschriften nach der Konsolidierung und überprüfe jede geänderte Aussage anhand ihrer kanonischen Quelle.
- Berichte direkte Änderungen, ungelöste Entscheidungspunkte, Verifikationsergebnisse und Risiken in präzisen Worten. Jede geänderte Zeile muss auf die angeforderte Konvergenz zurückgeführt werden können.