omonuj/claude-fähigkeiten

building-backends

Dies ist die grundlegende Fähigkeit für Backend-Arbeit. Lies sie, bevor du Servercode schreibst – sie setzt die Standards und die unverhandelbaren Regeln, sodass jeder Dienst konsistent wird, und übergibt dann an die spezifischen Fähigkeiten für die detaillierten Verfahren. Wenn eine Regel hier mit einer lokalen Repo-Konvention kollidiert, gewinnt das Repo; wenn sie mit nichts kollidiert, befolge sie.

Zuerst verstehen, dann bauen

• Lies den vorhandenen Code, bevor du etwas hinzufügst. Passe dich an das Framework, Fehlermodell, Layering, Namenskonventionen und den Teststil des Repos an. Ein „korrektes“ Muster, das gegen die Codebasis kämpft, ist das falsche Muster. Eine zweite Art, etwas zu tun, was das Repo bereits tut, einzuführen, ist ein Fehler, keine Verbesserung.
• Klär den Vertrag, nicht die Implementierung. Kenne die Eingaben, Ausgaben, Fehlerfälle, wer es aufruft und die Konsistenz-/Latenzerwartungen, bevor du ein Design wählst. Die meiste Backend-Nacharbeit entsteht durch schnelles Bauen des falschen Vertrags.
• Bevorzuge langweilig. Bewährte, lesbare, offensichtliche Lösungen gegenüber cleveren. Das Backend läuft unbeaufsichtigt um 3 Uhr morgens; optimiere für den Bereitschaftsingenieur, der es halbschlafend verstehen muss, nicht für Eleganz.

Architektur – die Regeln

• Schichten mit nach innen gerichteten Abhängigkeiten. Transport (HTTP) → Services (Anwendungsfälle) → Domain (Entitäten/Regeln) und Services → Repositories (I/O) → Domain. Die Domain importiert nichts nach außen und führt keine E/A durch. Wenn ein Importpfeil in die falsche Richtung zeigt, ist das Design kaputt.
• Handler orchestrieren, Services entscheiden, Repositories erledigen E/A. Ein Handler parst/validiert Eingaben, ruft einen Service auf, bildet das Ergebnis auf eine Antwort ab – keine Geschäftslogik. Ein Repository ist der einzige Ort, der eine DB, Warteschlange oder externes HTTP berührt.
• Halte die Domain ohne Infrastruktur testbar. Wenn du die Kernlogik nicht ohne Datenbank oder Netzwerk unit-testen kannst, ist die Logik in der falschen Schicht.
• Ein Kompositionswurzel. Baue Konfiguration, verdrahte Abhängigkeiten und starte den Server an einem einzigen Ort. Alles andere erhält seine Abhängigkeiten; nichts greift aus, um globale Singletons zu konstruieren.
• Zustandslos entwerfen. Sitzungs-/Zwischenzustand lebt in einem gemeinsamen Speicher (DB/Cache), nicht im Prozessspeicher, damit der Dienst horizontal skaliert und einen Neustart überlebt. Wenn du in einer Modulvariablen cachest, halte inne und denke nach.

→ Verwende api-service-scaffold, um das Grundgerüst mit diesen bereits verdrahteten Schichten aufzubauen.

API-Design – die Regeln

• Explizite, versionierte Verträge. Versioniere die API (URL oder Header) von Tag eins an; mache niemals eine bahnbrechende Änderung an einem ausgelieferten Vertrag – füge die neue Form daneben hinzu und kennzeichne die alte als veraltet.
• Validiere jede Eingabe an der Grenze in einen typisierten Wert. Der Kern sieht niemals einen rohen Request-Body. Lehne ungültige Eingaben mit 422 und feldspezifischen Details ab; vertraue niemals dem Client.
• Ein Fehlermodell, einmal abgebildet. Domain-Code löst typisierte Fehler aus (NotFoundError, ConflictError, ValidationError, UnauthorizedError…); ein einzelner Grenz-Mapper wandelt sie in Status + { code, message, details? } um. Gib niemals Stack-Traces oder interne Meldungen preis. 404 für „nicht gefunden“ und „nicht deins“ – deren Unterscheidung gibt Existenz preis.
• Konsistente Formen. Dieselbe Hülle für Erfolg, dieselbe Hülle für Fehler, konsistente Paginierung (Cursor über Offset für große Mengen), konsistente Feldbenennung. Ein Aufrufer sollte deine Konventionen einmal lernen.
• Idempotenz für unsichere Operationen. PUT/DELETE sind per Definition idempotent; mache POSTs, die wiederholt werden können, mit einem Idempotenzschlüssel sicher. Netzwerke wiederholen – ein doppelt berechneter Kunde ist ein Designfehler.
• Richtige Statuscodes. 2xx Erfolg, 4xx Fehler des Aufrufers, 5xx dein Fehler. Ein Validierungsfehler ist 422, nicht 200-mit-einem-Fehlerbody; ein Authentifizierungsfehler ist 401/403, nicht 400.

