DanielandClaude Opus 5.5
97413265f2
- test_referenzmodelle.py: kreuzungen() prüft alle Sequenz- und Nachrichtenflüsse gegen Aufgaben, Ereignisse (Kreis), Gateways (Raute) und Datenelemente und liefert alle Funde. Neuer Test je Modell unter beispiele/ (auch Syntaxbeispiele): keine unbekannte Kreuzung. - Bekannte Fälle je Kreuzung in BEKANNTE_KREUZUNGEN, jeder mit eigenem xfail(strict=True)-Test: #12 (Rücksprung durch S5 in beispiel_lanes), #13 (Nachrichtenfluss durch S5 in beispiel_lanes und durch S24 im Referenzmodell). - test_keine_kante_fuehrt_durchs_innere_eines_gateways entfällt: Die neue Prüfung deckt Gateways mit derselben Rautengeometrie ab und meldet mehr. Gegenprobe am Stand vor #8: alle sieben Kreuzungen auf einmal gefunden. - Selbsttest der Prüfung und test_ausweichabstand_liegt_in_beiden_layouts _im_freien_gang (bindet AUSWEICHABSTAND an DEFAULT_SIZE und Abstände). - AGENTS.md: xfail-Ausnahme gilt für alle Modelle unter beispiele/, je Fehler einzeln. Anleitung, Fallstricke, STATUS nachgezogen. - Tests: python -m pytest -q -> 97 bestanden, 3 xfail (#12, #13). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
115 lines
7.8 KiB
Markdown
115 lines
7.8 KiB
Markdown
# Projektwissen AG_Prozesse – Anweisungen für KI-Agenten und Mitwirkende
|
||
|
||
Kanonische, werkzeugneutrale Anweisungsdatei. Claude Code liest sie über `CLAUDE.md`.
|
||
Sie bleibt bewusst kurz: Details liegen in `docs/` und werden nur bei Bedarf gelesen.
|
||
|
||
## Worum es geht
|
||
|
||
- Arbeitsgruppe der sächsischen Flurbereinigungsbehörden („LNO Sachsen") zur **Modellierung von
|
||
Verwaltungsprozessen in BPMN 2.0**. Zielwerkzeug für den Import ist **PICTURE**.
|
||
- Kernwerkzeug ist der Skill `sn-bpmn`: Prozessbeschreibung (Rohtext, Stichpunkte, Word/PDF) → strukturierte
|
||
Arbeitsschritt-`.md` → BPMN-2.0-Datei (`.agents/skills/sn-bpmn/md_to_bpmn.py`).
|
||
- Dieser Ordner ist der Klon des Repositories **`AG_Prozesse/Projektwissen`**. Weitere Repositories der Gruppe
|
||
liegen als eigenständige Git-Klone in Unterordnern und stehen in `workspace.toml`: derzeit
|
||
**`Prozessbibliothek`** mit den versionierten Prozessmodellen (ADR 0004).
|
||
- Die Arbeitsweise (Skripte, Skills, Git-Regeln) stammt aus `AG_QGIS/Projektwissen`, siehe
|
||
`docs/entscheidungen/0001-uebernahme-aus-ag-qgis.md`.
|
||
|
||
## Zuerst lesen – nur was die Aufgabe braucht
|
||
|
||
1. `docs/status/STATUS.md` – aktueller Stand, offene Baustellen, wer woran arbeitet.
|
||
2. `docs/wissen/fallstricke.md` – bekannte Stolperfallen (BPMN-Layout, PICTURE-Import, Werkzeuge).
|
||
3. Für Modellierungsaufgaben: `.agents/skills/sn-bpmn/SKILL.md` und die dort genannten Dateien.
|
||
4. Fachbegriffe: `docs/wissen/glossar.md`. Übersicht aller Dokumente: `docs/README.md`.
|
||
|
||
## Harte Regeln
|
||
|
||
### Git und Server – der Mensch drückt ab
|
||
|
||
- **Nie pushen, mergen, taggen oder etwas auf Gitea verändern.** Agenten bereiten vor, eine Person sendet ab.
|
||
`.claude/settings.json` sperrt `git push`, `git merge`, `git rebase`, `git tag` technisch.
|
||
- Hauptbranch ist `main`. Nie direkt auf `main` committen: eigener Branch `feature/<nr>-<kurzname>` bzw.
|
||
`bugfix/<nr>-<kurzname>`, dann Pull Request. Vollständig: `docs/leitfaden/05_git_arbeitsweise.md`.
|
||
- Sitzungsbeginn: `python scripts/hallo.py` (bzw. `/hallo`), bevor irgendetwas geändert wird.
|
||
|
||
### Tests
|
||
|
||
- Vor jedem Commit: `python -m pytest -q` – alle Tests grün.
|
||
- **Neue Funktionalität ohne Test wird nicht gemergt** – im Konverter wie in den Skripten. Mindestens ein Test je
|
||
neuem beobachtbarem Verhalten, ohne Netzwerk. Bei einer Fehlerbehebung zuerst der Test, der den Fehler zeigt.
|
||
- **Jeder neue oder geänderte Test bekommt einen deutschen Docstring**, erste Zeile in der Form `"""Prüft, dass …"""`.
|
||
- Tests werden nicht gelöscht, nicht mit `skip` stillgelegt und nicht in ihrer Erwartung angepasst, um grün zu werden –
|
||
außer das Verhalten wurde bewusst geändert und der Pull Request begründet es.
|
||
- **Einzige Ausnahme:** ein bekannter, per Issue erfasster Konverterfehler an einem Modell unter
|
||
`.agents/skills/sn-bpmn/beispiele/` (Referenzmodell oder Syntaxbeispiel) darf als `xfail(strict=True)` mit
|
||
Issue-Nummer im Grund eingetragen werden, und zwar je Fehler einzeln, nie für ein ganzes Modell
|
||
(`BEKANNTE_KREUZUNGEN` in `tests/test_referenzmodelle.py`). Nie für Fehler, die die eigene Änderung verursacht.
|
||
- **Referenzmodelle** unter `.agents/skills/sn-bpmn/beispiele/referenz_*.md` sind echte, größere Prozesse zum
|
||
Testen von Konverteränderungen. Ändert sich deren `.bpmn`, im Pull Request mit Vorschau begründen.
|
||
|
||
### Inhalte
|
||
|
||
- **Keine personenbezogenen Daten, keine Zugangsdaten, keine internen Originalunterlagen** im Repository, in der Doku
|
||
oder in Prompts. Quelldokumente (Word/PDF) bleiben lokal unter `referenz/` (nicht versioniert); ins Repository kommen
|
||
nur die daraus abgeleiteten, bereinigten Arbeitsschritt-`.md` und BPMN-Dateien. Dasselbe gilt für den
|
||
Eingangsordner `input/` (Skill `sn-einlesen`): Dateien dort nie löschen, verschieben oder umbenennen; einziger
|
||
Eingriff ist der Einlese-Vermerk über `scripts/einlesen.py`.
|
||
- **Prozessmodelle liegen im eigenen Repository `Prozessbibliothek`**, geklont nach `Prozessbibliothek/<name>/`
|
||
(ADR 0004, Regeln in `docs/leitfaden/08_prozessbibliothek.md`). Issues, Branches und Pull Requests zu Modellen
|
||
laufen dort. Die `.md` ist maßgeblich, die `.bpmn` wird nie von Hand bearbeitet, sondern mit `python scripts/pruefe_prozesse.py --erzeugen`
|
||
neu erzeugt. Den Status `abgenommen` setzt der Agent nie von sich aus.
|
||
- Rollen und Verantwortliche in Prozessmodellen als Funktion benennen („Sachbearbeitung Flurbereinigung"),
|
||
nie als Person.
|
||
- Keine Python-Abhängigkeiten außer der Standardbibliothek und `pytest` ohne Issue-Absprache und Eintrag in
|
||
`fallstricke.md`. Einzige eingebettete Fremdbibliothek ist bpmn-js unter `werkzeuge/vorschau/bpmn-js/` –
|
||
nicht von Hand ändern, Aktualisierung nach `werkzeuge/vorschau/README.md`.
|
||
- **Die Markdown-Syntax und das Ablageformat der Prozessbibliothek sind Verträge.** Wer sie ändert, prüft vorher
|
||
alle Modelle der Bibliothek, zieht `Anleitung.md` bzw. `docs/leitfaden/08_prozessbibliothek.md` nach und nennt die Änderung im Pull
|
||
Request unter „Änderungen an Syntax und Ablageformat“.
|
||
- Kein Umbau „nebenbei". Strukturänderungen nur über eigenes Issue.
|
||
|
||
### Allgemein
|
||
|
||
- Sprache: Doku, Kommentare, Docstrings, Commit-Nachrichten, Issues und PRs auf Deutsch, mit echten Umlauten
|
||
(Prüfung: `python scripts/pruefe_umlaute.py`). Bezeichner nach dem Stil der jeweiligen Datei.
|
||
|
||
## Arbeitsablauf in Kurzform (Details: Skill `sn-aufgabe-bearbeiten`)
|
||
|
||
1. `python scripts/hallo.py` – Stand holen.
|
||
2. Gitea-Issue lesen (Skill `sn-ticket`, `python scripts/gitea.py ticket Projektwissen <nr>`) oder als Entwurf
|
||
vorbereiten. Ziel und Abnahmekriterien klären, bevor etwas geändert wird.
|
||
3. Branch `feature/<issue-nr>-<kurzname>` bzw. `bugfix/<issue-nr>-<kurzname>` von `main`. Ohne Issue kein
|
||
solcher Branch: erst den Entwurf, dann legt der Mensch das Issue an (Ausnahme: `doku/…`).
|
||
4. In kleinen Schritten umsetzen; nur betroffene Dateien und Abschnitte lesen.
|
||
5. `python -m pytest -q` (enthält `pruefe_prozesse.py`) und `python scripts/pruefe_umlaute.py`. Erzeugte BPMN-Dateien zusätzlich
|
||
in PICTURE importieren und das Ergebnis im PR nennen.
|
||
6. Pull-Request-Text vollständig nach `docs/vorlagen/pull_request.md` vorbereiten – alle Abschnitte einschließlich
|
||
Checkliste –, mit Übergabenotiz (Skill `sn-uebergabe`).
|
||
**Push und Pull Request macht der Mensch.**
|
||
7. Neue Erkenntnisse in `docs/wissen/` oder `docs/entscheidungen/` festhalten, nicht nur im lokalen Gedächtnis des Werkzeugs.
|
||
|
||
## Tokensparend arbeiten
|
||
|
||
- Gezielt `grep`, dann nur die nötigen Abschnitte lesen. `md_to_bpmn.py` (über 1000 Zeilen) nie komplett laden.
|
||
- Keine Dateien oder Testausgaben in den Chat kopieren; Pfade mit Zeilennummern nennen.
|
||
- Am Ende jeder Aufgabe eine Übergabenotiz, damit die nächste Sitzung nicht neu erkunden muss.
|
||
- Breite Suchen an einen Unteragenten delegieren, wenn das Werkzeug das kann; Hauptkontext schlank halten.
|
||
|
||
## Befehle
|
||
|
||
- Sitzungsbeginn: `python scripts/hallo.py` (Claude Code: `/hallo`)
|
||
- Tickets: `python scripts/gitea.py tickets` | `python scripts/gitea.py ticket Projektwissen 12` | `… suche "<text>"`
|
||
- Tests: `python -m pytest -q`
|
||
- Umlaute prüfen: `python scripts/pruefe_umlaute.py`
|
||
- Prozessmodelle prüfen bzw. alle `.bpmn` neu erzeugen: `python scripts/pruefe_prozesse.py [--erzeugen]`
|
||
- Diagramm im Browser ansehen (offline): `python scripts/vorschau.py <datei.bpmn|datei.md>`
|
||
- Eingangsordner prüfen bzw. Einlese-Vermerk setzen: `python scripts/einlesen.py [--json]` |
|
||
`python scripts/einlesen.py vermerk input/<datei>.md --ergebnis neu|aktualisiert --ziel <pfad>`
|
||
- Workspace einrichten oder aktualisieren: `python scripts/setup_workspace.py` (mit `--pull` für fast-forward)
|
||
- Entwurf umwandeln: `python .agents/skills/sn-bpmn/md_to_bpmn.py entwuerfe/<name>.md entwuerfe/<name>.bpmn`
|
||
|
||
## Skills
|
||
|
||
Liegen in `.agents/skills/` (Agent-Skills-Standard) und werden nach `.claude/skills/` gespiegelt:
|
||
`sn-bpmn`, `sn-einlesen`, `sn-aufgabe-bearbeiten`, `sn-ticket`, `sn-uebergabe`.
|