CommunityCodierung & Entwicklunggithub.com

Backend Silk – gemeinsame Backend-Standards

Programmier-Skill. Gemeinsame Engineering-Standards für Backend- und API-Projekte in Python (Flask, FastAPI, Django, FastMCP) und Node.js (Express). Deckt Projektstruktur, Schichtung von Routes, Helpers und Services, klassenbasierte Code-Regeln, Fehlerbehandlung und Statuscodes, Randfälle, Logging, .env-Konfiguration, Authentifizierung und Datenbesitz, Kommunikation zwischen Repositories, Git-Hygiene und Tests ab.

Was ist Backend Silk – gemeinsame Backend-Standards?

Dieser Skill definiert einen gemeinsamen Satz an Backend-Standards, der für alle Python- und Node.js-Projekte (insbesondere Flask, FastAPI, Django, FastMCP und Express) gilt. Sein Hauptziel ist es, zwei häufige Fehler zu vermeiden: falsche Struktur (Logik in der falschen Schicht, überflüssige Dateien) und Over-Engineering (Abstraktionen vor einer funktionierenden App). Ein dritter, stillerer Fehler ist ebenso kostspielig: eine Änderung oder Refaktorisierung, die unbemerkt ein zuvor funktionierendes Verhalten entfernt. Der Skill legt eine klare, strikt eingehaltene Schichtenarchitektur (Routes → Helpers → Services → Datenbank/externe Systeme) fest, bei der jeder Schicht genau definierte Zuständigkeiten und Verbote zugewiesen sind. Er enthält detaillierte Code-Regeln (klassenbasierte Module, Funktionslänge, Importreihenfolge, keine verschachtelten Funktionen), eine Checkliste gegen Over-Engineering sowie Anleitungen zu Fehlerbehandlung, Logging, Konfiguration, Sicherheit, Git und Tests. Der Skill ist als gemeinsame Grundlage („Seide“) für projektspezifische Spider-Skills (wie flask-spider, sql-silk) gedacht und wird immer dann geladen, wenn ein Python-Backend, eine REST-API, ein MCP-Server oder ein RAG-Backend erstellt, erweitert, debuggt, refaktoriert oder reviewed wird.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VivekShevale/eight-eye/tree/HEAD/skills/backend/backend-silk

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Backend Silk: gemeinsame Backend-Standards

Handle als Senior-Python-Backend-Ingenieur, der einfachen, produktionsreifen Code schreibt. Die beiden Fehler, die dieser Skill verhindern soll, sind falsche Struktur (Logik in der falschen Schicht, Dateien, die niemand braucht) und Over-Engineering (Abstraktionen, bevor es eine funktionierende App gibt). Ein dritter, stillerer Fehler ist ebenso kostspielig: eine Änderung oder Refaktorisierung, die unbemerkt ein zuvor funktionierendes Verhalten entfernt.

Begleit-Skills

Namensgebung: *-spider-Skills bauen eine bestimmte Art von Projekt auf; *-silk-Skills sind die gemeinsamen Standards, die jede Spinne spinnt. Dieser Skill enthält die Prinzipien, die für jedes Backend gelten. Lade auch die passenden Begleiter:

SituationAußerdem verwenden
Flask / FastAPI / Django-Projektflask-spider / fastapi-spider / django-spider
Node.js / Express-Projektnode-spider (die Regeln hier gelten; Python-Codebeispiele sind in Python)
MCP-Server oder MCP-Clientmcp-spider
PostgreSQL, MySQL, SQLite (SQLAlchemy, Django ORM)sql-silk
MongoDBmongodb-silk
LLM, Embeddings, Vektor-Store, RAGrag-spider

Framework-Skills entscheiden über die Framework-Mechanik; dieser Skill entscheidet über die Prinzipien. Sollten sie in Konflikt geraten, folge dem Framework-Skill für die Syntax und diesem Skill für die Struktur.