Die Datenschicht – die Regeln

• Die Datenbank ist die Quelle der Wahrheit; erzwinge Invarianten dort. Fremdschlüssel, Unique-Constraints, NOT NULL und Checks gehören in das Schema, nicht nur in Anwendungscode – App-Code hat Fehler und Race-Conditions; die DB lügt nicht.
• Transaktionen umfassen Invarianten und sind so kurz wie möglich. Alles, was alles-oder-nichts sein muss, kommt in eine Transaktion; mache keine langsamen Arbeiten (externe Aufrufe, schwere Berechnungen), während du eine hältst. Lange Transaktionen halten Sperren und hungern alle anderen aus.
• Erwarte Nebenläufigkeit. Zwei Anfragen werden gleichzeitig dieselbe Zeile treffen. Verwende optimistisches Sperren (eine Versionsspalte) oder geeignete Isolation; führe niemals Lese-Ändern-Schreiben über eine Netzwerkrunde ohne Schutz durch.
• Migrationen sind abwärtskompatibel und umkehrbar. Ändere niemals die Bedeutung einer Spalte in einem Deployment; erweitern→migrieren→zusammenziehen. Nehme niemals eine tabellensperrende Sperre auf einer heißen Tabelle. Jede Migration wird mit einem getesteten Rollback ausgeliefert.
• Achte auf den N+1. Rufe zusammengehörige Daten als Menge ab, nicht in einer Schleife von Abfragen. Miss die Abfrageanzahl an echten Endpunkten, nicht nur die Latenz.
• Indiziere die Abfragen, die du tatsächlich ausführst – und nur diese. Ein ungenutzter Index ist Schreibverstärkung für nichts.

→ Verwende db-migration-guardian für die Migrationsmechanik (Sperren, Expand-Contract, Backfills, Rollbacks).

Sicherheit – die Grundlinie (unverhandelbar)

• Authentifiziere, dann autorisiere, bei jeder Anfrage, serverseitig. Vertraue niemals einer Client-Behauptung darüber, wer es ist oder was es tun darf. Prüfe den Besitz bei jedem Ressourcenzugriff – „Ich habe ein gültiges Token“ ≠ „Dieser Datensatz gehört mir“.
• Parametrisiere jede Abfrage. Niemals string-gebautes SQL. Gleiches gilt für jede injizierbare Schnittstelle (Shell, LDAP, Template).
• Geheimnisse kommen aus der Umgebung/dem Secret-Manager, niemals aus dem Code. Nichts Sensibles in Quellen, Logs oder Fehlermeldungen. (Siehe die secrets-management-Fähigkeit.)
• Minimales Privileg überall – DB-Benutzer, Dienst-Anmeldeinformationen, Cloud-Rollen auf genau das beschränkt, was der Dienst benötigt.
• Ratenbegrenzung und Timeouts setzen für eingehende Endpunkte und ausgehende Aufrufe. Ein unbegrenzter Aufruf oder ein unbegrenzter Endpunkt ist ein Denial-of-Service, der nur darauf wartet, zu passieren.
• Validiere und kodiere an den Grenzen, um Injection und SSRF zu verhindern; behandle jede externe Eingabe, einschließlich der von anderen internen Diensten, als nicht vertrauenswürdig.

Nebenläufigkeit, Jobs und Fehler

