From f5281a5aeae9feccee564e9bd9bc3a1419d26472 Mon Sep 17 00:00:00 2001 From: Sandro Date: Sat, 31 Oct 2026 12:27:19 +0100 Subject: [PATCH] docs: agent instructions (language, checks, release order via CI, UI rules) Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 82 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b007ef6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,81 @@ +# Hinweise für Coding-Agenten + +Regeln für die Arbeit an MindSift, die nicht aus dem Code selbst hervorgehen. Aufbau und Technik stehen in [Doku/](Doku/README.md), vor allem [architecture.md](Doku/architecture.md). + +## Sprache und Stil + +- **Deutsch:** Oberflächentexte, Fehlermeldungen für Nutzer, E-Mails, `CHANGELOG.md`, `README.md`, `Doku/`. +- **Englisch:** Code-Kommentare und Commit-Nachrichten. +- **Commit-Nachrichten** im Stil `feat(bereich): …`, `fix(bereich): …`, `docs: …`, `style(bereich): …`. Am Ende die Zeile `Co-Authored-By: …` des jeweiligen Agenten. +- Neuer Code richtet sich nach dem umgebenden Code: Benennung, Kommentardichte, vorhandene Helfer statt neuer Varianten. + +## Umgebung + +Auf dem Entwicklungsrechner sind weder Node noch Go installiert. Alles läuft in Containern (podman): + +```bash +# Frontend: Typen, Lint, Tests +podman run --rm -v "$PWD/frontend":/app:Z -w /app docker.io/library/node:22-alpine \ + sh -c "npx tsc --noEmit && npx eslint src/… && npx vitest run" + +# Backend: vet und Tests +podman run --rm -v "$PWD":/src:Z -w /src docker.io/library/golang:1.24-alpine \ + sh -c "go vet ./... && go test ./internal/..." +``` + +Die Linter-Warnungen `react-hooks/exhaustive-deps` gibt es schon länger; neuer Code soll keine zusätzlichen Warnungen bringen. + +## Prüfen während der Arbeit + +- **Gezielt prüfen:** `tsc`, die betroffenen Frontend-Tests, `go vet` und `go test`. Den vollen Build macht nur der Server (siehe Release-Ablauf); ein kompletter `podman build .` vorher ist doppelte Arbeit. +- **Oberfläche im Browser ansehen**, besonders Handy-Ansichten: Image bauen, im Demo-Modus starten, mit Playwright aus dem `e2e/`-Ordner prüfen (Vorbild: `e2e/screenshots.sh`). Handy-Emulation mit `isMobile: true, hasTouch: true`; Finger-Gesten lassen sich über das Chrome DevTools Protocol (`Input.dispatchTouchEvent`) nachstellen. + + ```bash + podman build -q -t mindsift-check . + podman run -d --rm --name ms-check --network host -e PORT=18555 -e MINDA_DEMO=true \ + -e DEMO_RESET_MINUTES=0 -e JWT_SECRET=check-only mindsift-check + # Demo-Anmeldung: admin/admin bzw. user/user + ``` +- **Zeitabhängiger Code** (Alarme, Tageszusammenfassung, Begrüßungen, Termine): nie `time.Now()` dort, wo eine übergebene Zeit gemeint ist. Die betroffenen Go-Tests zusätzlich mit verschiedenen `TZ`-Werten laufen lassen (z. B. `Europe/Berlin`, `America/Los_Angeles`, `Asia/Tokyo`). Ein uhrzeitabhängiger Test hat schon einmal einen Release verhindert, weil er nur vormittags grün war. + +## Release-Ablauf + +**Committen** ist jederzeit erlaubt. **Jeder Push ist ein Release**, also mit Version und CHANGELOG-Eintrag. + +1. **Version erhöhen** (SemVer: Fehlerbehebung → Patch, neue Funktion → Minor): + - `frontend/package.json` (Feld `version`) + - `frontend/package-lock.json`: nur die beiden Versionszeilen von MindSift selbst (Zeile 3 und 9), nicht die gleichlautenden Versionen von Abhängigkeiten + - Versions-Badge oben in `README.md` +2. **CHANGELOG:** neuer Abschnitt `## [x.y.z] - JJJJ-MM-TT` unter `## [Unreleased]` (Format *Keep a Changelog*, Abschnitte Added/Changed/Fixed), unten die Vergleichslinks `[Unreleased]` und `[x.y.z]` anpassen. Einträge auf Deutsch und aus Sicht der Nutzer. +3. **Doku nachziehen**, wenn sich Verhalten oder API ändern (`README.md`, `Doku/api/rest.md`, `Doku/architecture.md`). +4. Committen, dann **nur nach `dev` pushen**. +5. **Warten, bis der `dev`-Build auf dem Server grün ist.** Schlägt er fehl: auf `dev` beheben, nicht nach `main` mergen. +6. Nach `main` mergen (`git merge --no-ff dev -m "Merge dev into main (vx.y.z)"`) und pushen. +7. **Warten, bis der `main`-Build grün ist.** Erst dann gilt das Release als draußen. + +Ist ein Release nie gebaut worden (CI fehlgeschlagen), bleibt die Versionsnummer, und die Korrektur kommt in denselben CHANGELOG-Abschnitt. + +**Git-Tags nur auf ausdrücklichen Wunsch.** Tags lassen zusätzliche Images bauen; genutzt werden nur `:dev` und `:latest`. Wenn gewünscht: `git tag -a vx.y.z -m "MindSift vx.y.z"` auf den Merge-Commit in `main` und den Tag pushen. + +Fremde Branches (z. B. von anderen Agenten) werden vor dem Mergen geprüft. + +### CI auf dem Git-Server + +- Workflow: `.gitea/workflows/build-and-publish.yaml`, Entscheidung in `.gitea/scripts/build-plan.sh`. +- `dev` → Image `:dev`, mit allen Tests (Dockerfile: tsc, Lint, Frontend-Tests, `go vet`, Go-Tests). +- `main` → Image `:latest` mit `APP_VERSION=v`; überspringt die Tests, wenn `:dev` aus demselben Code gebaut wurde. Deshalb erst nach grünem `dev`-Build mergen. +- Tag `v*` → `:vx.y.z` und `:stable`. +- Status der letzten Läufe: + + ```bash + curl -s "https://git.dsit.me/api/v1/repos/sandrodach/MindSift/actions/tasks?limit=4" + # workflow_runs[].head_branch / .status (success|failure|…) / .display_title + ``` + +## Oberfläche + +- **Einheitliche Bedienelemente:** Personen-Suche, Profilbild-Stapel, Zähler und weitere Muster stehen in [Doku/ui-patterns.md](Doku/ui-patterns.md). Vorhandene Komponenten verwenden statt neuer Varianten; neue gemeinsame Muster dort ergänzen. +- **Handy und Desktop:** Unter `sm` ist Handy-Layout, ab `lg` die volle Desktop-Ansicht (z. B. Seitenleiste neben der Notiz). Wird nur das Handy geändert, bleiben die Werte ab `sm`/`lg` exakt wie vorher. +- **Antippen am Handy:** Ziele mindestens 44 px hoch (`h-11 sm:h-…`). Auf reinen Touch-Geräten gibt es kein HTML5-Drag-&-Drop; Kanban nutzt dafür `useKanbanTouchDrag`, die Notizen die Leiste über der Tastatur (`MobileOutlineBar`). +- **Themes:** Farben nur über die Theme-Variablen bzw. Klassen (`bg-panel`, `bg-canvas`, `text-main`, `text-muted`, `border-border`, `bg-accent` …), keine festen Farben. Rahmen mit `bg-panel`/`bg-canvas` bekommen die Ecken des Themes automatisch; liegt darin ein Kopfbereich mit eigenem Hintergrund, braucht der Rahmen `overflow-hidden`, sonst ragen bei runden Ecken die Kanten heraus. +- **Installierte App (PWA):** Manifest-Änderungen (Farben, Verknüpfungen) übernimmt Android erst, wenn es die App aktualisiert (bis etwa einen Tag) oder nach Neuinstallation; normaler App-Code kommt beim nächsten Start. Ändert sich der Cache-Inhalt des Service Workers, `VERSION` in `frontend/public/sw.js` erhöhen. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md