Projektwissen/docs/leitfaden/04_werkzeuge_einrichten.md

Werkzeuge einrichten: von null bis zur ersten Aufgabe

Stand 23.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
B · Claude Code in VS Code	Erweiterung mit Chatpanel	Einstieg; Entwürfe und 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 — auch am Arbeitsschritt-Entwurf — 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 am Repository. 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_Prozesse (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.
• PICTURE-Zugang zum Prüfen des BPMN-Imports (nicht für alle nötig).

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 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 "<dienstliche Adresse aus dem Gitea-Konto>"
  

  Wer den Rechner auch privat nutzt, setzt die dienstliche Adresse besser je Repository statt global — --local statt --global.
• Prüfen, bevor der erste Commit entsteht:

  git -C AG_Prozesse config user.email     # muss die Gitea-Adresse sein
  

2.3 Python

Benötigt: Python ≥ 3.11 und das Paket pytest für die Tests des Konverters.

• Python von python.org installieren, beim Setup „Add to PATH" anhaken, dann python -m pip install pytest.
• Prüfen: python --version und python -m pytest --version müssen beide ohne Fehler durchlaufen.

Die Skripte (hallo.py, gitea.py, setup_workspace.py, pruefe_umlaute.py) und der Konverter md_to_bpmn.py brauchen nur die Standardbibliothek.

2.4 Projektwissen holen

git clone https://entwicklung.flurneuordnung-sachsen.de/AG_Prozesse/Projektwissen.git AG_Prozesse
cd AG_Prozesse
python scripts/setup_workspace.py       # spiegelt die Skills, holt ggf. weitere Repos
python -m pytest -q      # erwartet: alle Tests grün

Der Zielordner AG_Prozesse ist bewusst anders benannt als das Repository: darin können später weitere Repositories der Gruppe nebeneinander liegen.

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_Prozesse 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-bpmn, sn-aufgabe-bearbeiten, sn-ticket, sn-uebergabe) 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.

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_Prozesse öffnen (Datei → Ordner öffnen).
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 Text 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 Mermaid-Diagramme in der Vorschau

Zum Ansehen einer .bpmn ohne PICTURE ist keine Erweiterung nötig: python scripts/vorschau.py <datei> öffnet sie im Browser, offline (werkzeuge/vorschau/README.md).

4.2 Persönliche Einstellungen

Diese Einstellungen gehören in die Benutzereinstellungen, nicht ins Repository. Das Repo enthält bewusst keinen .vscode/-Ordner. Wer sie haben will, kopiert sie sich in die eigene settings.json (Strg+Shift+P → „Preferences: Open User Settings (JSON)").

{
  "files.exclude": { "**/__pycache__": true, "**/.pytest_cache": true },

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

5. Einschränkungen und Datenschutz

• Gitea statt GitHub. Alle Cloud-Agenten setzen GitHub voraus und entfallen damit. 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.
• Inhalte gehen an den Anbieter. Alles, was der Agent liest, wird an den Anbieter übertragen — auch eine Prozessbeschreibung aus referenz/. Deshalb: keine Zugangsdaten, keine personenbezogenen Daten, keine als vertraulich eingestuften Unterlagen in Prompts oder Dateien. Im Zweifel die Quelle vorher bereinigen.
• 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. setup_workspace.py fällt auf eine Junction oder Kopie 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 -m pytest -q ist grün.
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.
4. Zum Kennenlernen einen kleinen, unkritischen Prozess modellieren lassen (Skill sn-bpmn), den Entwurf prüfen, umwandeln und in PICTURE importieren.
5. Für Änderungen am Repository: python scripts/gitea.py tickets, ein Ticket auswählen, in docs/status/STATUS.md unter „Wer arbeitet woran" eintragen.
6. Auftrag nach dem Muster in 03_arbeitsweise.md Abschnitt 3 geben, mit dem Skill sn-aufgabe-bearbeiten.
7. Ergebnis prüfen: Tests grün, 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 -m pytest --version ohne Fehler
• git config user.email im Ordner AG_Prozesse liefert die Adresse des Gitea-Kontos
• python scripts/setup_workspace.py ohne Fehler, .claude/skills/ vorhanden
• python -m pytest -q grün
• python scripts/hallo.py läuft und zeigt den Stand
• python scripts/gitea.py tickets läuft
• Claude Code im Ordner AG_Prozesse gestartet; /context zeigt CLAUDE.md und AGENTS.md
• Gitea-Token gespeichert (Test: git fetch ohne Passwortabfrage)

Quellen

• Claude Code: VS-Code-Erweiterung · Gedächtnis und CLAUDE.md · Skills · Einstellungen und Berechtigungen
• Agent-Skills-Standard