AG_QGIS/Projektwissen
3
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
de05b04e21a2bdcfc3105cc05eb23f1a1fb609e5
Projektwissen/AGENTS.md
T
AndreasTharangandClaude Sonnet 5 ab416fb34c Projektwissen: Git-Vorgaben, Ticketzugriff, Tests und Einstieg 
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>
2026-09-04 11:57:26 +02:00

106 lines
7.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`.
Reference in New Issue View Git Blame Copy Permalink