Projektwissen/docs/leitfaden/04_werkzeuge_einrichten.md

Werkzeuge einrichten: von null bis zur ersten Aufgabe

Stand 04.09.2026. Ergänzt 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 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 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.

  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:

  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

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 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 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)").

{
  // 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:

{
  "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 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, Ü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 · Gedächtnis und CLAUDE.md · Skills · Einstellungen und Berechtigungen
• Agent-Skills-Standard