Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Automatische Dokumentation

Lektion 8 von 20 Aktualisiert am 29. Juli 2026 Entwickler
Auf dieser Seite
  1. Dokumentation ohne Entwicklungsunterbrechung
  2. Inline-Dokumentation: JSDoc und Kommentare
  3. README-Erstellung
  4. API-Dokumentation
  5. Architektur-Dokumentation
  6. Aktualisierung bestehender Dokumentation
  7. Automatisierung über AGENTS.md
  8. Kernaussagen

Dokumentation ohne Entwicklungsunterbrechung

Alle sind sich einig, dass Dokumentation notwendig ist, doch fast niemand schreibt sie. Warum? Weil das Schreiben zum ungünstigsten Zeitpunkt stattfindet: Die Funktion ist abgeschlossen, und die Aufmerksamkeit ist bereits gewechselt. Codex verschiebt diese Kosten. Es analysiert den Code in seinem aktuellen Zustand und erstellt vollständige, aktuelle Dokumentation, die mit der tatsächlichen Implementierung übereinstimmt. Diese Treue ist der entscheidende Faktor: Erfindungen schaden mehr als eine leere Seite, da sie falsches Vertrauen wecken.

Inline-Dokumentation: JSDoc und Kommentare

Die am häufigsten konsultierte Dokumentation befindet sich direkt im Tooltip des Editors, genau dort, wo die Frage aufkommt.

"Fügen Sie JSDoc-Dokumentation für alle exportierten Funktionen
und Typen in src/lib/ hinzu. Fügen Sie für jede Funktion
eine Beschreibung, Parameter, Rückgabetyp und ein
Nutzungsbeispiel hinzu."

Hier ist, was Codex für eine Preisberechnungsfunktion erstellt:

/**
 * Berechnet den Gesamtpreis nach Anwendung des Rabatts.
 * 
 * @param basePrice - Stückpreis in Cent
 * @param quantity - Anzahl der Einheiten (Minimum 1)
 * @param discountPercent - Rabattprozentsatz (0-100)
 * @returns Der Gesamtpreis in Cent, auf eine ganze Zahl gerundet
 * 
 * @example
 * calculateTotal(1000, 3, 10) // 2700 (30€ - 10% = 27€)
 * 
 * @throws {ValidationError} Wenn Preis oder Menge negativ sind
 */
export function calculateTotal(
  basePrice: number,
  quantity: number,
  discountPercent: number = 0
): number {
  // ...
}

Zwei Informationen hier sind alles wertvollere als alles andere: die Einheit – Cent, nicht Euro – und die geworfene Ausnahme für negative Werte. Genau diese beiden Dinge entdecken Entwickler in der Produktion meist erst, nachdem sie Kunden zehnmal weniger berechnet haben als beabsichtigt. Codex hat sie aus der Implementierung extrahiert, nicht aus einem generischen Kommentartemplate.

README-Erstellung

Für ein neues Projekt oder für ein README, das durch Drift fiktional geworden ist, listen Sie auf, was der Leser nach dem Lesen tun können muss.

"Erstellen Sie ein umfassendes README.md für dieses Projekt.
Fügen Sie hinzu:
- Projektdescription und Zweck
- Voraussetzungen (Node.js, PostgreSQL usw.)
- Schritt-für-Schritt-Installationsanweisungen
- Benötigte Umgebungsvariablen (ohne Werte)
- Verfügbare Befehle (dev, test, build, lint)
- Projektstruktur
- Wie man beiträgt"

Codex stützt sich auf package.json, Konfigurationsdateien und den tatsächlichen Verzeichnisbaum, um ein Dokument zu erstellen, das den aktuellen Zustand des Projekts widerspiegelt. Die Anweisung “ohne Werte” ist keine Laune: Ohne sie könnte ein Agent, der nur eine gut gefüllte .env.example gelesen hat, glücklich Werte kopieren, die Sie nicht in einer versionierten Datei erscheinen lassen möchten.

