10 KiB
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/hilfe/seiten/). 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 — 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
## 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
releaseuntersynonymsmitgeht oder im Eintrag unter „Auch gesucht als" steht. Im Zweifellistfür den Überblick. forgetlegt 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 mitremembersind trotzdem der bessere Weg: Die vorherige Fassung bleibt im Verlauf (Weboberfläche → Verlauf ansehen), und der Eintrag bleibt auffindbar.rememberauf 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.