Projektwissen/AGENTS.md

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/<nr>-<kurzname> bzw. bugfix/<nr>-<kurzname>, 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 <paket> --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.
• Testfälle nur auf ausdrückliche Aufforderung als „geprüft" markieren (scripts/test_audit.py markieren). Die Markierung bestätigt, dass ein Mensch den Test fachlich abgenommen hat; ein Auftrag wie „Audit fortsetzen" reicht dafür nicht. Agenten sichten, ergänzen Tests und schlagen die Markierung vor – markieren erst nach Freigabe.

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 <repo> <nr>) oder als Entwurf vorbereiten. Ziel, Abnahmekriterien und betroffenes Plugin klären, bevor Code angefasst wird.
3. Branch feature/<issue-nr>-<kurzname> bzw. bugfix/<issue-nr>-<kurzname> 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 <paket> --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 "<text>"
• 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<JJ.M.N>-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.