Bevor du Code änderst

  1. Lies zuerst den echten Code. Überprüfe die Ordnerstruktur, Modelle, Konfiguration und die Datei, die du ändern möchtest. Rate niemals einen Feldnamen, eine Funktionssignatur, einen Dateinamen oder einen Importpfad; lies ihn nach. (Ein geratenes date anstelle des echten expense_date hat einmal Schema, Helper und Response auf einmal zerstört.) Wenn du dir unsicher bist, wie eine installierte Bibliothek funktioniert, überprüfe ihre eigentliche API, anstatt Annahmen zu treffen.
  2. Entscheide zuerst die Routen. Liste für ein Feature jeden Endpunkt (Methode, Pfad, Request, Response, Statuscodes, Authentifizierung) auf, bevor du implementierst.
  3. Der Umfang ergibt sich aus der Anforderung. Baue, was die Problemstellung benötigt. Zusätzliche Endpunkte, Analysen, Caching, Ratenbegrenzung, Re-Ranking, Kostenverfolgung, Download-/Such-Endpunkte, die niemand verlangt hat: erwähne sie in einer Zeile als „möglicherweise später“, baue sie nicht.
  4. Erhalte funktionierendes Verhalten. Wenn du eine Funktion umschreibst, liste auf, was sie jetzt tut (Filter, Paginierung, Validierung, Logging, Response-Felder) und stelle sicher, dass die neue Version immer noch all das tut.

Schichten

routes -> helpers -> services -> Datenbank / externe Systeme
            |            |
          utils        utils
OrdnerBesitztDarf nicht enthalten
routes/ (Flask-Blaupausen, FastAPI-Router, Django views.py + urls.py, MCP tools/)URL, Methode, Auth-Dependency/Dekorator, Statuscode, Response-Modell, ein Aufruf eines HelpersGeschäftslogik, Abfragen, Validierungscode, try/except, Logging
helpers/Geschäftslogik für ein Feature, wie ein Controller: Validierung über das Schema hinaus, Besitzprüfungen, featurespezifische Abfragen und Filter, Orchestrierung von Services, Abbildung erwarteter Fehler auf HTTP-Fehler, Aufbau der ResponseÖffnen/Schließen von DB-Sitzungen, Commit/Rollback, Erstellen von LLM- oder SDK-Clients
services/Jeweils ein externes System oder Infrastrukturteil: DB-Verbindung und generisches CRUD (db_service.py), LLM, Embeddings, Vektor-Store, PDF, E-Mail, API eines anderen ReposFeaturespezifische Geschäftsregeln, HTTP-Kenntnisse (HTTPException, Statuscodes), Aufrufe von Helfern
utils/Klassenbasierter Code, der von mehreren Modulen wiederverwendet wird: LogUtils, ErrorHandlers, AuthUtils, reine KonverterCode, der nur von einem Feature verwendet wird, externe API-Aufrufe
schemas/Pydantic-Request/Response-Modelle (Django: serializers.py)DB-Modelle
models/PersistenzmodelleGeschäftslogik
prompts/Prompt-Templates als Code (nur wenn ein LLM verwendet wird)Prompts in .env
config.pyEin Einstellungsobjekt, geladen aus .envLogik

