Projektwissen/docs/leitfaden/03_arbeitsweise.md

Arbeitsweise: So arbeiten wir mit KI-Agenten an Prozessmodellen

Für Kolleginnen und Kollegen, die neu einsteigen. Fachwissen wird vorausgesetzt, Software-Erfahrung nicht. Wir arbeiten mit Claude Code; die Dateien bleiben werkzeugneutral (ADR 0001). Die Kurzfassung für den Agenten selbst ist AGENTS.md, dieser Leitfaden erklärt das Warum und das Wie. Git im Detail: 05_git_arbeitsweise.md. Einrichtung Schritt für Schritt: 04_werkzeuge_einrichten.md.

1. Zwei Arten von Arbeit

Arbeit	Wer	Womit	Ergebnis
Einen Prozess modellieren	Fachleute	Skill sn-bpmn	BPMN-Datei für PICTURE
Werkzeug und Wissen verbessern	alle, die einen PR stellen	Skill sn-aufgabe-bearbeiten	Pull Request auf main

Wer nur modelliert, braucht Git kaum: Beschreibung als .md nach input/ legen, Claude Code im Ordner AG_Prozesse starten, „Lies den Ordner input ein“, Entwurf prüfen, umwandeln (07_prozesse_einlesen.md). Git und Pull Requests kommen erst ins Spiel, wenn sich am Konverter, an den Regeln oder an der Doku etwas ändern soll — oder wenn ein Modell in der Prozessbibliothek abgelegt oder geändert wird (Abschnitt 2).

2. Einen Prozess modellieren

flowchart TD
    A["Quelle nach referenz/ legen<br/><i>Word, PDF, Rohtext</i>"] --> B["Agent: sn-bpmn<br/>Entwurf entwuerfe/&lt;name&gt;.md"]
    B --> C["Annahmen lesen, Entwurf fachlich prüfen und anpassen"]
    C -->|"noch nicht richtig"| C
    C -->|"passt so, wandle um"| D["&lt;name&gt;.bpmn"]
    D --> E["Import in PICTURE"]
    E -->|"Darstellungsfehler"| F["Issue anlegen<br/><i>Skill sn-ticket</i>"]
    E -->|"für alle ablegen"| G["Prozessbibliothek/&lt;name&gt;/<br/>Status Entwurf, Pull Request"]
    G -->|"fachlich bestätigt"| H["Pull Request: Status abgenommen"]

