docs
Zweck
Dokumentations-Lebenszyklus-Manager. Generiert die initiale Projektdokumentation, hält die Dokumentation mit Codeänderungen synchron, erstellt API-Referenzen und generiert automatisch Changelogs. Löst das Problem Nummer 1 der Dokumentation: Dokumente, die es gibt, aber veraltet sind.
Auslöser
- Aufgerufen von
scaffoldPhase 7 zur initialen Dokumentationsgenerierung - Aufgerufen von
cooknach Phase 7, um die Dokumentation nach der Feature-Implementierung zu aktualisieren - Aufgerufen von
launchvor dem Deployment, um sicherzustellen, dass die Dokumentation aktuell ist /rune docs init– Erstmalige Dokumentationsgenerierung/rune docs update– Synchronisation der Dokumentation mit aktuellen Codeänderungen/rune docs api– Generierung der API-Dokumentation/rune docs changelog– Automatische Generierung des Changelogs aus der Git-Historie
Aufrufe (ausgehend)
scout(L2): Scannt den Codebestand nach Dokumentationszielen (Routes, Exports, Komponenten, Konfigurationen)doc-processor(L3): Generiert PDF/DOCX-Exporte, falls angefordertgit(L3): Liest die Commit-Historie für die Changelog-Generierung
Aufgerufen von (eingehend)
scaffold(L1): Phase 7 – Generiert initiale Dokumentation für ein neues Projektcook(L1): Nach der Implementierung – Aktualisiert die Dokumentation für geänderte Modulelaunch(L1): Vor dem Deployment – Überprüft, ob die Dokumentation aktuell istmcp-builder(L2): Generiert die MCP-Server-Dokumentation- Benutzer:
/rune docsDirekter Aufruf
Modi
Init-Modus – /rune docs init
Erstmalige Dokumentationsgenerierung für ein Projekt.
Update-Modus – /rune docs update
Inkrementelle Synchronisation – aktualisiert nur die Dokumente, die von aktuellen Codeänderungen betroffen sind.
API-Modus – /rune docs api
Generiert oder aktualisiert gezielt die API-Dokumentation.
Changelog-Modus – /rune docs changelog
Automatische Generierung des Changelogs aus der Git-Commit-Historie.
Ausführbare Schritte
Init-Modus
Schritt 1 – Codebestand scannen
rune:scout aufrufen, um zu extrahieren:
- Projektname, Beschreibung, Tech-Stack
- Verzeichnisstruktur und Schlüsseldateien
- Einstiegspunkte (main, index, app)
- Öffentliche API-Oberfläche (Exports, Routes, Komponenten)
- Konfigurationsdateien (.env.example, Konfigurationsmuster)
- Vorhandene Dokumente (falls vorhanden – zusammenführen, nicht überschreiben)
Schritt 2 – README.md generieren
Struktur:
# [Projektname]
[Einzeilige Beschreibung]
## Schnellstart
[3-5 Befehle zum Starten: installieren, konfigurieren, starten]
## Funktionen
[Liste aus Code extrahiert – Routes, Komponenten, Fähigkeiten]
## Tech-Stack
[Aus package.json, requirements.txt, Cargo.toml usw. erkannt]
## Projektstruktur
[Wichtige Verzeichnisse mit einzeiligen Beschreibungen]
## Konfiguration
[Umgebungsvariablen aus .env.example mit Beschreibungen]
## Entwicklung
[Dev-Server, Test, Lint, Build-Befehle]
## API-Referenz
[Link zu API.md, falls zutreffend, oder Inline-Zusammenfassung]
## Lizenz
[Aus LICENSE-Datei oder package.json erkannt]
Schritt 3 – ARCHITECTURE.md generieren (falls das Projekt 10+ Dateien hat)
Struktur:
# Architektur
## Übersicht
[Systemdiagramm in Text/Mermaid – Komponenten und Datenfluss]
> Der ARCHITEKTUR-Überblick kann `rune:diagramm` für eine gestaltete Systemabbildung (Typ `architektur`) anstelle von rohem Mermaid aufrufen – `suggested_next: diagramm`.
## Wichtige Entscheidungen
[Erkannte Muster: Framework-Wahl, State-Management, DB, Auth-Ansatz]
## Modulzuordnung
[Jedes übergeordnete Verzeichnis: Zweck, Schlüsseldateien, Abhängigkeiten]
## Datenfluss
[Beschreibung des Request-Lebenszyklus oder der Datenpipeline]
Schritt 4 – API.md generieren (falls Routes/Endpunkte erkannt wurden)
Routendateien scannen und extrahieren:
- HTTP-Methode + Pfad
- Request-Parameter (Pfad, Query, Body)
- Antwortstruktur
- Authentifizierungsanforderungen
- Fehlerantworten
Als Markdown-Tabelle oder OpenAPI-kompatible Referenz formatieren.
Schritt 5 – Bericht
Generierte Dokumente dem Benutzer mit einer Zusammenfassung präsentieren:
- Generierte Dateien: [Liste]
- Abdeckung: [Was dokumentiert ist vs. was existiert]
- Lücken: [Codebereiche ohne Dokumentation – nächste Schritte vorschlagen]
Update-Modus
Schritt 1 – Änderungen erkennen
git diff seit der letzten Dokumentationsaktualisierung lesen (verfolgt via Git-Log der Dokumentationsdateien oder .rune/docs-sync.json).
Identifizieren:
- Neue Dateien/Module → neue Dokumentationsabschnitte erforderlich
- Geänderte Funktionen/Routes → Dokumentationsaktualisierungen erforderlich
- Gelöschter Code → Dokumentationsentfernung erforderlich
- Neue Konfiguration → Aktualisierung der Konfigurationsdokumentation erforderlich
Schritt 2 – Betroffene Abschnitte aktualisieren
Für jeden geänderten Bereich:
- Den geänderten Code lesen
- Den entsprechenden Dokumentationsabschnitt finden
- Dokumentation an den aktuellen Code anpassen
- Wenn der Dokumentationsabschnitt nicht existiert → erstellen
- Wenn der Code gelöscht wurde → in der Dokumentation als veraltet markieren oder entfernen
Schritt 3 – Changelog-Eintrag generieren
rune:git changelog beauftragen, einen Changelog-Eintrag aus den Commits seit der letzten Dokumentationsaktualisierung zu erstellen.
Schritt 4 – Dokumentenübergreifender Konsistenzdurchlauf
Dokumentenübergreifende Konsistenz verhindert das zweithäufigste Dokumentationsproblem: Dokumente, die existieren, sich aber widersprechen.
Nach der Aktualisierung eines Dokuments die Konsistenz über die gesamte Projektdokumentation hinweg überprüfen:
| Prüfung | Dateien | Was zu vergleichen ist |
|---|---|---|
| Versionsnummern | README, CLAUDE.md, package.json, CHANGELOG | Müssen alle mit der aktuellen Version übereinstimmen |
| Funktionslisten | README, Landingpage, CLAUDE.md | Gleiche Funktionen aufgeführt (können im Detailgrad variieren) |
| Statistiken | README, CLAUDE.md, Landingpage, Dashboard | Skill-Anzahl, Test-Anzahl, Signal-Anzahl müssen übereinstimmen |
| Befehle | README, CLAUDE.md, docs/ | Gleiche Befehle mit gleichen Flags |
| Tech-Stack | README, ARCHITECTURE.md, CLAUDE.md | Konsistente Framework-/Bibliotheksverweise |
Dokumentenübergreifende Konsistenz:
- [x] README.md ↔ CLAUDE.md: Versionen stimmen überein, Befehle stimmen überein
- [x] README.md ↔ docs/index.html: Statistiken stimmen überein, Funktionen stimmen überein
- [ ] README.md sagt "62 Skills" aber CLAUDE.md sagt "59" → CLAUDE.md KORRIGIEREN
Inkonsistenzen sofort beheben – nicht nur melden. Das veraltete Dokument aktualisieren, um es an die Quelle der Wahrheit anzupassen (normalerweise der Code oder das zuletzt aktualisierte Dokument).
Schritt 5 – Bericht
Dem Benutzer anzeigen: was aktualisiert wurde, was hinzugefügt wurde, was zur Überprüfung markiert wurde. Ergebnisse der dokumentenübergreifenden Konsistenzprüfung einschließen.
API-Modus
Schritt 1 – API-Framework erkennen
| Framework | Routenmuster | Dateimuster |
|---|---|---|
| Express | router.get/post/put/delete | routes/*.ts, *.router.ts |
| FastAPI | @app.get/post/put/delete | routers/*.py, main.py |
| NestJS | @Get/@Post/@Put/@Delete | *.controller.ts |
| Next.js App | export async function GET/POST | app/**/route.ts |
| Next.js Pages | export default function handler | pages/api/**/*.ts |
| SvelteKit | export function GET/POST | src/routes/**/+server.ts |
| Hono | app.get/post/put/delete | src/*.ts |
Schritt 2 – Endpunkte extrahieren
Für jede erkannte Route:
- Methode (GET, POST, PUT, DELETE, PATCH)
- Pfad (mit hervorgehobenen Parametern)
- Request: Parameter, Query, Body-Struktur (aus Zod-Schemas, TypeScript-Typen, Pydantic-Modellen)
- Response: Struktur (aus dem Rückgabetyp oder Response-Helfer)
- Auth: erforderlich? (Middleware wie
authMiddleware,@UseGuardserkennen) - Beschreibung: aus JSDoc/Docstring, falls vorhanden
Schritt 3 – API-Referenz generieren
Als Markdown formatieren:
# API-Referenz
## Authentifizierung
[Beschreibung des Auth-Mechanismus]
## Endpunkte
### `POST /api/auth/login`
**Beschreibung**: Benutzer authentifizieren und Tokens zurückgeben
**Auth**: Keine
**Request-Body**:
| Feld | Typ | Erforderlich | Beschreibung |
|------|-----|--------------|--------------|
| email | string | ja | Benutzer-E-Mail |
| password | string | ja | Benutzer-Passwort |
**Response** (200):
```json
{ "token": "string", "refreshToken": "string" }
Fehler:
- 401: Ungültige Anmeldeinformationen
- 422: Validierungsfehler
#### Schritt 4 – Ausgabe
In `docs/API.md` oder einem projektspezifischen Speicherort speichern. Wenn OpenAPI angefordert wurde, `openapi.yaml` generieren.
### Changelog-Modus
#### Schritt 1 – An Git delegieren
`rune:git changelog` aufrufen, um Commits nach Typ zu gruppieren und im Format "Keep a Changelog" zu formatieren.
#### Schritt 2 – Anreichern
Kontext zum rohen Changelog hinzufügen:
- PR-Nummern mit tatsächlichen Beschreibungen verlinken
- Zusammengehörige Änderungen unter Feature-Überschriften gruppieren
- Breaking Changes deutlich hervorheben
#### Schritt 3 – Ausgabe
An `CHANGELOG.md` anhängen oder diese aktualisieren.
## Ausgabeformat
### Init-Modus-Ausgabe
Generierte Dateien im Projektstammverzeichnis:
- `README.md` – Schnellstart, Funktionen, Tech-Stack, Struktur, Konfiguration, Entwicklungsbefehle
- `ARCHITECTURE.md` – Übersichtsdiagramm, Wichtige Entscheidungen, Modulzuordnung, Datenfluss (falls 10+ Dateien)
- `docs/API.md` – Endpunkt-Referenz mit Methode, Pfad, Parametern, Antwort, Authentifizierung (falls Routen erkannt)
### Update-Modus-Ausgabe
Geänderte Dokumentationsabschnitte mit einer Zusammenfassung der Änderungen:
Dokumentationsaktualisierungsbericht:
- Aktualisiert: [Liste der geänderten Dokumentationsabschnitte]
- Hinzugefügt: [Neue Abschnitte für neuen Code]
- Markiert: [Veraltete Abschnitte, die auf gelöschten Code verweisen]
- Changelog: [Eintrag an CHANGELOG.md angehängt]
### API-Modus-Ausgabe
`docs/API.md` – Markdown-Referenz pro Endpunkt:
METHODE /pfad/:param
Beschreibung: [aus JSDoc/Docstring] Auth: [erforderlich/keine] Request: [Parameter, Query, Body-Tabelle] Response: [Struktur mit Statuscodes] Fehler: [Fehlercodes und Beschreibungen]
### Changelog-Modus-Ausgabe
`CHANGELOG.md` – Format "Keep a Changelog", gruppiert nach: Hinzugefügt, Behoben, Geändert, Entfernt.
## Einschränkungen
1. MUSS Dokumentation aus dem tatsächlichen Code generieren – nie Funktionen oder APIs erfinden, die nicht existieren
2. MUSS vorhandene Dokumentation bewahren – Abschnitte aktualisieren, nicht ganze Dateien überschreiben
3. MUSS Veralterung der Dokumentation erkennen – Abschnitte markieren, die auf gelöschten/geänderten Code verweisen
4. MUSS in jeder README einen Schnellstart enthalten – Benutzer müssen in < 2 Minuten starten können
5. DARF KEINE Dokumentation für Code generieren, der noch nicht existiert (es sei denn, es werden explizit Spezifikationsdokumente erstellt)
6. API-Dokumentation MUSS mit den tatsächlichen Routensignaturen übereinstimmen – falsche API-Dokumentation ist schlimmer als keine
## Rückgaben
| Artefakt | Format | Speicherort |
|----------|--------|-------------|
| README.md | Markdown | Projektstammverzeichnis |
| ARCHITECTURE.md | Markdown | Projektstammverzeichnis (falls 10+ Dateien) |
| API-Referenz | Markdown | `docs/API.md` |
| Changelog-Eintrag | Markdown (Keep a Changelog) | `CHANGELOG.md` |
| Dokumentationsaktualisierungsbericht | Markdown | Inline (Chat-Ausgabe) |
**Scope-Schutzmassnahme:** Dokumentiert nur, was im Codebestand tatsächlich existiert – erfindet niemals Funktionen, Endpunkte oder APIs.
## Problematische Kantenfälle
| Fehlermodus | Schweregrad | Minderungsmaßnahme |
|---|---|---|
| Erfinden nicht existierender API-Endpunkte | KRITISCH | Einschränkung 1: tatsächliche Routendateien scannen, nicht raten |
| Überschreiben benutzergeschriebener README-Abschnitte | HOCH | Einschränkung 2: zusammenführen, nicht überschreiben – benutzerdefinierte Abschnitte erkennen |
| Veraltete Dokumentation nach Codeänderungen | HOCH | Update-Modus erkennt Diffs und aktualisiert betroffene Abschnitte |
| API-Dokumentation mit falschen Request/Response-Strukturen | HOCH | Aus Zod/Pydantic/TypeScript-Typen extrahieren, nicht aus dem Gedächtnis |
| Fehlender Schnellstart-Abschnitt | MITTEL | Einschränkung 4: jede README hat einen Schnellstart |
| Changelog mit verwaisten PR-Links | NIEDRIG | PR-Nummern validieren, bevor sie verlinkt werden |
| Dokumentenübergreifende Inkonsistenz (README sagt X, CLAUDE.md sagt Y) | HOCH | Schritt 7: Dokumentenübergreifender Konsistenzdurchlauf – Statistiken, Versionen und Funktionslisten über alle Dokumente hinweg überprüfen |
| Aktualisieren eines Dokuments, aber nicht anderer (Statistik-Drift) | HOCH | Nach jeder Dokumentationsaktualisierung alle verwandten Dokumente auf veraltete Statistiken prüfen – besonders README ↔ CLAUDE.md ↔ Landingpage |
## Abgeschlossen, wenn
### Init-Modus
- Codebestand mit Scout gescannt
- README.md mit Schnellstart, Funktionen, Tech-Stack, Struktur generiert
- ARCHITECTURE.md generiert (falls 10+ Dateien)
- API.md generiert (falls Routen erkannt)
- Abdeckungsbericht dem Benutzer präsentiert
### Update-Modus
- Änderungen seit der letzten Dokumentationsaktualisierung erkannt
- Betroffene Dokumentationsabschnitte aktualisiert
- Changelog-Eintrag generiert
- Aktualisierungsbericht dem Benutzer präsentiert
### API-Modus
- API-Framework erkannt
- Alle Endpunkte mit Methode, Pfad, Request, Response extrahiert
- API-Referenz in Markdown generiert
- In docs/API.md gespeichert
### Changelog-Modus
- Commits nach Typ gruppiert
- Als "Keep a Changelog" formatiert
- CHANGELOG.md aktualisiert
## Kostenprofil
~2000–5000 Tokens Eingabe, ~1000–3000 Tokens Ausgabe. Sonnet – Dokumentation erfordert das Verständnis von Codemustern, aber keine tiefgehende architektonische Argumentation.