know-how vertraulich owner: matus

Guidelines — Master-Index (tuxametrics)

Verbindlich. Sagt, WIE wir Dinge bauen. Für WAS das System fachlich tut → ../documentation/.

Bevor hier ein neues Dokument angelegt oder geändert wird: ../../zwirn/guidelines/documentation-conventions.md (GG-META-0001).

Key-Schema: GG-* / PG-*

Präfix	Bedeutung
`GG-*`	Global Guidelines — kanonisch in Zwirn, hier nur verlinkt
`PG-*`	Product Guidelines — nur für `tuxametrics` gültig

GG-* — Generische Regeln (kanonisch in Zwirn)

Master-Index: ../../zwirn/guidelines/INDEX.md — lokaler Geschwister-Checkout, erwartet unter C:\dev\zwirn bzw. <parent>/zwirn. Fehlt er → klonen. Kein GG-Markdown wird hierher kopiert (GG-META-0002 §5).

Für dieses Produkt besonders relevant:

Key	Titel	Datei in Zwirn
`GG-META-0002`	Projektanlage: ein neues Produkt auf Zwirn starten	`project-setup.md`
`GG-META-0004`	Kunden-Vorbereitung fürs Prototyping (7 Kategorien)	`prototyping-preparation.md`
`GG-META-0005`	Use-Case-Extraktion: vom Rohmaterial zum ersten Entwurf	`use-case-extraction.md`

GG-META-0005 ist hier nicht nur relevant, sondern die Quelle: das gesamte Fachmaterial dieses Produkts ist das Ergebnis eines solchen Durchlaufs im Repo tuxamed.

GG-AGENTIC-ENGINEERING — mehrere Sessions, ein Working Tree

Nachgetragen am 2026-08-26. Diese vier Regeln galten schon vorher — sie standen nur in keinem Index, den eine Session dieses Repos liest, und sind deshalb in der Praxis nicht angewendet worden. Der konkrete Anlass steht in ../agentic-engineering/CLAIMS.md § Historie (Eintrag 2026-08-26).

Key	Titel	Datei in Zwirn
`GG-AGENTIC-ENGINEERING-0002`	Claim-Pflicht pro Modul vor Arbeitsbeginn	`agentic-engineering/parallel-agent-claims.md`
`GG-AGENTIC-ENGINEERING-0003`	Agent-Log: retrospektives Änderungsprotokoll	`agentic-engineering/agent-log-convention.md`
`GG-AGENTIC-ENGINEERING-0005`	Git-Worktree-Isolation für parallele Sub-Agenten	`agentic-engineering/agent-worktree-isolation.md`
`GG-AGENTIC-ENGINEERING-0007`	State-Board: was gilt gerade über das laufende System	`agentic-engineering/live-state-broadcast.md`

Warum jede davon hier zählt — am Zuschnitt dieses Produkts, nicht generisch:

-0002 (Claims). Sperr-Einheit ist das Modul aus PG-DOMAINS-0001. Dieses Repo hat davon nur fünf schreibbare (Authority, VID, Laborauswertung, Process-Hub-Cockpit, UI) — wenige genug, dass zwei parallele Sessions regelmäßig in derselben landen. Der Java-Teil ist dabei der harmlose: vier Module, vier Verzeichnisse, vier DBs. Die Kollisionen konzentrieren sich in tuxametrics-ui/, das als ein Modul geführt wird, aber mit src/shell/ einen von allen Domain-Slices geteilten Kern hat — wer an Nav, Layout oder Routing arbeitet, arbeitet dort, egal aus welcher fachlichen Richtung er kam. Board: ../agentic-engineering/CLAIMS.md.
-0003 (Agent-Log). Der Punkt ist nicht die Historie — der Punkt ist, dass Git über uncommittete Arbeit einer anderen Session nichts sagt. Genau in diesem Zustand liegt dieser Working Tree regelmäßig über Stunden. Enthält der Log-Eintrag keine Dateipfade, ist er für diesen Zweck wertlos; deshalb ist das Zeilenprotokoll aus -0003 seit 2026-08-26 Pflichtteil der hiesigen Konvention (siehe ../agentic-engineering/agent-log/README.md). Der zweite Teil von -0003 ist eine Entlastung: kein pauschaler Log-Read mehr vor jeder Arbeit, nur bei Claim-Konflikt gezielt greppen.
-0005 (Worktrees). Gilt hier, aber nicht als Antwort auf den Vorfall vom 2026-08-26 — die Regel sagt in ihrem eigenen Abschnitt „Grenze", dass sie unabhängige Zweit-Sessions im selben Haupt-Checkout gerade nicht erfasst. Wirksam ist sie für Sub-Agenten, die eine Session parallel schreiben lässt. Kostenhinweis für dieses Repo: ein frischer Worktree hat kein node_modules und kein ~/.m2-warmes target/; für einen Sub-Agenten, der nur tuxametrics-ui/ anfasst und npm run typecheck braucht, ist das ein npm ci extra. Für UI-only-Parallelarbeit deshalb eher Claim + pfadgenaues Staging, für schreibende Java-/Doku- Sub-Agenten der Worktree.
-0007 (State-Board). Dieses Produkt wird nicht lokal betrieben, sondern auf tuxametrics-vm — jede Session handelt gegen dieselbe laufende Umgebung. Dazu kommt ein Capability-Modell, in dem ein registrierter Key ohne Grant wirkungslos ist: das produziert genau die 403-Fehlersuche, deren Ursache im Repo nicht steht. Und ein Re-Import des Realms digital-labs löscht provisionierte Identitäten — das ist wörtlich eines der Beispiele in -0007. Board: ../agentic-engineering/STATE.md.