• Der Agent wartet nach dem Entwurf. Er wandelt erst um, wenn du ausdrücklich zustimmst. Das ist Absicht: die fachliche Richtigkeit verantwortest du, nicht der Agent.
• Ansehen statt nur lesen. python scripts/vorschau.py entwuerfe/<name>.md zeigt den Entwurf als Diagramm im Browser, offline. Ohne Python: werkzeuge/vorschau/vorschau.html öffnen und die .bpmn hineinziehen.
• Annahmen ernst nehmen. Der Agent nennt, wo er Schrittgrenzen, Verzweigungen oder Verantwortliche geraten hat. Genau dort liegen die Fehler.
• Rollen statt Personen. Verantwortliche immer als Funktion („Sachbearbeitung"), nie mit Namen.
• Darstellungsfehler in PICTURE (Kanten durch Elemente, überlappende Lanes) sind Fehler des Konverters, nicht deines Entwurfs. Issue anlegen, mit dem Entwurf als Beispiel (bereinigt).
• Ablegen in der Prozessbibliothek macht das Modell für alle sichtbar und versioniert (eigenes Repository, ADR 0004, Regeln in 08_prozessbibliothek.md). Die .md ist maßgeblich: Was nur in PICTURE nachgebessert wird, ist bei der nächsten Erzeugung weg. Abnahme heißt: ein eigener Pull Request, der im Steckbrief den Status auf abgenommen setzt; das Review dieses Pull Requests ist die fachliche Bestätigung.

3. Wie man einem Agenten einen Auftrag gibt

Der Agent liest AGENTS.md automatisch. Was er nicht weiß: was genau gewollt ist, wo es endet, und was fachlich richtig ist. Ein guter Auftrag hat vier Teile:

1. Ziel und Issue: „Bearbeite Issue #12: …“ oder das Ziel in zwei Sätzen.
2. Kontext-Zeiger statt Erklärungen: „Betroffen ist die Lane-Beschriftung in md_to_bpmn.py, Regel in Modellierregeln.md Abschnitt Lanes.“
3. Grenzen: „Keine Änderung an der Markdown-Syntax. Keine neuen Abhängigkeiten. Kein Umbau.“
4. Abnahme: „Fertig ist es, wenn ein Test für einen Rollennamen über 30 Zeichen existiert, alle Tests grün sind und die Übergabenotiz geschrieben ist.“

Beispiel eines schlechten Auftrags: „Mach die Diagramme schöner.“ Das erzeugt lange Erkundung, unklare Änderungen und einen PR, den niemand reviewen kann.

Während der Arbeit: Rückfragen beantworten, fachlich prüfen, was der Agent behauptet, und ihn bei Abschweifungen zurückholen („Nur Issue #12“). Wenn er anfängt, Tests zu ändern statt Code, nach der Begründung fragen.

4. Die Regeln und warum es sie gibt

Regel (aus AGENTS.md)	Warum
Der Mensch pusht, mergt und legt Tickets an	Jede Aktion auf dem Server trägt den Namen einer Person
Nie direkt auf main	main ist der abgenommene Stand, den alle nutzen
Neues Konverter-Verhalten nur mit Test	Tests sind der einzige schnelle Nachweis für Agentenarbeit; Layoutfehler kommen sonst unbemerkt zurück
Keine personenbezogenen Daten, keine Originalunterlagen	Alles, was der Agent liest, geht an den Anbieter; das Repository ist für die ganze Gruppe sichtbar
Kein Umbau nebenbei	Umbauten ohne Plan sind nicht reviewbar
Deutsch mit echten Umlauten	Modelle landen in PICTURE und werden von Fachleuten gelesen
Übergabenotiz	Die nächste Person oder der nächste Agent soll nicht von vorn beginnen

5. Wissen festhalten

Situation	Was tun
Etwas hat überraschend Zeit gekostet	Eintrag in docs/wissen/fallstricke.md (Rubrik, Datum, Quelle)
Markdown-Syntax, Element oder Modellierregel geändert	.agents/skills/sn-bpmn/Anleitung.md, Elementkatalog.md, Modellierregeln.md
Team hat etwas entschieden	neue Datei docs/entscheidungen/NNNN-<thema>.md nach Vorlage
Aufgabe abgegeben oder pausiert	Übergabenotiz im PR (Vorlage) und Zeile in STATUS.md
Fachbegriff musste erklärt werden	docs/wissen/glossar.md

Der Skill sn-uebergabe führt den Agenten am Ende jeder Aufgabe durch genau diese Liste. Das eigene Gedächtnis des Werkzeugs (Claude Auto-Memory) ist ein Notizzettel; teilbares Wissen gehört in die Dateien oben.

6. Was liegt wo, und was liest der Agent

Datei	Wird gelesen
AGENTS.md	ja, über CLAUDE.md (@AGENTS.md) – kanonisch
CLAUDE.md	ja, enthält nur den Verweis und wenige Claude-spezifische Zeilen
.agents/skills/	kanonischer Ort; gelesen wird der Spiegel .claude/skills/
.claude/commands/	Slash-Befehle, z. B. /hallo
.claude/settings.json	Berechtigungen – sperrt git push, merge, tag
docs/	auf Abruf, nicht automatisch
Prozessbibliothek/	auf Abruf; eigener Klon mit den versionierten Modellen, eigene AGENTS.md
input/	beim Einlesen (Skill sn-einlesen); nicht versioniert
referenz/, entwuerfe/	nur, wenn du darauf verweist; nicht versioniert
CLAUDE.local.md	ja, lokal, nicht versioniert

7. Häufige Fragen

Der Agent kennt den Skill sn-bpmn nicht. Er wurde im falschen Ordner gestartet, oder der Skill-Spiegel fehlt: python scripts/setup_workspace.py --nur-skills.

Der Agent wandelt sofort um, ohne auf mich zu warten. Das widerspricht dem Skill. Stoppen und auf Schritt 3 in .agents/skills/sn-bpmn/SKILL.md verweisen.

Der Agent „repariert“ rote Tests durch Anpassen der Erwartung. Nach Begründung fragen; nur akzeptieren, wenn das Verhalten bewusst geändert wurde und das Issue es abdeckt.

Der Agent hat eine Datei komplett umgeschrieben. Diff prüfen, auf das Issue zurückführen, Rest verwerfen.

Zwei Personen arbeiten am selben Thema. In STATUS.md steht, wer woran arbeitet; vorher dort eintragen und kleine PRs machen.

8. Checklisten

Vor dem PR

• Issue verlinkt, Branch von main mit Issue-Nummer im Namen
• python -m pytest -q grün, python scripts/pruefe_umlaute.py ohne Funde
• Neue Funktionalität hat mindestens einen Test je neuem Verhalten
• Jeder neue oder geänderte Test hat einen deutschen Docstring """Prüft, dass …"""
• Keine Debug-print, kein auskommentierter Code
• Änderungen an Markdown-Syntax oder Ablageformat im PR benannt (oder „keine“)
• Bei geänderter BPMN-Ausgabe: PICTURE-Import dokumentiert, .bpmn der Bibliothek neu erzeugt (eigener PR dort)
• Keine personenbezogenen Daten, keine Originalunterlagen
• PR-Text vollständig nach Vorlage, mit Checkliste und Übergabenotiz; Wissensbasis nachgezogen, falls nötig
• Diff gelesen: nur, was das Issue verlangt

Review

• Fachlich richtig? (BPMN-Regeln, Begriffe; bei Modellen: Diff der .md lesen, nicht der .bpmn, und das Diagramm mit python scripts/vorschau.py ansehen)
• Tests vorhanden und sinnvoll (nicht nur angepasst)?
• Umfang überschaubar (< 400 Zeilen)?
• Nach dem Merge: STATUS.md

Sitzungsende (auch bei Abbruch)

• Zwischenstand auf dem Arbeitsbranch committet
• Offene Fragen im Issue notiert
• STATUS.md-Zeile aktualisiert