AndreasTharangandClaude Sonnet 5
ab416fb34c
Erster Stand des Repositories AG_QGIS/Projektwissen (bisher Arbeitstitel "Workspace", ADR 0006). Der lokale Ordner heisst weiter AG_QGIS, weil darin auch die Plugin-Klone liegen. Git verbindlich (ADR 0007), aus dem bisherigen Wiki-Konzept entwickelt: - docs/leitfaden/05_git_arbeitsweise.md mit Kanal-Kette, Branch-Namen und Gitea-Branch-Schutz. - Der Einstiegspunkt eines Fixes richtet sich nach dem Kanal, in dem der Fehler sitzt; ein Fix an testing oder stable ist erst mit der Rueckfuehrung nach unten abgeschlossen. Das fehlte bisher. - Der stabile Kanal heisst stable, nicht main: der Release-Workflow in Repository:hidden/workflows fuehrt git checkout "$CHANNEL" aus, der Branchname muss also dem Kanalnamen entsprechen. Er existiert in keinem Plugin-Repo und ist vom Maintainer anzulegen. - Der Mensch drueckt ab: .claude/settings.json sperrt push, merge, tag. - scripts/hallo.py und /hallo holen den Stand aller Klone, per Fast-Forward wo gefahrlos; nie mergen, stashen oder verwerfen. Ticketzugriff: - scripts/gitea.py liest Issues, Kommentare und PRs ueber die oeffentliche API, ohne Token, nur GET. Schreibendes nur als Entwurf in entwuerfe/. - Skill sn-ticket. Tests (ADR 0009): - docs/leitfaden/06_tests.md: Testebenen, Testpflicht, und wie eine Fachperson beurteilt, ob Tests fachlich sinnvoll sind. - scripts/testkatalog.py erzeugt docs/tests/testkatalog.md per ast-Parsing, ohne Import und ohne QGIS. Befund: nur 100 von 332 Tests haben einen Docstring, sn_basis keinen einzigen von 87. - Vorlage und erste Testkonzept-Seite mit Mermaid. Dabei gefunden und gegen origin geprueft: _ermittle_gebietstyp_aus_fbschl hat keinen Test, obwohl PR #44/#45 genau diese Funktion tolerant gemacht hat. - docs/konzept/07_qgis_tests_plan.md: Stufenplan fuer Tests gegen echtes QGIS. Dabei aufgefallen: QGIS 3.40 ist seit Januar 2026 End of Life, qgis_min steht aber noch darauf. Werkzeuge (ADR 0008): - 04_werkzeuge_einrichten.md nur noch Claude Code als CLI und in VS Code. - .vscode/ entfernt, brauchbare Einstellungen als persoenliche Vorlage. Ausserdem: README als Einstieg neu aufgebaut, Mermaid-Diagramm in schnittstellen.md repariert (unmaskierte Klammern, rendert seither nicht). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
204 lines
12 KiB
Markdown
204 lines
12 KiB
Markdown
# 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).
|
||
|
||
```bash
|
||
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
|
||
|
||
```mermaid
|
||
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
|