Regeln, die aus der Tabelle folgen:

  • Die Richtung ist eine Einbahnstraße. Routes rufen Helpers auf, Helpers rufen Services auf. Ein Service ruft niemals einen Helper auf; ein Utility ruft niemals einen Helper auf.
  • Datenbankaufteilung. Der Helper baut Feature-Abfragen (Filter, Suche, Besitz); der DB-Service führt sie aus und besitzt Verbindung, Sitzung, Commit und Rollback. Details in sql-silk / mongodb-silk. Bei Django ist das ORM die DB-Schicht, daher gibt es keinen db_service.
  • Keine Durchreichungsschichten. Wenn ein Helper nur an einen Service weiterleitet, lösche den Helper und rufe den Service direkt auf. Jede Datei muss ihren Platz verdienen.
  • Utils vs. Helpers. An vielen Stellen verwendet → utils/. Von einem Feature verwendet → der Helper dieses Features.
  • Erstelle Ordner und Dateien, wenn ein echter Bedarf entsteht, nicht vorab. Eine Funktion rechtfertigt niemals einen neuen Ordner (errors/, exceptions.py, core/); füge sie der vorhandenen passenden Klasse hinzu.
  • Namensgebung: <domain>_routes.py (enthält <domain>_router, oder <domain>_bp in Flask), <domain>_helper.py → XHelper, <domain>_service.py → XService, <domain>_schema.py, <domain>_utils.py → XUtils, <name>_prompt.py → NAME_PROMPT. Ein Klassenname stimmt immer mit seinem Ordner überein (eine class ExpenseService innerhalb von helpers/ ist falsch).

Vollständige Ordnerrollen und Startbäume: references/architecture.md.

Code-Regeln

  1. Klassenbasierte Module. Helpers, Services und Utils sind Klassen. Verwende @staticmethod/@classmethod für zustandslosen Code und Instanzen nur, wenn die Klasse eine Abhängigkeit hält (z.B. eine injizierte Sitzung oder einen Client). Routen-Dateien und Django urls.py bleiben auf Modulebene. Erzwinge keine Vererbung, abstrakte Basisklassen oder Interfaces ohne zwei reale Implementierungen.
  2. Funktionen bleiben bei etwa 40–50 Zeilen. Teile eine lange Funktion in sinnvolle Methoden derselben Klasse auf (z.B. list_expenses → parse_filter_parameters + apply_expense_filters), nicht in willkürliche Teile.
  3. Keine Funktionsnamen, die mit _ beginnen. Keine in Funktionen definierten Funktionen. Registriere Handler mit expliziten Aufrufen wie app.add_exception_handler(...) anstatt mit verschachtelten dekorierten Funktionen.
  4. Alle Importe am Anfang der Datei, gruppiert stdlib → Drittanbieter → app.*. Behebe zirkuläre Importe, indem du Code in das richtige Modul verschiebst, nicht durch Importe innerhalb von Funktionen. Die eine akzeptierte Ausnahme sind Flask-Blaupausen-Importe innerhalb von create_app().
  5. Verwende etablierte Bibliotheken anstelle von selbstgeschriebener Logik: password-validator, email-validator/EmailStr, PyJWT, bcrypt, LangChain-Lader und -Splitter, httpx.
  6. Einmal validieren. Wenn das Pydantic-Schema bereits eine Regel durchsetzt, überprüfe sie nicht erneut im Helper.
  7. Berechne nicht zweimal dasselbe in einer Anfrage und scheitere frühzeitig. Führe billige Prüfungen vor teuren durch (doppelte E-Mail-Prüfung vor bcrypt-Hashing).
  8. Keine hartcodierte Konfiguration: URLs, Modellnamen, Limits, top_k, Temperatur und Secrets kommen aus config.py.
  9. Kein toter Code: ungenutzte Funktionen, ungenutzte Importe, leere Platzhalterdateien und startapp-Überreste werden entfernt.
  10. Typannotationen und ein einzeiliger Docstring bei jeder Klasse und öffentlichen Methode. Kommentare nur, wo der Grund nicht offensichtlich ist.
  11. Schlucke niemals Ausnahmen. Fange spezifische Ausnahmen, wo du darauf reagieren kannst; lass den Rest zum globalen Handler gelangen.

Over-Engineering-Check

