Projektwissen/docs/leitfaden/04_werkzeuge_einrichten.md

# Werkzeuge einrichten: von null bis zur ersten Aufgabe

Stand 23.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 |
| **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`](../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](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 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 "<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:
  ```bash
  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

```bash
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`](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 eignet sich der Camunda Modeler (Desktop, offline) oder `demo.bpmn.io`,
siehe `.agents/skills/sn-bpmn/Anleitung.md` Abschnitt „Diagramm vorab prüfen“.

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

```jsonc
{
  "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`](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`](../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](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)