API-Dokumentation

Für eine REST-API ist die kosteneffektivste Dokumentation das, was andere Tools ohne menschliches Eingreifen konsumieren können.

"Analysieren Sie alle Routen in src/api/routes/ und erstellen Sie
eine openapi.yaml-Datei. Fügen Sie Anforderungs- und Antwortschema
basierend auf existierenden TypeScript-Typen und Zod-Validierungen hinzu."

Alles wird aus dem Code extrahiert: Routenpfade, HTTP-Methoden, Validierungsschemata und Antworttypen. Die resultierende Spezifikation ist daher der Implementierung treu, sodass Ihre Konsumenten einen typisierten Client oder eine Testsammlung ableiten können, ohne Sie eine einzige Frage zu stellen.

Architektur-Dokumentation

Architektur-Entscheidungen werden selten schriftlich festgehalten. Wenn sie es tun, beschreiben sie die ursprüngliche Absicht statt der Realität nach drei Jahren. Fragen Sie Codex, die tatsächliche Existenz im Code zu formalisieren.

"Analysieren Sie die Projektarchitektur und erstellen Sie eine
docs/architecture.md-Datei, die dokumentiert:
- Ebenen (API, Dienste, Repositories, Modelle)
- Datenfluss für eine typische Anforderung
- Verwendete Muster (Repository-Muster, Dependency Injection)
- Abhängigkeiten zwischen Modulen"

Dieses Dokument hat einen unerwarteten sekundären Nutzen: Indem es Modulabhängigkeiten so beschreibt, wie sie wirklich sind, offenbart es Kopplungen, die niemand anerkannt hat – wie z. B. dass der Billing-Dienst ein Utility aus dem Authentifizierungsmodul importiert.

Aktualisierung bestehender Dokumentation

Veraltete Dokumentation ist schlimmer als keine Dokumentation, da sie Zeit mit Autorität verschwendet.

"Vergleichen Sie README.md mit dem aktuellen Zustand des Projekts.
Identifizieren Sie veraltete Abschnitte (Befehle, die nicht mehr existieren,
entfernte Abhängigkeiten, falsche Anweisungen).
Aktualisieren Sie das README entsprechend."

Codex stellt jede Behauptung im README dem tatsächlichen Code gegenüber und korrigiert Inkonsistenzen. Planen Sie diese Aufgabe periodisch, z. B. vor jedem Release, statt die Notwendigkeit zu entdecken, an dem Tag, an dem ein neuer Mitarbeiter feststellt, dass keine der Installationsbefehle funktionieren.

Automatisierung über AGENTS.md

Um die Behandlung von Dokumentation als separate Aufgabe zu stoppen, machen Sie sie zu einer dauerhaften Einschränkung des Projekts.

## Dokumentation
- Jede neue exportierte Funktion MUSS vollständige JSDoc haben
- API-Änderungen MUSS openapi.yaml aktualisieren
- Kommentarformat: Französisch für Geschäftslogik, Englisch für technische Details

Mit diesen drei Regeln trägt jede Entwicklungsaufgabe ihre eigene Dokumentationsaktualisierung. Die Lücke zwischen Code und Beschreibung hört auf, sich stumm zu vergrößern, was der einzige nachhaltige Weg ist, diesen Kampf zu gewinnen.

Kernaussagen

  • Codex generiert Dokumentation, die dem tatsächlichen Code treu ist, nicht erfunden
  • Inline-Dokumentation (JSDoc) ist am nützlichsten für tägliche Arbeiten
  • Codex kann READMEs, OpenAPI-Spezifikationen und Architektur-Dokumentation erstellen
  • Nutzen Sie Codex, um veraltete Dokumentation zu erkennen und zu korrigieren
  • Fügen Sie Dokumentationsregeln zu AGENTS.md hinzu, um den Prozess zu automatisieren