Shuffle – Projektkontext für Claude Code

Diese Datei wird in jeder Claude-Code-Session automatisch geladen. Sie ist das "Gedächtnis" des Projekts. Halte sie kurz, aktuell und verbindlich. Details gehören nach docs/ oder in Outline.

Was ist Shuffle?

Shuffle ist eine Brettspiel-App für iOS, Android und Web aus einer gemeinsamen Codebasis. Die fachlichen Anforderungen liegen in requirements/ (Quelle der Wahrheit) und werden als User Stories in Forgejo-Issues umgesetzt.

Tech-Stack (ADR-0001 angenommen, Hosting ADR-0002)

Frontend: Flutter (stable) / Dart 3 – eine Codebasis für iOS, Android, Web
State-Management: Riverpod (mit Code-Generierung)
Navigation: go_router (Deep Links + Web-URLs)
Backend: Supabase (PostgreSQL 16, Auth, Storage, Realtime, Edge Functions), selbst gehostet auf Hetzner (ADR-0002); lokal per Supabase CLI. Nur Features nutzen, die auch self-hosted verfügbar sind; Dashboard-Einstellungen im Repo dokumentieren.
Modelle: freezed + json_serializable
Tests: flutter_test, mocktail, integration_test, Playwright (Web-E2E)
CI/CD: Forgejo Actions (.forgejo/workflows/)
Doku: Outline (Collection „Shuffle“), Architektur-Entscheidungen als ADRs in docs/adr/

Repository-Struktur

app/                    Flutter-App
  lib/
    core/               Theme, Routing, DI, Fehlerbehandlung, gemeinsame Widgets
    features/<feature>/ Feature-first: data/ domain/ presentation/
  test/                 Unit- und Widget-Tests (Spiegel von lib/)
  integration_test/
supabase/
  migrations/           SQL-Migrationen (nur additive Änderungen, nie bestehende editieren)
  functions/            Edge Functions (TypeScript/Deno)
  seed.sql
  tests/database/       pgTAP-Tests für Schema und RLS (`supabase test db`)
requirements/           Fachliche Anforderungen (10-anforderungen.md, 20-r1-akzeptanzkriterien.md)
docs/
  adr/                  Architecture Decision Records
  datenmodell-r1.md     Datenmodell R1 inkl. Tabellenstruktur (Migrationen sind maßgeblich)
  specs/                Technische Feature-Spezifikationen (eine pro Issue)
.claude/agents/         Spezialisierte Subagents
.claude/commands/       Slash-Commands für Workflows

Arbeitsweise (verbindlich)

Jede Änderung hat ein Forgejo-Issue. Kein Code ohne Issue-Nummer.
Branch pro Issue: feature/<nr>-<kurzname>, fix/<nr>-<kurzname>.
Spec vor Code: Für jedes Feature-Issue entsteht zuerst docs/specs/<nr>-<kurzname>.md (Agent architect). Chris gibt die Spec frei, bevor implementiert wird.
Tests sind Teil des Features, nicht nachgelagert. Kein PR ohne Tests für neue Logik.
Pull Request in Forgejo, Review durch Agent code-reviewer, Merge nur durch Chris.
Conventional Commits: feat(collection): ..., fix(auth): ..., test: ..., docs: ..., mit Refs #<nr> bzw. Closes #<nr>.

Definition of Done

Akzeptanzkriterien des Issues erfüllt und im PR einzeln abgehakt
dart format --set-exit-if-changed . und flutter analyze ohne Befund
Unit-/Widget-Tests grün, neue Logik getestet
Läuft auf Android, iOS und Web (oder Abweichung im PR begründet)
Supabase: Migration + RLS-Policies + Policy-Tests vorhanden, wenn Tabellen betroffen
Texte über l10n (app/lib/l10n/*.arb), keine hartkodierten UI-Strings (Deutsch + Englisch)
Barrierefreiheit: Semantics-Labels, ausreichende Kontraste, Touch-Ziele ≥ 48dp
Doku aktualisiert (Spec, ggf. ADR, ggf. Outline-Seite)

Code-Konventionen

Code, Bezeichner, Commits: Englisch. Doku, Specs, Issue-Texte: Deutsch.
Feature-first-Struktur, Abhängigkeiten nur nach innen (presentation → domain ← data).
Keine Geschäftslogik in Widgets. Widgets sind dumm, Logik in Notifiern/Use-Cases.
Keine print-Aufrufe; Logging über das zentrale Logger-Utility.
Secrets niemals ins Repo. Konfiguration über --dart-define-from-file=env/<stage>.json (in .gitignore).
Sicherheit: Jede Tabelle hat RLS aktiviert. Der Client vertraut niemals Client-Daten für Berechtigungen.

Agents (siehe `.claude/agents/`)

Agent	Zuständig für
`requirements-analyst`	Anforderungen → User Stories mit Akzeptanzkriterien → Forgejo-Issues
`architect`	Architektur, Datenmodell, ADRs, Feature-Specs, Aufgaben-Schnitt
`backend-dev`	Supabase: Migrationen, RLS, Edge Functions, Seeds
`flutter-dev`	Flutter-UI, State, Navigation, Datenanbindung
`ui-designer`	Design-System, Theme, Komponenten, UX-Konsistenz, Barrierefreiheit
`test-engineer`	Teststrategie, Unit-/Widget-/Integration-/E2E-Tests
`code-reviewer`	Review gegen DoD, Sicherheit, Architektur (nur lesend)
`devops`	Forgejo Actions, Builds, Releases, Umgebungen
`docs-writer`	Outline-Doku, Changelog, Release Notes

Workflows (Slash-Commands)

/intake – neue Anforderungen aus requirements/ in Stories + Issues überführen
/feature <issue-nr> – komplette Pipeline: Spec → Freigabe → Umsetzung → Tests → Review → PR
/review <pr-nr> – Review eines PRs
/adr <titel> – neue Architekturentscheidung dokumentieren
/release <version> – Release vorbereiten

Wichtige Befehle

cd app && flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter analyze && flutter test
flutter run -d chrome --dart-define-from-file=env/dev.json
supabase start            # lokales Backend
supabase db reset         # Migrationen + Seed neu einspielen
supabase test db          # RLS-/pgTAP-Tests

Werkzeuge (MCP)

forgejo – Issues, PRs, Labels, Milestones im Repo shuffle
outline – Doku-Collection „Shuffle“
dart – Analyse, Tests, pub.dev-Suche, laufende App inspizieren
playwright – Web-Build im Browser testen

Daten & Sicherheit (R1)

Datenmodell: docs/datenmodell-r1.md, Migrationen in supabase/migrations/ (nie bestehende ändern).
Alle Tabellen: id (uuid), created_at, updated_at; FKs nur zwischen verwandten Tabellen (<tabelle>_id).
Jede neue Tabelle braucht RLS, Policies und pgTAP-Tests in supabase/tests/database/.
In R1 sind alle Nutzerdaten privat; Katalog ist öffentlich lesbar, Pflege nur Admin.
Akzeptanzkriterien werden als „KTO-01 Kriterium 3“ in Tests und PR-Checklisten referenziert.

Grenzen

Nichts nach main pushen. Kein Force-Push. Keine Releases ohne Freigabe von Chris.
Bei unklaren fachlichen Fragen: nicht raten – Frage als Kommentar ins Issue schreiben und Label needs-clarification setzen.

6.5 KiB Raw Blame History Unescape Escape