260 lines
10 KiB
Markdown
260 lines
10 KiB
Markdown
# Agenten anbinden
|
||
|
||
Wie man KI-Werkzeuge so einrichtet und anspricht, dass sie den Munin
|
||
tatsächlich benutzen.
|
||
|
||
> Dieselben Inhalte stehen für Nutzer auch in der Weboberfläche unter
|
||
> `/hilfe/mit-agenten-arbeiten` (Quelle: `internal/help/pages/`). Wer hier
|
||
> etwas ändert, sollte dort nachziehen.
|
||
|
||
---
|
||
|
||
## 1. Verbinden
|
||
|
||
Key erzeugen unter `/p/<projekt>/keys`. Der Klartext wird genau einmal angezeigt.
|
||
|
||
Die fertigen Konfigurationsblöcke für **Claude Code**, **Cline** und **OpenCode**
|
||
stehen im [README](README.md#mcp-einrichten) — dort auch, worin sich die drei
|
||
Dateien unterscheiden. Kurzfassung:
|
||
|
||
| Client | Datei | Schlüssel | `type` |
|
||
|---|---|---|---|
|
||
| Claude Code | `.mcp.json` | `mcpServers` | `http` |
|
||
| Cline | `cline_mcp_settings.json` | `mcpServers` | `streamableHttp` |
|
||
| OpenCode | `opencode.json` | `mcp` | `remote` |
|
||
|
||
Ein Server je Projekt. Der Key bestimmt das Projekt — kein weiterer Parameter nötig.
|
||
|
||
**Ein Key je Person und je Agent.** Der Key-Name landet als Autor an jedem Eintrag
|
||
und im Protokoll.
|
||
|
||
---
|
||
|
||
## 2. Werkzeuge
|
||
|
||
| Werkzeug | Parameter | Rolle |
|
||
|---|---|---|
|
||
| `recall` | `query`, `synonyms?`, `tags?`, `limit?` | read |
|
||
| `get` | `slug` | read |
|
||
| `list` | `tag?`, `curated?`, `limit?` | read |
|
||
| `related` | `slug`, `distance?`, `limit?` | read |
|
||
| `remember` | `title`, `content`, `slug?`, `tags?`, `expected_version?`, `force?`, `override_curated?`, `reason?` | write |
|
||
| `forget` | `slug` | write |
|
||
|
||
---
|
||
|
||
## 3. Das eigentliche Problem
|
||
|
||
Der Server schickt jedem Client eine Anleitung mit (`instructions`). Viele Clients
|
||
gewichten sie schwach oder ignorieren sie. **Ohne eigene Anweisung im Projekt-
|
||
oder Systemprompt greift ein Agent selten von selbst zum Werkzeug** — er antwortet
|
||
lieber aus seinem eigenen Wissen.
|
||
|
||
Deshalb der folgende Block.
|
||
|
||
---
|
||
|
||
## 4. Projektprompt
|
||
|
||
### Wohin der Block gehört
|
||
|
||
| Werkzeug | im Projekt | persönlich, für alle Projekte |
|
||
|---|---|---|
|
||
| OpenCode | `AGENTS.md` (ersatzweise `CLAUDE.md`) | `~/.config/opencode/AGENTS.md` |
|
||
| Cline | `AGENTS.md` oder `.clinerules/` | `~/Documents/Cline/Rules/` |
|
||
| Claude Code | `CLAUDE.md` | `~/.claude/CLAUDE.md` |
|
||
| eigene Anwendung | Systemprompt | |
|
||
|
||
**Mehrere Werkzeuge im Team:** Den Block in **eine** `AGENTS.md` im
|
||
Projektverzeichnis schreiben. OpenCode und Cline lesen sie direkt. Claude Code
|
||
liest `AGENTS.md` nur, wenn es keine `CLAUDE.md` gibt (und erst in neueren
|
||
Fassungen). Sicher ist deshalb: in die `CLAUDE.md` die Zeile `@AGENTS.md`
|
||
schreiben, gegebenenfalls als einzige Zeile. So steht der Block an genau einer
|
||
Stelle und läuft nicht auseinander.
|
||
|
||
**Persönlich statt im Projekt:** Ist Munin global eingerichtet (Claude Code mit
|
||
`--scope user`, OpenCode in `~/.config/opencode/opencode.json`), passt der Block
|
||
auch in die persönliche Datei. Dann gilt er überall, ohne dass jedes Repository
|
||
ihn braucht.
|
||
|
||
### Der Block
|
||
|
||
```markdown
|
||
## Munin
|
||
|
||
Für dieses Projekt gibt es einen Munin über MCP (Werkzeuge: recall,
|
||
get, list, related, remember, forget). Er ist das gemeinsame Gedächtnis des Teams.
|
||
|
||
LESEN — vor jeder Antwort zu projektspezifischen Fragen:
|
||
- Zuerst `recall` mit der Frage aufrufen, nicht mit Stichworten. Unter
|
||
`synonyms` weitere Namen für das Thema mitgeben (Synonyme, Übersetzung,
|
||
Abkürzungen) — die Suche vergleicht Wörter, keine Bedeutungen.
|
||
- Findet `recall` nichts, mit anderen Begriffen erneut suchen.
|
||
- Passenden Treffer mit `get` vollständig laden.
|
||
- Für mehr Kontext mit `related` die verknüpften Einträge ansehen.
|
||
- Einträge mit `"stale": true` sind über ein Jahr alt: vor Verwendung prüfen
|
||
und in der Antwort erwähnen, dass der Stand alt ist.
|
||
- Erst wenn nichts Passendes da ist, aus eigenem Wissen antworten — und das
|
||
kenntlich machen.
|
||
- Nie raten, wenn es um Prozesse, Zugänge oder Entscheidungen dieses Teams geht.
|
||
|
||
SCHREIBEN — sobald etwas festgehalten werden sollte:
|
||
- IMMER zuerst `recall`, ob es zum Thema schon einen Eintrag gibt.
|
||
- Gibt es einen: mit DESSEN slug `remember` aufrufen. Das aktualisiert ihn.
|
||
- Nur wenn wirklich nichts passt, einen neuen slug wählen.
|
||
- Meldet `remember` `judgment_required`, die `candidates` prüfen: Passt einer,
|
||
ihn fortschreiben. Nur bei wirklich anderem Thema mit `force: true` anlegen.
|
||
- Einträge mit `"curated": true` hat ein Mensch geprüft: Sie haben Vorrang.
|
||
Nur ändern, wenn sie nachweislich nicht mehr stimmen — dann mit
|
||
`override_curated: true` und einer Begründung unter `reason`.
|
||
- Vor dem Aktualisieren `get` aufrufen und die gelieferte `version` als
|
||
`expected_version` mitgeben.
|
||
|
||
WAS festgehalten wird:
|
||
- Entscheidungen mit Begründung
|
||
- Abläufe, die sich wiederholen
|
||
- Lösungen für Probleme, die länger gedauert haben
|
||
- Nicht: Zwischenstände, Diskussionsverlauf, was im Code steht
|
||
|
||
WIE festgehalten wird:
|
||
- Destilliert, nicht als Protokoll. Ein Eintrag beantwortet eine Frage.
|
||
- Verwandtes mit [[bezeichner]] verknüpfen.
|
||
- Am Ende eine Zeile `Auch gesucht als: …` mit 2–5 Begriffen, die nicht im
|
||
Text stehen, unter denen man den Eintrag aber suchen würde.
|
||
- Schlagworte sparsam: 1–3 aus dem bestehenden Bestand (`list` zeigt sie).
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Bezeichner (slug)
|
||
|
||
Der slug ist der Schlüssel gegen Dubletten: gleicher slug = Aktualisierung.
|
||
|
||
| gut | schlecht | warum |
|
||
|---|---|---|
|
||
| `deployment-prozess` | `notiz-2026-01-15` | Datum ist kein Thema |
|
||
| `fehler-zugriff-verweigert` | `problem-3` | nicht wiederfindbar |
|
||
| `entscheidung-sqlite` | `sqlite-entscheidung-final-v2` | Fassungen zählt das System |
|
||
|
||
Regeln: `a-z`, `0-9`, `-`, `_`. Kurz, sprechend, dauerhaft. Ohne Angabe wird er
|
||
aus dem Titel abgeleitet.
|
||
|
||
---
|
||
|
||
## 6. Muster für einzelne Aufgaben
|
||
|
||
**Nachschlagen**
|
||
|
||
```
|
||
Wie läuft bei uns das Deployment? Schau zuerst im Munin nach.
|
||
```
|
||
|
||
**Festhalten nach getaner Arbeit**
|
||
|
||
```
|
||
Halte fest, was wir über den abgelaufenen Token herausgefunden haben.
|
||
Prüfe vorher mit recall, ob es dazu schon einen Eintrag gibt — dann
|
||
ergänze diesen, statt einen neuen anzulegen.
|
||
```
|
||
|
||
**Bestand aufräumen**
|
||
|
||
```
|
||
Rufe list auf und nenne mir Einträge, die dasselbe Thema doppelt behandeln.
|
||
Nichts ändern, nur auflisten.
|
||
```
|
||
|
||
**Einarbeiten**
|
||
|
||
```
|
||
Verschaffe dir mit list und recall einen Überblick über den Munin
|
||
und fasse zusammen, was dieses Team über Betrieb und Deployment festgehalten hat.
|
||
```
|
||
|
||
**Vorhandenes fortschreiben**
|
||
|
||
```
|
||
Lies deployment-prozess mit get, ergänze den Schritt mit dem Rollback und
|
||
schreibe zurück — mit expected_version aus dem get.
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Was Dubletten erzeugt
|
||
|
||
| Ursache | Gegenmittel |
|
||
|---|---|
|
||
| Agent schreibt ohne vorher zu suchen | „IMMER zuerst recall" im Projektprompt |
|
||
| Neuer slug für vorhandenes Thema | slug-Regeln oben; `recall` liefert den vorhandenen |
|
||
| Zeitstempel im slug | verbieten — Fassungen zählt das System |
|
||
| Jede Erkenntnis als eigener Eintrag | „Ein Eintrag beantwortet eine Frage" |
|
||
| Thema unter anderem Namen gesucht, nichts gefunden | `synonyms` bei `recall`, „Auch gesucht als" im Eintrag |
|
||
|
||
Als letzte Hürde prüft `remember` beim Anlegen, ob es schon einen Eintrag mit
|
||
ähnlichem Titel gibt, und fragt dann nach (`judgment_required` mit
|
||
`candidates`). Jeder Kandidat nennt die gemeinsamen Wörter (`matched_words`);
|
||
steht dort nur ein allgemeines Wort, ist es meist ein anderes Thema. Erst
|
||
`force: true` legt trotzdem an. Es übergeht nur diese Rückfrage — kuratierte
|
||
Einträge, `expected_version` und Schreibbudget gelten weiter.
|
||
|
||
---
|
||
|
||
## 8. Prüfen, ob es wirkt
|
||
|
||
**Protokoll:** `/p/<projekt>/audit` — jeder Schreibvorgang mit Zugang und Zeit.
|
||
|
||
**Nutzung:** `/p/<projekt>/usage` — Schreibvorgänge der letzten 30 Tage
|
||
(angelegt/aktualisiert), *Zur Prüfung* (kuratierte Einträge, die ein Agent
|
||
geändert hat), Suchen der Agenten (Anteil ohne Treffer, Anteil mit Synonymen,
|
||
häufigste Anfragen ohne Treffer), Verweise ins Leere.
|
||
|
||
**Faustregel:** Nach ein paar Wochen sollte das Verhältnis von Aktualisierungen zu
|
||
Neuanlagen steigen. Viele Neuanlagen bei ähnlichen Themen heißt: Der Projektprompt
|
||
greift nicht. Ein niedriger Anteil an Suchen mit Synonymen heißt dasselbe für
|
||
die Suche.
|
||
|
||
**In der Oberfläche:** Einträge mit Herkunft „Agent" und ohne Marke „kuratiert"
|
||
sind ungeprüfte Beobachtungen. Wer sie durchsieht und bestätigt, setzt den Haken
|
||
„Kuratiert" — Agenten sehen das Feld über `recall` und `get`.
|
||
|
||
**Was „kuratiert" bewirkt:** Kuratierte Einträge stehen in der Suche bei sonst
|
||
gleicher Relevanz weiter vorn (Faktor 1,2). Ein Agent kann sie nicht nebenbei
|
||
überschreiben: `remember` meldet erst `judgment_required`, geschrieben wird nur
|
||
mit `override_curated: true` und einer Begründung (`reason`). Dabei fällt der
|
||
Haken weg, und der Eintrag steht auf der Nutzungsseite unter *Zur Prüfung*, bis
|
||
ein Mensch ihn wieder kuratiert.
|
||
|
||
---
|
||
|
||
## 9. Rollen
|
||
|
||
| Rolle | darf | wofür |
|
||
|---|---|---|
|
||
| `read` | recall, get, list, related | Agenten, die nur auskunftsfähig sein sollen |
|
||
| `write` | zusätzlich remember, forget | der Normalfall |
|
||
| `admin` | zusätzlich Zugänge verwalten | Menschen |
|
||
|
||
Ein Agent, der ohne Aufsicht läuft, bekommt `read`. Schreibrecht dort, wo jemand
|
||
die Einträge auch durchsieht.
|
||
|
||
---
|
||
|
||
## 10. Grenzen
|
||
|
||
- **Suche ist wortbasiert.** Sie gleicht Wortanfänge, Endungen und
|
||
zusammengesetzte Wörter aus („deployen" findet „Deployment", „prozess" findet
|
||
„Releaseprozess"), aber keine Bedeutungen: „wie deployen wir" findet
|
||
„Release-Prozess" nur, wenn `release` unter `synonyms` mitgeht oder im Eintrag
|
||
unter „Auch gesucht als" steht. Im Zweifel `list` für den Überblick.
|
||
- **`forget` legt in den Papierkorb.** Der Eintrag ist für Agenten sofort
|
||
unsichtbar, ein Mensch kann ihn 30 Tage lang in der Weboberfläche
|
||
zurückholen. Agenten können weder wiederherstellen noch den Papierkorb
|
||
leeren. Änderungen mit `remember` sind trotzdem der bessere Weg: Die
|
||
vorherige Fassung bleibt im Verlauf (Weboberfläche → *Verlauf ansehen*),
|
||
und der Eintrag bleibt auffindbar.
|
||
- **`remember` auf einen Bezeichner im Papierkorb** holt den Eintrag zurück
|
||
und überschreibt ihn; der gelöschte Stand wandert in den Verlauf. Die
|
||
Antwort sagt das ausdrücklich.
|
||
- **Was drinsteht, landet im Kontext aller.** Wer schreiben darf, schreibt
|
||
indirekt in die Prompts der anderen — Herkunft und Autor stehen deshalb an
|
||
jedem Eintrag.
|