Projektwissen/docs/leitfaden/03_arbeitsweise.md

Arbeitsweise für Entwickler: So arbeiten wir mit KI-Agenten an den LNO-Plugins

Für Kolleginnen und Kollegen, die neu einsteigen. Fachwissen wird vorausgesetzt, Software-Erfahrung nicht. Wir arbeiten mit Claude Code (ADR 0008); die Dateien bleiben werkzeugneutral. Die Kurzfassung für den Agenten selbst ist AGENTS.md, dieser Leitfaden erklärt das Warum und das Wie. Git im Detail: 05_git_arbeitsweise.md. Tests im Detail: 06_tests.md.

1. In zehn Minuten startklar

Voraussetzungen: Git, Python ≥ 3.11 (ist in OSGeo4W enthalten: python-qgis.bat oder das OSGeo-Python), Zugang zu Gitea (entwicklung.flurneuordnung-sachsen.de), Claude Code (CLI oder VS-Code-Erweiterung). Für QGIS-Tests: QGIS 3.44 LTR oder 4 mit einem eigenen Profil (z. B. dev), in dessen Plugin-Ordner die Pakete sn_basis, sn_verfahrensgebiet, sn_plan41 liegen (Verknüpfungen auf die Klone).

git clone https://entwicklung.flurneuordnung-sachsen.de/AG_QGIS/Projektwissen.git AG_QGIS
cd AG_QGIS
python scripts/setup_workspace.py     # klont die Plugin-Repos, spiegelt Skills
python scripts/run_tests.py           # muss laufen: 3 Suiten, Zusammenfassung

Solange AG_QGIS/Projektwissen auf Gitea noch nicht angelegt ist (Phase 0 im Konzept), schlägt der Clone mit „Repository not found“ fehl, obwohl die Anmeldung gelingt. Übergangslösung: den Ordner AG_QGIS aus dem Projektverzeichnis auf dem Netzlaufwerk (Projekte\QGIS Plan 41\AG_QGIS) komplett kopieren, darin python scripts/setup_workspace.py ausführen (erneuert den Skill-Spiegel und prüft die Klone) und weiter wie oben.

Dann das Werkzeug im Ordner AG_QGIS/ starten:

Form	Start	Prüfen
Claude Code CLI	claude im Ordner AG_QGIS	/context zeigt CLAUDE.md und AGENTS.md unter „Memory files“; /hallo ist im Menü
Claude Code in VS Code	Ordner AG_QGIS öffnen, Panel starten	dasselbe; Diffs erscheinen im Editor

Einrichtung Schritt für Schritt: 04_werkzeuge_einrichten.md.

Erste Frage an den Agenten zum Warmwerden: „Fasse docs/status/STATUS.md zusammen und nenne die drei wichtigsten Regeln aus AGENTS.md.“ Antwortet er korrekt, ist die Einrichtung fertig.

2. Der Arbeitszyklus

flowchart TD
    A["1 Issue auf Gitea (Vorlage docs/vorlagen/issue.md)"] --> B["2 Branch von unstable: feature/<nr>-<kurzname>"]
    B --> C["3 Auftrag an den Agenten (Abschnitt 3)"]
    C --> D["4 Umsetzung in kleinen Schritten, Zwischenstände committen"]
    D --> E["5 python scripts/run_tests.py <paket> --baseline"]
    E -->|rot| D
    E -->|grün| F["6 Bei UI/QGIS-Verhalten: Test in QGIS, Ergebnis notieren"]
    F --> G["7 changelog.txt oben ergänzen"]
    G --> H["8 PR auf unstable (Vorlage docs/vorlagen/pull_request.md) mit Übergabenotiz"]
    H --> I["9 Review durch eine Kollegin/einen Kollegen"]
    I -->|Änderungswünsche| D
    I -->|Merge| J["10 STATUS.md und Wissensbasis nachziehen"]

Jeder Schritt ist klein. Ein PR sollte an einem Tag entstehen und in einer Viertelstunde reviewbar sein. Wenn das nicht geht, ist das Issue zu groß: aufteilen.

