---
description: Nexumi – verbindliche Projektregeln
alwaysApply: true
---

# Nexumi – Projektregeln

## Quelle der Wahrheit

- `docs/SPEC.md` ist die verbindliche Spezifikation. Lies sie vollständig, bevor du Architektur- oder Feature-Entscheidungen triffst.
- Bei Widerspruch zwischen Nutzer-Prompt und SPEC.md: nachfragen, nicht still entscheiden.
- Nichts aus der SPEC weglassen, vereinfachen oder durch Alternativen ersetzen, ohne vorher zu fragen.

## Arbeitsweise

- Arbeite strikt die Phasen im SPEC-Abschnitt „Vorgehen beim Bau" ab. Beginne keine neue Phase ohne ausdrückliche Freigabe.
- Jede Phase endet mit lauffähigem Stand: `docker compose up -d` funktioniert, Build, Lint und Tests sind grün.
- Keine Stub-Implementierungen, keine `TODO`-Platzhalter, keine auskommentierten Halbfertigteile in abgeschlossener Arbeit. Ein Modul ist fertig, wenn Commands, Datenbank, Jobs und (ab Phase 7) die WebUI-Seite funktionieren.
- Das Moderations-Modul aus Phase 1 ist das Referenzmodul. Jedes weitere Modul übernimmt dessen Struktur (Ordnerlayout, Command-Registrierung, Settings-Zugriff, Fehlerbehandlung, Tests) exakt.
- Bei Unsicherheit über Discord-API-Verhalten: discord.js-v14-Dokumentation prüfen statt raten. Keine erfundenen Methoden oder Events.

## Stack (nicht verhandelbar)

- TypeScript strict, discord.js v14+, ausschließlich Slash Commands / Context Menus / Komponenten. Keine Message-Prefix-Commands.
- PostgreSQL (Container im Stack) mit Prisma. Redis für Cache, Sessions, Rate Limits. Alle zeitgesteuerten Aufgaben über BullMQ, niemals über `setTimeout`/`setInterval` für persistenzpflichtige Dinge.
- WebUI: Next.js (App Router), Tailwind CSS, shadcn/ui, Lucide. Design-Vorgaben aus SPEC.md einhalten.
- Keine zusätzlichen Frameworks oder Bibliotheken mit überschneidender Funktion einführen, ohne zu fragen.

## Code-Konventionen

- Code, Bezeichner, Kommentare und Commit-Messages auf Englisch. Alle nutzersichtbaren Strings (Bot-Antworten, Embeds, WebUI) ausschließlich über i18n-Locale-Dateien, Deutsch und Englisch immer gemeinsam pflegen.
- Jede Eingabe validieren: Zod-Schemas für Command-Optionen und API-Routen. Bot und WebUI teilen sich die Schemas aus einem gemeinsamen Package.
- Jeder Command und jede API-Route prüft Berechtigungen (Discord-Permissions plus Dashboard-Rollenregeln), bevor irgendetwas ausgeführt wird.
- Destruktive Aktionen (Ban, Purge, Restore, Guild verlassen) immer mit Bestätigung und Audit-Eintrag.
- Keine Secrets im Code oder in Commits. Konfiguration nur über ein zentrales, mit Zod validiertes Env-Modul; `.env.example` bei jeder neuen Variable aktualisieren.
- Prisma: bereits angewendete Migrationen niemals nachträglich editieren; Schemaänderungen immer über neue Migration.
- Fehlerbehandlung zentral (Sentry + pino); keine leeren `catch`-Blöcke, keine verschluckten Promise-Rejections.

## Selbstkontrolle vor Abschluss

- `tsc --noEmit`, Lint und Tests laufen lassen und Ergebnis nennen.
- Kurz auflisten: was wurde gebaut, was ist bewusst offen, was muss der Nutzer manuell testen.