petfeed/WORKFLOW.md

WORKFLOW.md

Dokumentiert den Ablauf, den ich (Claude Code) in diesem Projekt einhalte, sobald ein Prompt eingeht. Stand: nach der ersten Automatisierungsrunde vom 2026-09-19 — vier Punkte wurden vom Entscheidungs- in den verbindlichen Status überführt (siehe „Beschlossene Automatisierungen" unten). Basis sind weiterhin zwei Quellen, die nicht immer deckungsgleich sind:

1. Die formalen Projektregeln unter .claude/rules/ecc/** (Agent-Orchestrierung, TDD, Code-Review-Agenten, 80 %-Testabdeckung, ...)
2. Das tatsächliche Verhalten in laufenden Sessions

Verbleibende Lücken zwischen beidem stehen weiter unten, offen zur Diskussion.

---

1. Eingang eines Prompts

Bei jeder neuen Nachricht lade ich (automatisch, vom Harness bereitgestellt, kein eigener Schritt):

• CLAUDE.md (Projekt-Root + mobile/ + globale ~/.claude/CLAUDE.md)
• Alle .claude/rules/ecc/**-Dateien, die für den Kontext relevant sind (common + web + react + typescript + ...)
• Gespeicherte Memories (~/.claude/projects/.../memory/*.md) — projektspezifisches Wissen, das nicht im Code steht (z. B. "NAS hat kein Node im PATH", "nie git add -A")
• Git-Status-Snapshot (Branch, offene Änderungen, letzte Commits)

Ich lese das als Kontext, nicht als neue Anweisung — es sei denn, der Prompt selbst bezieht sich darauf.

2. Einordnen der Anfrage

Art der Anfrage	Beispiel	Reaktion
Bug-Report / Fehleranalyse	"die Notification zeigt PET_SUGGESTION an"	Root-Cause suchen, bevor irgendwas geändert wird
Konkreter Umsetzungsauftrag	"richte den NAS-Cron ein"	Direkt umsetzen, Zwischenstände kurz melden
Frage / Erklärung	"haben wir eine Backup-Funktion im Adminpanel?"	Antworten, ggf. mit Code-Beleg — nicht ungefragt bauen
Deploy-/Produktions-Aktion außerhalb der beschlossenen Automatisierung	z. B. DB-Restore	Nur nach expliziter Bestätigung ausführen
Großes Mobile-Feature (neu, nicht Bugfix/kleiner Fix)	z. B. Story-Musik-Overlay, Pet-Suggestion-Notifications	Zuerst Planner, dann eigener Feature-Branch — siehe Abschnitt 9a
Doku-/Meta-Auftrag	dieses Dokument hier	Direkt umsetzen

Bei Unklarheit: lieber die naheliegendste Lesart umsetzen und den Punkt kurz benennen, als mit einer Rückfrage blockieren — außer die Aktion ist riskant/schwer umkehrbar (siehe 6).

3. Root-Cause-Untersuchung (bei Bugs)

Bevor ich etwas ändere:

1. Code lesen, nicht raten — betroffene Datei(en) über Grep/Glob/Read finden, nicht über Vermutung
2. Bei Diskrepanz zwischen Code und beobachtetem Verhalten: prüfen, ob der Code überhaupt in Produktion läuft (Beispiel aus der Praxis: OTA-Update war 6 Tage nicht gepublished → Code war korrekt, kam aber nie an)
3. Datenbank-Fakten statt Annahmen: bei Verdacht auf Datenproblem lieber direkt gegen die echte DB prüfen (via NAS-Container) als zu spekulieren
4. Denselben Fehler an anderer Stelle suchen — gezielt per Grep nach demselben Muster in verwandten Dateien. Seit 2026-09-19 beschlossen: gefundene Zwillings-Instanzen werden automatisch mitgefixt, nicht nur gemeldet (Beispiel: story-new.tsx/search.tsx hatten denselben Dark-Mode-Bug wie post-new.tsx). Ausnahme: der Fix wäre selbst ein größeres, eigenständiges Vorhaben (neues Feature, Architekturänderung) statt einer echten Wiederholung desselben Musters — dann melden + Rückfrage statt automatisch ausweiten.

4. Umsetzung

• Pattern-Matching mit bestehendem Code: neue/geänderte Screens nach dem Muster einer bereits funktionierenden, vergleichbaren Datei im selben Projekt bauen (z. B. milestone-new.tsx als Vorlage für den post-new.tsx-Fix), nicht nach generischem Best-Practice-Wissen
• Kleinstmöglicher Diff für den gemeldeten Fehler, plus die in Schritt 3.4 automatisch mitgefixten Zwillings-Instanzen
• Rules aus .claude/rules/ecc/** (Naming, Dateigröße, Immutability, Fehlerbehandlung etc.) fließen beim Schreiben ein, ohne dass ich das jedes Mal einzeln abhake

5. Verifikation vor "fertig"

1. npx tsc --noEmit (bzw. npx tsc --noEmit --incremental je nach Hook-Konfiguration)
2. npx eslint <geänderte Datei(en)>
3. Bei Unsicherheit, ob eine Lint-/Type-Warnung neu ist: git stash → Tool erneut laufen lassen → git stash pop, um "vorbestehend vs. neu eingeführt" sauber zu trennen, statt das zu behaupten
4. Tests (npx vitest run), wenn im Umfeld der Änderung vorhanden — bei mobile-only-UI-Fixes bisher nicht Teil der Suite (kein RN-Testsetup in mobile/, nur src/__tests__/ auf Web-Seite)

Kein Schritt wird als "sauber" gemeldet, ohne dass er tatsächlich ausgeführt wurde.

6. Code-Review vor Commit (neu, seit 2026-09-19)

Nach Schritt 5, vor jedem Commit: Review des Diffs über die code-review-Skill (Findings-Format wie in .claude/rules/ecc/common/code-review.md vorgesehen — CRITICAL/HIGH/MEDIUM/LOW).

Anmerkung zur Umsetzung: .claude/rules/ecc/common/agents.md referenziert dafür einen code-reviewer-Agenten aus ~/.claude/agents/. Dieser Agent ist in der aktuell verfügbaren Agent-Liste dieser Umgebung nicht installiert (nur pentest-bezogene Agents + general-purpose/Explore/Plan). Die tatsächlich verfügbare, gleichwertige Instanz ist die code-review-Skill — die kommt hier zum Einsatz. Falls der code-reviewer-Agent künftig installiert wird, übernimmt er diese Rolle 1:1.

Ablauf:

• CRITICAL/HIGH-Befund → beheben, bevor committed wird (kein Override ohne Rückfrage)
• MEDIUM/LOW → beheben, wenn der Aufwand gering ist, sonst im Commit/found.md vermerken statt zu blockieren
• Keine Befunde → direkt weiter zu Schritt 7

7. Bestätigung vor riskanten/schwer umkehrbaren Aktionen

Ohne Rückfrage (laut Memory feedback_auto_commit_tested_changes: "tested/positive changes get auto commit+push+found.md update, no asking" — seit 2026-09-19 erweitert um die Deploy-Automatisierung aus Schritt 9):

• Commit + Push von verifiziertem, code-reviewtem Code (exakte Pfade stagen, nie git add -A)
• found.md-Einträge mit Analyse/Fix-Vermerk ergänzen
• Lesende Diagnose-Befehle (DB-Query, Log-Ansicht, crontab -l, ...)
• Web-Rolling-Deploy, sobald ein Web-Fix committed + verifiziert (Schritt 5) + code-reviewt (Schritt 6) ist
• Mobile-OTA-Publish, sobald ein reiner JS/UI-Fix committed + verifiziert + code-reviewt ist

Mit expliziter Rückfrage (weiterhin):

• Restore/Backup-Ausführung gegen die echte Produktions-DB
• Neue Infrastruktur/Cron-Einträge auf der NAS, bevor sie aktiv geschaltet werden
• Jede native Mobile-Änderung (neuer nativer Build/Store-Submission) — kein OTA-Fall
• Jede Aktion, die der Auto-Mode-Classifier selbst als "Production Deploy" blockiert — siehe Caveat in Schritt 9

Bei "riskant" zähle ich: nicht rückgängig machbar, betrifft echte Nutzer/echte Daten, oder verändert etwas außerhalb des Git-Repos (NAS, externe Dienste) und ist nicht durch die Deploy-Automatisierung aus Schritt 9 bereits abgedeckt.

8. Dokumentation

• found.md (mobile Tester-Feedback-Log): Antwort/Root-Cause/Fix direkt unter den gemeldeten Punkt schreiben, Format - [x] <Frage> + eingerückter →-Analyse-Text
• README.md (Projekt-Root, nicht mobile/): strukturelle Erkenntnisse, die über den Einzelfall hinaus relevant sind (neue Scripts, wiederkehrende Stolperfallen, dieser Workflow) — Ziel: nächste Session muss dasselbe Problem nicht neu lösen
• Keine Doku für Dinge, die nur diese Konversation betreffen oder die der Code/Git-Verlauf schon selbsterklärend zeigt

9. Git, Deploy und OTA-Publish — jetzt eine durchgehende Kette

Seit 2026-09-19 hängen Commit → Deploy/Publish direkt aneinander, ohne Zwischen-Rückfrage, sofern Schritt 5 (Verifikation) und Schritt 6 (Code-Review) sauber durchlaufen sind:

1. Commit: <type>: <Beschreibung> + ausführlicher Body (Root Cause, Warum-nicht-anders, Testergebnis) + Attribution-Zeile. Nie git add -A — immer exakte Pfade (siehe Memory project_repo_has_stray_uncommitted_work).
2. Push direkt danach, kein Sammel-Commit über mehrere Themen.
3. Automatischer Deploy/Publish, abhängig vom Änderungsort:
   • Änderung unter src/** (Web) → ./docker/rolling-deploy.sh auf der NAS
   • Änderung unter mobile/**, rein JS/UI, kein neues natives Modul → eas update --branch production --environment production --platform android
   • Änderung, die ein natives Modul/eine App-Version/app.json-Permission betrifft → kein automatischer Publish, stattdessen Rückfrage (das ist kein OTA-Fall, siehe mobile/PENDING-NATIVE-BUILD.md-Konvention)
   • Reine Doku-/Script-Änderung ohne Laufzeitwirkung auf App-Code (z. B. dieses Dokument, docker/backup-db.sh) → kein Deploy nötig

Technischer Vorbehalt: Der Auto-Mode-Classifier des Harness blockt bestimmte Bash-Kommandos aktiv als "Production Deploy" und verlangt dann trotzdem eine manuelle Bestätigung — unabhängig davon, was dieses Dokument vorsieht. Dieses Dokument beschreibt meine Absicht, den Deploy ohne Rückfrage anzustoßen; ob das technisch auch ohne Prompt durchläuft, hängt von der Classifier-Konfiguration ab, die ich nicht selbst ändern kann. Falls der Classifier weiter blockt, versuche ich den Deploy trotzdem sofort (statt vorher zu fragen) und der Prompt kommt dann vom Harness, nicht von mir aus Vorsicht.

• DB-Änderungen bleiben unverändert manuell/mit Rückfrage: prisma db push ausschließlich über einen Wegwerf-Container auf der NAS, nie migrate dev/reset (siehe Memory project_nas_db_tooling).

9a. Ausnahme: Große Mobile-Features → Planner + eigener Branch (neu, seit 2026-09-19)

Die durchgehende Commit→Deploy-Kette aus Schritt 9 gilt für Fixes und kleine Änderungen. Für ein großes neues Mobile-Feature gilt stattdessen:

1. Erst Planner, dann Code. Bevor eine Zeile geschrieben wird, läuft die Anforderung durch eine Planungsphase (Plan-Agent bzw. EnterPlanMode — das ist die in dieser Umgebung tatsächlich installierte Entsprechung von .claude/rules/ecc/common/agents.mds planner-Agent, der hier nicht verfügbar ist). Ergebnis: ein abgenommener Plan, bevor implementiert wird — wie bereits bei den Features "Pet-Suggestion-Notifications" und "Story-Musik-Overlay" praktiziert (Plan unter ~/.claude/plans/).
2. Eigener Feature-Branch statt direkt auf main: git checkout -b feature/<kurzname> vor dem ersten Commit des Features. Alle Zwischen-Commits des Features laufen auf diesem Branch.
3. Die Automatik aus Schritt 9 (OTA-Publish/Rolling-Deploy ohne Rückfrage) greift auf dem Feature-Branch nicht. Verifikation (5) und Code-Review (6) laufen trotzdem pro Commit mit — nur der automatische Publish/Deploy bleibt aus, solange der Branch nicht auf main ist.
4. Merge nach main erst nach Abschluss des Features (alle Teilschritte fertig, verifiziert, code-reviewt) — danach greift die normale Automatik aus Schritt 9 für den Merge-Commit.

Was als "groß" zählt (Beispiele aus bisherigen Sessions): neues Feature mit eigenem DB-Schema-Zusatz, neuer Screen/Flow, mehrere zusammenhängende Dateien über mehrere Domains (DB + tRPC + UI). Was NICHT darunterfällt (bleibt bei der normalen Kette aus Schritt 9): Einzeldatei-Bugfixes, auch wenn dabei mehrere Zwillings-Instanzen mitgefixt werden (Schritt 3.4) — das sind Fixes, keine neuen Features.

10. Abschlussmeldung

• Auf Deutsch, knapp, ohne Wiederholung des bereits Gesagten
• Faktentreu: was wirklich getestet wurde vs. was nur plausibel ist, wird nicht vermischt
• Offene Punkte/Restrisiken werden benannt statt verschwiegen
• Wenn automatisch deployed/published wurde: das explizit im Ergebnis nennen (nicht stillschweigend voraussetzen, dass der Nutzer es an den Log-Zeilen erkennt)

---

Beschlossene Automatisierungen (2026-09-19)

Diese vier Punkte sind nicht mehr zur Diskussion offen, sondern aktiver Bestandteil der Schritte oben:

#	Automatisierung	Bedingung	Umgesetzt in
1	OTA-Publish ohne Rückfrage	Typecheck + Lint sauber, Code-Review ohne CRITICAL/HIGH, reiner JS/UI-Fix	Schritt 9
2	Code-Review-Lauf vor jedem Commit	Immer, nach Verifikation	Schritt 6
3	Verwandte Bug-Instanzen automatisch mitfixen	Echtes Wiederholungsmuster, kein neuer Scope	Schritt 3.4
4	Web-Rolling-Deploy automatisch anstoßen	Web-Fix committed + verifiziert + code-reviewt	Schritt 9
5	Große Mobile-Features: Planner vorschalten + eigener Feature-Branch statt direkt auf main	Nur "groß" (siehe Definition in 9a), nicht für Einzeldatei-Fixes	Schritt 9a

Verbleibende Lücke zwischen formalen Regeln und gelebter Praxis

Formale Regel (.claude/rules/ecc/**)	Tatsächliche Praxis
planner-Agent für Planung vor jeder komplexen Änderung	Für große Mobile-Features jetzt via Plan-Agent/EnterPlanMode übernommen (Schritt 9a); für Web-Features weiterhin offen
tdd-guide-Agent, Test-First (RED→GREEN→REFACTOR), 80 % Coverage	Kein neuer Test für Mobile-UI-Fixes (keine RN-Testinfrastruktur vorhanden) — nur Typecheck/Lint/Code-Review als Gate
Parallele Multi-Agent-Recherche (GitHub-Suche, Context7, Exa) vor jeder Neuimplementierung	Nicht angewendet — direkt im bestehenden Code nach Mustern gesucht
Explizite Checkliste (Security/Quality) vor "fertig"	Implizit über Typecheck/Lint/Code-Review, nicht als abgehakte Liste

code-reviewer-Agent/-Skill ist mit der Automatisierung oben aus dieser Tabelle raus — nicht mehr offen.

Noch offen (zur Diskussion)

• Tests verpflichtend für mobile UI-Fixes einführen? Aktuell keine RN-Testinfrastruktur vorhanden — wäre selbst ein Vorprojekt (Jest/RNTL-Setup, erste Tests), bevor TDD für Mobile überhaupt greifen kann.
• planner-Agent (bzw. Plan/EnterPlanMode) auch für große Web-Features vorschalten? Für Mobile ist das seit 2026-09-19 entschieden (9a), für Web noch offen.
• Multi-Agent-Recherche (GitHub/Context7/Exa) vor Neuimplementierungen einführen, oder bei diesem Projektstand (etabliertes Codebase-Pattern-Matching reicht meist) verzichtbar?