# Agenten – Arbeitsweise (projektübergreifend)

> Gilt für alle KI-Agenten, agentisch (Claude Code, Codex, Gemini CLI, VSCodium/Continue) wie im Chat.
> `ai/rules/*.md` haben Vorrang.

## 1. Arbeitsweise
- **Sitzungsstart** gemäß `AGENTS.md`.
- **Erst verstehen, dann bauen:** vorhandenen Code, Knowledge-Einträge und Projektstand lesen, bevor etwas Neues entsteht. Bestehendes wiederverwenden.
- **Empfehlung statt Optionsliste.** Alternativen nur, wenn die Entscheidung wirklich beim Bediener liegt – dann knapp mit Empfehlung.
- **Nachfragen**, wenn: Ziel/Projekt unklar, Regel berührt (Produktion, Löschen, extern), Verantwortliche für den Header fehlen, Annahmen das Ergebnis wesentlich ändern.
- **Selbstständig handeln** bei: Formalien, Konventionen aus `common/`, offensichtlichen Defaults – im Ergebnis kurz erwähnen.
- **Keine Erfindungen:** Hostnamen, IPs, Versionen, Optionen nur aus Knowledge/Projekt/Quelle. Unsicheres als „unsicher“ markieren.
- **Ergebnisse ablegen, nicht nur im Chat:** Projektstand → `context.md`; Dauerhaftes → Knowledge-DB.

## 2. Qualitätsmaßstab („nah am Optimum“)
Vor Abgabe von Code/Doku/Architektur selbst prüfen:
- [ ] Passender Standard aus `common/` eingehalten, Vorlage aus `common/templates/` genutzt
- [ ] Header mit Verantwortlichen (`rules/headers.md`), Funktionen mit Kurz-Doku
- [ ] Keine Geheimnisse, keine internen Daten in Beispielen für Externe
- [ ] Lokal getestet (Syntax, Lint, Trockenlauf) – oder ausdrücklich gesagt, was **nicht** getestet wurde
- [ ] Doku/Knowledge aktualisiert, `bin/kb_index.sh` gelaufen
- [ ] Einfachste Lösung, die das Ziel erfüllt – keine Vorratsfunktionen

## 3. Formales
- Sprache, Datum: `rules/language.md`.
- Markdown: `common/markdown.md`.
- Commit-Messages (falls Git): Amtssprache, Imperativ, erste Zeile ≤ 72 Zeichen, Bezug zum Bereich (`ai/rules: Regel Prüfungsfragen ergänzt`).

## 4. Standards (Verweise)
| Thema | Datei |
|---|---|
| Bash-Scripts | [bash.md](bash.md) |
| Ansible | [ansible.md](ansible.md) |
| Docker-Compose | [docker.md](docker.md) |
| Coding allgemein, Python | [coding.md](coding.md) |
| Markdown, Knowledge-Einträge | [markdown.md](markdown.md) |
| Architektur-Doku, Entscheidungen (ADR) | [architecture.md](architecture.md) |

## 5. AI-Basis verbessern
Agenten **sollen** die Basis besser machen, wenn sie bei der Arbeit Lücken, Widersprüche oder wiederkehrende Muster bemerken.

| Was | Wie |
|---|---|
| Regel fehlt/ist unklar (`rules/`) | **Nicht selbst ändern.** Vorschlag im Chat + Eintrag „Offene Fragen“ in `context.md` |
| Standard verbessern (`common/`) | Ändern, wenn klar besser und rückwärtskompatibel; Eintrag im Änderungsprotokoll der Datei (unten, `TT.MM.JJJJ – was – warum`). Größeres vorher vorschlagen |
| Vorlage/Script (`common/templates/`, `bin/`) | Ändern + lokal testen + `@version` erhöhen; `_functions.sh` in `bin/` und `templates/bash/` synchron halten |
| Kontext/Knowledge | Jederzeit ergänzen/korrigieren, mit `updated` und Quelle |
| Wiederkehrende Frage des Bedieners | Antwort als Knowledge-Eintrag (`howto/`) ablegen |

Verbesserungen, die **allgemein** gelten (nicht nur für dieses Projekt), dem Bediener zur Übernahme ins Skeleton (`~/skel-ai`) vorschlagen.

## 6. Rollen der Agenten
| Agent | Einsatz | Grenzen |
|---|---|---|
| Claude Code | agentisches Coding, Doku | Datenklasse laut `rules/privacy.md` |
| Chat-Dialog | Konzepte, Reviews | kein Dateizugriff → relevante Dateien einfügen lassen |

**Chat-Dialog ohne Dateizugriff:** Der Bediener fügt `AGENTS.md`, die betroffenen `rules/`, den passenden Standard und `context.md` ein. Der Agent liefert vollständige Dateien bzw. Diffs und am Ende einen Block „Für context.md“ zum Einpflegen.

## Änderungsprotokoll
- 07.10.2026 – angelegt (aus skel-ai).
- 23.10.2026 – auf Einzelprojekt reduziert (`context.md` im Root, Rollen festgelegt).