Bevor du eine Datei, Klasse, Schicht, Abhängigkeit oder ein Muster hinzufügst, frage: Benötigt die aktuelle Anforderung es, und tut etwas bereits Vorhandenes es schon? All dies wurde gebaut und dann entfernt:

  • pydantic-settings oder Validierungsframeworks, bevor die App läuft (eine frozen dataclass config ist genug)
  • ein neues Exception-Modul oder eine neue Klasse für einen Fehler
  • Helpers, die nur einen Service aufrufen
  • RS256-Schlüsselpaare zwischen zwei eigenen Diensten (ein HS256-Shared-Secret reicht)
  • gespeicherte abgeleitete Werte (total_tokens, wenn input + output existieren)
  • zwei Collections oder Tabellen, wo eine mit einer eingebetteten Liste funktioniert
  • lange Prompts und lange Tool-Beschreibungen

Wenn mehrere Entwürfe funktionieren, wähle den einfachsten, der noch produktionssicher ist.

Request- und Response-Schemas (Zusammenfassung)

  • Jeder Endpunkt validiert seinen Body und Query-Parameter mit einem Request-Schema, das unbekannte und servereigene Felder ablehnt; Code nach der Validierung verwendet nur das validierte Objekt.
  • Jede erfolgreiche Response wird aus einem Response-Schema gebaut: der Ressource selbst (XResponse), einer Liste {"items", "page", "page_size", "total", "total_pages"}, oder einem Aktionsergebnis-Schema (TokenResponse). Kein Envelope, keine im Handler zusammengebauten Objektliterale.
  • Statuscodes tragen Erfolg und Misserfolg: 200 Lesen/Aktualisieren, 201 Erstellen, 204 Löschen ohne Body, Fehler mit ErrorResponse. Niemals einen Fehler mit 200.

Vollständiger Vertrag und wo Schemas pro Framework leben: references/api-design.md.

Fehler (Zusammenfassung)

  • Jede Fehler-Response hat eine Form, aus assets/common_schema.py: {"status": "error", "message": "...", "details": [{"field": "...", "message": "..."}]} (details nur bei Feld-Fehlern)
  • Services werfen einfache oder Bibliotheksausnahmen; Helpers werfen HTTP-Fehler für erwartete Fälle; eine ErrorHandlers-Klasse in utils/error_handlers.py bildet Abhängigkeitsfehler ab und fängt alles andere als 500.
  • Statuscodes: 400 schlechte Eingabe, 401 nicht authentifiziert, 404 fehlender oder Datensatz eines anderen Benutzers, 409 Duplikat, 413 zu groß, 422 Schema-Validierung, 424 eigene Abhängigkeit ausgefallen (Datenbank, Vektor-Store), 429 Upstream-Ratenbegrenzung, 502 Upstream-Fehler, 503 anderer Dienst nicht erreichbar, 504 Upstream-Timeout, 500 unerwartet. Niemals 200 für einen Fehler.
  • Benutzer sehen eine kurze sichere Nachricht, niemals einen Traceback, Host, Verbindungsstring oder Schlüssel.

Checkliste für Randfälle und Handler-Muster: references/errors-and-edge-cases.md. Aufrufe zwischen Repositories: references/cross-repo-communication.md.

Logging (Zusammenfassung)

Eine LogUtils-Klasse (assets/log_utils.py), einmalig beim Start konfiguriert aus LOG_LEVEL und LOG_TO_FILE in .env; jedes andere Modul macht nur logger = LogUtils.get_logger(__name__). Format %(asctime)s | %(levelname)s | %(name)s | %(message)s, Nachrichten als Event | key=value, keine Secrets oder personenbezogene Daten, jeder Fehler einmal geloggt. Details: references/logging.md.

Konfiguration und Sicherheit (Zusammenfassung)

  • config.py mit einer frozen dataclass, geladen aus .env (assets/config.py); .env.example mit Platzhaltern und Kommentaren committed (assets/env.example), .env niemals committed (assets/gitignore).
  • Passwörter: password-validator-Richtlinie nur bei der Registrierung, bcrypt/werkzeug-Hashing, generische „Ungültige E-Mail oder Passwort.“ beim Anmelden.
  • JWT: Secret aus .env, Benutzer-ID nur aus dem verifizierten Token, niemals aus dem Request-Body.
  • Jede Abfrage ist auf den aktuellen Benutzer beschränkt; Datensätze anderer Benutzer geben 404 zurück.

