ninelands-reddit/CLAUDE.md

CLAUDE.md – Ninelands für Reddit (Devvit)

Diese Datei lädt Claude Code in jeder Sitzung. Sie hält fest, was dieses Projekt ist, wie gearbeitet wird und wo wir stehen. Stand: 2026-11-13, frisch angelegt aus der Devvit-Vorlage Bare.

Projekt

• Ninelands auf Reddit: eine Basic-Version von Ninelands als Reddit-Spiel (Devvit Web) für den Jam Reddit Game of the Day 2026 – https://redditgameofday2026.devpost.com/ (Regeln: /rules). Besitzer: Lukas Müllner (StackTeam). Mit dem Besitzer Deutsch sprechen.
• App-Name in devvit.json: ninelands-game. Ordner: /data/Documents/projects/ninelands-game.
• Repo: git@git.stackteam.at:DieLustigeTierwesen/ninelands-reddit.git (Forgejo, privat, angelegt 2026-11-13).
• Was die Basic-Version können soll, ist noch offen – das klären wir zuerst gemeinsam (Spieldesign entscheidet der Besitzer). Vorher nichts Spielerisches bauen.

Woher Fragen beantwortet werden

• Das Hauptspiel (Regeln, Engine, Gestaltung): Repo DieLustigeTierwesen/DokuHive, lokal /data/Documents/projects/hivedoku – dort README.md, hicedoku_plan.md (Entscheidungen „as built“), Leitfaden guide/chapters/. Bei Fragen zu Regeln oder Absicht dort nachlesen, nicht raten.
• Allgemeiner Spiele-Blueprint (Arbeitsweise, Fallstricke, Releases): Repo DieLustigeTierwesen/game-blueprint, lokal /data/Documents/projects/game-blueprint/AGENT.md. Erkenntnisse, die für künftige Spiele gelten (z. B. „wie baut man ein Devvit-Spiel“), dort nachtragen.

Grenzen zum Hauptspiel

• In /data/Documents/projects/hivedoku nichts ändern, committen oder pushen. Jeder Push auf dessen main deployt die Live-Seite; Releases dort (itch, Desktop, Android) laufen über npm run release und gehören nicht zu diesem Projekt.
• Die Engine von Ninelands (hivedoku/src/core, reines TypeScript ohne DOM/Server, seeded RNG, applyMove, legalMoves, Replay) darf übernommen werden – als Kopie mit festem Stand (z. B. Sync-Skript, das src/core von einem Ninelands-Tag holt und den Tag notiert). Die Kopie hier nicht von Hand ändern; Änderungen an der Engine gehören ins Hauptspiel. Achtung: src/core importiert JSON aus ../campaign/ und ../puzzles/ – nur mitnehmen, was die Basic-Version braucht.
• Lizenz klären, bevor Engine-Code kopiert wird: Ninelands steht unter GPL-3.0, diese Vorlage unter BSD-3-Clause (LICENSE stammt aus der Devvit-Vorlage). Kopierte GPL-Teile machen das Ganze GPL – die Lizenz entscheidet der Besitzer (auch, ob der Jam eine Open-Source-Lizenz verlangt).

Jam – vor der Arbeit prüfen

Die Devpost-Seiten blockieren automatische Abrufe (403). Der Besitzer liefert die Regeln; offen sind:

• Darf ein bestehendes Spiel (Basic-Version von Ninelands) eingereicht werden, oder nur während des Jams Entstandenes? Muss Vorhandenes angegeben werden?
• Abgabefrist, Pflichtteile der Einreichung (Video, Repo-Link, Test-Subreddit, Beschreibung), Bewertungskriterien, Regeln zu KI-Nutzung und Fremdcode.

Ergebnis hier unter „Stand“ festhalten.

Technik (Vorlage Bare)

