Projektwissen/README.md

Projektwissen — AG QGIS Sachsen

Hier fängst du an. Dieses Repository ist das gemeinsame Gedächtnis der QGIS-Plugin-Entwicklung der sächsischen Flurbereinigungsbehörden („LNO Sachsen"). Es enthält keinen Plugin-Code, sondern alles, was man wissen muss, um an den Plugins mitzuarbeiten: die Regeln, die Wissensbasis, die Anweisungen für KI-Agenten, die Skripte und das Verzeichnis aller Repositories.

Der Plugin-Code liegt in eigenen Repositories, die als Unterordner hierher geklont werden. Danach ist dieser Ordner der Ort, an dem du arbeitest — mit einem KI-Agenten, der die Regeln aus diesem Repository automatisch liest.

flowchart TB
    subgraph GITEA["Gitea · entwicklung.flurneuordnung-sachsen.de/AG_QGIS"]
        PW[("Projektwissen<br/><i>dieses Repo</i>")]
        PB[("Plugin_SN_Basis")]
        PF[("Plugin_SN_Verfahrensgebiet<br/>Plugin_SN_Plan41<br/>Plugin_SN_Widmung · …")]
        RE[("Repository<br/><i>Plugin-Feeds</i>")]
    end

    subgraph LOKAL["Dein Rechner · Ordner AG_QGIS/"]
        W["Regeln, Wissensbasis,<br/>Skills, Skripte"]
        K["Plugin-Klone<br/>Plugin_SN_*/"]
    end

    PW -->|"git clone"| W
    PB --> K
    PF --> K
    W -.->|"setup_workspace.py<br/>holt die Klone"| K

    LOKAL -->|"Pull Request"| GITEA
    RE -->|"Plugin-Feed"| QGIS(["QGIS auf den<br/>Arbeitsplätzen"])

    style PW fill:#e8f6ec,stroke:#2f9e44
    style W fill:#e8f6ec,stroke:#2f9e44

Ordnername ≠ Reponame. Das Repository heißt Projektwissen, der lokale Ordner heißt AG_QGIS — weil darin nicht nur das Projektwissen liegt, sondern auch alle Plugin-Klone daneben. Der Klon-Befehl unten setzt das automatisch richtig.

In 15 Minuten startklar

Vorher da sein muss: Git, Python ≥ 3.11, ein Gitea-Konto mit Schreibrecht in der Organisation AG_QGIS. Details und Windows-Besonderheiten: docs/leitfaden/04_werkzeuge_einrichten.md.

# 1. Projektwissen holen — Zielordner AG_QGIS nicht vergessen
git clone https://entwicklung.flurneuordnung-sachsen.de/AG_QGIS/Projektwissen.git AG_QGIS
cd AG_QGIS

# 2. Alle Plugin-Repositories dazuholen
python scripts/setup_workspace.py

# 3. Prüfen, dass alles läuft (Sekunden, ohne QGIS)
python scripts/run_tests.py

Erwartete Ausgabe von Schritt 3: drei Test-Suiten mit Zahlen. Dass dabei nicht alles grün ist, ist bekannt und in Ordnung — siehe docs/status/STATUS.md.

# 4. Claude Code installieren und den Ordner AG_QGIS in PATH aufnehmen
npm install -g @anthropic-ai/claude-code

# Windows (PowerShell) — AG_QGIS dauerhaft an den Benutzer-PATH anhängen:
[Environment]::SetEnvironmentVariable(
    "Path",
    [Environment]::GetEnvironmentVariable("Path", "User") + ";$HOME\AG_QGIS",
    "User")

# Linux/macOS (bash/zsh) — Zeile in ~/.bashrc bzw. ~/.zshrc:
export PATH="$PATH:$HOME/AG_QGIS"

Nach der PATH-Änderung die Shell neu öffnen, damit sie wirksam wird. Ohne Claude Code lässt sich der KI-gestützte Arbeitsablauf dieses Repositories nicht nutzen; ohne den Ordner in PATH finden manche Skripte und Aufrufe den Workspace nicht.

# 5. KI-Werkzeug starten — im Ordner AG_QGIS, nicht in einem Plugin-Unterordner
claude

Zum Warmwerden diese Frage stellen:

„Fasse docs/status/STATUS.md zusammen und nenne die drei wichtigsten Regeln aus AGENTS.md."

Kommt eine brauchbare Antwort, ist die Einrichtung fertig. Kommt keine, wurde das Werkzeug im falschen Ordner gestartet.

Dein erster Beitrag

flowchart LR
    A["/hallo<br/><i>Stand holen</i>"] --> B["Ticket wählen<br/><i>gitea.py tickets</i>"]
    B --> C["Branch von unstable"]
    C --> D["Umsetzen<br/><i>mit Test</i>"]
    D --> E["run_tests.py<br/>--baseline"]
    E -->|rot| D
    E -->|grün| F["Push + Pull Request"]
    F --> G["Review<br/><i>durch Kollegin</i>"]
    G --> H["Merge + STATUS.md"]

    style E fill:#fff4e6,stroke:#d9822b
    style F fill:#e6f2ff,stroke:#2b7dd9

Konkret, mit Befehlen:

#	Schritt	Womit
1	Stand holen — immer zuerst	/hallo bzw. python scripts/hallo.py
2	Offene Tickets ansehen	python scripts/gitea.py tickets
3	Ein Ticket im Detail lesen	python scripts/gitea.py ticket Basis 48
4	Aufgabe an den Agenten geben	Skill sn-aufgabe-bearbeiten, Muster in 03_arbeitsweise.md Abschnitt 3
5	Nachweis erbringen	python scripts/run_tests.py <paket> --baseline
6	Pull Request	Vorlage docs/vorlagen/pull_request.md

Für den Anfang eignet sich ein kleines Ticket oder ein einzelner roter Test aus docs/status/testbaseline.json.

Die Regeln, die immer gelten

Die vollständige, für Agenten verbindliche Fassung steht in AGENTS.md. Das Wichtigste in Kurzform:

1. Der Mensch drückt ab. Agenten bereiten alles vor — Push, Merge, Tag und alles auf dem Gitea-Server macht eine Person mit ihrem eigenen Zugang. → 05_git_arbeitsweise.md
2. Nie direkt auf stable, testing oder unstable committen. Immer Arbeitsbranch und Pull Request.
3. Neue Funktionalität ohne Test wird nicht gemergt. Vor jedem Commit python scripts/run_tests.py <paket> --baseline, keine neuen roten Tests. → 06_tests.md
4. QGIS und Qt nie direkt importieren, nur über die Wrapper in sn_basis.functions. Deshalb laufen die Tests in Sekunden ohne QGIS. → schnittstellen.md
5. Kein Refactoring nebenbei. Strukturänderungen brauchen ein eigenes Issue.
6. Deutsch in Doku, Kommentaren, Commits, Issues und Pull Requests.
7. Keine Zugangsdaten, keine echten Verfahrensdaten in Repositories, Doku oder Prompts.
8. Wissen gehört in docs/, nicht in das Gedächtnis des KI-Werkzeugs — das ist lokal und teilt sich nicht.

Wegweiser

Wenn du neu bist, lies in dieser Reihenfolge: 03_arbeitsweise.md → 05_git_arbeitsweise.md → 04_werkzeuge_einrichten.md.

Pfad	Inhalt
AGENTS.md / CLAUDE.md	Anweisungen für Agenten (kanonisch ist AGENTS.md)
workspace.toml	Verzeichnis aller Repositories: Branch, Paketname, Rolle
scripts/	hallo.py, setup_workspace.py, run_tests.py, gitea.py, testkatalog.py, link_qgis_profile.py
.agents/skills/	Skills für wiederkehrende Abläufe, gespiegelt nach .claude/skills/
.claude/commands/	Slash-Befehle für Claude Code (/hallo)
docs/status/	Aktueller Stand, Test-Baseline — immer zuerst lesen
docs/leitfaden/	Arbeitsweise, Werkzeuge, Git, Tests
docs/architektur/	Modulkarte und Schnittstellen (lebende Referenz)
docs/wissen/	Fallstricke, Glossar, externe Dienste — das gemeinsame Gedächtnis
docs/entscheidungen/	Warum etwas so ist (ADR, append-only)
docs/tests/	Testkatalog und Testkonzepte je Fachablauf
docs/konzept/	Zusammenarbeit mit KI-Agenten, QGIS-Testplan, Repo-Einrichtung
docs/analyse/	Momentaufnahmen 09/2026, werden nicht fortgeschrieben
docs/vorlagen/	Issue, Pull Request, Übergabe, Testkonzept, Repo-AGENTS.md, CI-Workflow
Plugin_SN_*/, Repository/, Linkliste/, Defaults/	eigenständige Git-Klone, nicht Teil dieses Repos

Wenn etwas nicht geht

Symptom	Ursache und Abhilfe
git clone meldet „Repository not found"	Zugang zur Organisation AG_QGIS fehlt — Maintainer fragen
ModuleNotFoundError: sn_basis	Tests nicht über scripts/run_tests.py gestartet, oder Klone fehlen (setup_workspace.py)
ModuleNotFoundError: openpyxl	pip install openpyxl im selben Python, mit dem du run_tests.py aufrufst
Der Agent kennt die Regeln nicht	Er wurde in einem Plugin-Unterordner gestartet statt in AG_QGIS/
Plugin erscheint nicht in QGIS	Profil verknüpfen: python scripts/link_qgis_profile.py --profil dev, dann sn_basis zuerst aktivieren
Konflikte beim Pullen	/hallo vor der Arbeit vergessen — siehe 05_git_arbeitsweise.md Abschnitt 11

Mehr davon in docs/leitfaden/03_arbeitsweise.md Abschnitt 9 und in docs/wissen/fallstricke.md.

Mitmachen

Auch dieses Repository wird per Pull Request geändert — Regeln, Wissensbasis und Skripte sind genauso versioniert wie Code. Wer eine Regel für falsch hält, macht ein Issue auf. Wer etwas gelernt hat, das andere Zeit kostet, trägt es in docs/wissen/fallstricke.md ein.