AndreasTharangandClaude Sonnet 5
ab416fb34c
Erster Stand des Repositories AG_QGIS/Projektwissen (bisher Arbeitstitel "Workspace", ADR 0006). Der lokale Ordner heisst weiter AG_QGIS, weil darin auch die Plugin-Klone liegen. Git verbindlich (ADR 0007), aus dem bisherigen Wiki-Konzept entwickelt: - docs/leitfaden/05_git_arbeitsweise.md mit Kanal-Kette, Branch-Namen und Gitea-Branch-Schutz. - Der Einstiegspunkt eines Fixes richtet sich nach dem Kanal, in dem der Fehler sitzt; ein Fix an testing oder stable ist erst mit der Rueckfuehrung nach unten abgeschlossen. Das fehlte bisher. - Der stabile Kanal heisst stable, nicht main: der Release-Workflow in Repository:hidden/workflows fuehrt git checkout "$CHANNEL" aus, der Branchname muss also dem Kanalnamen entsprechen. Er existiert in keinem Plugin-Repo und ist vom Maintainer anzulegen. - Der Mensch drueckt ab: .claude/settings.json sperrt push, merge, tag. - scripts/hallo.py und /hallo holen den Stand aller Klone, per Fast-Forward wo gefahrlos; nie mergen, stashen oder verwerfen. Ticketzugriff: - scripts/gitea.py liest Issues, Kommentare und PRs ueber die oeffentliche API, ohne Token, nur GET. Schreibendes nur als Entwurf in entwuerfe/. - Skill sn-ticket. Tests (ADR 0009): - docs/leitfaden/06_tests.md: Testebenen, Testpflicht, und wie eine Fachperson beurteilt, ob Tests fachlich sinnvoll sind. - scripts/testkatalog.py erzeugt docs/tests/testkatalog.md per ast-Parsing, ohne Import und ohne QGIS. Befund: nur 100 von 332 Tests haben einen Docstring, sn_basis keinen einzigen von 87. - Vorlage und erste Testkonzept-Seite mit Mermaid. Dabei gefunden und gegen origin geprueft: _ermittle_gebietstyp_aus_fbschl hat keinen Test, obwohl PR #44/#45 genau diese Funktion tolerant gemacht hat. - docs/konzept/07_qgis_tests_plan.md: Stufenplan fuer Tests gegen echtes QGIS. Dabei aufgefallen: QGIS 3.40 ist seit Januar 2026 End of Life, qgis_min steht aber noch darauf. Werkzeuge (ADR 0008): - 04_werkzeuge_einrichten.md nur noch Claude Code als CLI und in VS Code. - .vscode/ entfernt, brauchbare Einstellungen als persoenliche Vorlage. Ausserdem: README als Einstieg neu aufgebaut, Mermaid-Diagramm in schnittstellen.md repariert (unmaskierte Klammern, rendert seither nicht). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
189 lines
13 KiB
Markdown
189 lines
13 KiB
Markdown
# 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.
|