pyramid/CLAUDE.md

Pyramid – Arbeitsregeln für Claude

Pyramid ist Bernds eigener Matrix-Client (Flutter, kein FluffyChat-Fork). Bernd ist kein Entwickler – er gibt Ziele und Prioritäten vor, Claude trifft die technischen Entscheidungen und erklärt sie in einfachem Deutsch. Die App ist bei echten Nutzern im Einsatz (u. a. Uta) – Stabilität und Datensicherheit gehen vor Feature-Tempo.

Dies ist das einzige aktuelle Repo: C:\Users\nordm\pyramid - Kopie\. (C:\Users\nordm\pyramid und C:\Users\nordm\MatrixPi\pyramid sind veraltete April-Schnappschüsse – dort NIE arbeiten.)

Bernds Entscheidungen zu den offenen Richtungsfragen stehen in ANTWORTEN_BERND.md (zuletzt 2026-07-05) – vor dem Abarbeiten von ROADMAP-Punkten lesen, sie sind maßgeblich.

Infrastruktur

• Homeserver: Continuwuity auf dem Pi5 (steggi-matrix.work)
• LiveKit/TURN: Hetzner „Leuchtturm" → wss://livekit.steggi-matrix.work (API-Key LKMatrixPi), coturn 94.130.78.116:3478
• Git-Remote: Gitea auf dem Pi (http://192.168.178.71:3000/steggi/pyramid.git) – Push = Backup
• Push-Benachrichtigungen: FCM + Sygnal auf dem Pi (Memory „Pyramid Push" lesen, bevor daran gearbeitet wird)
• Vollbackup vom 2026-07-03: MatrixPi\backups\pyramid-kopie_backup_2026-07-03.tar.gz

Arbeitszyklus (IMMER einhalten)

Jede Session – egal ob frisch gestartet oder fortgesetzt – läuft so:

1. Einlesen: PROGRESS.md (letzter Stand, Stolperfallen) und ROADMAP.md (nächster offener Punkt) lesen. NIE Arbeit doppelt machen, die dort als erledigt steht.
2. Einen Punkt nehmen: den obersten nicht abgehakten Punkt des aktuellen Meilensteins aus ROADMAP.md – nicht mehrere gleichzeitig, keine Sprünge in spätere Meilensteine.
3. Umsetzen & prüfen: Nach der Änderung mindestens flutter analyze sauber bekommen; wo sinnvoll flutter test und flutter run -d windows (schnellster Praxistest).
4. Protokollieren: PROGRESS.md aktualisieren (Format siehe dort) und den Punkt in ROADMAP.md abhaken.
5. Commit + Push: kleiner git commit (feat:/fix:/refactor:/chore:) und git push origin master (Gitea = Backup). Lieber 5 kleine Commits als ein riesiger.
6. Weiter mit dem nächsten Punkt, solange Kontingent/Zeit da ist.

Wird eine Session mitten in einem Punkt abgebrochen (Limit erreicht), MUSS der letzte Eintrag in PROGRESS.md den Zwischenstand beschreiben: was halb fertig ist, welche Dateien angefasst wurden, was der nächste konkrete Handgriff ist.

Qualitätsleitplanken

• Kein Aussperren, kein Datenverlust: Alles rund um Login, Sessions, Verschlüsselung und Key-Backup ist heilig. Der Uta-Random-Logout-Bug zeigt: Fehlerpfade dürfen NIE in einem stillen Logout enden. Änderungen daran immer mit Test: Login → Nachrichten → Logout → erneuter Login → alte verschlüsselte Nachrichten noch lesbar?
• Nach dem Refactoring (M2) gilt: keine Verhaltensänderung ohne Not – Refactoring heißt gleiche Funktion, bessere Struktur. Nach jedem Refactoring-Schritt App starten und Kernflows prüfen (Login, Raum öffnen, Nachricht senden, Voice-Channel beitreten).
• Keine Secrets ins Repo: Tokens, Recovery-Keys, Passwörter, Keystore-Dateien niemals committen (Signing-Keys liegen in Documents\pyramid_keys_20260425.txt).
• Modularität (Bernd wichtig!): Die Architektur muss aus austauschbaren Bausteinen bestehen – jedes Feature (Calls, Streaming, Push, Chat-Timeline, …) hinter einer klaren, schmalen Schnittstelle, sodass man einen alten Baustein durch einen neuen ersetzen kann, ohne den Rest anzufassen. Beim Refactoring (M2) ist das DAS Leitprinzip; bei jedem neuen Feature fragen: „Könnte man dieses Modul in einem Jahr komplett neu schreiben, ohne andere Module zu ändern?"
• Abhängigkeiten: neue Pakete nur mit gutem Grund, etabliert und gepflegt.
• Umgebung beachten: Auf dem Pi (SSH/tmux-Sessions) ist evtl. kein Flutter-Toolchain verfügbar. Dann trotzdem sauber arbeiten, aber jeden Schritt in PROGRESS.md als „UNGETESTET (Pi)" markieren – der nächste PC-Lauf holt flutter analyze + Praxistest nach.
• Bernd fragen nur bei echten Richtungsentscheidungen (UX-Geschmack, Priorität) – Fragen in PROGRESS.md unter „Fragen an Bernd" sammeln statt die Session zu blockieren.

Nützliches Wissen

• Discord ist die UX-Referenz für Calls/Voice-Channels (Join/Leave, Nutzer-Lautstärke, Geräteauswahl, Noise Suppression, Streaming-Qualitätswahl).
• CHANGES.md ist ein automatisches Änderungslog (Hook) – nicht von Hand pflegen.
• Windows-Build ist der schnellste Testweg; Android-Release über das Release-Skript (siehe Commit d706ace), signiert – Play-Protect-Warnung siehe ROADMAP M6.