Projektwissen/docs/leitfaden/04_werkzeuge_einrichten.md

# Werkzeuge einrichten: von null bis zur ersten Aufgabe

Stand 04.09.2026. Ergänzt [`03_arbeitsweise.md`](03_arbeitsweise.md) um die konkrete Einrichtung. Wer Abschnitt 2
durchgearbeitet hat, kann beide Varianten aus Abschnitt 3 und 4 nutzen und jederzeit zwischen ihnen wechseln —
sie greifen auf dieselben Dateien zu.

## 1. Zwei Varianten

Wir arbeiten mit **Claude Code**. Es gibt zwei Formen, dieselbe Software zu bedienen:

| Variante | Form | Wofür geeignet |
|---|---|---|
| **A · Claude Code CLI** | Terminal | lange, eigenständige Aufgaben; Skripte; Arbeiten über mehrere Repos |
| **B · Claude Code in VS Code** | Erweiterung mit Chatpanel | Einstieg; Diffs im Editor sehen und einzeln annehmen |

Beide lesen `CLAUDE.md` (und darüber `AGENTS.md`), beide finden die Skills unter `.claude/skills/`, beide
arbeiten über Git mit Gitea. **Empfehlung für Einsteiger: Variante B**, weil man jede Änderung als Diff sieht,
bevor sie übernommen wird.

**Nicht genutzt und nicht unterstützt:** Cloud-Agenten (Claude Code Web, Codex Cloud, Copilot Coding Agent) —
sie setzen GitHub voraus, wir arbeiten mit Gitea. Reine Chat-Oberflächen ohne Ordnerzugriff (claude.ai,
chatgpt.com) sind für Fachfragen brauchbar, aber **nicht** für Änderungen an den Repos: Code-Fragmente per
Kopieren einzubauen ist genau die Arbeitsweise, die zur heutigen Struktur geführt hat. Wer nur Chat hat,
formuliert Issues nach [`docs/vorlagen/issue.md`](../vorlagen/issue.md) und lässt sie von jemandem mit Agent
umsetzen.

## 2. Gemeinsame Grundlage (einmal pro Rechner)

### 2.1 Konten und Zugänge

- **Gitea-Konto** auf `entwicklung.flurneuordnung-sachsen.de` mit Schreibrecht in der Organisation `AG_QGIS`
  (beim Maintainer anfragen). Für HTTPS-Push ein **Zugriffstoken** anlegen:
  Gitea → Einstellungen → Anwendungen → Token, Berechtigung `repository: read/write`.
- **Claude-Konto**: Abo (Pro, Max, Team, Enterprise) oder Console-Konto. Dienstliche E-Mail verwenden;
  die Abrechnung klärt die Behörde.
- **Behördennetz:** ausgehendes HTTPS zu `claude.ai` und `api.anthropic.com` muss möglich sein. Bei Proxy die
  Variablen `HTTPS_PROXY` und `HTTP_PROXY` setzen; bei Problemen mit der Zertifikatsprüfung die IT ansprechen.

### 2.2 Git

