Michael Otto
3ba7a32c7e
Bisher gab es keinen Platz fuer rein fachliche Ablaufbeschreibungen unabhaengig von Tests: docs/ ist projektuebergreifendes Wissen, docs/tests/ ist testkonzept-gebunden. projekte/<paket>/ablaeufe/ schliesst diese Luecke, gegliedert nach Plugin-Paketname wie in workspace.toml. Erster Eintrag: projekte/sn_verfahrensgebiet/ablaeufe/alkis-laden.md, uebernommen aus Plugin_SN_Verfahrensgebiet/docs/aus_alkis_laden.md (dort entstanden, bevor es dieses Wissensrepo gab).
184 lines
8.9 KiB
Markdown
184 lines
8.9 KiB
Markdown
# 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.
|