GG-ARCH-FRONTEND — jede Liste, jede Tabelle, jedes Suchfeld

Nachgetragen am 2026-08-26, aus exakt demselben Grund wie die vier Regeln darüber und am selben Tag: die Regeln galten längst, standen aber in keinem Index, den eine Session dieses Repos liest. CLAUDE.mds Leseliste („BEFORE implementing anything") nannte fürs Frontend nur das Beispielprojekt ../zwirn/samples/sample-frontend-react — ein Muster zum Abschauen ist aber keine Regel, und wer die falsche Nachbarseite als Vorlage nimmt, schaut die Abweichung ab statt der Regel. Genau das ist an SubstanzstammdatenPage passiert (Details unten).

Key	Titel	Datei in Zwirn
`GG-ARCH-FRONTEND-0001`	Domain-Slices	`architecture/web-frontend/frontend-architecture-guidelines.md`
`GG-ARCH-FRONTEND-0002`	Seitenlayout	`architecture/web-frontend/frontend-page-layout.md`
`GG-ARCH-FRONTEND-0003`	Tabellen & Pagination	`architecture/web-frontend/frontend-tables-pagination.md`
`GG-ARCH-FRONTEND-0004`	API-Clients	`architecture/web-frontend/frontend-api-clients.md`
`GG-ARCH-FRONTEND-0005`	URL-Naming	`architecture/web-frontend/url-naming.md`
`GG-ARCH-FRONTEND-0006`	Design System (`@zwirn/web` importieren, nicht nachbauen)	`architecture/web-frontend/frontend-design-system.md`
`GG-ARCH-FEREACT-0001`	React-Konventionen	`architecture/web-frontend/react-conventions.md`

-0003 ist die, die hier regelmäßig gerissen wird, und sie ist gleichzeitig die mit der klarsten Ansage: „Jede Liste/Tabelle, die potenziell mehr als eine Bildschirmseite an Zeilen zurückgeben kann, MUSS paginiert sein — unabhängig davon, wie klein der aktuelle Datenbestand (Demo/Prototyp) gerade ist." Konkret heißt das start/limit (nie page/pageSize) im Request, eine Seitengrößen-Auswahl, 400 ms Debounce bei jeder Suche, die einen Request auslöst, und DataTable/SearchInput/Pagination/EmptyState aus @zwirn/web statt handgeschriebenem <table>-Markup.

Warum das ausgerechnet für dieses Produkt zählt:

„Ist ja nur ein Prototyp" ist hier der Normalzustand, nicht die Ausnahme. Fast jede Liste dieses Repos zeigt heute einen zweistelligen Demo-Bestand. Genau diese Ausrede schließt die Regel ausdrücklich aus — und der Bestand wächst: Substanzstammdaten sind laut ADR-0012 als extern anzubindende Referenz gedacht, die Patientenhistorie ist append-only.
Es gibt in diesem Repo eine dokumentierte, legitime Ausnahme — und sie ist ansteckend. KatalogeRegelwerkPage lädt bewusst den vollständigen, kleinen Regelkatalog und filtert/blättert clientseitig; ihr Javadoc begründet das. Als Vorlage für eine Seite mit server-seitiger Suche ist sie trotzdem falsch. Die erste Fassung von SubstanzstammdatenPage hat genau das getan: Aufbau übernommen, Pagination und Debounce mit übernommen — also weggelassen. Wer hier abschreibt, muss vorher die Regel gelesen haben, sonst kopiert er die Ausnahme.
Stand einer Stichprobe vom 2026-08-26: von 13 Listen-/Übersichtsansichten erfüllen 4 das Muster vollständig, 3 teilweise, 6 nicht. Kein einziger API-Aufruf spricht page/pageSize — die Abweichungen sind durchweg fehlende Pagination und handgeschriebenes <table>-Markup, nicht falsche Parameter. Auffälligster Fall: die Auswertungsübersicht lädt fest limit: 200 und schneidet ab dort still ab.

PG-ARCH — Produktspezifisches Setup

Key	Titel	Datei
`PG-ARCH-0001`	Projekt-Phase DEV	`project/development-phase.md`
`PG-ARCH-0002`	Implementation Gaps	`project/implementation-gaps.md`

PG-DOMAINS — Service-Landschaft & Ownership

Key	Titel	Datei
`PG-DOMAINS-0001`	Service-Landschaft	`project/service-landscape.md`
`PG-DOMAINS-0002`	Domain-Map	`project/domain-map.md`

PG-UI — Oberflächen-Konventionen

Key	Titel	Datei
`PG-UI-0001`	UI-Text: keine Erklärungstexte	`project/ui-text-minimal.md`

PG-FACH — Fachlicher Zuschnitt

Key	Titel	Datei
`PG-FACH-0001`	Gold Path E1/E3 — Umfang, Nicht-Umfang, gefilterte Testfälle	`project/gold-path-scope.md`

Fachliche Doku

../documentation/ — Domänenmodell, Prozess, Testfallkatalog.

ADRs

Siehe adr/README.md. Zwölf Entscheidungen, davon elf gültig — ADR-0006 ist seit 2026-08-14 durch ADR-0007 abgelöst, und von ADR-0010 ist seit 2026-08-24 der Abschnitt „kein Rückkanal" durch ADR-0011 überholt (der Rest gilt). ADR-0002 (regulatorischer Status) und ADR-0003 (Pilot-Betriebsmodus) sind die beiden Leitplanken, die jede weitere Ausbaustufe binden — von ADR-0005 und ADR-0007 unberührt.