Projektwissen der AG Prozesse aus AG_QGIS/Projektwissen abgeleitet

Übernommen ohne Historie aus AG_QGIS/Projektwissen (main @ decd2a0), Skill sn-bpmn vom Branch BPMN-Skill @ 6efcac4 (ADR 0001). - Skripte hallo.py, gitea.py, setup_workspace.py auf die Organisation AG_Prozesse umgestellt; das Workspace-Repo zählt über [workspace] repo als Ticket-Repo, auch ohne weitere [[repos]]. - pruefe_umlaute.py prüft jetzt die .py-Dateien des Workspace selbst. - Branchmodell main plus Arbeitsbranches (ADR 0002). - AGENTS.md, README, Leitfäden, Skills, Vorlagen, Fallstricke und Glossar auf die Prozessmodellierung zugeschnitten; QGIS- und Plugin-Spezifisches entfernt. - Tests: python -m pytest -q .agents/skills -> 32 bestanden. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-23 12:34:37 +02:00
commit 012509b6d1
36 changed files with 4414 additions and 0 deletions
@@ -0,0 +1,186 @@
+# 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 .agents/skills      # 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 |
+
+Ein BPMN-Betrachter als Erweiterung ist nicht nötig: `md_to_bpmn.py` kann eine Vorschau ohne PICTURE erzeugen,
+siehe `.agents/skills/sn-bpmn/Anleitung.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)").
+
+```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 .agents/skills` 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 .agents/skills` 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)