# Projektwissen AG_QGIS – Anweisungen für KI-Agenten und Entwickler 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 - QGIS-Plugins der sächsischen Flurbereinigungsbehörden („LNO Sachsen"): Plattform-Plugin `sn_basis` plus Fachplugins `sn_verfahrensgebiet`, `sn_plan41` (Wege- und Gewässerplan nach § 41 FlurbG), `sn_widmung` (Gerüst) und Platzhalter. - Dieser Ordner ist der Klon des Repositories **`AG_QGIS/Projektwissen`**. Die Plugin- und Daten-Repositories liegen als **eigenständige Git-Klone** in Unterordnern (`Plugin_SN_*/`, `Repository/`, `Linkliste/`, `Defaults/`), jedes mit eigenen Branches, Issues und Releases auf Gitea. Zuordnung Repo-Name → Paketname (`Plugin_SN_Basis` → `sn_basis`) steht in `workspace.toml`. - Zielumgebung: QGIS 3.44 LTR (Qt5) und QGIS 4 (Qt6) unter Windows/OSGeo4W. Die Mindestversion steht noch auf 3.40, das seit Januar 2026 End of Life ist – offene Entscheidung, siehe `docs/konzept/07_qgis_tests_plan.md`. Die KI-Agenten laufen meist ohne QGIS; dafür gibt es den Mock-Modus der Wrapper und `scripts/run_tests.py`. ## Zuerst lesen – nur was die Aufgabe braucht 1. `docs/status/STATUS.md` – aktueller Stand, offene Baustellen, wer woran arbeitet. 2. `docs/architektur/modulkarte.md` – welche Datei was tut und wie groß sie ist (statt Dateien blind zu lesen). 3. `docs/architektur/schnittstellen.md` – Verträge zwischen `sn_basis` und Fachplugins, Projektvariablen, Release. 4. `docs/wissen/fallstricke.md` – bekannte Stolperfallen (Qt5/Qt6, Mock-Modus, WFS-Grenzen, Release-Kanäle). 5. 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. - Arbeitsbranch ist `unstable`. Nie direkt auf `unstable`, `testing` oder `stable` committen: eigener Branch `feature/-` bzw. `bugfix/-`, dann Pull Request. - **Wo ein Fix beginnt, richtet sich nach dem Kanal, in dem der Fehler sitzt** – bei `testing` von `testing` abzweigen, danach Rückführung nach `unstable`. 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 scripts/run_tests.py --baseline`. Neue rote Tests sind nicht erlaubt; bereits rote Tests (Baseline in `docs/status/testbaseline.json`) dürfen nicht vermehrt werden. Die Baseline ändert nur ein Maintainer. - **Neue Funktionalität ohne Test wird nicht gemergt.** Mindestens ein Test je neuem beobachtbarem Verhalten, im Mock-Modus, 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 …"""`. Danach `python scripts/testkatalog.py` neu erzeugen und mitcommitten. - 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. Details: `docs/leitfaden/06_tests.md`. ### Code - QGIS und Qt **nie direkt importieren** (einzige Ausnahme: `qgis.utils` in `main.py`). Ausschließlich über die Wrapper in `sn_basis.functions` (`qt_wrapper`, `qgiscore_wrapper`, `qgisui_wrapper`, `dialog_wrapper`, `message_wrapper`, `variable_wrapper`). Fehlt ein Symbol, wird es zuerst im Wrapper mit Mock-Fallback ergänzt. - Projektvariablen nur über `get_variable`/`set_variable` (Präfix `sn_` wird automatisch gesetzt – Schlüssel ohne Präfix übergeben). - Fachlogik gehört in das Fachplugin, nicht nach `sn_basis`. `sn_basis` importiert keine Fachplugins (dokumentierte Ausnahme: Lazy-Import in `DataGrabber`, siehe `schnittstellen.md`). - Änderungen an öffentlichen Funktionen von `sn_basis` sind API-Änderungen: vorher alle Verwendungen in den Fachplugins per `grep` prüfen und mit anpassen. - Keine Python-Abhängigkeiten außerhalb der QGIS-Python-Umgebung ohne Issue-Absprache und Eintrag in `fallstricke.md`. - Kein Refactoring „nebenbei". Strukturänderungen nur über eigenes Issue; das grundlegende Refactoring ist eine eigene Phase. ### Allgemein - Sprache: Doku, Kommentare, Docstrings, Commit-Nachrichten, Issues und PRs auf Deutsch. Bezeichner nach dem Stil der jeweiligen Datei. - Keine Zugangsdaten, API-Keys, personenbezogene Daten oder echte Verfahrensdaten in Repositories, Doku oder Prompts. - `AGENTS.md`, `CLAUDE.md`, `.agents/`, `.claude/` gehören nicht in Release-ZIPs (siehe `fallstricke.md`, Release-Excludes). ## Arbeitsablauf in Kurzform (Details: Skill `sn-aufgabe-bearbeiten`) 1. `python scripts/hallo.py` – Stand aller Klone holen. 2. Gitea-Issue lesen (Skill `sn-ticket`, `python scripts/gitea.py ticket `) oder als Entwurf vorbereiten. Ziel, Abnahmekriterien und betroffenes Plugin klären, bevor Code angefasst wird. 3. Branch `feature/-` bzw. `bugfix/-` vom passenden Kanal. 4. In kleinen Schritten umsetzen; nur betroffene Dateien und Abschnitte lesen. Neue Logik bekommt einen Test. 5. `python scripts/run_tests.py --baseline` und `python scripts/testkatalog.py`. UI- oder QGIS-Verhalten zusätzlich in QGIS prüfen und das Ergebnis im PR nennen. 6. `changelog.txt` des Plugins oben ergänzen (Block ohne Versionszeile = nächstes Release). 7. Pull-Request-Text nach `docs/vorlagen/pull_request.md` vorbereiten, inklusive Übergabenotiz (Skill `sn-uebergabe`). **Push und Pull Request macht der Mensch.** 8. Neue Erkenntnisse in `docs/wissen/` oder `docs/entscheidungen/` festhalten, nicht nur im lokalen Gedächtnis des Werkzeugs. ## Tokensparend arbeiten - Erst `modulkarte.md` und `schnittstellen.md`, dann gezielt `grep`, dann nur die nötigen Abschnitte lesen. Dateien über 600 Zeilen (Liste in der Modulkarte) nie komplett laden. - Keine Dateien oder Testausgaben in den Chat kopieren; Pfade mit Zeilennummern nennen. - Tests immer über `scripts/run_tests.py` (Zusammenfassung statt Rohausgabe; `--verbose` nur bei Bedarf). - 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 Basis 48` | `… suche ""` - Tests (Mock-Modus, Sekunden): `python scripts/run_tests.py` | `python scripts/run_tests.py sn_basis --baseline` - Testkatalog: `python scripts/testkatalog.py` | `--pruefen` (meldet, wenn veraltet) - Workspace einrichten oder aktualisieren: `python scripts/setup_workspace.py` (mit `--pull` für fast-forward) - Klone in ein QGIS-Profil verknüpfen: `python scripts/link_qgis_profile.py --profil dev` - Tests in echter QGIS-Umgebung: Skill `sn-tests`; Ausbauplan `docs/konzept/07_qgis_tests_plan.md` - Release: Tag `v-u` (unstable), `-t` (testing) oder ohne Suffix (stable) auf dem Kanal-Branch – **nur Maintainer**, Skill `sn-release` ## Skills Liegen in `.agents/skills/` (Agent-Skills-Standard) und werden nach `.claude/skills/` gespiegelt: `sn-aufgabe-bearbeiten`, `sn-ticket`, `sn-tests`, `sn-uebergabe`, `sn-neues-fachplugin`, `sn-release`.