cf35c3f5db
- 3.7: MCP-Werkzeug "related" liefert Nachbarn im Verweisgraphen in beide
Richtungen, bis zur zweiten Reihe (store.RelatedEntries).
- 3.5: Einträge, die seit über einem Jahr unverändert sind, tragen in
recall/get/list/related "stale": true; get und recall geben einen
Hinweis, die Eintragsseite eine Marke. instructions erklären das Feld.
- 3.2: Import von Markdown-Dateien als ZIP unter /p/{projekt}/import
(Rolle admin), mit Vorschau, überspringen/überschreiben, Erkennung von
Unverändertem und Papierkorb. Neue Einträge behalten Autor, Herkunft,
Prüfvermerk und Zeitstempel aus dem Export.
Nebenbei behoben: Das 1-MB-Body-Limit für Formulare lag über dem ganzen
Mux und begrenzte damit auch /mcp auf 1 MB statt MAX_API_BODY_BYTES.
LimitBodies wählt die Grenze jetzt einmal außen je Route.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
155 lines
6.1 KiB
Markdown
155 lines
6.1 KiB
Markdown
## Das eigentliche Problem
|
||
|
||
Munin schickt jedem Werkzeug eine kurze Gebrauchsanleitung mit. Viele Werkzeuge
|
||
gewichten sie aber schwach. **Ohne eigene Anweisung antwortet ein Agent lieber
|
||
aus seinem eigenen Wissen**, statt im Gedächtnis nachzusehen, und schreibt
|
||
Neues, ohne vorher zu suchen.
|
||
|
||
Abhilfe schafft ein kurzer Block im Projekt- oder Systemprompt.
|
||
|
||
## Der Projektprompt
|
||
|
||
In `CLAUDE.md`, `.clinerules`, *Custom Instructions* oder den Systemprompt
|
||
deiner Anwendung übernehmen:
|
||
|
||
```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.
|
||
- 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.
|
||
- 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.
|
||
- Schlagworte sparsam: 1–3 aus dem bestehenden Bestand (`list` zeigt sie).
|
||
```
|
||
|
||
## Die Werkzeuge
|
||
|
||
| Werkzeug | Rolle | Wofür |
|
||
|---|---|---|
|
||
| `recall` | read | Suchen. Der wichtigste Einstieg, auch vor dem Schreiben. |
|
||
| `get` | read | Einen Eintrag vollständig laden, mit Verweisen und Fassungsnummer. |
|
||
| `list` | read | Überblick: zuletzt geänderte Einträge und alle Schlagworte. |
|
||
| `related` | read | Verknüpfte Einträge finden, auch solche, die die Suche nicht trifft. |
|
||
| `remember` | write | Einen Eintrag anlegen oder aktualisieren. |
|
||
| `forget` | write | Einen Eintrag in den Papierkorb legen. |
|
||
|
||
## Gute Bezeichner
|
||
|
||
Der Bezeichner entscheidet, ob ein Eintrag aktualisiert oder neu angelegt wird.
|
||
|
||
| Gut | Schlecht | Warum |
|
||
|---|---|---|
|
||
| `deployment-prozess` | `notiz-2026-01-15` | Ein Datum ist kein Thema. |
|
||
| `fehler-zugriff-verweigert` | `problem-3` | Nicht wiederzufinden. |
|
||
| `entscheidung-sqlite` | `sqlite-entscheidung-final-v2` | Fassungen zählt das System selbst. |
|
||
|
||
Kurz, sprechend und dauerhaft. Ohne Angabe wird der Bezeichner aus dem Titel
|
||
abgeleitet.
|
||
|
||
## Muster für den Alltag
|
||
|
||
**Nachschlagen**
|
||
|
||
```
|
||
Wie läuft bei uns das Deployment? Schau zuerst im Munin nach.
|
||
```
|
||
|
||
**Nach getaner Arbeit festhalten**
|
||
|
||
```
|
||
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.
|
||
```
|
||
|
||
**Vorhandenes fortschreiben**
|
||
|
||
```
|
||
Lies deployment-prozess mit get, ergänze den Schritt mit dem Rollback und
|
||
schreibe zurück — mit expected_version aus dem get.
|
||
```
|
||
|
||
**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.
|
||
```
|
||
|
||
## Wenn zwei gleichzeitig schreiben
|
||
|
||
`get` liefert eine Fassungsnummer (`version`). Gibt ein Agent sie beim
|
||
Schreiben als `expected_version` mit, lehnt Munin die Änderung ab, falls
|
||
inzwischen jemand anderes den Eintrag geändert hat. Der Agent lädt dann neu und
|
||
führt beides zusammen. Ohne diese Angabe würde die fremde Änderung einfach
|
||
überschrieben. Sie wäre zwar im Verlauf noch zu finden, aber niemand würde es
|
||
merken.
|
||
|
||
## Grenzen, die man kennen sollte
|
||
|
||
- **Die Suche ist wortbasiert.** „Wie deployen wir“ findet „Release-Prozess“
|
||
nicht. Im Zweifel hilft `list` für den Überblick.
|
||
- **`forget` legt in den Papierkorb.** Der Eintrag ist für alle Agenten sofort
|
||
weg, lässt sich aber 30 Tage lang von einem Menschen zurückholen. Agenten
|
||
selbst können nichts wiederherstellen und den Papierkorb nicht leeren.
|
||
Veraltetes trotzdem besser mit `remember` richtigstellen: Dann bleibt der
|
||
Eintrag auffindbar, und der Verlauf zeigt, was sich geändert hat.
|
||
- **Schreibt ein Agent unter einem Bezeichner, der im Papierkorb liegt**, holt
|
||
er den Eintrag zurück und überschreibt ihn. Der gelöschte Stand steht danach
|
||
im Verlauf, und die Antwort an den Agenten sagt, was passiert ist.
|
||
- **Was drinsteht, landet im Kontext aller Agenten des Projekts.** Wer schreiben
|
||
darf, schreibt damit indirekt in deren Prompts. Deshalb stehen Herkunft und
|
||
Autor an jedem Eintrag.
|
||
|
||
## Prüfen, ob es wirkt
|
||
|
||
Die Seite **Nutzung** in der Seitenleiste zählt die Schreibvorgänge der letzten
|
||
30 Tage, getrennt nach Agenten und Menschen und nach „neu angelegt“ und
|
||
„aktualisiert“. Der wichtigste Wert steht darunter: welcher Anteil der
|
||
Schreibvorgänge einen vorhandenen Eintrag fortgeschrieben hat.
|
||
|
||
Am Anfang legen Teams naturgemäß vor allem an. Nach ein paar Wochen sollte der
|
||
Anteil der Aktualisierungen steigen. Viele Neuanlagen zu ähnlichen Themen
|
||
bedeuten: Der Projektprompt greift nicht.
|
||
|
||
Außerdem zeigt die Seite:
|
||
|
||
- **Verweise ins Leere:** Bezeichner, auf die mit `[[…]]` verwiesen wird, ohne
|
||
dass es den Eintrag gibt. Die meistgenannten sind gute Kandidaten für den
|
||
nächsten Eintrag; mit Schreibrecht führt *anlegen* direkt dorthin.
|
||
- **Einträge ohne Schlagwort**, zum Nachtragen mit der Sammelbearbeitung.
|
||
- **Zuletzt aktive Zugänge**, um zu sehen, welche Agenten wirklich arbeiten.
|
||
|
||
Einzelne Vorgänge mit Zugang und Zeit stehen unter *Protokoll*.
|