• Nimm an, dass jeder externe Aufruf fehlschlägt. Setze Timeouts, füge begrenzte Wiederholungen mit Backoff + Jitter und einen Circuit Breaker für eine unzuverlässige Abhängigkeit hinzu. Eine Wiederholung ohne Timeout ist, wie eine langsame Abhängigkeit den gesamten Dienst lahmlegt.
• Mache Operationen idempotent, damit eine Wiederholung (deine oder die des Aufrufers) sicher ist.
• Hintergrundarbeit geht in eine Warteschlange, nicht in den Request-Pfad. Der Request stellt in die Warteschlange; ein Worker verarbeitet; Fehler landen in einer Dead-Letter-Warteschlange zur Überprüfung, nicht in einem stillen catch {}.
• Scheitere laut, degradiere anmutig. Mache Fehler in der Telemetrie sichtbar; wo eine nicht kritische Abhängigkeit ausfällt, degradiere (bediene mit alten Daten, überspringe die Anreicherung), anstatt die gesamte Anfrage mit 500 zu beantworten.

Observability ist Teil von „fertig“, kein nachträglicher Gedanke

Ein Dienst, den du in der Produktion nicht debuggen kannst, ist nicht fertig. Strukturierte Logs, RED/USE-Metriken und Traces, die an eine Korrelations-ID gebunden sind, gehören während des Bauens hinein, nicht nach dem ersten Vorfall.

→ Verwende backend-observability für die Instrumentierungsdetails und die Kardinalitäts-/PII-Leitplanken.

Testhaltung

• Teste Verhalten durch die öffentliche Oberfläche (den Endpunkt / den Anwendungsfall), nicht private Interna – damit Tests Refactorings überleben.
• Eine Pyramide, kein Eisbecher: viele schnelle Unit-Tests für Domain-/Service-Logik, eine fokussierte Sammlung von Integrationstests über die echte DB und Verdrahtung, wenige End-to-End-Tests für kritische Pfade.
• Jeder Bugfix bekommt einen Regressionstest, der vor dem Fix fehlschlägt und danach besteht.
• Deterministische Tests. Keine Abhängigkeit von Echtzeituhr, Netzwerk oder Reihenfolge; Daten explizit vorsäen; Tests voneinander isolieren.

Vorgehen für jede Backend-Aufgabe

1. Lies den umgebenden Code; mache den Vertrag klar (Eingaben/Ausgaben/Fehler/Aufrufer/Konsistenz).
2. Platziere die Arbeit in der richtigen Schicht; halte die Domain E/A-frei.
3. Validiere Eingaben an der Grenze; verwende das eine Fehlermodell; gib den richtigen Status zurück.
4. Platziere Invarianten in der DB + eine kurze Transaktion; behandle Nebenläufigkeit; plane Migrationen als Expand-Contract.
5. Wende die Sicherheitsgrundlinie an (Autorisierung + Besitz, parametrisierte Abfragen, Geheimnisse, Timeouts/Limits).
6. Mache externe Aufrufe und Jobs widerstandsfähig und idempotent.
7. Instrumentiere beim Bauen; füge Tests in der richtigen Schicht hinzu, einschließlich eines Regressionstests für jeden Bug.
8. Bestätige gegen die relevante spezifische Fähigkeit: Definition of done.

Definition of done

• Schichten respektiert (Domain macht keine E/A; Abhängigkeiten zeigen nach innen); ein Kompositionswurzel.
• Jede Eingabe an der Grenze validiert; ein Fehlermodell einmal abgebildet; korrekte Statuscodes; versionierter Vertrag.
• Invarianten in der DB erzwungen; Transaktionen kurz; Nebenläufigkeit behandelt; Migrationen abwärtskompatibel + umkehrbar.
• Sicherheitsgrundlinie erfüllt: Autorisierung + Besitzprüfungen, parametrisierte Abfragen, Geheimnisse extern, Timeouts/Ratenbegrenzungen vorhanden.
• Externe Aufrufe/Jobs idempotent und widerstandsfähig; Hintergrundarbeit außerhalb des Request-Pfads.
• Observability verdrahtet (Logs/Metriken/Traces auf einer Korrelations-ID); Tests auf den richtigen Schichten, grün, mit Regressionstests.