- **Windows:** [Git for Windows](https://git-scm.com/downloads/win) mit den Standardoptionen. Enthält Git Bash
  und den Credential Manager, der sich das Gitea-Token nach dem ersten Push merkt. Claude Code setzt Git for
  Windows voraus.
- **macOS/Linux:** Git über Xcode-Tools bzw. die Paketverwaltung.
- Einmalig einstellen — **die E-Mail-Adresse muss die des Gitea-Kontos sein.** Gitea ordnet Commits über die
  Adresse dem Benutzerkonto zu; passt sie nicht, erscheinen die Commits im Browser ohne Zuordnung und ohne
  Profilbild, und niemand sieht, wer etwas geändert hat. Nachträglich lässt sich das nur durch Umschreiben der
  Historie korrigieren.
  ```bash
  git config --global user.name  "Vorname Nachname"
  git config --global user.email "vorname.nachname@lfulg.sachsen.de"
  ```
  Wer den Rechner auch privat nutzt, setzt die dienstliche Adresse besser **je Repository** statt global —
  `--local` statt `--global`, in jedem Klon einmal. `python scripts/hallo.py` meldet nichts dazu; prüfen mit
  `git config user.email` im jeweiligen Ordner.

- Prüfen, bevor der erste Commit entsteht:
  ```bash
  git -C AG_QGIS config user.email     # muss die Gitea-Adresse sein
  ```

### 2.3 Python

Benötigt: **Python ≥ 3.11** und das Paket `openpyxl` für `scripts/run_tests.py`.

- **Windows mit QGIS:** am einfachsten die OSGeo4W-Shell mitnutzen — das dortige `python` ist das QGIS-Python.
  Darin `python -m pip install openpyxl`.
- **Alternativ:** Python von python.org installieren, beim Setup „Add to PATH" anhaken, dann
  `pip install openpyxl`.
- Prüfen: `python --version` und `python -c "import openpyxl"` müssen beide ohne Fehler durchlaufen.

Die übrigen Skripte (`hallo.py`, `gitea.py`, `testkatalog.py`, `setup_workspace.py`) brauchen **nur die
Standardbibliothek** — sie laufen auch ohne `openpyxl`.

### 2.4 Projektwissen holen

```bash
git clone https://entwicklung.flurneuordnung-sachsen.de/AG_QGIS/Projektwissen.git AG_QGIS
cd AG_QGIS
python scripts/setup_workspace.py     # klont alle Plugin-Repos, spiegelt die Skills
python scripts/run_tests.py           # erwartet: drei Suiten mit den Baseline-Zahlen
```

Der Zielordner `AG_QGIS` ist bewusst anders benannt als das Repository: darin liegen später nicht nur das
Projektwissen, sondern auch alle Plugin-Klone nebeneinander.

> **Solange `AG_QGIS/Projektwissen` auf Gitea noch nicht existiert**, 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`) kopieren und darin `python scripts/setup_workspace.py`
> ausführen.

### 2.5 QGIS für manuelle Tests

Empfohlen, für den Start nicht zwingend.

**Warum das nötig ist:** QGIS lädt Plugins nur aus dem Plugin-Ordner eines Profils, und zwar unter dem
**Paketnamen** (`sn_basis`), nicht unter dem Repo-Namen (`Plugin_SN_Basis`). Die Klone sind genau der Inhalt, der
sonst per Release-ZIP in QGIS landet. Statt zu kopieren oder ein Release zu bauen, wird der Klon in das Profil
**verknüpft**; QGIS arbeitet dann direkt auf der Arbeitskopie.

- QGIS 3.44 LTR (Qt5) und nach Möglichkeit QGIS 4.2 (Qt6) installieren. Eigenes Profil `dev` anlegen
  (Einstellungen → Benutzerprofile → Neues Profil) und einmal damit starten. Im Profil `dev` die Plugins
  **nicht** aus dem Release-Feed installieren.
- Verknüpfungen anlegen — unter Windows als Junction, ohne Administratorrechte:
  ```
  python scripts/link_qgis_profile.py --profil dev            # alle Plugins
  python scripts/link_qgis_profile.py --profil dev --status   # prüfen
  python scripts/link_qgis_profile.py --profil dev --entfernen
  ```
  Liegt das Profil woanders (OSGeo4W-Installation, Netzprofil):
  `--pfad "<…>\profiles\dev\python\plugins"`.
- In QGIS: Erweiterungen → Verwalten → Einstellungen → „Auch experimentelle Erweiterungen anzeigen".
  Dann zuerst „LNO Sachsen | Plugin Basisfunktionen" (`sn_basis`) aktivieren, danach die Fachplugins.
  Menü und Toolbar „LNO Sachsen" erscheinen.
- Nach jeder Codeänderung: Plugin „Plugin Reloader" (offizielles QGIS-Repository) → `sn_basis` neu laden, oder
  QGIS neu starten. Änderungen in `functions/` und `modules/` brauchen meist den Neustart, weil Module gecacht
  werden.

> Die QGIS-Mindestversion des Projekts steht noch auf 3.40, das seit Januar 2026 End of Life ist.
> Siehe [`../konzept/07_qgis_tests_plan.md`](../konzept/07_qgis_tests_plan.md) Abschnitt 2.

## 3. Variante A: Claude Code CLI

1. **Installieren.**
   Windows (PowerShell): `irm https://claude.ai/install.ps1 | iex`
   macOS/Linux: `curl -fsSL https://claude.ai/install.sh | bash`
   Node.js wird nicht benötigt; der Installer aktualisiert sich selbst.
2. **Anmelden:** `claude` starten, im Browser mit dem Claude-Konto anmelden.
3. **Starten:** im Ordner `AG_QGIS` (nicht in einem Plugin-Unterordner) `claude` eingeben. Beim ersten Mal den
   Import `@AGENTS.md` bestätigen.
4. **Prüfen:** `/context` listet `CLAUDE.md` und `AGENTS.md` unter „Memory files". `/hallo` und die Skills
   (`sn-aufgabe-bearbeiten`, `sn-tests`, `sn-ticket`, …) erscheinen im Menü.
5. **Berechtigungen:** Der Standardmodus fragt vor Änderungen. Für Routinearbeit ist „Accept edits" praktikabel.
   `--dangerously-skip-permissions` niemals außerhalb einer Sandbox.
   Das Repo verbietet über `.claude/settings.json` ohnehin `git push`, `git merge` und `git tag` —
   siehe [`05_git_arbeitsweise.md`](05_git_arbeitsweise.md) Abschnitt 6.
6. **Erste Aufgabe:** Abschnitt 6 dieser Seite.

Bei Arbeit in einem Plugin-Unterordner lädt Claude zusätzlich dessen `CLAUDE.md`. Für breite Codesuchen den
Explore-Unteragenten nutzen (steht in `CLAUDE.md`). Die Auto-Memory ist lokal und wird nicht geteilt; Teilbares
gehört nach `docs/` — Skill `sn-uebergabe`.

## 4. Variante B: Claude Code in VS Code

1. **VS Code installieren**, dann **den Ordner `AG_QGIS` öffnen** (Datei → Ordner öffnen) — nicht einen
   Plugin-Unterordner.
2. **Erweiterung installieren:** `Strg+Shift+X` → „Claude Code" (Herausgeber Anthropic) → Installieren.
   Die Erweiterung bringt eine eigene CLI-Kopie mit; die Installation aus Variante A ist nur nötig, wenn man
   `claude` zusätzlich im integrierten Terminal nutzen will.
3. **Anmelden:** Symbol in der Aktivitätsleiste → Sign in → Browser-Anmeldung.
4. **Python-Interpreter wählen:** `Strg+Shift+P` → „Python: Select Interpreter" → das Python aus Abschnitt 2.3.
5. **Arbeiten:** Panel öffnen. Markierter Code wird automatisch mitgesendet (`Alt+K` fügt einen Verweis ein).
   Diffs erscheinen im Editor und werden einzeln angenommen oder verworfen. Den Berechtigungsmodus wählt man
   unten im Eingabefeld; Pläne lässt man vor der Umsetzung im Plan-Modus prüfen.

### 4.1 Empfohlene Erweiterungen

| Erweiterung | Kennung | Wofür |
|---|---|---|
| Claude Code | `anthropic.claude-code` | der Agent selbst |
| Python | `ms-python.python` | Syntax, Interpreterwahl, Debugger |
| Markdown Preview Mermaid Support | `bierner.markdown-mermaid` | zeigt die Mermaid-Diagramme in `docs/` in der Vorschau |

### 4.2 Persönliche Einstellungen

**Diese Einstellungen gehören in die Benutzereinstellungen, nicht ins Repository.** Das Repo enthält bewusst
keinen `.vscode/`-Ordner: er würde persönliche Pfade (OSGeo-Installation, QGIS-Profil, Benutzername) versionieren
und bei jedem eine andere Datei erzeugen. Wer sie haben will, kopiert sie sich in die eigene `settings.json`
(`Strg+Shift+P` → „Preferences: Open User Settings (JSON)").

```jsonc
{
  // Aufgeräumte Datei- und Suchansicht
  "files.exclude": {
    "**/__pycache__": true,
    "**/.sn_testlauf": true
  },
  "search.exclude": {
    "**/.git": true,
    "**/__pycache__": true,
    "Plugin_SN_Plan41/assets/**": true
  },

  // Einheitliche Dateiform — die Repos sind auf UTF-8 und LF eingestellt
  "files.encoding": "utf8",
  "files.eol": "\n",
  "[python]": { "editor.tabSize": 4, "editor.insertSpaces": true },
  "[markdown]": { "editor.wordWrap": "on" },

  // Tests laufen über scripts/run_tests.py, nicht über den VS-Code-Testrunner:
  // die Pakete müssen dafür erst unter ihren Paketnamen verlinkt werden.
  "python.testing.unittestEnabled": false,
  "python.testing.pytestEnabled": false
}
```

Wer zusätzlich Code-Vervollständigung für die QGIS-API möchte, ergänzt die eigenen Pfade — **nur lokal**:

```jsonc
{
  "python.analysis.extraPaths": [
    "C:/OSGeo4W/apps/qgis/python",
    "C:/Users/<benutzer>/AppData/Roaming/QGIS/QGIS3/profiles/dev/python/plugins"
  ]
}
```

## 5. Einschränkungen und Datenschutz

- **Gitea statt GitHub.** Alle Cloud-Agenten setzen GitHub voraus und entfallen damit. Lokale Agenten arbeiten
  problemlos mit Gitea über Git. Issues und Pull Requests entstehen im Gitea-Browser; lesend geht die API auch
  ohne Anmeldung — dafür gibt es `scripts/gitea.py` und den Skill `sn-ticket`.
- **Code geht an den Anbieter.** Die Repos sind öffentlich; trotzdem gilt: keine Zugangsdaten, keine
  Verfahrensdaten, keine personenbezogenen Daten in Prompts, Dateien oder Testdaten. API-Schlüssel (VLN) nie in
  den Chat kopieren.
- **Der Mensch drückt ab.** Agenten dürfen nicht pushen, mergen, taggen oder irgendetwas auf dem Gitea-Server
  verändern. Das ist in `.claude/settings.json` technisch hinterlegt, nicht nur als Bitte formuliert.
- **Windows-Symlinks.** Die Skripte fallen auf Junctions oder Kopien zurück, wenn Symlinks nicht erlaubt sind.
  Nach Änderungen an Skills `python scripts/setup_workspace.py --nur-skills` erneut ausführen.

## 6. Von null zur ersten Aufgabe (etwa eine Stunde)

1. Abschnitt 2 durcharbeiten; `python scripts/run_tests.py` zeigt drei Suiten.
2. Variante A oder B einrichten. Prüfung: der Agent nennt auf Nachfrage die Regeln aus `AGENTS.md`.
3. `/hallo` ausführen — holt den Stand aller Klone.
4. `python scripts/gitea.py tickets` — offene Tickets ansehen und eines auswählen. Für den Anfang eignet sich
   auch ein einzelner roter Test aus `docs/status/testbaseline.json` oder ein Eintrag in `fallstricke.md`.
5. In `docs/status/STATUS.md` unter „Wer arbeitet woran" eintragen (kleiner Pull Request oder Nachricht an den
   Maintainer).
6. Auftrag nach dem Muster in [`03_arbeitsweise.md`](03_arbeitsweise.md) Abschnitt 3 geben, mit dem Skill
   `sn-aufgabe-bearbeiten`.
7. Ergebnis prüfen: `python scripts/run_tests.py <paket> --baseline` ohne `NEU ROT`, Diff gelesen.
8. Branch pushen (selbst!), Pull Request im Gitea-Browser nach
   [`docs/vorlagen/pull_request.md`](../vorlagen/pull_request.md), Übergabenotiz aus dem Skill `sn-uebergabe`.
9. Review durch eine Kollegin oder einen Kollegen; nach dem Merge `STATUS.md` nachziehen.

## 7. Prüfliste „Einrichtung fertig"

- [ ] `git --version` und `python --version` (≥ 3.11) laufen, `python -c "import openpyxl"` ohne Fehler
- [ ] `git config user.email` im Ordner `AG_QGIS` liefert die Adresse des Gitea-Kontos
- [ ] `AG_QGIS/` mit allen Repos vorhanden, `python scripts/setup_workspace.py` ohne Fehler
- [ ] `python scripts/run_tests.py` zeigt drei Suiten mit den Baseline-Zahlen
- [ ] `python scripts/hallo.py` läuft und zeigt den Stand aller Klone
- [ ] `python scripts/gitea.py tickets` listet die offenen Tickets
- [ ] Claude Code im Ordner `AG_QGIS` gestartet; `/context` zeigt `CLAUDE.md` und `AGENTS.md`
- [ ] Gitea-Token gespeichert (Test: `git fetch` in einem Plugin-Repo ohne Passwortabfrage)
- [ ] Optional: QGIS-Profil `dev` mit Verknüpfungen, `sn_basis` lädt ohne Fehler

## Quellen

- Claude Code: [VS-Code-Erweiterung](https://code.claude.com/docs/en/vs-code) ·
  [Gedächtnis und CLAUDE.md](https://code.claude.com/docs/en/memory) ·
  [Skills](https://code.claude.com/docs/en/skills) ·
  [Einstellungen und Berechtigungen](https://code.claude.com/docs/en/settings)
- [Agent-Skills-Standard](https://agentskills.io/home)