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 unter `prozesse/` abgelegt oder geändert wird (Abschnitt 2).

## 2. Einen Prozess modellieren

```mermaid
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["prozesse/&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 unter `prozesse/`** macht das Modell für alle sichtbar und versioniert (ADR 0003, Regeln in
  `prozesse/README.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 |
| `prozesse/` | auf Abruf; versionierte Modelle mit Steckbrief |
| `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` unter `prozesse/` neu erzeugt
- [ ] 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