Entwicklungsansatz — True North, Leitprinzipien & Way-of-Working
Zweck. Diese Seite stellt den Entwicklungsansatz von Medidentas Digital explizit und an einer Stelle dar:
woran wir Wert messen (True North), welche Prinzipien jede Entscheidung leiten
(Leitprinzipien G-1…G-8) und wie wir arbeiten (Way-of-Working). Sie ist die lesbare Übersicht
über den Ansatz — die verbindliche Kurzfassung steht in der Root-CLAUDE.md,
die detaillierten Agenten-Regeln in agents.md. Bei Widerspruch gilt CLAUDE.md.
In einem Satz: Jedes Feature, jeder PR und jede Doku muss den Kunden-Lebenszyklus lückenlos und rechtssicher orchestrieren — gemessen an True North, gebaut nach den Leitprinzipien, festgehalten als Code im Repo.
1. True North — die drei Leitfragen
Medidentas Digital hat genau eine Aufgabe: die drei folgenden Fragen jederzeit schnell und korrekt beantwortbar machen. Sie sind der Nordstern für Priorisierung und Design.
| # | Leitfrage | Bedeutung |
|---|---|---|
| 1 | Wo steht der Kunde im Prozess? | Onboarding-/Beratungs-Status: welcher Schritt, was fehlt? |
| 2 | Was ist offen und fällig? | Wiedervorlagen, ausstehende Unterschriften, fehlende Dokumente/Angaben. |
| 3 | Ist alles vollständig & rechtssicher dokumentiert? | Beratungsdoku · Unterschriften · Belege — lückenlos, auditierbar, DSGVO-konform. |
Regel (verbindlich): Jedes Feature/PR/Doc muss ≥ 1 dieser Fragen direkter, schneller oder genauer beantworten — sonst wird es kritisch hinterfragt. Die lebende Prüfliste mit Status führt
betrieb/Sanity-Checkliste.md.
2. Leitprinzipien G-1…G-8
Die Guiding Principles sind die Leitplanken jeder Entscheidung. Sie sind global (G-n) und werden in
Commits/PRs referenziert.
| ID | Prinzip | Kern in einem Satz |
|---|---|---|
| G-1 | Standardwerkzeuge bevorzugen (integrate-before-build) | Bewährte Tools anbinden statt nachbauen — Dokumente → NextCloud, Unterschriften → DocuSign/PandaDoc, Kundenstamm → CRM; Eigenbau nur mit begründetem Mehrwert (die Orchestrierung dazwischen). |
| G-2 | Everything-as-Code / Single Source of Truth | Das Repo ist die einzige Quelle der Wahrheit; Entscheidungen landen als .md-Commit. Derived State nie doppelt speichern — immer ableiten. |
| G-3 | Selbsterklärbarkeit | Sprechende Begriffe aus der Beratungs-/Backoffice-Praxis statt technischer Labels — in UI und Doku (z. B. "Unterschrift ausstehend" statt pending_signature). |
| G-4 | Rechtssichere, lückenlose Dokumentation | Beratungsdoku, Unterschriften und Belege sind append-only und auditierbar (nicht reverse-engineerbar). Audit-Trail ist Pflicht. |
| G-5 | Datenschutz & Datenminimierung by design | PII minimal, EU-/CH-Datenresidenz, keine PII/Secrets im Klartext. Mandant = Stammdaten-Referenz + CRM-Link (Single Source extern). |
| G-6 | Datensparsamkeit & Scrubbing-at-Source (ingress) | PII am Eingang (API, Import, Webhook, Log) auf das Nötigste reduzieren/pseudonymisieren/verwerfen — Default: nicht speichern; jede neue PII-Persistenz wird begründet. Schärft G-5. |
| G-7 | Betriebskosten automatisch ziehen (cost-pull-at-source) | Laufende Infra-/Cloud-/API-Kosten je Dienst aus dessen Billing-API ziehen (Cron + on-demand) statt von Hand pflegen; Kosten sind abgeleitete Sicht (G-2), jeder Pull ein Audit-Event (G-4). |
| G-8 | Weltmodell / Data Dictionary | Jede Entität/jedes Wertobjekt einmal definiert, überall gleich strukturiert (UI · API/DTO · Persistenz · Doku) — z. B. Anschrift = strasse·plz·ort. Katalog: architektur/Weltmodell-Data-Dictionary.md (MED-D-85). |
Details & Anker: CLAUDE.md → Leitprinzipien ·
Kosten-Design architektur/Kosten.md ·
Datensparsamkeit-Umsetzung architektur/Audit-Log.md.
3. Wie das zusammenspielt
True North sagt wozu, die Leitprinzipien sagen wie, der Prozess führt es aus, und die Artefakte im Repo sind der auditierbare Nachweis.
Lesart: Ein Vorhaben beginnt an True North (welche Leitfrage wird besser beantwortet?), wird von den Leitprinzipien geformt (Standardwerkzeug? PII minimal? ableitbar?), läuft durch den Prozess und hinterlässt auditierbare Spuren, die wiederum gegen True North geprüft werden.
4. Way-of-Working — der Prozess
4.1 Everything-as-Code & Audit-Trail (G-2/G-4)
Das Repo ist die einzige Quelle der Wahrheit. Jede Design-/Architektur-/Prozess-Entscheidung wird festgehalten — bevor die Session endet — in den lebenden Logs:
| Artefakt | Rolle | Pflege |
|---|---|---|
betrieb/Decision-Log.md | Chronologisches Entscheidungsprotokoll (D-n / MED-D-n, ADR-artig). | je PR |
../../CHANGELOG.md | Audit-Trail je PR (Datum · Link · Entscheidungen), neueste zuerst. | je PR |
fachlich/Feature-Liste.md | Lebende Übersicht des tatsächlich Gebauten (✅/🟡/⛔). | je PR |
betrieb/Test-Uebersicht.md | Lebende Übersicht der automatischen Tests + CI. | je PR |
../../HANDOFF.md | Kompakter Gesamtstand + offene Punkte (§4). | je PR |
betrieb/Kunden-Besprechungspunkte.md | Mit dem Kunden zu klärende Punkte (KB-n), vor dem Bau. | je PR |
4.2 ID-System (Selbsterklärbarkeit & Verweisbarkeit)
Commits/Docs referenzieren stabile IDs. Neue IDs tragen das Projekt-Kürzel MED- (ab MED-D-51);
Bestands-IDs bleiben unverändert (gemischter Alt-/Neu-Bestand).
G-n global · R-n Module · Rn-F## Felder · A-n Architektur · S-n Vereinfachungen ·
OP-<Thema>-n offene Punkte · D-n Entscheidungen · UC-x Use-Cases · FR-n · RISK-n · KB-n · <TOOL>-n tool-scoped (z. B. DEX-n Dexman).
4.3 Branch-first & Draft-PR (MED-D-60)
- Nie direkt auf
main. Feature-Branch → PR → Squash-Merge → Branch löschen. - Draft-PR-Workflow: Feature-PRs als Draft öffnen und im Draft frei pushen (CodeRabbit reviewt Drafts nicht → kein Rauschen); erst bei "ready for review" 1× Review + Merge scharf.
- Required Checks:
CI Gate+CodeRabbit(MED-D-59). GitHub-Writes laufen über die GitHub-API/MCP, nicht über lokalesgit(Remote-Session). - Feature-Branches regelmäßig mit
mainabgleichen (mind. zu Session-Beginn und vor dem PR). - Kanonische Quelle (agents.md §5.4): Diese Kurzfassung ist die Übersicht; Detail (Bot-PR-Handling,
MED-D-100-Konfiguration, Stacked-Branch-Interaktion):
docs/konventionen/agents.md§7.
4.4 Doku-Konsistenz-Check (OP-DOCS-1)
Die Doku muss in sich widerspruchsfrei sein und zur Implementierung passen — zu Session-Beginn
sichten, vor jedem PR gegenprüfen. Mechanik (Teilmenge): bash scripts/check-doc-consistency.sh; der
semantische Teil (IDs, Glossar, Modul-Liste, Doku↔Code) bleibt Aufgabe des/der Bearbeitenden.
4.5 Versionierung (SemVer)
MAJOR.MINOR.PATCH, bewusst je PR gesetzt (PATCH = Fix · MINOR = neues rückwärtskompatibles Feature ·
MAJOR = Meilenstein/Breaking). Erstes Ziel: MVP = 1.0.0; bis dahin 0.x. Single Source:
server/src/version.ts; die Build-Nummer wird automatisch aus dem Git-Commit-Count gestempelt.
4.6 Dokumentation als Meisterwerk & Standard-Bausteine (drkv)
Doku ist Produkt, nicht Beiwerk: pyramidal (Kernaussage zuerst), zielgruppen-gerecht (benannte
Rolle, deren Sprache), visuell wo es trägt (Mermaid/Tabellen) — jedes Doc beantwortet ≥ 1 True-North-
Frage. Medidentas Digital folgt zudem dem bewirtschafteten drkv-Standard-Tech-Stack (kanonisch im Template):
Echtzeit, moderne Frameworks, ein In-App-Chatbot (LLM + RAG auf Live-Daten & Doku —
../architektur/In-App-Assistent.md, OP-ASSIST-1) und Feedback
(sammeln + anzeigen). Abweichung wird als MED-D-n begründet. Detail: CLAUDE.md → Dokumentation als
Meisterwerk / Standard-Bausteine.
5. Standard-Prozess (Mandanten-Lebenszyklus)
Der fachliche Rahmen, den die Plattform orchestriert:
Je Schritt mit Doku/Kommentar. Lifecycle-Status (Lead → … → archiviert) und fachliche Phase sind
getrennt zu denken. Fachquelle: fachlich/Lastenheft.md §5.
6. Compliance-Haltung (DE · AT · CH)
Proaktiv, nicht nachgelagert: Tauchen regulatorisch relevante Themen auf (eIDAS/ZertES-Signaturniveau,
DSGVO/revDSG, Aufbewahrungsfristen GoBD/§147 AO), wird aktiv darauf hingewiesen und werden
Handlungsoptionen aufgezeigt — nie still übergangen. Geführt in
betrieb/Compliance.md und betrieb/Risikoregister.md.
7. Quellen & Vertiefung
| Was | Wo |
|---|---|
| Verbindliche Kurzfassung (Guiding Principles, Regeln) | Root-CLAUDE.md |
| Detaillierte Agenten-Konventionen (Way-of-Working) | agents.md |
| True-North-Prüfliste (Status) | betrieb/Sanity-Checkliste.md |
| Was für eine Anwendung ist das? (Archetyp) | architektur/System-Charakter.md |
| In-App-Chatbot (LLM + RAG auf Live-Daten & Doku) + Feedback | architektur/In-App-Assistent.md |
| Entscheidungsprotokoll | betrieb/Decision-Log.md |
| Doku-Landkarte (Navigation) | README.md |