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

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.