Zum Hauptinhalt springen

agents.md — Konventionen für KI-Agenten und Coding-Agenten

Dieses Dokument beschreibt, wie ein KI-Agent (Claude, Codex, Cursor, Continue, etc.) in diesem Repo arbeitet. Es ist verbindlich für jede Session und sollte beim Start jeder neuen Konversation mitgelesen werden — typischerweise zusammen mit HANDOFF.md. Es ist unsere „Way of Working" und wird laufend aktuell gehalten: ändert sich, wie wir zusammenarbeiten, landet es hier (kein paralleles Prozess-Doc — Decision-Sprawl vermeiden).

1. Repo-Philosophie: „Everything as Code"​

Alle Artefakte des Projekts leben im Repo: Spezifikation, Entscheidungen, Architektur, Code, Diagramme, Konventionen. Nichts Überlebenswertes verbleibt im flüchtigen Konversations-Verlauf oder im Session-Memory einer einzelnen Agenten-Instanz.

Konsequenzen:

  • GitHub drkv-com/medidentas ist die einzige Quelle der Wahrheit.
  • Eine neue Session startet nicht „bei null" — sie liest HANDOFF.md, docs/fachlich/Lastenheft.md und dieses Dokument und ist sofort im Kontext.
  • Wenn etwas entschieden wird, landet es als Commit im Repo, bevor die Konversation endet.

2. Doku-Format: Markdown + Mermaid (kein .docx, kein .pdf)​

Regel: Alle versionierten Dokumente sind .md mit Inline-Mermaid für Diagramme. Keine binären Formate (.docx, .pdf, .pptx, .xlsx) als Master-Quelle. Falls ein externer Stakeholder PDF/Word braucht, kann es bei Bedarf aus dem .md exportiert werden (pandoc, Mermaid-CLI für SVG).

Begründung: Git-diffbar, reviewable, mergeable; Diagramme als Code (Mermaid) sind genauso versioniert wie der Prosa-Text; Coding-Agenten können .md direkt lesen, ändern und Diffs erzeugen; keine Tooling-Abhängigkeit.

Mermaid-Typen, die wir im Repo verwenden:

TypWofür
flowchartUse-Cases, Architektur, Prozess-Logik
erDiagramDatenmodell, Entitäts-Beziehungen
stateDiagram-v2Lifecycle (Mandant, Dokument, Unterschrift)
sequenceDiagramInteraktionen (NextCloud-Upload, Signatur-Webhook)
ganttzeitliche Abläufe (Wiedervorlagen, Fristen)

3. Identifikator-System​

Jede Entscheidung, jedes Feld, jede Empfehlung, jeder offene Punkt hat eine kurze stabile ID. Diese IDs sind über das gesamte Repo durchsuchbar und werden in Commits, PRs, Issues, Chats referenziert.

PräfixBedeutungQuelle
G-nGlobales PrinzipCLAUDE.md / Lastenheft §3
RxModul (R1 Mandant, R2 Onboarding, …)Lastenheft §4–5
Rx-F##Feld einer EntitätLastenheft Tabellen
A-nArchitektur-EntscheidungLastenheft §9 / docs/architektur/
S-nVereinfachungLastenheft §10
UC-xKern-Use-CaseLastenheft §2
OP-<Thema>-nOffener Punkt (z. B. OP-SIGN-1, OP-STACK-1)Lastenheft §11 / HANDOFF.md §4
FR-nFuture-Release-NoteLastenheft §12
<TOOL>-nAnforderung eines Spezial-Tools (tool-scoped, z. B. DEX-n für Dexman)docs/spezialtools/<Tool>.md

Regel für Commits: Wenn ein Commit eine entscheidungs-relevante Änderung vornimmt, ID(s) in der Commit-Message nennen, z. B.:

Resolve OP-SIGN-1: E-Signatur-Provider = DocuSign (eIDAS-QES für Verträge)

