DanielandClaude Opus 5.5
27589749ff
- input/ ist lokal und nicht versioniert (.gitignore); scripts/einlesen.py legt ihn bei Bedarf an. - scripts/einlesen.py ordnet jede Datei ein: abgelehnt (kein .md, nicht UTF-8, leer, Unterordner), neu, geändert, eingelesen. Für neue und geänderte Dateien: Prozessname, Ordnernamen-Vorschlag, ob schon eine Arbeitsschritt-.md, und ähnliche Prozesse aus prozesse/ und entwuerfe/. „vermerk“ schreibt nach Erfolg eine erste Zeile <!-- eingelesen: <Zeitstempel> | neu|aktualisiert | <Ziel> | inhalt: <sha> -->; die Prüfsumme erkennt spätere Änderungen. Zeilenenden bleiben erhalten. - Skill sn-einlesen: Übersicht, Bestandsvergleich, Entscheidung des Nutzers, neue Prozesse durch sn-bpmn, Vermerk nur bei Erfolg. - docs/leitfaden/07_prozesse_einlesen.md: Ablauf für neue Nutzer. - AGENTS.md, README, Leitfaden 03, Skill sn-bpmn, Fallstricke, STATUS. - Tests: python -m pytest -q -> 79 bestanden (18 neu in tests/test_einlesen.py). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
83 lines
6.5 KiB
Markdown
83 lines
6.5 KiB
Markdown
# Fallstricke und Erkenntnisse
|
||
|
||
Gemeinsames Gedächtnis: Dinge, die man **nicht aus dem Code ablesen kann** und die schon einmal Zeit gekostet haben.
|
||
Kurz, konkret, mit Datum und Quelle. Neue Einträge oben in der passenden Rubrik. Veraltetes löschen, nicht auskommentieren.
|
||
|
||
## BPMN und PICTURE (Skill sn-bpmn, md_to_bpmn.py)
|
||
|
||
- **Das bpmn.io-Wasserzeichen ist Lizenzauflage.** bpmn-js steht unter MIT, verlangt aber, dass das Wasserzeichen
|
||
unten rechts sichtbar bleibt und nicht überdeckt wird. In `werkzeuge/vorschau/vorschau.html` deshalb nichts in die
|
||
untere rechte Ecke der Zeichenfläche legen. (bpmn-js `LICENSE`, 23.09.2026)
|
||
- **Diagramme nie roh in ein `<script>` schreiben.** Eine Beschriftung mit `</script>` würde den Skriptblock beenden.
|
||
`scripts/vorschau.py` maskiert jedes `<` im Diagramm als `\u003c`; die Bibliothek selbst wird nicht verändert,
|
||
sondern nur auf `<script`/`</script` geprüft. (23.09.2026)
|
||
|
||
- **Jede Änderung an der Ausgabe von `md_to_bpmn.py` macht die abgelegten `.bpmn` rot.** Der Test in
|
||
`tests/test_pruefe_prozesse.py` vergleicht jede `.bpmn` unter `prozesse/` und in `beispiele/` byte-genau mit der
|
||
Umwandlung ihrer `.md`. Nach einer Konverteränderung `python scripts/pruefe_prozesse.py --erzeugen` ausführen und
|
||
die neu erzeugten Dateien mit in den Pull Request nehmen. Das setzt voraus, dass der Konverter deterministisch
|
||
bleibt: keine Zufalls-IDs, keine Zeitstempel, keine Reihenfolge aus `set`-Iteration. (ADR 0003, 23.09.2026)
|
||
- **Zusätzliche Zeilen in einer Arbeitsschritt-`.md` nur ganz oben oder mit `#`.** `parse_markdown()` bricht
|
||
nach dem ersten Schritt bei jeder unbekannten Zeile ab; davor überspringt es Zeilen, die nicht wie
|
||
`Schlüssel: Wert` aussehen. Deshalb steht der Einlese-Vermerk (`<!-- eingelesen: … -->`) als erste Zeile.
|
||
(23.09.2026, `scripts/einlesen.py`)
|
||
- **`Path.read_text()` macht aus CRLF stillschweigend LF.** Wer eine Datei liest und mit Zusatz zurückschreibt,
|
||
stellt so Windows-Dateien unbemerkt um. `scripts/einlesen.py` liest deshalb als Bytes. (23.09.2026, Test)
|
||
- **Metadaten gehören nicht als Kopfzeile in die Arbeitsschritt-`.md`.** `parse_markdown()` liest eine Zeile wie
|
||
`Verantwortliche Stelle: …` als Schritt mit ID `Verantwortliche` und Typ `Stelle` und bricht ab. Status und Stand
|
||
stehen deshalb im Steckbrief `README.md` des Prozessordners. (23.09.2026)
|
||
- **Zuständigkeit gilt auch für Gateways und Ereignisse.** Ohne `Rolle:`-Präfix landen sie in der Lane
|
||
„Nicht zugeordnet“. Ein `?` stört nur vor dem Doppelpunkt: `Sachbearbeitung: Antrag vollständig?` funktioniert.
|
||
(23.09.2026, beim Erstellen der Beispiele)
|
||
|
||
- **Ein Gateway hat in PICTURE nur vier feste Anschlusspunkte (N/O/S/W auf der Rautenkontur), keinen
|
||
variablen Rand wie ein Rechteck.** Eine Kante, die diesen Punkt verlässt bzw. dort ankommt, darf sich
|
||
danach **nicht** direkt zur Ziel-/Quellkoordinate drehen, wenn diese auf der anderen Achse liegt – sonst
|
||
läuft der rechtwinklige Streckenzug quer durchs Innere der Raute zurück, statt außen herumzugehen
|
||
(`orthogonal_points()` in `md_to_bpmn.py`, behoben BPMN-Skill 21.09.2026). Ursache: die feste
|
||
Anschlusspunkt-Zuteilung (`assign_gateway_sides()`, Präferenzreihenfolge S/O/W/N bzw. N/W/O/S) kennt die
|
||
tatsächliche Lage des anderen Endes nicht. Die Kante muss beim Verlassen/Ankommen an einer Raute zuerst
|
||
ein Stück auf der sicheren Stub-Achse bleiben (die einzige garantiert freie Koordinate außerhalb der
|
||
Kontur), bevor sie zur anderen Achse abbiegt – sonst reicht ein einfacher Bounding-Box-Test nicht, um den
|
||
Fehler zu erkennen (ein Punkt auf der Rautenkontur liegt immer innerhalb der Bounding-Box). Prüfen mit
|
||
echter Diamant-Geometrie (Manhattan-Abstand zum Mittelpunkt, skaliert auf die Halbachsen, < 1 heißt innen),
|
||
nicht mit der Bounding-Box – siehe `test_kante_fuehrt_nicht_durchs_innere_eines_gateways` in
|
||
`test_md_to_bpmn.py`.
|
||
|
||
## Text und Sprache
|
||
|
||
- **Deutscher Text ohne Umlaute/ß ist ein eigenständiges Muster, kein Einzelfall.** KI-generierter Text weicht
|
||
gern auf ASCII aus (`gueltig` statt `gültig`, `ueber` statt `über`) – in AG_QGIS über alle Plugins verteilt
|
||
gefunden (Plugin_SN_Basis #42), im BPMN-Skill in Elementnamen und Docstrings. Neuen deutschen Text
|
||
(Beschriftungen im Modell, Kommentare, Docstrings) immer mit echten Umlauten/ß schreiben. Vor dem Commit
|
||
`python scripts/pruefe_umlaute.py` laufen lassen – findet das Muster in `.py`-Dateien (String-Inhalte und
|
||
Kommentare mit Leerzeichen). Die Wortstammliste ist bewusst konservativ; Ersatz fürs Lesen ist sie nicht.
|
||
Arbeitsschritt-`.md` prüft das Skript nicht. (AG_QGIS 09/2026)
|
||
|
||
## Umgebung und Werkzeuge
|
||
|
||
- **Öffentliche Organisation heißt nicht öffentliches Repo.** In Gitea haben Organisation und Repo getrennte
|
||
Sichtbarkeit. `AG_Prozesse` war öffentlich, `Projektwissen` privat: Die Weboberfläche zeigte es angemeldeten
|
||
Personen normal, die API ohne Anmeldung lieferte 404. `scripts/gitea.py` liest bewusst ohne Token und braucht deshalb
|
||
ein öffentliches Repo; es prüft das jetzt vor jeder Abfrage. Prüfen ohne Anmeldung:
|
||
`curl -s -o /dev/null -w "%{http_code}" https://entwicklung.flurneuordnung-sachsen.de/api/v1/repos/AG_Prozesse/Projektwissen`
|
||
muss `200` liefern. (23.09.2026)
|
||
|
||
- **Gitea ordnet Commits über die E-Mail-Adresse zu.** Stimmt `user.email` nicht mit einer im Gitea-Konto
|
||
hinterlegten Adresse überein, erscheinen die Commits ohne Zuordnung zum Benutzer. Es gilt die dienstliche
|
||
Adresse, die im Gitea-Konto hinterlegt ist. Wer den Rechner auch privat nutzt, setzt sie je Repository mit
|
||
`git config --local` statt global. Nachträglich nur durch Umschreiben der Historie korrigierbar. (AG_QGIS 04.09.2026)
|
||
- **`pytest` ist die einzige Abhängigkeit außerhalb der Standardbibliothek.** Die Tests des Konverters brauchen
|
||
es; `md_to_bpmn.py` selbst läuft ohne. (23.09.2026)
|
||
- **`.vscode/` gehört nicht ins Repository.** Einstellungen mit Pfaden eines einzelnen Arbeitsplatzes gehören in
|
||
die Benutzereinstellungen, siehe `docs/leitfaden/04_werkzeuge_einrichten.md`. (AG_QGIS 04.09.2026)
|
||
|
||
## Zusammenarbeit
|
||
|
||
- **Tool-Gedächtnis ist lokal.** Die Claude-Auto-Memory sieht niemand sonst. Geteiltes Wissen nur in diesem Ordner.
|
||
- **Issues sind teils Diskussionen**, nicht Aufträge (Label `Diskussion`). Vor der Umsetzung Konsens im Issue
|
||
abwarten oder im PR als Annahme kennzeichnen.
|
||
- **Quelldokumente enthalten oft Interna.** Word/PDF-Prozessbeschreibungen nur lokal unter `referenz/` ablegen
|
||
(nicht versioniert). Vor dem Committen eines Arbeitsschritt-Entwurfs prüfen, dass keine Namen, Aktenzeichen
|
||
oder Verfahrensdaten darin stehen. (23.09.2026)
|