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.

```mermaid
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`](docs/leitfaden/04_werkzeuge_einrichten.md).

```bash
# 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`](docs/status/STATUS.md).

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

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

```mermaid
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`](docs/leitfaden/03_arbeitsweise.md) Abschnitt 3 |
| 5 | Nachweis erbringen | `python scripts/run_tests.py <paket> --baseline` |
| 6 | Pull Request | Vorlage [`docs/vorlagen/pull_request.md`](docs/vorlagen/pull_request.md) |

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

## Die Regeln, die immer gelten

Die vollständige, für Agenten verbindliche Fassung steht in [`AGENTS.md`](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`](docs/leitfaden/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`](docs/leitfaden/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`](docs/architektur/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`](docs/leitfaden/03_arbeitsweise.md) →
[`05_git_arbeitsweise.md`](docs/leitfaden/05_git_arbeitsweise.md) →
[`04_werkzeuge_einrichten.md`](docs/leitfaden/04_werkzeuge_einrichten.md).

| Pfad | Inhalt |
|---|---|
| [`AGENTS.md`](AGENTS.md) / `CLAUDE.md` | Anweisungen für Agenten (kanonisch ist `AGENTS.md`) |
| [`workspace.toml`](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 |
| `projekte/<paket>/ablaeufe/` | Fachablauf-Diagramme je Plugin (z. B. `sn_verfahrensgebiet/ablaeufe/alkis-laden.md`) — unabhängig von Tests, im Unterschied zu den Testkonzepten in `docs/tests/` |
| `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`](docs/leitfaden/05_git_arbeitsweise.md) Abschnitt 11 |

Mehr davon in [`docs/leitfaden/03_arbeitsweise.md`](docs/leitfaden/03_arbeitsweise.md) Abschnitt 9 und in
[`docs/wissen/fallstricke.md`](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`](docs/wissen/fallstricke.md) ein.