Die KI in einem großen Repository erst lesen, dann ändern und nur per Review ausliefern lassen

## Zuerst die Root-Regeln lesen, dann den Leitfaden des Ordners, in dem du arbeitest Das Root-Dokument beschränkt sich auf verbindliche Richtlinien und Weichenstellung; die detaillierten Arbeitsabläufe für jeden Bereich gehören in die jeweiligen bereichsspezifischen Leitfäden. Bevor du in einem Teilbaum arbeitest, lies den dafür zuständigen Leitfaden. ### Ein fester Ort für jede Regelart Verbindliche Richtlinien, bereichsübergreifende Grenzen und die Zuständigkeit der einzelnen Leitfäden gehören ins Root-Dokument. Aufgabenspezifische Abläufe gehören in den bereichsspezifischen Leitfaden direkt neben dem Code, den sie regeln. Beschreibe einen Arbeitsablauf nicht an zwei Stellen, da die Kopien sonst auseinanderlaufen können. ### Code so referenzieren wie im Repository üblich Verweise auf Dateien immer über den repository-relativen Pfad, nicht über einen absoluten Pfad oder einen Pfad im Home-Verzeichnis, damit ein Verweis für jeden Leser dasselbe bedeutet. ## Vor dem Selbstbauen nach einer vorhandenen Bibliothek oder einem Tool suchen Bevor du ein eigenes System, Feature, Tool, eine Integration oder Automatisierung vorschlägst oder baust, prüfe kurz, ob nicht bereits eine vorhandene Bibliothek, ein Plugin oder eine kostenlose Plattform die Aufgabe ausreichend gut löst. ### Der bewährten Option den Vorzug geben Wenn eine vorhandene Option ausreicht, verwende sie. Baue nur dann eine eigene Lösung, wenn die Alternativen ungeeignet, zu teuer, unwartbar, unsicher oder nicht konform sind oder der Nutzer ausdrücklich eine eigene Lösung verlangt hat. ### Die Prüfung schlank halten Das ist eine kurze Vorabprüfung, kein Rechercheauftrag. Empfehle keinen kostenpflichtigen Dienst, ohne dass der Nutzer die Ausgabe freigegeben hat. ## Für Reviews Aufrufer, aufgerufenen Code und Tests lesen, nicht nur den Diff Fixes, Triage und Reviews brauchen eine hohe Sicherheit, die auf tatsächlichem Lesen beruht, nicht auf einer Vermutung anhand der sichtbaren Änderung. Ein reines Diff-Review reicht nicht aus. ### Vor einem Urteil die gesamte betroffene Fläche lesen Bevor du „gut“, „schlecht“, „beste Lösung“ oder „ausreichend belegt“ sagst, lies die gesamte geänderte Funktion oder das gesamte Modul samt aufrufenden und aufgerufenen Stellen, verwandten Implementierungen, angrenzenden Tests, bereichsspezifischer Dokumentation und den Verträgen aller Abhängigkeiten. ### Eine kleine Beleglandkarte erstellen Benenne die geänderte Fläche, ihren Einstiegspunkt, die Zuständigkeitsgrenze, mindestens eine aufrufende und eine aufgerufene Stelle, verwandte Flächen mit derselben Invariante, vorhandene Tests und das aktuell ausgelieferte Verhalten. Fehlt ein Punkt, benenne die Lücke, statt trotzdem ein Urteil zu fällen. ### Bei Widerspruch erst lesen, dann verteidigen Wird ein Urteil infrage gestellt, prüfe zuerst den noch fehlenden Pfad; verteidige die frühere Schlussfolgerung erst, nachdem du nachgesehen hast. ## Den Quellcode von Abhängigkeiten lesen und externe APIs live testen Hängt das Verhalten von einer Bibliothek oder einem externen Dienst ab, prüfe es am echten System, nicht anhand von Erinnerung, einem Wrapper, einem generierten Schema oder dem Bericht eines anderen Agenten. ### Den Quellcode der Abhängigkeit selbst lesen Bei Verhalten, das von einer Abhängigkeit bestimmt wird, lies direkt den Upstream-Quellcode, die Dokumentation oder die Typdefinitionen und gib an, was du geprüft hast. Die meisten Abhängigkeiten sind Open Source, es gibt also keine Ausrede, einen Standardwert, einen Fehler oder ein Timing zu erraten. ### Externe Dienste live testen Arbeit an externen APIs braucht einen Live-Test plus aktuellen, belegten Nachweis; behaupte nichts über eine API aus dem Gedächtnis. Verifiziere live, wo immer möglich, und gib dabei niemals ein Geheimnis preis. ## Prüfen, ob ein Fix der beste ist, nicht nur einer, der funktioniert Ein Review-Urteil muss entscheiden, ob die Änderung die beste Lösung ist, nicht nur eine, die zufällig funktioniert. Vergleiche Zuständigkeitsgrenzen, aufrufende Stellen, verwandte Flächen, Tests und das aktuelle Verhalten, bevor du zu einem Schluss kommst. ### Einseitige Fixes brauchen einen Nachweis für verwandte Flächen Ein Fix, der nur eine Fläche betrifft, nicht aber verwandte Flächen, braucht entweder den Nachweis, dass diese unberührt bleiben, oder eine ausdrückliche Folgeaufgabe, die sie abdeckt. ### Geschmack nicht als Befund einreichen Melde keinen Befund für eine reine Stilvorliebe der Repository-Richtlinie, wenn der geänderte Code seinem bereichsspezifischen Leitfaden folgt und kein für Nutzer sichtbares, laufzeit-, sicherheits- oder wartungsbezogenes Risiko zeigt. ## Konfiguration nur auf eine Art lesen und alte Schlüssel migrieren statt verwerfen Die Laufzeit liest ausschließlich die aktuelle kanonische Form von Konfiguration und Daten. Es gibt keine stillschweigende Kompatibilität für alte oder fehlerhafte Schlüssel. ### Den alten Pfad löschen Bevorzuge einen kanonischen Pfad und lösche den alten, es sei denn, ein ausdrücklich ausgelieferter Vertrag oder ein gekennzeichneter Upgrade-Pfad wird angeführt. Ein Refactoring, das einen zweiten Pfad übrig lässt, ist wahrscheinlich gescheitert. ### Migrieren statt stillschweigend verwerfen Macht eine Änderung bestehende Konfiguration ungültig, füge im dafür vorgesehenen Migrations- oder Reparaturschritt eine passende Migration hinzu; verwirf niemals stillschweigend einen Schlüssel, denn ein verworfener Schlüssel ist eine versteckte Verhaltensänderung. ### Die Konfigurationsfläche klein halten Für die Konfigurations- und Umgebungsfläche gilt eine hohe Hürde. Bevor du eine Option hinzufügst, weise nach, dass das vorhandene Verhalten das Problem nicht lösen kann, und bevorzuge das Entfernen oder Zusammenlegen von Optionen. Behandle dokumentierte Einrichtungsabläufe als kompatibilitätsempfindlich: bevorzuge additive Flags gegenüber dem Brechen bestehender Codeschnipsel. ## Modulspezifischen Code im eigenen Modul halten, nicht im gemeinsamen Code Gemeinsam genutzter Code und Kerncode bleiben generisch; besitzerspezifisches Verhalten gehört in das zuständige Modul. Überschreite eine Grenze nur über eine dokumentierte öffentliche Schnittstelle, niemals durch einen Zugriff auf die internen Details eines anderen Moduls. ### Verantwortung verschieben, nicht umhüllen Die Standardform eines Fixes ist ein sauberes, begrenztes Refactoring, das Logik zum richtigen Zuständigen verschiebt und veraltete Abstraktionen, doppelte Richtlinien und toten Code entfernt – nicht der kleinstmögliche Patch. ### Korrekt, aber nicht überkonstruiert Korrektheit bei echten Eingaben und Zuständen ist Pflicht; zusätzliche Schichten und Absicherungen für nur ausgedachte Eingaben sind Mängel, keine Sorgfalt. Tauschst du einen unwahrscheinlichen Grenzfall gegen echte Einfachheit ein, benenne diesen Kompromiss ausdrücklich, damit er eine Entscheidung ist und kein Versehen. ## Laufzeitzustand im Speicher des Projekts ablegen, nicht in Extra-Dateien Halte den Laufzeitzustand im kanonischen Speicher des Projekts. Verstreue keine Nebendateien für Zustand, Caches, Warteschlangen, Indizes oder temporäre Daten, die eigentlich in den Speicher gehören. ### Migrationen sind für die alte Form zuständig Veraltete Dateispeicher und ausrangierte Formen werden ausschließlich in Migrations- oder Reparaturcode vor der Laufzeit normalisiert; die stabil laufende Anwendung liest niemals von einem Ausweichort. ### Eine Schemaversion niemals im Alleingang erhöhen Eine Änderung der Schemaversion, die ältere Leser nicht vertragen, braucht zuerst eine ausdrückliche Abstimmung mit dem Nutzer und dessen Zustimmung; erhöhe sie niemals eigenmächtig. Eine rein additive Änderung, die ältere Builds noch vertragen, erfordert keine Versionserhöhung. ## Früher ermittelte Fakten wiederverwenden, statt sie bei jeder Anfrage neu zu suchen Ein Hot Path sollte bereits früher ermittelte Fakten weitertragen, statt sie bei jeder Anfrage neu zu ermitteln. ### Einmal auflösen, wiederverwenden Reiche Bezeichner, aufgelöste Pfade und Fähigkeits-Fakten weiter und verwende das vorbereitete Objekt wieder. Behebe wiederholte Ermittlung zur Anfragezeit nicht durch verstreute Caches; verschiebe den kanonischen Fakt nach vorne und entferne die doppelten Nachschlagevorgänge. ### Keine Aktualitätsprüfung in der Schleife Prozessstabile Metadaten wie Installationen, Manifeste und aufgelöste Pfade ändern sich nur bei einem Neustart oder einem ausdrücklichen Neuladen; Hot Paths dürfen die Aktualität deshalb nicht durch erneutes Lesen oder Hashen prüfen. Ein prozesslokaler Cache ist nur dann in Ordnung, wenn er an einen Lebenszyklus gebunden und begrenzt ist. ## Kurzen, gut lesbaren Code mit strengen Typen schreiben Halte die strenge Typprüfung aktiv und den Code ehrlich. Ziel ist kleiner, klarer Code, nicht der kleinstmögliche Diff. ### Grenzen typisieren, Verzweigungen abschließen Vermeide den dynamischen Auffangtyp; bevorzuge echte Typen und schmale Adapter. Validiere externe Eingaben mit einem Schema. Verzweige anhand diskriminierter Unions oder abgeschlossener Ergebniscodes statt freier Strings oder Sentinel-Werte, und mache unmögliche Zustände unrepräsentierbar. ### Für Lesbarkeit strukturieren Bevorzuge frühe Rückgaben gegenüber verschachtelten Pyramiden und gliedere die Arbeit in Sammeln, Normalisieren, Entscheiden und Ausführen. Halte Aufrufstellen unspektakulär: komplexe Entscheidungen finden weiter oben statt, sodass Argumente Namen, Literale oder einfache Lesevorgänge bleiben. ### Das Nicht-Offensichtliche kommentieren Ein Inline-Kommentar rechtfertigt sich bei einer nicht offensichtlichen Invariante, einer Reihenfolgebedingung, einer Zuständigkeitsgrenze oder einer Aufräum-Kopplung: ein bis drei Zeilen, die erklären, warum die Verzweigung existiert und was ohne sie kaputtgeht. Keine Nacherzählung der Syntax. ## Wird Code durch ein Refactoring länger, kürzen oder begründen Ein Refactoring sollte etwa so viel lokale Komplexität entfernen, wie es hinzufügt. Eine positive Zeilenbilanz im Produktivcode ist ein Warnsignal, das begründet werden muss, kein Normalfall, den man einfach hinnimmt. ### Vor dem Abschluss den Umfang prüfen Bevor du ein nicht-triviales Refactoring abschließt, vergleiche den Umfang der Änderung; ist der Nicht-Test-Code gewachsen, kürze ihn oder erkläre klar, warum weniger Pfade jetzt mehr Zeilen kosten. ### Neue Flächen müssen sich lohnen Ein neuer Helfer oder eine neue Datei muss sofort Aufrufpfade, Konzepte oder wiederholte Logik reduzieren. Füge keinen hinzu für einmalige Kompatibilität, das Umbenennen von Feldern oder spekulative Ausfallsicherheit. Halte öffentliche Schnittstellen schmal und gib die kleinstmögliche nützliche Form zurück. ## Verhalten statt Wortlaut testen und jeden Test isoliert halten Tests belegen Verhalten und schützen vor Regressionen; sie sind keine Checkbox für jede interne Verzweigung. ### Verhalten testen, nicht Formulierungen Bevorzuge Verhaltenstests gegenüber dem Durchsuchen von Dokumentation oder Richtlinien-Strings, und platziere Hinweise für Betreiber in der Dokumentation statt in Testassertions. Prüfe neue Tests vor dem Merge und lösche wertarme Tests, einschließlich solcher für gerade entfernte Pfade. ### Tests isoliert und ehrlich halten Räume Timer, Umgebungsvariablen, globale Zustände, Mocks und temporären Zustand auf. Ein Mock muss jede Bindung exportieren, die der echte Code verwendet, einschließlich Fehlertypen, die bei Identitätsprüfungen genutzt werden. Bearbeite eine Baseline- oder Snapshot-Datei nicht ohne Freigabe, nur um eine Prüfung zum Schweigen zu bringen. ### Auf einer Kopie des echten Zustands testen Wenn realistische Daten wichtig sind, kopiere den Zustand an einen temporären Ort und teste die Kopie; verändere niemals den Zustand eines Live-Dienstes direkt vor Ort ohne ausdrückliche Freigabe. ## Nicht vertrauenswürdigen Code nie lokal ausführen und schwere Builds an den Remote-Runner senden Bewerte das Vertrauen in die Quelle, bevor du entscheidest, wie viel Nachweis nötig ist, und wähle den Ausführungsort des Nachweises anhand desselben Vertrauens. ### Nicht vertrauenswürdigen Code niemals lokal ausführen Vertrauenswürdige Quellen dürfen lokal einige gezielte Tests und günstige statische Prüfungen ausführen, wenn die Abhängigkeiten bereitstehen. Nicht vertrauenswürdiger oder von außen beigetragener Code führt lokal keine eigenen Skripte, Tests, Hooks oder Konfigurationen aus, unabhängig vom Umfang des Nachweises; nutze stattdessen eine isolierte Ausführung ohne Zugangsdaten. ### Aufwendige Arbeit an den Remote-Runner senden Vollständige Testsuiten, Builds, Typprüfungen, Paketierung und plattformübergreifende Nachweise gehen an einen Remote-Runner, der erst beim ersten aufwendigen Befehl bezogen, für eine Sitzung wiederverwendet und vor der Übergabe wieder freigegeben wird. Ist der Remote-Runner nicht verfügbar, darf vertrauenswürdige Arbeit auf lokal ausweichen; nicht vertrauenswürdige Arbeit niemals. ### Den Merge an ein frisches Review knüpfen Führe vor dem Merge ein frisches automatisiertes Review durch, bis keine umsetzbaren Befunde mehr übrig sind; merge nicht allein aufgrund einer grünen Continuous Integration, außer der Umfang ist trivial oder der Nutzer verzichtet ausdrücklich darauf. Ist ein Nachweis blockiert, benenne genau, was fehlt und warum. ## Issues und Pull Requests nach dem Ablauf des Projekts öffnen und Releases freigeben lassen Eine gemeinsam genutzte Fläche zu ändern ist ein sozialer Akt: folge dem Beitragsprozess des Projekts und hole für jeden nicht umkehrbaren Schritt eine Freigabe ein. ### Dem Review- und Merge-Prozess folgen Lies den Beitragsleitfaden, die Issue- und Pull-Request-Vorlagen sowie die Code-Owners-Datei, bevor du irgendetwas eröffnest. Eröffne bei Bugs, nutzerseitig sichtbaren Features und Architekturentscheidungen zuerst ein Issue. Schreibe eine echte Pull-Request-Beschreibung mit Problem, Auswirkung und Beleg, und überprüfe den Live-Zustand über das plattformeigene Tool, bevor du irgendetwas veränderst. ### Nichts Unumkehrbares ungefragt tun Vergib keine Labels, ändere keinen Titel, rebase nicht und merge nicht, ohne darum gebeten worden zu sein. Zeige einen öffentlichen Kommentar zuerst als Entwurf, außer der Nutzer hat ausdrücklich gebeten, ihn zu veröffentlichen, und nenne bei jedem veröffentlichten Kommentar den zugehörigen Link. Schließe die Arbeit an Issues und Pull Requests mit der vollständigen URL des Elements ab. ### Sauber committen und branchen Committe nur die beabsichtigten Dateien mit knappen, gruppierten Nachrichten, rebase vor dem Push auf den aktuellen Hauptzweig und lösche oder benenne niemals unerwartete Dateien um. Halte die Dokumentation innerhalb derselben Änderung mit dem Verhalten synchron und überlasse den Release-Changelog dem Release-Prozess. ### Freigabe für Releases und Geheimnisse einholen Releases, Versionserhöhungen sowie Änderungen an Abhängigkeiten oder Lockfiles brauchen eine ausdrückliche Freigabe. Committe niemals echte Zugangsdaten oder Live-Konfiguration, und bewahre Geheimnisse im dafür vorgesehenen Speicher auf.