Code-Dokumentations-Skill
Übersicht
Dieser Skill generiert professionelle, umfassende Dokumentation für Softwareprojekte, Codebasen, Bibliotheken und APIs. Er folgt den Best Practices von Projekten wie React, Django, Stripe und Kubernetes, um eine genaue, gut strukturierte und sowohl für neue Mitwirkende als auch für erfahrene Entwickler nützliche Dokumentation zu erstellen.
Die Ausgabe reicht von einzelnen README-Dateien bis hin zu mehrteiligen Entwicklerleitfäden, die stets an die Komplexität des Projekts und die Bedürfnisse des Benutzers angepasst wird.
Kernfunktionen
- Erstellen umfassender README.md-Dateien mit Badges, Installation, Nutzung und API-Referenz
- Erstellung von API-Referenzdokumentation durch Quellcode-Analyse
- Erstellung von Architektur- und Design-Dokumentation mit Diagrammen
- Erstellung von Entwickler-Onboarding- und Beitragsleitfäden
- Generierung von Changelogs aus Commit-Verläufen oder Versionshinweisen
- Erstellung von Inline-Code-Dokumentation gemäß sprachspezifischer Konventionen
- Unterstützung von JSDoc, Docstrings, GoDoc, Javadoc und Rustdoc-Formaten
- Anpassung des Dokumentationsstils an die Sprache und das Ökosystem des Projekts
Wann dieser Skill verwendet werden sollte
Diesen Skill immer laden, wenn:
- Der Benutzer darum bittet, Code zu "dokumentieren", "Dokumente zu erstellen" oder "Dokumentation zu schreiben"
- Der Benutzer eine README, API-Referenz oder einen Entwicklerleitfaden anfordert
- Der Benutzer eine Codebasis oder ein Repository teilt und eine Dokumentation wünscht
- Der Benutzer darum bittet, bestehende Dokumentation zu verbessern oder zu aktualisieren
- Der Benutzer Architektur-Dokumentation einschließlich Diagrammen benötigt
- Der Benutzer ein Changelog oder einen Migrationsleitfaden anfordert
Dokumentations-Workflow
Phase 1: Codebasis-Analyse
Bevor Dokumentation geschrieben wird, muss die Codebasis gründlich verstanden werden.
Schritt 1.1: Projekt-Erkennung
Identifiziere die Projektgrundlagen:
| Feld | Ermittlungsmethode |
|---|---|
| Sprache(n) | Dateierweiterungen, package.json, pyproject.toml, go.mod, Cargo.toml usw. prüfen |
| Framework | Abhängigkeiten auf bekannte Frameworks prüfen (React, Django, Express, Spring usw.) |
| Build-System | Nach Makefile, CMakeLists.txt, webpack.config.js, build.gradle usw. suchen |
| Paketmanager | npm/yarn/pnpm, pip/uv/poetry, cargo, go modules usw. |
| Projektstruktur | Verzeichnisbaum kartieren, um die Architektur zu verstehen |
| Einstiegspunkte | Hauptdateien, CLI-Einstiegspunkte, exportierte Module finden |
| Vorhandene Dokus | Nach vorhandenen READMEs, docs/, Wiki oder Inline-Dokumentation suchen |
Schritt 1.2: Codestruktur-Analyse
Verwende Sandbox-Tools, um die Codebasis zu erkunden:
# Verzeichnisstruktur abrufen
ls /mnt/user-data/uploads/projekt-verzeichnis/
# Schlüsseldateien lesen
read_file /mnt/user-data/uploads/projekt-verzeichnis/package.json
read_file /mnt/user-data/uploads/projekt-verzeichnis/pyproject.toml
# Nach öffentlichen API-Oberflächen suchen
grep -r "export " /mnt/user-data/uploads/projekt-verzeichnis/src/
grep -r "def " /mnt/user-data/uploads/projekt-verzeichnis/src/ --include="*.py"
grep -r "func " /mnt/user-data/uploads/projekt-verzeichnis/ --include="*.go"
Schritt 1.3: Dokumentationsumfang festlegen
Basierend auf der Analyse festlegen, welche Dokumentation erstellt werden soll:
| Projektgröße | Empfohlene Dokumentation |
|---|---|
| Einzeldatei / Skript | Inline-Kommentare + Nutzungskopf |
| Kleine Bibliothek | README mit API-Referenz |
| Mittleres Projekt | README + API-Dokumente + Beispiele |
| Großes Projekt | README + Architektur + API + Mitwirken + Changelog |
Phase 2: Dokumentations-Generierung
Schritt 2.1: README-Generierung
Jedes Projekt braucht eine README. Dieser Struktur folgen:
# Projektname
[Einzeilige Projektbeschreibung – was es tut und warum es wichtig ist]
[](#) [](#)
## Funktionen
- [Hauptfunktion 1 – kurze Beschreibung]
- [Hauptfunktion 2 – kurze Beschreibung]
- [Hauptfunktion 3 – kurze Beschreibung]
## Schnellstart
### Voraussetzungen
- [Voraussetzung 1 mit Versionsanforderung]
- [Voraussetzung 2 mit Versionsanforderung]
### Installation
[Installationsbefehle mit kopierfertigen Codeblöcken]
### Grundlegende Nutzung
[Minimales Arbeitsbeispiel, das die Kernfunktionalität demonstriert]
## Dokumentation
- [Link zur vollständigen API-Referenz, falls separat]
- [Link zu Architektur-Dokumenten, falls separat]
- [Link zum Beispiele-Verzeichnis, falls vorhanden]
## API-Referenz
[Inline-API-Referenz für kleinere Projekte ODER Link zu generierten Dokumenten]
## Konfiguration
[Umgebungsvariablen, Konfigurationsdateien oder Laufzeitoptionen]
## Beispiele
[2-3 praktische Beispiele, die typische Anwendungsfälle abdecken]
## Entwicklung
### Einrichtung
[Wie eine Entwicklungsumgebung eingerichtet wird]
### Testen
[Wie Tests ausgeführt werden]
### Build
[Wie das Projekt gebaut wird]
## Mitwirken
[Richtlinien zum Mitwirken oder Link zur CONTRIBUTING.md]
## Lizenz
[Lizenzinformationen]
Schritt 2.2: API-Referenz-Generierung
Für jede öffentliche API-Oberfläche dokumentieren:
Funktions- / Methoden-Dokumentation:
### `functionName(param1, param2, options?)`
Kurze Beschreibung, was diese Funktion tut.
**Parameter:**
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|-----------|------|----------|---------|-------------|
| `param1` | `string` | Ja | — | Beschreibung von param1 |
| `param2` | `number` | Ja | — | Beschreibung von param2 |
| `options` | `Object` | Nein | `{}` | Konfigurationsoptionen |
| `options.timeout` | `number` | Nein | `5000` | Timeout in Millisekunden |
**Rückgabewert:** `Promise<Result>` — Beschreibung des Rückgabewerts
**Wirft:**
- `ValidationError` — Wenn param1 leer ist
- `TimeoutError` — Wenn der Vorgang das Timeout überschreitet
**Beispiel:**
```javascript
const result = await functionName("hallo", 42, { timeout: 10000 });
console.log(result.data);
**Klassen-Dokumentation**:
```markdown
### `ClassName`
Kurze Beschreibung der Klasse und ihres Zwecks.
**Konstruktor:**
```javascript
new ClassName(konfiguration)
| Parameter | Typ | Beschreibung |
|---|---|---|
konfiguration.option1 | string | Beschreibung |
konfiguration.option2 | boolean | Beschreibung |
Methoden:
method1()— Kurze Beschreibungmethod2(param)— Kurze Beschreibung
Eigenschaften:
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
eigenschaft1 | string | Beschreibung |
eigenschaft2 | number | Schreibgeschützt. Beschreibung |
#### Schritt 2.3: Architektur-Dokumentation
Für mittelgroße bis große Projekte Architektur-Dokumentation einfügen:
```markdown
# Architektur-Übersicht
## Systemdiagramm
[Mermaid-Diagramm, das die hochrangige Architektur zeigt, einfügen]
```mermaid
graph TD
A[Client] --> B[API-Gateway]
B --> C[Dienst A]
B --> D[Dienst B]
C --> E[(Datenbank)]
D --> E
Komponenten-Übersicht
Komponentenname
- Zweck: Was diese Komponente tut
- Ort:
src/components/name/ - Abhängigkeiten: Wovon sie abhängt
- Öffentliche API: Wichtige Exporte oder Schnittstellen
Datenfluss
[Beschreiben, wie Daten für Schlüsseloperationen durch das System fließen]
Design-Entscheidungen
Entscheidungstitel
- Kontext: Welche Situation führte zu dieser Entscheidung
- Entscheidung: Was wurde entschieden
- Begründung: Warum dieser Ansatz gewählt wurde
- Kompromisse: Was wurde geopfert
#### Schritt 2.4: Inline-Code-Dokumentation
Sprachangepasste Inline-Dokumentation generieren:
**Python (Docstrings — Google-Stil)**:
```python
def process_data(input_path: str, options: dict | None = None) -> ProcessResult:
"""Verarbeitet Daten aus dem angegebenen Dateipfad.
Liest die Eingabedatei, wendet Transformationen basierend auf den
bereitgestellten Optionen an und gibt ein strukturiertes Ergebnisobjekt zurück.
Args:
input_path: Absoluter Pfad zur Eingabedatendatei.
Unterstützt CSV-, JSON- und Parquet-Formate.
options: Optionales Konfigurationswörterbuch.
- "validate" (bool): Eingabevalidierung aktivieren. Standardwert: True.
- "format" (str): Ausgabeformat ("json" oder "csv"). Standardwert: "json".
Returns:
Ein ProcessResult mit den transformierten Daten und Metadaten.
Raises:
FileNotFoundError: Wenn input_path nicht existiert.
ValidationError: Wenn die Validierung aktiviert ist und die Daten fehlerhaft sind.
Example:
>>> result = process_data("/data/input.csv", {"validate": True})
>>> print(result.row_count)
1500
"""
TypeScript (JSDoc / TSDoc):
/**
* Ruft Benutzerdaten von der API ab und transformiert sie für die Anzeige.
*
* @param userId - Die eindeutige Kennung des Benutzers
* @param options - Konfigurationsoptionen für den Abrufvorgang
* @param options.includeProfile - Ob das vollständige Profil eingeschlossen werden soll. Standardwert: `false`.
* @param options.cache - Cache-Dauer in Sekunden. Auf `0` setzen, um zu deaktivieren.
* @returns Die transformierten Benutzerdaten, bereit zum Rendern
* @throws {NotFoundError} Wenn die Benutzer-ID nicht existiert
* @throws {NetworkError} Wenn die API nicht erreichbar ist
*
* @example
* ```ts
* const user = await fetchUser("usr_123", { includeProfile: true });
* console.log(user.displayName);
* ```
*/
Go (GoDoc):
// ProcessData liest die Eingabedatei am angegebenen Pfad, wendet die angegebenen
// Transformationen an und gibt das verarbeitete Ergebnis zurück.
//
// Der Eingabepfad muss ein absoluter Pfad zu einer CSV- oder JSON-Datei sein.
// Wenn options nil ist, werden Standardoptionen verwendet.
//
// ProcessData gibt einen Fehler zurück, wenn die Datei nicht existiert oder nicht analysiert werden kann.
func ProcessData(inputPath string, options *ProcessOptions) (*Result, error) {
Phase 3: Qualitätssicherung
Schritt 3.1: Vollständigkeitsprüfung der Dokumentation
Überprüfen, ob die Dokumentation Folgendes abdeckt:
- Was es ist — Klare Projektbeschreibung, die ein Neuling verstehen kann
- Warum es existiert — Problem, das es löst, und Wertversprechen
- Wie zu installieren — Kopierfertige Installationsbefehle
- Wie zu verwenden — Mindestens ein minimales Arbeitsbeispiel
- API-Oberfläche — Alle öffentlichen Funktionen, Klassen und Typen dokumentiert
- Konfiguration — Alle Umgebungsvariablen, Konfigurationsdateien und Optionen
- Fehlerbehandlung — Häufige Fehler und wie sie behoben werden
- Mitwirken — Wie die Entwicklungsumgebung eingerichtet und Änderungen eingereicht werden
Schritt 3.2: Qualitätsstandards
| Standard | Prüfung |
|---|---|
| Genauigkeit | Jedes Codebeispiel muss mit der beschriebenen API tatsächlich funktionieren |
| Vollständigkeit | Keine öffentliche API-Oberfläche undokumentiert lassen |
| Konsistenz | Gleiche Formatierung und Struktur durchgängig |
| Aktualität | Dokumentation entspricht dem aktuellen Code, nicht einer älteren Version |
| Zugänglichkeit | Kein Fachjargon ohne Erklärung, Akronyme bei erster Verwendung definiert |
| Beispiele | Jedes komplexe Konzept hat mindestens ein praktisches Beispiel |
Schritt 3.3: Querverweis-Validierung
Sicherstellen:
- Alle erwähnten Dateipfade existieren im Projekt
- Alle referenzierten Funktionen und Klassen existieren im Code
- Alle Codebeispiele verwenden die korrekten Funktionssignaturen
- Versionsnummern entsprechen der tatsächlichen Version des Projekts
- Alle Links (intern und extern) sind gültig
Dokumentations-Stilrichtlinie
Schreibprinzipien
- Mit dem "Warum" beginnen — Bevor erklärt wird, wie etwas funktioniert, erklären, warum es existiert
- Progressive Offenlegung — Einfach beginnen, Komplexität schrittweise hinzufügen
- Zeigen, nicht erzählen — Codebeispiele bevorzugen statt langer Erklärungen
- Aktivform — "Die Funktion gibt X zurück" nicht "X wird von der Funktion zurückgegeben"
- Präsens — "Der Server startet auf Port 8080" nicht "Der Server wird auf Port 8080 starten"
- Zweite Person — "Sie können konfigurieren..." nicht "Benutzer können konfigurieren..."
Formatierungsregeln
- ATX-Überschriften verwenden (
#,##,###) - Codeblöcke mit Sprachangabe (
```python,```bash) verwenden - Tabellen für strukturierte Informationen verwenden (Parameter, Optionen, Konfiguration)
- Hinweise für wichtige Notizen, Warnungen und Tipps verwenden
- Zeilenlänge lesbar halten (Text auf ~80-100 Zeichen im Quelltext umbrechen)
Code-Formatierungfür Funktionsnamen, Dateipfade, Variablennamen und CLI-Befehle verwenden
Sprachspezifische Konventionen
| Sprache | Dokumentationsformat | Stilrichtlinie |
|---|---|---|
| Python | Google-Stil Docstrings | PEP 257 |
| TypeScript/JavaScript | TSDoc / JSDoc | TypeDoc-Konventionen |
| Go | GoDoc-Kommentare | Effective Go |
| Rust | Rustdoc (///) | Rust API Guidelines |
| Java | Javadoc | Oracle Javadoc Guide |
| C/C++ | Doxygen | Doxygen Handbuch |
Ausgabe-Behandlung
Nach der Generierung:
- Dokumentationsdateien nach
/mnt/user-data/outputs/speichern - Bei mehrteiliger Dokumentation die Verzeichnisstruktur des Projekts beibehalten
- Generierte Dateien dem Benutzer mit dem
present_files-Tool präsentieren - Iteration über bestimmte Abschnitte oder Anpassung des Detailgrads anbieten
- Zusätzliche Dokumentation vorschlagen, die wertvoll sein könnte
Hinweise
- Vor dem Schreiben von Dokumentation immer den tatsächlichen Code analysieren – nie über API-Signaturen oder Verhalten raten
- Wenn vorhandene Dokumentation existiert, deren Struktur beibehalten, es sei denn, der Benutzer bittet explizit um eine Neufassung
- Bei großen Codebasen zuerst die öffentliche API-Oberfläche und die wichtigsten Abstraktionen dokumentieren
- Die Dokumentation sollte in derselben Sprache wie die vorhandene Dokumentation des Projekts verfasst sein; Standard ist Englisch, wenn keine vorhanden ist
- Bei der Generierung von Changelogs das Format Keep a Changelog verwenden
- Dieser Skill funktioniert gut in Kombination mit dem Skill
deep-researchzur Dokumentation von Integrationen oder Abhängigkeiten Dritter