• Devvit Web: Client src/client/ (Splash splash.ts → public/splash.html, Spiel game.ts → public/game.html), Server src/server/ (index.ts, server.ts, Speicher db.ts), gemeinsame Typen src/shared/api.ts. Gebaut mit esbuild nach public/ und dist/server/.
• Werkzeuge der Vorlage beibehalten: Biome (Lint + Format, npm run lint / npm run format) statt Prettier, Tests mit node --test (*.test.ts), Typprüfung tsc --build.
• Befehle: npm run test (Typen, Lint, Unit-Tests, Build – das ist die Prüfung vor jedem Merge), npm run playtest [r/sub] (baut, lädt hoch, installiert im Test-Subreddit), npm run publish (lädt hoch und stellt einen Review-Antrag bei Reddit – nur nach Rückfrage beim Besitzer).
• Node 24 über nvm (global ist 20): Befehle mit source ~/.nvm/nvm.sh && nvm use 24 >/dev/null && beginnen.
• Kein eigener Server, keine eigene Datenbank, keine eigenen Konten: Spieler sind Reddit-Nutzer, gespeichert wird über Devvit (Redis). Externe Netzaufrufe sind bei Devvit eingeschränkt – vor jeder Idee, die das Ninelands-Backend anspricht, in der Devvit-Doku prüfen (https://developers.reddit.com/docs).
• Aktuelle Devvit-Doku lesen, bevor etwas gebaut wird – die Plattform ändert sich schnell; nicht aus dem Gedächtnis arbeiten.
• .github/workflows/ci.yaml stammt aus der Vorlage. Forgejo führt .github/workflows aus, wenn es kein .forgejo/workflows gibt; runs-on: ubuntu-latest ist der gemeinsame Hetzner-Runner (für npm run test reicht er).

Arbeitsweise

• Ein Branch pro Änderung (feat/…, fix/…, chore/…), auch für Doku.
• Merge nur, wenn npm run test mit Exit-Code 0 endet. Ausgabe in eine Log-Datei, dann $? prüfen – nie mit | grep … && oder ; verketten. Muster: npm run test > log 2>&1; code=$?; if [ $code -eq 0 ]; then … merge; fi.
• git merge --no-ff, Branch löschen, main pushen (sobald ein Remote existiert), im Bericht erwähnen.
• Conventional Commits; Ende jeder Nachricht: Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>.
• Code-Kommentare auf Deutsch.
• Größere Entscheidungen und Fallstricke in PLAN.md (Abschnitt „as built“, Deutsch) festhalten; am Ende eines Schritts Erkenntnisse von sich aus nennen.
• Innerhalb eines vereinbarten Plans selbstständig weitermachen; anhalten bei Spieldesign, Geschmack, externen Konten, Geld, Lizenz und allem, was öffentlich wird (devvit publish, Posts in echten Subreddits).
• Kein Geld ausgeben.

Geheimnisse – nie ausgeben, nie committen

• Devvit-Token ~/.devvit/token (Reddit-Anmeldung des Besitzers): nie lesen, ausgeben oder kopieren; die devvit-Befehle nutzen ihn selbst.
• Forgejo-Token ~/.config/forgejo-token: nur innerhalb von Befehlen lesen.
• Nutzer sollen nie Schlüssel in den Chat kopieren.

Stand (2026-11-13)

• Vorlage Bare committet, Repo DieLustigeTierwesen/ninelands-reddit angelegt, main gepusht. Lint der Vorlage repariert (Biome-Schema 2.6.4 → 2.6.6, package.json ohne Schlusszeilenumbruch); npm run test lokal grün.
• CI auf Forgejo rot (Lauf 1 und 2, Workflow aus der Vorlage). Verdacht: die parallel:-Stufe in .github/workflows/ci.yaml (GitHub-Neuheit, Forgejo kennt sie vermutlich nicht) oder die per SHA gepinnten Actions (checkout v7, setup-node v6). Log-Zeilen vom Besitzer aus dem Browser holen, dann gezielt reparieren.
• Nächste Schritte:
  1. CI reparieren (siehe oben).
  2. Jam-Regeln vom Besitzer übernehmen (siehe oben).
  3. Mit dem Besitzer festlegen, was die Basic-Version kann.
  4. Lizenz entscheiden, dann Engine-Kopie + Sync-Skript.

Diese Datei bei neuen Arbeitsregeln und Entscheidungen aktualisieren.