Projektwissen/AGENTS.md

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.