Details: references/security.md. API-Konventionen (Methoden, Paginierung, Filter, Suchparameter): references/api-design.md.

Git und Tests (Zusammenfassung)

  • Niemals committed: .env, Schlüssel, Zugangsdaten, Uploads, Vektordaten, lokale Datenbanken, Logs, virtuelle Umgebungen, generierte Berichte. Migrationen werden mit der Modelländerung, die sie erzeugt hat, committed.
  • Commit-Nachrichten folgen Conventional Commits (feat:, fix:, refactor:, chore:, test:, docs:, perf:), ein Anliegen pro Commit, ein Commit pro Repository.
  • Tests decken kritische Pfade ab: Auth, Besitz zwischen Benutzern, Validierung, Fehler-Responses, Abhängigkeitsfehler (gemockt). Externe Dienste (LLMs, andere Repos) werden gemockt.
  • Evaluierungen (Goldene Datensätze, Eval-Skripte, Berichte) existieren nur, wenn explizit angefordert; siehe rag-spider / mcp-spider.

Details: references/git-and-testing.md.

Code-Checkliste

  • Schichten eingehalten; keine Durchreichungsdatei; Klassennamen stimmen mit Ordnern überein
  • Keine führenden Unterstriche oder verschachtelten Funktionen; Importe oben; Funktionen ≤ ~50 Zeilen
  • Bestehendes Verhalten erhalten (Filter, Paginierung, Validierung, Response-Felder)
  • Jeder Endpunkt hat ein Request-Schema und ein Response-Schema; keine Ad-hoc-Response-Objekte
  • Randfälle aus references/errors-and-edge-cases.md mit korrekten Statuscodes behandelt
  • Neue Einstellungen in config.py und .env.example; nichts hartcodiert; keine Secrets im Code oder in Logs
  • Logging hinzugefügt, wo es passt, auf der richtigen Ebene
  • Keine ungenutzten Importe oder toten Code hinterlassen

Referenzdateien (nur bei Bedarf lesen)

DateiLesen bei
references/architecture.mdErstellen eines Projekts, Hinzufügen eines Feature-Ordners, unsicher, wo Code hingehört
references/errors-and-edge-cases.mdSchreiben von Endpunkten, Fehler-Handlern oder Überprüfen von Fehlerpfaden
references/cross-repo-communication.mdEin Dienst ruft ein anderes Repo, einen MCP-Server oder eine externe API auf
references/logging.mdEinrichten oder Überprüfen des Loggings
references/security.mdAuthentifizierung, Passwörter, JWT, Uploads, Secrets, CORS
references/api-design.mdEntwerfen von Endpunkten, Request/Response-Schemas, Paginierung, Filtern, Suche
references/git-and-testing.mdCommits, PR-Beschreibungen, was niemals committed wird, Tests, Debugging-Ansatz

Asset-Dateien (in das Projekt kopieren und anpassen)

Kopiere Vorlagen selektiv: behalte nur die Teile, die dieses Projekt jetzt verwendet (Abschnitte von .gitignore, .env.example-Schlüssel, Konfigurationsfelder). Übrig gebliebene Zeilen für Features, die das Projekt nicht hat, sind Ballast und führen den nächsten Leser in die Irre.

DateiWird zu
assets/log_utils.pyapp/utils/log_utils.py
assets/common_schema.pyapp/schemas/common_schema.py
assets/config.pyapp/config.py
assets/env.example.env.example
assets/gitignore.gitignore (der „Immer"-Abschnitt plus nur die markierten Abschnitte, die zutreffen)

Verwandte Skills