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:
| Situation | Außerdem verwenden |
|---|---|
| Flask / FastAPI / Django-Projekt | flask-spider / fastapi-spider / django-spider |
| Node.js / Express-Projekt | node-spider (die Regeln hier gelten; Python-Codebeispiele sind in Python) |
| MCP-Server oder MCP-Client | mcp-spider |
| PostgreSQL, MySQL, SQLite (SQLAlchemy, Django ORM) | sql-silk |
| MongoDB | mongodb-silk |
| LLM, Embeddings, Vektor-Store, RAG | rag-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
- 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
dateanstelle des echtenexpense_datehat 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. - Entscheide zuerst die Routen. Liste für ein Feature jeden Endpunkt (Methode, Pfad, Request, Response, Statuscodes, Authentifizierung) auf, bevor du implementierst.
- 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.
- 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
| Ordner | Besitzt | Darf 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 Helpers | Geschä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 Repos | Featurespezifische Geschäftsregeln, HTTP-Kenntnisse (HTTPException, Statuscodes), Aufrufe von Helfern |
utils/ | Klassenbasierter Code, der von mehreren Modulen wiederverwendet wird: LogUtils, ErrorHandlers, AuthUtils, reine Konverter | Code, der nur von einem Feature verwendet wird, externe API-Aufrufe |
schemas/ | Pydantic-Request/Response-Modelle (Django: serializers.py) | DB-Modelle |
models/ | Persistenzmodelle | Geschäftslogik |
prompts/ | Prompt-Templates als Code (nur wenn ein LLM verwendet wird) | Prompts in .env |
config.py | Ein Einstellungsobjekt, geladen aus .env | Logik |
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 keinendb_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>_bpin 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 (eineclass ExpenseServiceinnerhalb vonhelpers/ist falsch).
Vollständige Ordnerrollen und Startbäume: references/architecture.md.
Code-Regeln
- Klassenbasierte Module. Helpers, Services und Utils sind Klassen. Verwende
@staticmethod/@classmethodfü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 Djangourls.pybleiben auf Modulebene. Erzwinge keine Vererbung, abstrakte Basisklassen oder Interfaces ohne zwei reale Implementierungen. - 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. - Keine Funktionsnamen, die mit
_beginnen. Keine in Funktionen definierten Funktionen. Registriere Handler mit expliziten Aufrufen wieapp.add_exception_handler(...)anstatt mit verschachtelten dekorierten Funktionen. - 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 voncreate_app(). - Verwende etablierte Bibliotheken anstelle von selbstgeschriebener Logik:
password-validator,email-validator/EmailStr, PyJWT, bcrypt, LangChain-Lader und -Splitter,httpx. - Einmal validieren. Wenn das Pydantic-Schema bereits eine Regel durchsetzt, überprüfe sie nicht erneut im Helper.
- 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).
- Keine hartcodierte Konfiguration: URLs, Modellnamen, Limits, top_k, Temperatur und Secrets kommen aus
config.py. - Kein toter Code: ungenutzte Funktionen, ungenutzte Importe, leere Platzhalterdateien und
startapp-Überreste werden entfernt. - Typannotationen und ein einzeiliger Docstring bei jeder Klasse und öffentlichen Methode. Kommentare nur, wo der Grund nicht offensichtlich ist.
- 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": "..."}]}(detailsnur bei Feld-Fehlern) - Services werfen einfache oder Bibliotheksausnahmen; Helpers werfen HTTP-Fehler für erwartete Fälle; eine
ErrorHandlers-Klasse inutils/error_handlers.pybildet 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.pymit einer frozen dataclass, geladen aus.env(assets/config.py);.env.examplemit Platzhaltern und Kommentaren committed (assets/env.example),.envniemals 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.mdmit korrekten Statuscodes behandelt - Neue Einstellungen in
config.pyund.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)
| Datei | Lesen bei |
|---|---|
references/architecture.md | Erstellen eines Projekts, Hinzufügen eines Feature-Ordners, unsicher, wo Code hingehört |
references/errors-and-edge-cases.md | Schreiben von Endpunkten, Fehler-Handlern oder Überprüfen von Fehlerpfaden |
references/cross-repo-communication.md | Ein Dienst ruft ein anderes Repo, einen MCP-Server oder eine externe API auf |
references/logging.md | Einrichten oder Überprüfen des Loggings |
references/security.md | Authentifizierung, Passwörter, JWT, Uploads, Secrets, CORS |
references/api-design.md | Entwerfen von Endpunkten, Request/Response-Schemas, Paginierung, Filtern, Suche |
references/git-and-testing.md | Commits, 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.
| Datei | Wird zu |
|---|---|
assets/log_utils.py | app/utils/log_utils.py |
assets/common_schema.py | app/schemas/common_schema.py |
assets/config.py | app/config.py |
assets/env.example | .env.example |
assets/gitignore | .gitignore (der „Immer"-Abschnitt plus nur die markierten Abschnitte, die zutreffen) |