4. Verbindliche Dokumente (lesen in dieser Reihenfolge)​

  1. HANDOFF.md — Wie ist der aktuelle Stand? Status, geparkte Fragen, nächste Schritte. Zuerst.
  2. docs/fachlich/Lastenheft.md — Was bauen wir? Vollständige fachliche Spezifikation. Master.
  3. docs/konventionen/agents.md — dieses Dokument.
  4. CLAUDE.md / README.md — gebündelte Leitplanke bzw. Setup/Orientierung.

Außerdem gepflegt: docs/betrieb/Timesheet.md — Arbeitszeit-Timesheet; am Session-Ende aktualisieren. Protokoll → §5.1 „Arbeitszeit erfassen".

5. Verhaltensregeln für Agenten​

5.1 Was tun​

  • IDs respektieren: Beim Verweis auf existierende Entscheidungen ID nennen.
  • Lastenheft und HANDOFF gemeinsam pflegen: Eine neue Entscheidung landet im Lastenheft (Kern-Spec) und in HANDOFF.md (kompakt für die nächste Session).
  • Markdown + Mermaid: Neue Dokumente in .md. Diagramme als Mermaid inline.
  • Single Source of Truth: Wenn ein Wert abgeleitet werden kann, wird er abgeleitet — nirgends doppelt gespeichert (z. B. „Onboarding vollständig?" aus den Pflicht-Items).
  • Standardwerkzeuge bevorzugen (G-1): Wo ein bewährtes Standard-Tool die Aufgabe löst, anbinden statt nachbauen (Dokumente → NextCloud, Unterschriften → DocuSign/PandaDoc, Kundenstamm → CRM). Eigenbau begründen (warum kein Standard).
  • Selbsterklärbarkeit (G-3): durchgängig sprechende, eindeutige Bezeichnungen (Beratungs-/ Back-office-Sprache statt technischer Labels; z. B. „Unterschrift ausstehend" statt „pending"). UI und Doku.
  • Rechtssichere, lückenlose Doku (G-4): Beratungsdoku, Unterschriften, Belege append-only + auditierbar.
  • Datenschutz by design (G-5): PII minimal, EU-/CH-Residenz, keine PII/Secrets im Klartext.
  • Jedes Feature wird dokumentiert (goldene Regel): Kein Feature ist „fertig", bevor die zuständige Produkt-/Architektur-Doku es beschreibt. HANDOFF ist das Arbeitslog, kein Ersatz für die Fach-Docs.
  • Doku-Konsistenz-Check (verbindlich, OP-DOCS-1): Die Doku muss in sich konsistent sein und (sobald Code existiert) zur Implementierung passen. Cadence: zu Session-Beginn sichten und vor jedem PR/Merge gegenprüfen. Zwei Achsen:
    • Doku↔Doku: IDs (G-/R-/A-/S-/OP-…) existieren & sind eindeutig, Glossar-Begriffe einheitlich, Modul-/Phasen-Liste und Status (✅/🟡/⛔) stimmen über HANDOFF.md · Lastenheft.md · CHANGELOG.md überein, Querverweise lösen auf, keine widersprüchlichen Aussagen.
    • Doku↔Implementierung: genannte Feldnamen/Enums/DTOs/Routen existieren im Code (und umgekehrt); beschriebene Features sind gebaut — und Gebautes ist beschrieben.
    • Mechanik: der maschinell prüfbare Teil läuft als bash scripts/check-doc-consistency.sh (tote Links/Bilder + Log-Hygiene) — warnt, blockt nicht. Der semantische Teil ist Agenten-Pflicht. Bei Unklarheit/Widerspruch: nachfragen (nicht raten).
  • Audit-Trail: Entscheidungen + Diskussionsergebnisse festhalten: Jede Design-/Architektur-/Prozess- Entscheidung und jedes Diskussionsergebnis (auch verworfene Optionen mit Begründung) landet in der Doku — fachlich/OP in HANDOFF.md §4 + Lastenheft, Architektur in docs/architektur/, Guiding Principles in CLAUDE.md.
  • CHANGELOG.md pflegen (je PR): ein Eintrag pro PR — Datum · PR-Nummer mit Link · kurze Beschreibung inkl. getroffener Entscheidungen, neueste zuerst.
  • Versionierung (je PR): APP_VERSION (SemVer) bewusst setzen, sobald die Single-Source-Stelle existiert (OP-STACK-1) — Build-Nummer kommt dann automatisch. Solange nur Doku: keine Versions-Datei nötig.
  • Log-Hygiene (regelmäßig): die merge=union-Logs (CHANGELOG/HANDOFF/Timesheet) zu Session-Beginn
    • nach Merges glätten (Duplikate raus, IDs eindeutig, chronologisch) — check-doc-consistency.sh flaggt Kandidaten. Detail: §6.
  • Annahmen sichtbar machen + Optionen zuerst: Berührt eine Aufgabe versteckte Annahmen oder Produkt-/ Datenmodell-Entscheidungen, nicht drauflosbauen — Annahme explizit auflisten + begründen, Optionen mit Empfehlung vorlegen, entscheiden lassen, dann bauen + Entscheidung dokumentieren.
  • Verifizieren statt behaupten: Previewbare Änderungen live verifizieren (z. B. docs-site-Build) statt den User prüfen zu lassen.
  • Arbeitszeit erfassen: docs/betrieb/Timesheet.md pflegen — Start/Stop je Session, Gap-Regel (> 1 h seit letzter Interaktion → User nach Stop fragen, neue Session). Am Session-Ende aktualisieren.
  • Proaktives Compliance-Flagging: kritische/regulatorisch relevante Themen für DE/AT/CH (DSGVO/revDSG, eIDAS/ZertES, Aufbewahrungsfristen …) aktiv flaggen + Optionen zeigen; im Risikoregister eintragen.

5.2 Was NICHT tun​

  • ❌ Keine binären Dokumente als Master-Quelle.
  • ❌ Keine ungefragten Refactorings am Lastenheft oder Code. Erst klären, dann tun.
  • ❌ Kein Pushen ohne Confirm in main, wenn der Wert der Änderung unklar ist. Lieber Branch + PR.
  • ❌ Keine duplizierten Decision-Docs außerhalb von Lastenheft + HANDOFF (Decision-Sprawl vermeiden).
  • ❌ Kein Eigenbau, wo ein Standard-Werkzeug passt (G-1) — ohne begründete Ausnahme.
  • ❌ Keine PII / Passwörter / Secrets in Klartext committen.

5.3 Bei Unsicherheit​

  • Lieber eine kurze Frage stellen als annehmen.
  • Wenn nicht entscheidbar: Punkt als OP-<Thema>-n in Lastenheft §11 und HANDOFF §4 parken und weitermachen.

6. Workflow für Änderungen​

6.1 Eine Entscheidung treffen​

  1. ID vergeben (oder bestehende referenzieren).
  2. Lastenheft (passender Abschnitt) updaten.
  3. HANDOFF.md §3/§4 updaten (Entscheidung notieren oder offenen Punkt schließen).
  4. Commit-Message: Resolve <ID>: <kurz>.

6.2 Eine offene Frage aufnehmen​

  1. Eintrag in Lastenheft §11 mit neuer ID OP-<Thema>-n.
  2. Eintrag in HANDOFF.md §4 (Kurzform).
  3. Commit-Message: Park <ID>: <kurz>.

6.3 Doku-Konsistenz prüfen (Session-Start + vor jedem PR)​

  1. Session-Start: HANDOFF.md → Lastenheft.md → agents.md lesen; relevante Docs sichten.
  2. Vor dem PR: beide Achsen prüfen (§5.1); bash scripts/check-doc-consistency.sh laufen lassen; docs-site baut durch.
  3. Drift gefunden? Doku (oder Code) angleichen, bei Unklarheit nachfragen; im PR/CHANGELOG vermerken.

6.4 Merge-Strategie & Log-Hygiene (OP-PM-1)​

  • merge=union für CHANGELOG.md, HANDOFF.md, docs/betrieb/Timesheet.md (.gitattributes): Git konkateniert beide Seiten statt zu blocken.
  • Session-ID sprechend & branch-abgeleitet (<Datum>-<branch-slug>) → git-weit eindeutig, kollisionsfrei.
  • „Update branch" lokal, nicht server-seitig: GitHubs server-seitiger Merge wendet den merge=union- Treiber NICHT an → log-berührende PRs lokal aktualisieren (git fetch origin main → git merge origin/main → push).
  • Pflicht — Logs regelmäßig glätten: zu Session-Beginn + nach Merges: exakte Duplikate entfernen, Session-/OP-/PR-Nummern eindeutig + chronologisch, keine Konflikt-Marker-Reste. bash scripts/check-doc-consistency.sh flaggt Kandidaten (warnt, blockt nicht).

6.5 Nicht-automatisierbare Checks (Agenten-Pflicht)​

Einige Setup-Kontrollen lassen sich nicht per CI-Skript/MCP prüfen — dann per gh api (falls Token-Scope) oder den Nutzer fragen/hinweisen. Abweichungen melden, nie still übergehen.

  1. Merge-Methoden = nur Squash aktiv. — gh api repos/<o>/<r> --jq '.allow_squash_merge,.allow_merge_commit,.allow_rebase_merge'
  2. allow_auto_merge = true (OP-PM-1). — gh api repos/<o>/<r> --jq '.allow_auto_merge'
  3. delete_branch_on_merge = true. — gh api repos/<o>/<r> --jq '.delete_branch_on_merge'
  4. Branch-Protection auf main (erforderlicher Check CI Gate). — gh api repos/<o>/<r>/branches/main/protection
  5. Semantische Doku-Konsistenz (§5.1) — ohnehin Agenten-Pflicht.

7. Branch- und Push-Konventionen​

  • Default-Branch: main.
  • GitHub-Operationen über die GitHub-API/MCP, nicht über lokales git/gh für Remote-Writes (verbindlich, v. a. in der Remote-/Cloud-Session): PR anlegen/mergen, Review-/Issue-Kommentare, Commits/Pushes auf Remote-Branches über die GitHub-MCP-Tools; CI-Status & Mergeability über pull_request_read prüfen, nicht erraten. Lokales git bleibt für lokale Arbeit ok (Branch, Merge/Rebase, Reads).
  • Neuer Code (KI) → immer zuerst einen neuen Branch anlegen und nur dort arbeiten. Merge nach main nur via PR (mit grüner CI). Niemals Code direkt auf main.
  • Doku-Fast-Track: Auch reine Doku-Änderungen laufen über Branch + PR (nie Direkt-Push auf main) — der Audit-/PR-Nummern-Trail bleibt lückenlos. Reine-Doku-PRs dürfen per Auto-Merge (Squash) durch; der aggregierte CI Gate bleibt der einzige Required-Check.
  • „go"-Gate: Commit, Push und Merge erfolgen nur auf explizites „go" des Users. Branch anlegen + Dateien im Arbeitsbaum vorbereiten ist ok; das Schreiben in die Historie / nach außen wartet auf „go".
  • Branch laufend auf main aktuell halten: zu Beginn, in Abständen, vor PR & vor Merge (git fetch origin main → rebase/merge).
  • Branch nach Merge schließen: Sobald ein PR gemergt ist, wird der Feature-Branch gelöscht (remote + lokal); bevorzugt GitHub „Automatically delete head branches".
  • Doku-Pflicht je PR & Merge: Jeder PR pflegt HANDOFF.md und docs/betrieb/Timesheet.md mit (und die fachlich betroffenen Docs).

8. Was nicht in dieses Repo gehört​

  • Personendaten realer Kunden / Mitarbeiter (auch nicht in Beispielen — Beispiele sind synthetisch).
  • Secrets, API-Keys, Tokens (für CI: GitHub Encrypted Secrets nutzen).
  • Generierte Build-Artefakte (build/, .docusaurus/, node_modules/ — siehe .gitignore).
  • Binär-Exporte als „Master" (.docx, .pdf).

Letztes Update: 27.06.2026 (Repo-Init: Way-of-Working für Medidentas etabliert — übernimmt die bewährten Taktano-Konventionen [ID-System · md+mermaid · union-Merge-Logs · Branch-first · GitHub-MCP für Remote-Writes] und ergänzt G-1 Standardwerkzeuge-bevorzugen als domänenspezifisches Leitprinzip).