Branch-Namen: feature/<issue-nr>-<kurzname>, bugfix/<issue-nr>-<kurzname>, doku/<kurzname>. Commit-Nachrichten: deutsch, Präsens, erste Zeile ≤ 72 Zeichen, Issue-Nummer am Ende (Shape-Import: FBSchl.-Variante akzeptieren (#41)).

3. Wie man einem Agenten einen Auftrag gibt

Der Agent liest AGENTS.md automatisch. Was er nicht weiß: was genau gewollt ist, wo es endet, und was fachlich richtig ist. Ein guter Auftrag hat vier Teile:

1. Ziel und Issue: „Bearbeite Issue Verfahrensgebiet #41: …“ oder das Ziel in zwei Sätzen.
2. Kontext-Zeiger statt Erklärungen: „Betroffen ist functions/verfahrensgebiet_shape_komplett.py, Ablauf in docs/aus_shape_laden_technisch.md. Lies zuerst docs/architektur/schnittstellen.md Abschnitt 6.“
3. Grenzen: „Keine Änderung am ALKIS-Ablauf. Keine neuen Abhängigkeiten. Kein Refactoring.“
4. Abnahme: „Fertig ist es, wenn run_tests.py sn_verfahrensgebiet --baseline keine neuen roten Tests zeigt, ein Test für den Fall FBSchl. existiert und die Übergabenotiz geschrieben ist.“

Beispiel eines guten Auftrags (das Issue wurde am 02.09.2026 tatsächlich so in PR #45 gelöst; hier als Muster):

Nutze den Skill sn-aufgabe-bearbeiten für Issue Verfahrensgebiet #41. Der Shape-Import soll zusätzlich das Feld FBSchl. (mit Punkt) akzeptieren, wie es manche DAVID-Exporte liefern. Betroffen: _ermittle_gebietstyp_aus_fbschl in functions/verfahrensgebiet_shape_komplett.py. Nicht ändern: die Bedeutung der Schlüssel 901/10110F und 901/10120F. Schreibe einen Test im Mock-Modus für beide Feldnamen. Am Ende: Übergabenotiz nach Vorlage.

Beispiel eines schlechten Auftrags: „Schau dir das Shape-Laden an und mach es besser.“ Das erzeugt lange Erkundung, unklare Änderungen und einen PR, den niemand reviewen kann.

Während der Arbeit: Rückfragen des Agenten beantworten, fachlich prüfen, was er behauptet, und ihn bei Abschweifungen zurückholen („Nur Issue #41“). Wenn er anfängt, Tests zu ändern statt Code, nach der Begründung fragen.

Was der Agent nicht darf: mergen, taggen/releasen, Baseline ändern, Verträge (Abschnitt schnittstellen.md) ändern ohne Issue, Zugangsdaten anfassen.

4. Die Regeln und warum es sie gibt

Regel (aus AGENTS.md)	Warum
Qt/QGIS nur über Wrapper	Ein Code für Qt5 und Qt6; Tests ohne QGIS; ein Ort für Kompatibilitätsfixe
Projektvariablen nur über get_variable/set_variable, Schlüssel ohne sn_	Einheitliches Präfix; Mock-Speicher in Tests; Doppelpräfixe vermeiden
Fachlogik ins Fachplugin, sn_basis importiert keine Fachplugins	Basis muss allein laden können; sonst Startfehler wie Issue Basis #57
grep vor Änderungen an sn_basis	Drei Fachplugins in drei Repos hängen daran
Mock-Tests vor jedem Commit, keine neuen roten Tests	Tests sind der einzige schnelle Nachweis für Agentenarbeit
Kein Refactoring nebenbei	Umbauten ohne Plan zerstören Verträge, die nur im Code stehen; eigene Phase
Deutsch in Doku, Commits, Issues	Team und Fachbegriffe sind deutsch; Agenten folgen der Sprache der Dateien
Keine Zugangsdaten, keine echten Verfahrensdaten	Öffentliche Repos, Datenschutz
Übergabenotiz	Die nächste Person oder der nächste Agent soll nicht von vorn beginnen

5. Tests

Mock-Modus (immer): python scripts/run_tests.py <paket> --baseline. Läuft ohne QGIS in Sekunden, verlinkt die Repos unter ihren Paketnamen in ein temporäres Verzeichnis und fasst zusammen. --baseline vergleicht mit docs/status/testbaseline.json und meldet NEU ROT (nicht erlaubt) und neu grün (bitte Baseline-Update im PR vorschlagen). --verbose zeigt die volle Ausgabe eines Laufs, wenn man einen Fehler verstehen will.

QGIS-Tests (bei UI, Layern, WFS, Layouts): Windows, OSGeo4W-Shell, im Plugin-Repo tests\test_qgis.bat (Pfad zu python-qgis.bat anpassen) oder QGIS starten und den Ablauf manuell durchspielen. Ergebnis im PR unter „Nachweis“ eintragen: was geprüft wurde, mit welchen Daten, was herauskam.

Neue Tests: unittest, Datei tests/test_<modul>.py, Mock-Modus, ohne Netzwerk. Muster: vorhandene Tests des Pakets. Ein Test pro Verhalten, deutsche Methodennamen sind üblich (test_zip_fehler_gibt_none_und_warning).

Rote Tests reparieren: Erst klären, ob der Test veraltet ist oder der Code falsch. Bei veralteten Tests den Test an das neue Verhalten anpassen und in der Übergabenotiz begründen. Niemals Tests löschen oder mit skip stilllegen, um grün zu werden.

6. Wissen festhalten

Situation	Was tun
Etwas hat überraschend Zeit gekostet	Eintrag in docs/wissen/fallstricke.md (Rubrik, Datum, Quelle)
Ein Vertrag wurde geändert oder entdeckt	docs/architektur/schnittstellen.md anpassen
Modul neu, verschoben, gewachsen	docs/architektur/modulkarte.md anpassen
Team hat etwas entschieden	neue Datei docs/entscheidungen/NNNN-<thema>.md nach Vorlage
Aufgabe abgegeben oder pausiert	Übergabenotiz im PR (Vorlage) und Zeile in STATUS.md
Fachbegriff musste erklärt werden	docs/wissen/glossar.md

Der Skill sn-uebergabe führt den Agenten am Ende jeder Aufgabe durch genau diese Liste. Das eigene Gedächtnis des Werkzeugs (Claude Auto-Memory) ist ein Notizzettel; teilbares Wissen gehört in die Dateien oben.

7. Was liegt wo, und was liest der Agent

Datei	Wird gelesen
AGENTS.md (Projektwissen)	ja, über CLAUDE.md (@AGENTS.md) – kanonisch, ADR 0001
CLAUDE.md	ja, enthält nur den Verweis und wenige Claude-spezifische Zeilen
Plugin_*/AGENTS.md	über Plugin_*/CLAUDE.md, wenn in dem Ordner gearbeitet wird
.agents/skills/	kanonischer Ort; gelesen wird der Spiegel .claude/skills/
.claude/commands/	Slash-Befehle, z. B. /hallo
.claude/settings.json	Berechtigungen – sperrt git push, merge, tag
docs/	auf Abruf, nicht automatisch
CLAUDE.local.md	ja, lokal, nicht versioniert

8. Release in Kürze

Nur Maintainer. Kanal-Branch (unstable oder testing) auf den gewünschten Stand bringen, changelog.txt-Block prüfen, Tag v<JJ.M.N>-u bzw. -t auf dem Kopf des Kanal-Branches setzen und pushen. Der Workflow baut den Branch, erzeugt metadata.txt, legt das Release an und aktualisiert den Feed. Details und Prüfliste: Skill sn-release.

9. Häufige Fragen

Der Agent findet sn_basis nicht. Er hat nicht scripts/run_tests.py benutzt oder wurde im falschen Ordner gestartet. Tests immer über das Skript; Werkzeug im Workspace-Root starten.

Der Agent will qgis.core direkt importieren. Auf den Wrapper verweisen; fehlt ein Symbol, zuerst im Wrapper mit Mock-Fallback ergänzen (siehe Muster in qgiscore_wrapper.py, Zeilen 73–260).

Der Agent „repariert“ rote Tests durch Anpassen der Erwartung. Nach Begründung fragen; nur akzeptieren, wenn das Verhalten bewusst geändert wurde und das Issue es abdeckt.

Der Agent hat eine Datei komplett umgeschrieben. Diff prüfen, auf das Issue zurückführen, Rest verwerfen. Regel „kein Refactoring nebenbei“ zitieren.

Zwei Personen arbeiten am selben Modul. In STATUS.md steht, wer woran arbeitet; vorher dort eintragen und kleine PRs machen. Konflikte in unstable löst der Maintainer mit beiden.

Wie kommt das Plugin aus dem Workspace ohne Release in mein QGIS? Die Klone im Workspace verknüpfen: python scripts/link_qgis_profile.py --profil dev. QGIS lädt dann Plugin_SN_Basis als sn_basis direkt aus der Arbeitskopie. Details in 04_werkzeuge_einrichten.md Abschnitt 2.5.

Windows und Symlinks. setup_workspace.py und run_tests.py nutzen Junctions oder Kopien, wenn Symlinks nicht erlaubt sind. Nach Änderungen an Skills das Setup-Skript erneut ausführen, falls es „Kopie“ gemeldet hat.

10. Checklisten

Vor dem PR

• Issue verlinkt, Branch von unstable
• python scripts/run_tests.py <paket> --baseline ohne NEU ROT
• Bei UI/QGIS-Verhalten: Test in QGIS dokumentiert
• Keine direkten Qt/QGIS-Importe, keine Debug-print, kein auskommentierter Code
• changelog.txt ergänzt
• Übergabenotiz im PR; Wissensbasis nachgezogen, falls nötig
• Diff gelesen: nur, was das Issue verlangt

Review

• Fachlich richtig? (Verhalten, Begriffe, Dienste)
• Verträge unberührt oder per Issue abgestimmt?
• Tests vorhanden und sinnvoll (nicht nur angepasst)?
• Umfang überschaubar (< 400 Zeilen)?
• Nach dem Merge: STATUS.md

Sitzungsende (auch bei Abbruch)

• Zwischenstand committet oder gestasht und in der Übergabenotiz benannt
• Offene Fragen im Issue notiert
• STATUS.md-Zeile aktualisiert