Kleine Änderungen an einer App vornehmen, die auf einem lokalen Hintergrunddienst (Daemon) läuft

## Vor dem Programmieren die Entwurfsdokumente lesen und die Rolle jedes Ordners kennen Halten Sie Änderungen klein, richten Sie sich nach der Architektur, die das Repository derzeit anstrebt, und bevorzugen Sie die dokumentierten Grenzen von Daemon und API gegenüber Verhalten, das aus einer älteren, gerade abgelösten Implementierung übernommen wurde. Machen Sie sich mit dem Aufbau anhand der Rollen vertraut, nicht anhand von Dateinamen: - Das Backend enthält den Kommandozeilen-Client, den HTTP-Daemon auf der Loopback-Adresse, die Dienste, die Speicherung in der eingebetteten Datenbank, die Logik für Lebenszyklus und Aufräumprozesse (Reaper), die Adapter für Laufzeitumgebungen und Arbeitsbereiche sowie deren Tests. - Das Desktop- oder Web-Frontend ist eine schlanke Steuerungs- und Oberflächenschicht, die über einen generierten, typisierten Client mit dem Daemon verbunden ist. Verlagern Sie keine Daemon-Logik dorthin. - Das Verzeichnis mit der Dokumentation enthält die aktuellen Architektur- und Statusnotizen. Lesen Sie sie, bevor Sie das Verhalten von Lebenszyklus, Client, Agent, Speicherung oder Daemon ändern. - Ein eigenes Testverzeichnis enthält externe Ressourcen für grundlegende Funktionsprüfungen (Smoke-Tests) und durchgängige Tests (End-to-End), einschließlich Prüfungen einer Neuinstallation im Container. - Die Workflow-Definitionen der CI sind der Maßstab dafür, was erfolgreich durchlaufen muss. Bilden Sie diese Befehle nach Möglichkeit lokal nach. Lesen Sie vor einer nicht trivialen Änderung in dieser Reihenfolge: die README zum Schnelleinstieg, das Inhaltsverzeichnis der Dokumentation, das Architekturdokument (Denkmodell, Paketaufbau, Grenzen zwischen Lebenszyklus, Sitzung und Diensten sowie die tragenden Regeln), das Statusdokument (was heute im Hauptbranch ausgeliefert ist und was sich noch in Arbeit befindet) und das Client-Dokument (die dafür vorgesehene Gestalt). Falls das Repository zusätzlich Verweisdateien zur Kompatibilität mit anderen Agentenwerkzeugen enthält, behandeln Sie diese als Weiterleitungen auf den einen maßgeblichen Leitfaden und nicht als eigenständige Regelwerke. Finden Sie Einstiegspunkte über die Zuständigkeit statt durch blindes Suchen: Befehlsimplementierungen, HTTP-Controller und DTOs, Lese- und Schreibgrenzen der Dienste, Fachvokabular, Port-Verträge, Datenbankabfragen und Migrationen sowie generierter Datenbankcode liegen jeweils in einem eigenen Paket. Orientieren Sie sich an den benachbarten Befehls- und Testmustern, bevor Sie einen neuen Stil einführen. ## Die Prüfungen des Projekts ausführen und sichtbare Änderungen auf dem Bildschirm ansehen Verwenden Sie die Sammelbefehle des Repositorys, statt eigene Befehle für den Einzelfall zu erfinden. Vom Wurzelverzeichnis des Repositorys aus decken sie in der Regel Folgendes ab: die Stilprüfung (Backend-Tests zusammen mit einer festgelegten Version des Prüfwerkzeugs), die Typprüfung des Frontends, die Neuerzeugung des Datenbankzugriffscodes aus Abfragen und Schema, die Neuerzeugung der API-Spezifikation und der Frontend-Typen sowie einen lokalen Workflow-Runner, der die CI-Definitionen prüft (und dafür möglicherweise einen Container-Socket benötigt). Prüfungen auf Komponentenebene lohnen sich beim Iterieren weiterhin auch direkt: für das Backend Bauen, Testen, Testen mit aktivierter Wettlauferkennung (race), statische Analyse (vet) und das Starten des Dienstes; für das Frontend Typprüfung und Bauen. Wenn sich eine Änderung in der Oberfläche zeigt, stellen Sie sie mit dem Vorschaubefehl des Projekts tatsächlich innerhalb der Sitzung dar und sehen Sie sich das Ergebnis an. Beschreiben Sie nicht bloß, wie die Änderung aussehen sollte. ## Nur die sich selbst aktualisierende Desktop-App als Installationsweg empfehlen Wenn ein Projekt mehrere Installationswege hat, ist nur einer davon maßgeblich, und alle Hinweise müssen dorthin verweisen. - Der sich selbst aktualisierende Desktop-Build, der über die Releases veröffentlicht wird, ist der maßgebliche Installationsweg. Verweisen Sie Nutzerinnen und Nutzer zuerst dorthin. - Ein alter Weg über einen Paketmanager kann weiterhin funktionieren, ohne noch empfohlen zu werden. Wenn eine abschließende Version veröffentlicht wurde und das Paket eingefroren ist, erhält es keine weiteren Aktualisierungen. Es bleibt allein ein Einstieg für diejenigen, die den Befehl bereits in ihrem PATH haben: Beim Start lädt er den maßgeblichen Build herunter und öffnet ihn. - Fügen Sie keine Funktionen, keine Dokumentation und keine Abläufe hinzu, die einen eingefrorenen alten Weg als den vorgesehenen Weg zur Installation des Produkts darstellen. ## Nur ändern, was die Aufgabe verlangt, und die bestehende Aufteilung des Codes einhalten - Halten Sie jede Änderung unmittelbar an die Aufgabe gebunden. Vermeiden Sie nebenbei erledigte Aufräumarbeiten, großflächige Umbenennungen, unnötige Formatierungsänderungen, auf Vorrat gebaute Abstraktionen und Umbauten der Architektur, sofern die Aufgabe sie nicht ausdrücklich verlangt. - Halten Sie sich an die bestehenden Paketgrenzen. Client-Code ruft die HTTP-Routen des Daemons über die gemeinsam genutzten Client-Hilfsfunktionen auf; er darf die Datenbank nicht öffnen, keine Laufzeitumgebungen starten und keine Adapter direkt aufrufen. - Belassen Sie jeden Befehl in der zugehörigen Befehlsdatei und prüfen Sie ihn mit tabellengetriebenen Tests im Stil der benachbarten Befehlstests. - Bilden Sie Anfrage- und Antwort-DTOs auf der Client-Seite nach, statt Controller-Pakete des Servers in den Client-Code zu importieren – es sei denn, diese Abhängigkeit besteht in dem Paket bereits. - Geben Sie Fehler bei falscher Verwendung über den dafür vorgesehenen Fehlertyp zurück, damit eine falsche Verwendung des Clients mit einem eigenen Statuscode endet (zum Beispiel 2), während Fehler zur Laufzeit und Fehler des Daemons mit dem allgemeinen Fehlercode enden (zum Beispiel 1). - Erhalten Sie beim Weiterreichen von Daemon-Fehlern die Fehlerhüllen der API und die Anfrage-IDs, statt sie zu einfachen Zeichenketten zu verflachen. - Übergeben Sie einen Kontext für Abbruch und Zeitlimit als erstes Argument jeder Funktion, die Ein-/Ausgabe oder blockierende Arbeit ausführt. - Fügen Sie keine Abstraktionen für einmalige Anwendungsfälle hinzu. Führen Sie eine Hilfsfunktion nur dann ein, wenn sie Dopplungen an tatsächlichen Aufrufstellen beseitigt. - Tests sollten das für Nutzende sichtbare Verhalten und die jeweils geänderte Grenze abdecken: den Normalfall, Validierung und fehlende Argumente, die Fehlerhüllen des Daemons sowie jeden Bestätigungspfad für zerstörende Aktionen. ## Die Netzwerkzugänge des Daemons weder ändern noch neue hinzufügen - Der primäre Listener des Daemons bleibt an die Loopback-Adresse gebunden und bleibt ohne Authentifizierung. Ändern Sie seine Bindeadresse nicht und fügen Sie ihm keine Authentifizierung hinzu. - Der Daemon darf einen zweiten, ausdrücklich zuzuschaltenden Listener betreiben, der sich für den Zugriff aus dem lokalen Netzwerk an alle Schnittstellen bindet – aber nur, solange er ausdrücklich aktiviert ist, nur hinter der Authentifizierungsschicht mit Bearer-Passwort und nur für die Anwendungs-API. Dieser Listener darf niemals die auf Loopback beschränkten Steuerungsrouten bereitstellen, etwa zum Herunterfahren, zur Telemetrie und zur Fernsteuerung. - Wenn ein solcher Listener unverschlüsselt arbeitet und nur für ein vertrauenswürdiges Heimnetzwerk gedacht ist, ist das eine bewusste, dokumentierte Entscheidung, die in einem Architekturentscheidungsprotokoll festgehalten ist. Lesen Sie dieses Protokoll, bevor Sie daran etwas ändern. - Fügen Sie keine weitere Bindung hinzu, die zum Netzwerk hin geöffnet ist. - Der Kommandozeilen-Client bleibt ein schlanker Client. Übernehmen Sie kein älteres Verhalten aus dem eigenen Prozess, das die HTTP-Routen des Daemons umgeht. ## Gespeicherte Daten schützen und erzeugten Datenbankcode nicht von Hand ändern - Speichern Sie keinen abgeleiteten oder auf die Anzeige ausgerichteten Status. Leiten Sie den Status beim Lesen im Dienst aus dauerhaften Fakten ab (Aktivitätszustand, Beendigungskennzeichen, Fakten zu Pull Requests, Prüfungen und Kommentaren). - Werten Sie eine fehlgeschlagene oder unklare Laufzeitprüfung nicht als Beweis dafür, dass eine Sitzung beendet ist. - Erzwingen Sie nicht das Löschen registrierter Arbeitsbäume (Worktrees), in denen es noch nicht eingecheckte Änderungen gibt. - Ändern Sie keine Migrationen, die bereits zusammengeführt wurden. Fügen Sie stattdessen eine neue Migration hinzu. - Bearbeiten Sie generierten Datenbankcode nicht von Hand. Ändern Sie die Abfragen oder Migrationen und lassen Sie den Generator erneut laufen. - Änderungsereignisse fließen von Datenbank-Triggern in das Änderungsprotokoll. Fügen Sie keinen parallelen, manuellen Weg zum Auslösen von Änderungsereignissen aus den Methoden des Speichers hinzu, solange sich die Architektur nicht ausdrücklich ändert. - Achten Sie auf ein Auseinanderdriften zwischen generierten API-Artefakten und von Hand geschriebenen DTOs. Die Antwortformen der Controller liegen in einer einzigen DTO-Datei, und Tests können die Kompatibilität des Übertragungsformats zwischen der Client- und der HTTP-Schicht prüfen. - Fügen Sie Tests keine Netzwerkaufrufe hinzu, sofern das Paket dafür nicht bereits ein Muster für Integrationstests oder durchgängige Tests besitzt. Bevorzugen Sie Testserver im selben Prozess, Attrappen (Fakes) und per Injektion bereitgestellte Abhängigkeiten. - Nehmen Sie keinen lokalen Laufzeitzustand, keine Daemon-Daten, keine vorübergehenden Arbeitsbäume, keine Bauergebnisse und keine Zugangsdaten in Commits auf. - Halten Sie den gesamten Anwendungszustand unter dem einen dafür vorgesehenen Zustandsverzeichnis, das sich über die dokumentierten Umgebungsvariablen überschreiben lässt. Das Datenverzeichnis des Daemons, die Datei des laufenden Prozesses, die Arbeitsbäume und die Nutzerdaten der Desktop-Hülle (Browser-Zwischenspeicher, Cookies, lokaler Speicher und Sitzungsspeicher, Absturzabbilder) müssen sich alle unterhalb dieses Verzeichnisses auflösen. Lesen Sie niemals aus dem Standardablageort des Betriebssystems für Anwendungsdaten und schreiben Sie niemals dorthin. Der Einstiegspunkt der Desktop-Anwendung legt den Pfad für die Nutzerdaten der Hülle fest auf dieses Verzeichnis; entfernen Sie diese Festlegung nicht und verlassen Sie sich nicht auf den Standardpfad. ## Die API in den handgeschriebenen Dateien ändern und ihre Beschreibung neu erzeugen Die API des Daemons entsteht zuerst im Code. Die OpenAPI-Spezifikation und die Frontend-Typen sind generierte Artefakte; ändern Sie deshalb die Quelle und erzeugen Sie neu, statt die Ausgaben zu bearbeiten. - Bearbeiten Sie die DTO-Datei, in der die Formen von Anfragen und Antworten festgelegt sind. - Bearbeiten Sie das Operationsverzeichnis des Spezifikationserzeugers und ergänzen Sie für jeden neu benannten Typ einen Eintrag mit dem Schemanamen. - Erzeugen Sie mit dem Sammelbefehl des Repositorys für die API neu; dieser führt die Erzeugung der Spezifikation und die Erzeugung der Typen nacheinander aus. - Prüfen Sie das Ergebnis mit den Tests im HTTP-Paket des Servers; sie decken das Auseinanderdriften der Spezifikation sowie die Übereinstimmung von Routen und Spezifikation ab. Die generierten Frontend-Typen decken sie nicht ab; diese werden von einem eigenen CI-Auftrag zur Driftprüfung kontrolliert. - Nehmen Sie die generierte Spezifikation und die generierten Frontend-Typen gemeinsam mit den Quelländerungen in den Commit auf. Die CI erzeugt beides neu und schlägt fehl, wenn die eingecheckten Fassungen veraltet sind. - Die von Hand nachgebildeten Client-DTOs bleiben eine bewusst manuell gepflegte Grenze und werden nicht generiert. ## Pro Thema nur eine Änderungsanfrage (Pull Request) stellen - Zweigen Sie vom Hauptbranch ab, sofern Sie nicht ausdrücklich einen bestehenden Pull Request fortsetzen. - Behandeln Sie pro Pull Request nur ein Anliegen. Wenn eine davon getrennte Arbeit verlangt wird, legen Sie einen eigenen Branch und einen eigenen Pull Request an. - Verwenden Sie die üblichen Präfixe für Commit-Nachrichten wie feat, fix, docs, test und chore. - Erläutern Sie beabsichtigte Auslassungen im Text des Pull Requests, insbesondere dann, wenn eine Vorgängerimplementierung mehr Verhalten unterstützt hat, als der Fachbereich der aktuellen Neufassung abdeckt. - Führen Sie zuerst die engsten passenden Tests aus und danach die Repository- und CI-Befehle, die zu dem von Ihnen veränderten Bereich passen.