Einen Programmieragenten an die Regeln eines großen Repositorys mit Frontend und Backend halten

## Vor jedem Push die Prüfungen vor dem Commit bestehen Führe die Prüfsuite des Repositorys, die vor dem Commit greift, immer über alle Dateien aus, bevor du Commits pushst. Die fortlaufende Integration schlägt fehl, wenn diese Prüfungen fehlschlagen; das ist also eine nicht verhandelbare Schranke und keine Frage der Vorliebe. So läuft es effizient ab: - Merke die Änderungen zuerst zum Commit vor. Die Prüfungen betrachten ausschließlich vorgemerkte Dateien, eine nicht vorgemerkte Änderung wird also stillschweigend übersprungen. - Für eine schnelle innere Schleife führe die Suite nur über die vorgemerkten Dateien aus oder rufe einen einzelnen benannten Hook auf (Typprüfer, Formatierer, Linter). Den vollständigen Durchlauf über alle Dateien führe vor dem Push aus, der einen Pull Request eröffnet oder aktualisiert. - Aktiviere vor dem Ausführen die virtuelle Umgebung oder die Werkzeugkette des Projekts. Die üblichen Speicherorte unterscheiden sich je nach Entwicklerin und Entwickler; wird der Befehl nicht gefunden, frage die Nutzerin oder den Nutzer, welche Umgebung zu aktivieren ist, statt einen Pfad zu raten. - Manche Hooks korrigieren automatisch (Formatierer, abschließende Leerzeichen). Merke die korrigierten Dateien erneut vor und lasse den Lauf noch einmal durchlaufen, denn der erste Lauf meldet Fehler, die er bereits behoben hat. Rechne mit drei Fehlerklassen: Formatierungsprobleme, die automatisch behoben werden; Fehler des Typprüfers, die manuell behoben werden müssen; und Lint-Fehler, die ebenfalls manuell behoben werden müssen. ## Neuen Code nach den Mustern schreiben, auf die das Repository umstellt Mehrere Umstellungen laufen derzeit aktiv. Code, der dem alten Muster entspricht, existiert weiterhin; sein Vorhandensein ist aber keine Erlaubnis, mehr davon zu schreiben. Neuer und geänderter Code folgt dem Zielmuster. - Typisiertes Frontend: keine `any`-Typen als Notausstieg und keine neuen untypisierten Skriptdateien — schreibe im typisierten Dialekt und verwende vorhandene Typdefinitionen wieder. - Gemeinsame Komponentenschicht: Beziehe UI-Komponenten aus dem projekteigenen Designsystem-Paket statt direkt aus der Fremdbibliothek, bevorzuge die Gestaltungsvariablen des Designsystems gegenüber den überkommenen und verzichte auf maßgeschneidertes CSS zugunsten der von der Komponentenbibliothek unterstützten Gestaltungsmöglichkeiten. - Testpyramide: Bevorzuge Modultests gegenüber Integrationstests und Integrationstests gegenüber Ende-zu-Ende-Tests. Schreibe neue Ende-zu-Ende-Tests im eingeführten Rahmenwerk; das abgelöste Ende-zu-Ende-Rahmenwerk gilt als veraltet und wird entfernt, sobald die Umstellung abgeschlossen ist. - Typisierung im Backend: Aller neue Code trägt Typangaben, Modelle verwenden ordentliche Annotationen, und der Typprüfer muss fehlerfrei durchlaufen. - Umstellung der Bezeichner: Neue Modelle verwenden undurchsichtige eindeutige Bezeichner als Primärschlüssel, öffentliche Programmierschnittstellen geben diese Bezeichner statt der internen fortlaufenden Ganzzahlen nach außen, und bestehende Modelle erhalten den neuen Bezeichner zusätzlich zur Ganzzahl, damit die Umstellung schrittweise erfolgen kann. ## Sicherheitsprobleme danach bewerten, was jede Rolle darf Lies das maßgebliche Dokument zur Sicherheitsrichtlinie des Repositorys, bevor du irgendeinen Codepfad auf Sicherheitsprobleme bewertest. Es ist die verbindliche Quelle für das Sicherheitsmodell, und an ihm werden sowohl menschliche Meldende als auch automatische Prüfwerkzeuge gemessen. Es gibt genau eine Prüffrage dafür, ob ein Befund in den Geltungsbereich fällt: Ermöglicht er es einem Akteur, eine Aktion auszuführen, zu der ihn die Matrix der Rollen und Berechtigungen in der Sicherheitsrichtlinie nicht berechtigt? Wenn ja, fällt er in den Geltungsbereich. Wenn nein, fällt er nicht hinein. Drei Vertrauensgrenzen bilden den Rahmen für diese Prüfung: 1. Die Administratorrolle ist ein vollständig vertrauenswürdiger Akteur des Betriebs. Alles, was eine Administratorin oder ein Administrator über dokumentierte Konfiguration, Programmierschnittstelle oder Oberfläche tun kann, ist eine beabsichtigte Fähigkeit und keine Schwachstelle. 2. Der Betreiber verantwortet die Entscheidungen zur Bereitstellungszeit: Geheimnisse, Erreichbarkeit im Netzwerk, Auswahl von Funktionsschaltern, Wahl von Konnektoren und Codecs, Ziele für Benachrichtigungen sowie Erweiterungen von Dritten. Eine Fehlkonfiguration auf dieser Ebene ist ein Bereitstellungsfehler und keine Schwachstelle des Produkts. 3. Die Codebasis ist dafür verantwortlich, die Matrix der Rollen und Berechtigungen überall dort durchzusetzen, wo sie einem Akteur Funktionalität zugänglich macht — bei den Routen der Programmierschnittstelle, in der Befehls- und der Datenzugriffsschicht, bei den Handhabern der Oberfläche, in Hintergrundaufträgen und an jedem weiteren Einstiegspunkt. Eine fehlende oder falsche Durchsetzungsprüfung fällt in den Geltungsbereich, gleich an welcher Stelle sie sich befindet. Das Modell setzt voraus, dass die vom Betreiber kontrollierte Infrastruktur — Metadatenbank, Zwischenspeicher, Nachrichtenvermittler, Geheimnisspeicher, Bereitstellungsumgebung — innerhalb der Vertrauensgrenze des Betreibers bleibt. Ein gültiger Befund muss eine Grenzverletzung durch eine angreifende Person nachweisen, die diese Systeme nicht bereits kontrolliert. ## Für jede Route und Datenart die richtige Berechtigungsprüfung nutzen Die Berechtigungsprüfung auf Routenebene verwendet je Routenklasse einen Dekorator, und welcher davon der richtige ist, hängt von der Art der Route ab: einer für die moderne REST-Schnittstelle, einer für die alten JSON-Ansichtsrouten und einer für die alten HTML-Ansichtsrouten. Sie zu verwechseln ist ein Durchsetzungsfehler, selbst wenn eine Prüfung vorhanden zu sein scheint. Die Berechtigungsprüfung auf Objektebene ist eine zweite, davon getrennte Schranke. Sie gilt für datenführende Ressourcen — Dashboards, Diagramme, Datensätze und Datenquellen, Abfragen, Zugriff auf Datenbanken und Tabellen sowie Abfragekontexte — und wird je Objekt über die Zugriffsprüfung des Sicherheitsverwalters aufgerufen. Code, der auf einer Route, die ein bestimmtes datenführendes Objekt zurückgibt oder verändert, die Schranke je Objekt auslässt, fällt in den Geltungsbereich. Andere Ressourcen — Anmerkungen, Schlagwörter, Stilvorlagen, Berichte, Regeln zur Sicherheit auf Zeilenebene und Ähnliches — stützen sich bewusst auf den Dekorator auf Routenebene zusammen mit der Eingrenzung nach Eigentümerschaft in den Basisfiltern der Datenzugriffsschicht. Dass bei diesen Ressourcen keine Prüfung je Objekt stattfindet, ist so beabsichtigt und stellt keinen Befund dar. Das richtige Berechtigungsmuster für eine Ressourcenklasse einzuhalten spricht den Code nicht von anderen Problemen frei. Einschleusung von Befehlen, serverseitiges Fälschen von Anfragen, seitenübergreifendes Skripting und ähnliche Klassen haben mit der Berechtigungsprüfung nichts zu tun und werden getrennt bewertet. ## Automatische Prüfwerkzeuge die verletzte Regel und die Rolle des Angreifers nennen lassen Automatische Prüfwerkzeuge — modellbasierte Code-Prüfer, statische Analysewerkzeuge und Werkzeuge für Abhängigkeiten — müssen in jedem Befund, den sie zu dieser Codebasis melden, zwei Dinge ausdrücklich benennen: 1. Die konkrete Zeile der Matrix der Rollen und Berechtigungen in der Sicherheitsrichtlinie, die dem Befund zufolge verletzt wird. 2. Den Akteur, über den die angreifende Person dem Befund zufolge verfügt: ein anonymer oder öffentlicher Akteur, eine authentifizierte Rolle mit geringen Rechten, eine Rolle für das Abfragewerkzeug, eine erweiterte Rolle zum Erstellen von Inhalten, die Administratorrolle, ein eingebettetes Gast-Token oder eine benannte eigene Rolle mit ausdrücklich zugeteilten Berechtigungen. Ein Befund, der nicht beides benennen kann, muss als Frage gemeldet werden und nicht als Schwachstelle. Diese Anforderung besteht, damit jedes gemeldete Problem am veröffentlichten Sicherheitsmodell überprüfbar ist und damit spekulative Meldungen sowie solche, die nur auf einem Mustervergleich beruhen, nicht in die Sichtungswarteschlange gelangen. ## Die Code-Standards für Frontend und Backend einhalten Frontend: Vermeide `any` und verwende vorhandene Typen wieder; schreibe funktionale Komponenten mit Hooks; beziehe UI-Komponenten aus dem gemeinsamen Designsystem-Paket, statt die Fremdbibliothek direkt einzubinden; nutze den Standard-Testläufer und die Standard-Testbibliothek des Projekts und nicht den entfernten alten Renderer; nutze den globalen Zustandsspeicher dort, wo es ihn bereits gibt, und ansonsten lokalen Zustand über Hooks. Backend: Für allen neuen Code sind Typangaben verpflichtend, der statische Typprüfer muss fehlerfrei durchlaufen, Datenmodelle sind ordentlich typisiert, und für Tests wird das Standard-Testrahmenwerk des Projekts verwendet. Verwende beim Aufbau von Abfragen den Negationsoperator des objektrelationalen Abbilders auf einer booleschen Spalte, statt sie mit einem Falsch-Literal zu vergleichen; Letzteres beanstandet der Linter. Lizenzkopfzeilen: Neue Quelldateien benötigen die Standard-Lizenzkopfzeile des Projekts. Anweisungsdateien für Agenten (diese Datei und ihre Geschwisterdateien je Anbieter) sind bewusst von dieser Anforderung ausgenommen, damit keine Tokens für die Kopfzeile verbraucht werden. Kommentare: Vermeide zeitbezogene Formulierungen wie „jetzt“, „derzeit“ oder „heute“, weil sie veralten. Schreibe Kommentare, die zu jedem Lesezeitpunkt zutreffend bleiben. ## Dokumentation und Hinweise zu inkompatiblen Änderungen mit dem Code aktualisieren Dokumentation ist Teil der Änderung und keine nachgelagerte Aufgabe: - Aktualisiere den Dokumentationsbaum bei jeder Änderung, die für Nutzende sichtbar ist. - Halte brechende Änderungen in der dafür vorgesehenen Datei mit den Hinweisen zur Aktualisierung fest, damit Betreiber sie an einer Stelle finden. - Schreibe für jede neue Funktion und jede neue Klasse eine Dokumentationszeichenkette. Berührt eine Änderung ein Verhalten, das Betreiber oder Endnutzende beobachten können, ist ein Pull Request ohne die passende Anpassung der Dokumentation unvollständig. ## Erzeugte Komponentendokumentation in den Story-Dateien korrigieren, nicht im Generator Das Entwicklerportal erzeugt die Komponentendokumentation automatisch aus den Geschichten des Komponentenkatalogs. Die Geschichten sind die einzige Wahrheitsquelle, und daraus folgen zwei Regeln: Wird etwas falsch dargestellt, korrigiere zuerst die Geschichtsdatei und nicht den Generator; und halte den Generator schlank — er liest die Daten der Geschichten aus und reicht sie durch, füge ihm also keine Sonderfälle je Komponente hinzu. Damit die Dokumentation einer Komponente korrekt erzeugt wird, muss ihre Geschichtsdatei: - das Metadatenobjekt unmittelbar als Standardexport ausgeben, statt es einer Variablen zuzuweisen und diese Variable zu exportieren. - interaktive Geschichten mit einem einheitlichen Präfix plus dem Komponentennamen benennen. - Standardwerte für Eigenschaften in den Argumenten der Geschichte festlegen. - Argumenttypen auf der Ebene der Geschichte definieren und nicht auf der Ebene der Metadaten, einschließlich Steuerungstypen und Beschreibungen. - die dokumentierten Parameterschlüssel verwenden — für Rastervarianten, für Beispiel-Kindelemente bei Komponenten, die sie benötigen, für eigene Live-Codeblöcke und für komplexe Objekteigenschaften, die sich nicht inline auswerten lassen. Behalte bei der Diagnose eines Dokumentationsproblems das Generatorskript, seine Hüllkomponente und das Verzeichnis der erzeugten Ausgabe als die drei beweglichen Teile im Blick. ## Die Testhilfen des Repositorys nutzen, statt eigene Vorbereitung zu schreiben Das Repository liefert Hilfsmittel mit; nutze sie, statt den Aufbau von Hand zu stricken. Im Backend heißt das: die gemeinsame Basisklasse für Tests, Dekoratoren zum Nachbilden der Konfiguration und zum Umschalten von Funktionsschaltern, Hilfsmittel zur Anmeldung mit einer bestimmten Rolle sowie Fabrikhilfen zum Anlegen der Vorbedingungen, die ein Test benötigt. Im Frontend heißt das: die eigene Render-Hilfe, die die Standardanbieter einrichtet, die Fabrik für die Hülle aus Zustandsspeicher, Router und Gestaltungsthema sowie die Hilfe für Interaktionen mit Auswahlfeldern. Regeln für Nachbildungen: Verwende für Konfigurationsobjekte eine einfache Nachbildung und greife nicht zu einer asynchronen Nachbildung, wenn der geprüfte Code synchron ist. Erhält ein Modell ein neues Feld, aktualisiere die Listen der erwarteten Spalten in den Tests der Programmierschnittstelle. Wisse, wie sich jede Testsuite ausführen lässt: die gesamte Frontend-Suite, eine einzelne Frontend-Testdatei, alle Backend-Tests, eine einzelne Backend-Testdatei, ein Verzeichnis mit Backend-Tests sowie die Ende-zu-Ende-Suite in den Betriebsarten ohne Anzeige, interaktiv, mit sichtbarem Browser und zur Fehlersuche. Schlagen die Backend-Tests wegen der Einrichtung von Datenbank oder Umgebung fehl und nicht wegen des geprüften Codes, bitte die Nutzerin oder den Nutzer, die Einrichtung der Testumgebung auszuführen, statt an ihrer Umgebung improvisierte Reparaturen vorzunehmen. ## Vor der Fehlersuche den Health-Endpunkt der Anwendung prüfen Führe zuerst die schnelle Prüfung der Einrichtung durch: Rufe den Zustandsendpunkt der Anwendung auf und vergewissere dich, dass er antwortet, bevor du Zeit in eine Fehlermeldung steckst. Eine fehlgeschlagene Zustandsprüfung bedeutet meist, dass der Arbeitsbereich nie eingerichtet wurde, und nicht, dass der Code fehlerhaft ist. Schlägt die Zustandsprüfung fehl, teile der Nutzerin oder dem Nutzer mit, dass die Umgebung nicht eingerichtet zu sein scheint, und verweise auf die dokumentierte Einrichtungsanleitung des Projekts für die Arbeit mit Agenten, statt selbst zu versuchen, die Umgebung zu reparieren. Kenne zur Orientierung die zentralen Projektdateien: das Paketmanifest des Frontends für die Skripte zum Bauen, Testen und Linten sowie für den Port des Entwicklungsservers; die Python-Projektdatei für die Konfiguration von Linter und Typprüfer; und den Ordner mit den Abhängigkeitsanforderungen, der in einen Basissatz und einen Entwicklungssatz aufgeteilt ist. ## Die Pull-Request-Vorlage ausfüllen und Titel im Conventional-Commits-Format schreiben Beim Eröffnen eines Pull Requests: 1. Lies vor dem Verfassen die aktuelle Vorlagendatei für Pull Requests im Repository. Lies immer die tatsächliche Datei, statt zwischengespeicherte Inhalte wiederzuverwenden, denn die Vorlage ändert sich im Lauf der Zeit. 2. Fülle jeden Abschnitt aus, den die Vorlage vorsieht — Zusammenfassung, Belege für den Zustand davor und danach, Anleitung zum Testen und zusätzliche Angaben. 3. Betitle den Pull Request im Format der konventionellen Commits `type(scope): description`, zum Beispiel `fix(dashboard): load charts correctly`. Gültige Typen sind `fix`, `feat`, `docs`, `style`, `refactor`, `perf`, `test` und `chore`. ## Vor dem Bearbeiten unbekannter Bereiche Ordneraufbau und Dateimuster kennenlernen Zwei Gewohnheiten sorgen dafür, dass Änderungen in einem großen Repository an der richtigen Stelle landen. Erstens: Präge dir vor dem Bearbeiten die Verzeichnisübersicht ein — welcher Baum die Backend-Anwendung mit ihren Endpunkten der Programmierschnittstelle, ihren Datenmodellen und ihren Konnektoren enthält; welcher Baum den Frontend-Quellcode mit seinen Bereichen für Komponenten, Diagrammbaukasten, Dashboards und Abfrageeditor enthält; wo das gemeinsame Designsystem-Paket liegt; und wo Tests, Dokumentation und das Verzeichnis der brechenden Änderungen liegen. Zweitens: Kenne die wiederkehrenden Dateimuster, damit eine neue Funktion in den üblichen Dateien landet — das Schnittstellenmodul für Endpunkte mit ihren Dekoratoren und den Dokumentationszeichenketten, die das Schema erzeugen; das Schemamodul für die Prüfung von Anfragen und Antworten, aus dem die erzeugte Schnittstellenspezifikation gespeist wird; die Befehlsschicht für Geschäftslogik, die in Transaktionen eingefasst ist; und die Modellschicht für die dauerhafte Speicherung. Die erzeugte Dokumentation der Programmierschnittstelle leitet sich aus diesen Dokumentationszeichenketten und Schemata ab; eine Änderung an einem Endpunkt ohne Aktualisierung der Dokumentationszeichenkette verschlechtert sie also unbemerkt. Datenbankmigrationen folgen einer eigenen Konvention: Sie liegen im Verzeichnis der Migrationsversionen, werden mit Zeitstempel, Revisions-Hash und Beschreibung benannt und sollten die gemeinsamen Hilfsmittel für Migrationen aufrufen statt roher Operationen des objektrelationalen Abbilders, damit sie über verschiedene Datenbanksysteme hinweg kompatibel bleiben. Beachte schließlich, dass dieses Repository parallele Anweisungsdateien für verschiedene Anbieter von Agenten führt. Halte sie konsistent, wenn du eine Regel änderst, die für alle von ihnen gilt.