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`.

### 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`.