Projektwissen/docs/konzept/02_zusammenarbeit_ki_agenten.md

# Konzept: Gemeinsame KI-gestützte Entwicklung über mehrere Behörden und Werkzeuge

Stand 02.09.2026. Vorschlag zur Abnahme durch die AG QGIS. Die Umsetzung liegt als Struktur bereits in diesem
Workspace vor; was das Team anders entscheidet, wird hier und in `docs/entscheidungen/` nachgezogen.

## 1. Ausgangslage und Ziele

**Randbedingungen**

- Mehrere Entwickler in verschiedenen Flurbereinigungsbehörden, überwiegend Fachleute ohne Software-Ausbildung.
- Jeder nutzt eigene KI-Agenten: Claude Code, OpenAI Codex, teils GitHub Copilot in VS Code (Issue Basis #36).
  *Nachtrag 04.09.2026: Das Team arbeitet mit Claude Code; die Doku beschreibt nur noch dieses Werkzeug, die
  Dateistruktur bleibt werkzeugneutral (ADR 0008).*
  Alle arbeiten ordnerbasiert und lesen Anweisungsdateien aus dem Repository.
- Elf Repositories in einer Gitea-Organisation, eigener Release-Prozess, Zielplattform Windows/OSGeo4W mit QGIS 3.40
  und 4. Die Agenten laufen meist ohne QGIS.
- Der Code ist gewachsen und wird später grundlegend refaktoriert; bis dahin soll die Arbeit trotzdem sicher und
  effizient sein.

**Ziele**

1. Jeder Agent und jeder Entwickler bekommt **denselben Projektkontext**, unabhängig vom Werkzeug.
2. Wissen fließt **zurück ins Repository**, nicht in Chatverläufe oder lokale Gedächtnisse.
3. **Tokensparsamkeit**: Kontext wird schichtweise geladen; Verifikation (Tests) ist billig und schnell.
4. **Verbindlicher, leichter Arbeitszyklus**, der für Fachleute in einer Stunde erlernbar ist.
5. Vorbereitung des Refactorings, ohne es vorwegzunehmen.

## 2. Leitprinzipien

- **Eine Wahrheit, versioniert.** Alles, was mehr als eine Person wissen muss, steht in Git. Werkzeugspezifische
  Dateien sind nur dünne Zeiger auf die kanonische Quelle.
- **Kontext in Schichten (progressive Offenlegung).** Immer geladen: eine kurze Anweisungsdatei. Auf Abruf: Modulkarte,
  Schnittstellen, Fallstricke. Bei Bedarf: Skills mit Ablaufwissen. Nur wenn nötig: der Code selbst.
- **Verträge vor Code.** Agenten arbeiten sicher, wenn sie die impliziten Regeln kennen (Wrapper, Variablen, Dock,
  Release). Deshalb sind Verträge ausdrücklich dokumentiert und in Regeln übersetzt.
- **Verifikation ist Pflicht und billig.** Mock-Tests in Sekunden, Baseline gegen Verschlechterung, QGIS-Tests dort,
  wo Mocks nicht reichen.
- **Kleine Schritte, sichtbare Übergaben.** Ein Issue, ein Branch, ein PR, eine Übergabenotiz. Keine Sammel-PRs.
- **Menschen entscheiden, Agenten arbeiten.** Fachliche Entscheidungen und Merges bleiben bei Personen; Agenten
  liefern Vorschläge mit Nachweis.

## 3. Struktur des Projekts: drei Varianten

| Variante | Beschreibung | Vorteile | Nachteile |
|---|---|---|---|
| **A. Workspace-Meta-Repository mit Klonen** (empfohlen, umgesetzt) | Neues Repo `AG_QGIS/Projektwissen` mit `AGENTS.md`, `docs/`, Skills, Skripten, Manifest. Plugin-Repos werden als Unterordner geklont (per `.gitignore` ausgenommen). | Kein Eingriff in bestehende Repos und Release-Prozess; ein Ordner = ganzer Projektkontext; sofort nutzbar; Meta-Repo versioniert die Wissensbasis; Manifest hält kompatible Stände fest | Zwei Ebenen von Git; Entwickler müssen im Workspace-Root starten; per-Repo-Dateien bleiben nötig für Einzelklone |
| B. Monorepo | Alle Plugins in ein Repository überführen | Ein Kontext, ein PR über Plugin-Grenzen, einfache Verträge | Release-Prozess, Tags und Feeds müssten umgebaut werden; Historie-Migration; das ist Teil des Refactorings, nicht der Vorbereitung |
| C. Nur per-Repo-Dateien | `AGENTS.md` in jedem Plugin-Repo, keine Meta-Ebene | Minimal | Gesamtkontext fehlt genau dort, wo er gebraucht wird (Basis ↔ Fachplugin); Wissensbasis müsste dupliziert werden |

**Empfehlung A**, mit per-Repo-`AGENTS.md` als Ergänzung (Vorlage in `docs/vorlagen/AGENTS.repo.md`). Variante B bleibt als
Option für die Refactoring-Phase offen; der Workspace bereitet sie vor (Manifest, Verträge, Tests).

## 4. Anweisungsdateien: kanonisch `AGENTS.md`

| Werkzeug | liest | Lösung |
|---|---|---|
| Claude Code (genutzt) | `CLAUDE.md` (mit `@`-Importen), Skills in `.claude/skills/` | `CLAUDE.md` = `@AGENTS.md` + wenige Claude-Zeilen; Skills werden gespiegelt |
| andere (Codex, Copilot, Cursor, Gemini CLI, …) | überwiegend `AGENTS.md` und Agent-Skills-Standard | direkt, ohne dass wir etwas ändern müssten – wir dokumentieren die Einrichtung aber nicht (ADR 0008) |

Alternativen und warum nicht: getrennte Dateien je Werkzeug (Drift), Symlink `CLAUDE.md → AGENTS.md` (unter Windows
Administratorrechte nötig; Import ist gleichwertig).

**Inhalt und Grenzen der `AGENTS.md`:** unter 150 Zeilen; nur Fakten, die in jeder Sitzung gelten (Regeln, Befehle,
Leseliste, Arbeitsablauf in Kurzform). Alles Prozedurale wandert in Skills, alles Beschreibende in `docs/`.
Sie wird bei jeder Sitzung in den Kontext geladen und ist damit die teuerste Datei des Projekts.

**Per-Repo-`AGENTS.md`** (kurz, ≤ 40 Zeilen): Rolle des Repos, Aufbau, Zusatzregeln, Testbefehl, Verweis auf den
Workspace. Nötig, weil Codex Anweisungen nur bis zur Wurzel des jeweiligen Git-Repos sucht und weil Entwickler
gelegentlich nur ein Repo klonen. Für Claude Code liegt daneben eine `CLAUDE.md` mit `@AGENTS.md`.

## 5. Bausteine der Wissensbasis

```
AG_QGIS/                          Klon von Projektwissen (Meta)
├── AGENTS.md, CLAUDE.md          Schicht 1: immer geladen
├── workspace.toml                Manifest: Repos, Branches, Paketnamen, Rollen
├── scripts/                      setup_workspace.py, run_tests.py, link_qgis_profile.py
├── .agents/skills/<name>/SKILL.md   Schicht 3: Ablaufwissen auf Abruf
├── docs/status/STATUS.md         Schicht 2: aktueller Stand (Pflichtlektüre)
├── docs/architektur/             Modulkarte, Schnittstellen (lebend)
├── docs/wissen/                  Fallstricke, Glossar, externe Dienste (geteiltes Gedächtnis)
├── docs/entscheidungen/          ADRs: warum etwas so ist
├── docs/vorlagen/                Issue, PR, Übergabe, Repo-AGENTS.md, CI-Workflow
├── docs/analyse|konzept|leitfaden   Momentaufnahmen und stabile Texte
└── Plugin_SN_*/ …                eigenständige Klone, je mit AGENTS.md + CLAUDE.md
```

| Baustein | Zweck | Pflegeregel |
|---|---|---|
| `STATUS.md` | Was ist gerade los, wer arbeitet woran, offene Baustellen | bei jedem Merge/Übergabe |
| `modulkarte.md` | gezieltes Lesen statt Vollzugriff; Kennzeichnung großer Dateien | bei neuen/verschobenen Modulen |
| `schnittstellen.md` | die impliziten Verträge explizit | vor jeder Änderung daran |
| `fallstricke.md` | nicht ableitbares Wissen mit Datum und Quelle | sobald etwas Zeit gekostet hat |
| `glossar.md`, `externe_dienste.md` | Fachbegriffe, URLs, Abhängigkeiten | nach Bedarf |
| `entscheidungen/NNNN-*.md` | eine Entscheidung je Datei: Kontext, Entscheidung, Folgen, Status | neue Entscheidung = neue Datei; alte nie ändern, nur ersetzen |
| Skills | wiederkehrende Abläufe: Aufgabe bearbeiten, Tests, Übergabe, neues Fachplugin, Release | wenn sich ein Ablauf ändert |
| `testbaseline.json` | Liste bekannter roter Tests | nur mit Absprache (`--update-baseline`) |

### Shared Memory: was wohin

| Art von Wissen | Beispiel | Ort |
|---|---|---|
| Regel, die immer gilt | „Qt nur über Wrapper“ | `AGENTS.md` |
| Vertrag zwischen Komponenten | Prioritäten der Actions, Variablennamen | `schnittstellen.md` |
| Stolperfalle | „Release baut Kanal-Branch, nicht Tag“ | `fallstricke.md` |
| Warum-Entscheidung | „AGENTS.md kanonisch“ | `entscheidungen/` |
| Ablauf | Release-Schritte | Skill |
| Zwischenstand einer Aufgabe | „Test X ist rot, weil …“ | Übergabenotiz im PR und `STATUS.md` |
| Persönliche Vorlieben, lokale Pfade | Editor, OSGeo-Pfad | lokales Tool-Gedächtnis, `CLAUDE.local.md` (gitignored) |

Die werkzeugeigenen Gedächtnisse (Claude Auto-Memory) bleiben erlaubt, gelten aber als
**Notizzettel**. Die Regel in `AGENTS.md` und im Skill `sn-uebergabe` verpflichtet dazu, Teilbares in die Wissensbasis
zu überführen. Das greift den Vorschlag aus Issue Basis #36 auf und ersetzt die dort vorgesehenen
`copilot-instructions.md` je Plugin durch die werkzeugneutralen `AGENTS.md`.

## 6. Tokensparsamkeit: konkrete Maßnahmen

| Maßnahme | Wirkung | Umsetzung |
|---|---|---|
| Kurze `AGENTS.md`, Rest auf Abruf | jede Sitzung startet mit wenigen tausend Token statt Vollkontext | erledigt |
| Modulkarte mit Zeilenzahlen und Warnung ab 600 Zeilen | Agent liest Abschnitte statt Dateien | erledigt; Regel in `AGENTS.md` |
| Schnittstellen-Dokument | keine Erkundung von drei Repos, um einen Vertrag zu verstehen | erledigt |
| Fallstricke | keine Wiederholung bekannter Irrwege | erledigt, wächst |
| Skills statt wiederholter Erklärungen | Ablauf wird nur geladen, wenn er gebraucht wird | 5 Skills erledigt |
| `run_tests.py` mit Zusammenfassung und Baseline | Sekunden statt Minuten; keine Rohausgaben im Kontext | erledigt |
| Übergabenotiz je Aufgabe | nächste Sitzung beginnt bei Schritt 5 statt 1 | Vorlage + Skill erledigt |
| Issues mit Abnahmekriterien | weniger Rückfragen, weniger Fehlversuche | Vorlage erledigt |
| Unteragenten für breite Suchen (Claude Code) | Hauptkontext bleibt schlank | Hinweis in `CLAUDE.md` |
| Refactoring großer Dateien | dauerhaft kleinere Lesekosten | spätere Phase |

Anti-Muster, die vermieden werden: ganze Dateien in den Chat kopieren; „Lies das ganze Projekt“; Testrohausgaben
einfügen; parallele Erkundung durch mehrere Personen ohne Übergabe; Erkenntnisse nur im Chat.

## 7. Arbeitszyklus und Rollen

```mermaid
flowchart LR
    I[Issue mit Abnahmekriterien] --> B[Branch von unstable]
    B --> A[Agent-Auftrag mit Kontextverweisen]
    A --> U[Umsetzung in kleinen Schritten]
    U --> T[run_tests.py --baseline\n+ QGIS-Test bei UI]
    T --> P[PR mit Übergabenotiz]
    P --> R[Review durch Mensch]
    R -->|Änderungen| U
    R -->|Merge| S[STATUS.md, Wissen, Changelog]
    S --> REL[Release bei Bedarf]
```

| Rolle | Aufgaben |
|---|---|
| **Maintainer** (je Repo eine Person, Vorschlag: bisherige Hauptentwickler) | Merge-Recht, Release, Pflege von `AGENTS.md`/Verträgen, Baseline-Änderungen |
| **Entwickler** | Issues formulieren, Agenten steuern, PRs mit Nachweis liefern, Wissensbasis pflegen |
| **Agent** | umsetzen, testen, dokumentieren; keine Merges, keine Tags, keine Entscheidungen über Verträge |
| **AG QGIS** | Entscheidungen zu Verträgen, Datenmodell, Refactoring, Alternativansatz |

Review-Regeln: KI-erzeugter Code wird immer von einer Person gelesen; PRs unter etwa 400 geänderten Zeilen; jede
Vertragsänderung braucht ein Issue mit Label `Schnittstelle`.

## 8. Werkzeugspezifika

**Claude Code:** im Workspace-Root starten; `/context` zeigt, ob `CLAUDE.md` und `AGENTS.md` geladen sind. Skills
liegen nach `python scripts/setup_workspace.py --nur-skills` in `.claude/skills/`. Beim Arbeiten in einem
Plugin-Ordner lädt Claude die dortige `CLAUDE.md` automatisch dazu. Auto-Memory ist lokal; Regel siehe Abschnitt 5.

**Gitea:** Labels `Bug`, `Feature`, `Diskussion` ergänzen um `Schnittstelle`, `Tests`, `Doku`, `Refactoring`.
Issue- und PR-Vorlagen aus `docs/vorlagen/` in `.gitea/` der Repos übernehmen (optional).

## 9. Einführung in Phasen

| Phase | Inhalt | Ergebnis |
|---|---|---|
| **0 – Projektwissen veröffentlichen** | Repo `AG_QGIS/Projektwissen` anlegen, diesen Ordner pushen, Team liest Konzept und Leitfaden, Entscheidungen bestätigen (ADR-Status auf „angenommen“) | ab sofort gemeinsamer Kontext |
| **1 – Repos anbinden** | per-Repo `AGENTS.md`/`CLAUDE.md` per PR in Basis, Plan41, Verfahrensgebiet, Widmung; Release-Excludes ergänzen; Metadata-Templates korrigieren | Agenten arbeiten auch in Einzelklonen korrekt |
| **2 – Tests absichern** | Baseline committen, CI-Workflow aus Vorlage in die drei Plugin-Repos, Rot→Grün als Issues je Testdatei | Tests haben wieder Aussagekraft |
| **3 – Verträge festschreiben** | Abhängigkeiten deklarieren, Variablennamen bereinigen (kleiner, gezielter Eingriff), Linkliste-Entscheidung, Manifest kompatibler Versionen | stabile Basis für den Umbau |
| **4 – Refactoring planen** | Zielarchitektur (inkl. Fachschale-Idee), Scheiben, Reihenfolge, Monorepo-Frage | eigenes Konzept |

Phase 0 und 1 sind in wenigen Stunden erledigt; Phase 2 ist die erste echte Teamaufgabe mit Agenten und zugleich das
Training des Arbeitszyklus.

## 10. Entscheidungen, die das Team treffen muss

1. Name und Ort des Meta-Repositories (entschieden: `AG_QGIS/Projektwissen`, ADR 0006).
2. Bestätigung der ADRs 0001–0005 (`docs/entscheidungen/`).
3. Maintainer je Repository.
4. Bestätigung der ADRs 0006–0009 (Reponame, Branchmodell, Werkzeugfokus, Testpflicht).
5. Linkliste: zentrale CSV als einzige Quelle (Empfehlung) oder XLSX im Plugin.
6. Zeitpunkt des Refactorings (Empfehlung: nach Phase 3) und ob die Fachschale-Idee Teil des Zielbilds wird.