Technische Dokumentation mit Claude schreiben

1. Warum KI-gestützte Dokumentation sinnvoll ist

Technische Dokumentation gehört zu den Aufgaben, die in Magento-Projekten regelmäßig hinten anstehen. Ein neues Modul wird fertiggestellt, getestet und deployt, aber die README-Datei bleibt leer oder enthält nur ein Platzhalter-Stichwort, weil die eigentliche Feature-Arbeit Priorität hatte. Claude verändert diese Kalkulation, indem es die Einstiegshürde drastisch senkt: Statt vor einer leeren Seite zu sitzen, bekommt man in wenigen Minuten einen strukturierten Entwurf, der aus dem tatsächlichen Code abgeleitet ist. Das ersetzt keine Dokumentationsarbeit, aber es verschiebt den Aufwand vom Schreiben zum Prüfen und Verfeinern, was für die meisten Entwicklerinnen und Entwickler die deutlich angenehmere Aufgabe ist.

Konkret bedeutet das für ein Modul wie Mironsoft_SeoSuite: Man gibt Claude Zugriff auf die Model-Klassen, die Api/Interfaces und die etc/-Konfiguration, und bekommt eine strukturierte Übersicht über Zweck, Konfigurationspfade und Erweiterungspunkte zurück. Der Wert liegt nicht darin, dass die Ausgabe perfekt ist, sondern darin, dass sie als konkrete Diskussionsgrundlage dient. Es ist einfacher, einen vorhandenen Text zu korrigieren, als aus dem Nichts zu formulieren, was ein Modul eigentlich tut.

2. Kontext sammeln: Code, Tests und Historie als Grundlage

Die Qualität eines generierten Dokumentationsentwurfs hängt fast vollständig von der Qualität des bereitgestellten Kontexts ab. Wer Claude nur den Namen einer Klasse nennt, bekommt plausibel klingende, aber oft falsche Annahmen zurück. Wer dagegen die relevanten PHP-Klassen, die dazugehörigen PHPUnit-Tests, die system.xml und die letzten aussagekräftigen Commit-Nachrichten bereitstellt, bekommt einen Entwurf, der tatsächlich beschreibt, was der Code macht, statt was er plausibel machen könnte. Tests sind dabei besonders wertvoll, weil sie das beabsichtigte Verhalten explizit machen, während der Implementierungscode manchmal nur den aktuellen, aber nicht unbedingt den gewollten Zustand zeigt.

Claude Code hat hier einen strukturellen Vorteil gegenüber dem reinen Chat-Interface: Es kann selbstständig im Repository navigieren, verwandte Dateien nachladen und mit grep nach Verwendungsstellen suchen, statt auf manuell kopierte Snippets angewiesen zu sein. Eine projektweite CLAUDE.md mit Konventionen zu Namensräumen, Konfigurationspfaden und dem Dual-Vendor-Workflow liefert zusätzlichen, konsistenten Hintergrund, ohne dass man ihn bei jeder Anfrage neu erklären muss. Wichtig bleibt die Abgrenzung: Ganze Vendor-Verzeichnisse oder Dateien mit Zugangsdaten gehören nicht in den Kontext, weil sie weder zur Doku-Qualität beitragen noch dorthin gehören.

3. Die erste Version generieren: Prompting-Strategien

Ein guter Prompt für Dokumentationsgenerierung legt drei Dinge fest: die Zielgruppe, die erwartete Struktur und die Grenze dessen, was das Modell erfinden darf. Zielgruppe heißt konkret: Schreibt der Text für Entwicklerinnen, die das Modul erweitern, oder für Shop-Betreiber, die eine Konfigurationsoption suchen? Beide brauchen unterschiedliche Tiefe und unterschiedliches Vokabular. Struktur heißt, feste Überschriften vorzugeben, etwa Zweck, Installation, Konfiguration und Erweiterungspunkte, statt Claude frei entscheiden zu lassen, was wichtig ist.

Der wichtigste Baustein ist die explizite Anweisung, unsichere Aussagen zu kennzeichnen und nichts zu erfinden, das nicht im Code nachweisbar ist. Ohne diese Anweisung neigen Sprachmodelle dazu, Lücken mit plausibel klingenden, aber falschen Details zu füllen, etwa einem Konfigurationspfad, der so ähnlich, aber nicht exakt existiert. Mit der Anweisung markiert Claude solche Stellen als TODO: verify, was die anschließende Review erheblich beschleunigt, weil man gezielt nachschauen kann, statt jeden Satz gleich intensiv zu prüfen.

#!/usr/bin/env bash
# Draft a module README with Claude Code from inside the module directory
cd src/app/code/Mironsoft/SeoSuite

claude -p "Read every PHP file in Model/, Api/, Block/ and the etc/ directory.
Draft a README.md for this Magento 2 module covering:
1. Purpose (one paragraph, based only on what the code actually does)
2. Installation (composer require + setup:upgrade)
3. Configuration (list every system.xml path with its default value)
4. Extension points (plugins, observers, preferences this module defines)
Mark every claim you cannot verify from the code with 'TODO: verify'.
Do not invent config paths or class names that are not present in the files."

4. Praktischer Workflow: ein Modul-README erstellen

Ein belastbarer Workflow behandelt die Claude-Ausgabe wie jeden anderen Pull-Request-Vorschlag: erzeugen, diffen, prüfen, erst dann committen. Der erste Schritt ist ein eigener Branch, damit der generierte Entwurf isoliert bleibt und nicht versehentlich mit anderen Änderungen vermischt wird. Der zweite Schritt ist die eigentliche Generierung, idealerweise mit einem engen Scope wie einem einzelnen Modulverzeichnis, damit Claude nicht versucht, projektweite Aussagen aus einem unvollständigen Kontext abzuleiten.

Der entscheidende Schritt folgt danach: der Diff wird gelesen wie Code, nicht überflogen wie Fließtext. Jede Behauptung über Konfigurationspfade wird gegen die tatsächliche system.xml geprüft, am besten mit einem automatisierten Abgleich statt manuellem Nachschauen. Erst wenn dieser Abgleich sauber ist, wird committet, und zwar mit einem Commit-Text, der klarstellt, dass es sich um einen geprüften, generierten Entwurf handelt. Diese Kennzeichnung ist kein Formalismus, sondern hilft späteren Lesern der Git-Historie einzuschätzen, wie der Text entstanden ist.

#!/usr/bin/env bash
# Full workflow: generate, review, and commit a module README
git checkout -b docs/seosuite-readme

# 1. Let Claude Code read the module and draft the README
claude -p "Draft README.md for app/code/Mironsoft/SeoSuite based on the current code only" \
  > /dev/null

# 2. Inspect exactly what changed before trusting it
git diff --stat
git diff README.md

# 3. Verify every documented config path against the real system.xml
bin/magento config:show mironsoft_seosuite \
  | diff - <(grep -oP '(?<=<field id=")[^"]+' etc/adminhtml/system.xml)

# 4. Only commit after a human has read every paragraph
git add README.md
git commit -m "docs: add generated README for SeoSuite module (reviewed)"

5. Menschliche Review: Genauigkeit und Ton absichern

Die Review-Pflicht ist keine Formsache, sondern der eigentliche Kern eines seriösen Workflows mit KI-generierter Dokumentation. Sprachmodelle halluzinieren nicht willkürlich, sondern auf eine Weise, die besonders gefährlich ist: Der Text klingt kompetent und in sich stimmig, auch wenn er falsche Methodennamen, veraltete Konfigurationspfade oder nicht existierende Klassen enthält. Genau diese Überzeugungskraft macht die Prüfung notwendig, denn ein offensichtlich schlechter Text würde ohnehin auffallen, ein subtil falscher nicht.

Neben der fachlichen Prüfung braucht es eine Prüfung auf Ton und Zielgruppe. Claude neigt, je nach Prompt, zu einer etwas werblichen oder unnötig ausführlichen Sprache, die in technischer Dokumentation fehl am Platz ist. Ein Reviewer sollte gezielt nach Superlativen und vagen Formulierungen suchen und sie durch konkrete, überprüfbare Aussagen ersetzen. Ergänzend gehört eine Prüfung auf sensible Informationen dazu: interne Serverpfade, Kundennamen oder Testzugangsdaten, die versehentlich aus dem Kontext in den generierten Text gerutscht sind, dürfen ein Repository nicht verlassen.

6. Dokumentation und Code synchron halten

Das eigentliche Problem bei technischer Dokumentation ist selten die Erstellung, sondern die Pflege über Zeit. Ein einmalig generiertes README ist nach dem ersten größeren Refactoring bereits potenziell veraltet, und veraltete Dokumentation ist in vielen Fällen schädlicher als gar keine, weil sie falsches Vertrauen erzeugt. Ein einfacher, aber wirksamer Ansatz ist ein automatisierter Abgleich zwischen dokumentierten Methodennamen und den tatsächlich im Code vorhandenen Signaturen, der als Teil der Continuous-Integration-Pipeline läuft und bei Abweichungen fehlschlägt.

Ein solches Skript ersetzt keine inhaltliche Prüfung, aber es fängt die grobe Kategorie von Drift ab, in der eine öffentliche Methode umbenannt oder entfernt wurde, ohne dass die Doku angepasst wurde. Für tiefergehende Änderungen, etwa eine veränderte Business-Logik, bleibt der Mensch verantwortlich. Praktisch bewährt sich, Claude nach einem Pull Request gezielt nur den Diff zwischen altem und neuem Code als Kontext zu geben und um eine punktuelle Aktualisierung zu bitten, statt jedes Mal das gesamte README neu zu generieren und damit manuell eingefügte Nuancen zu verlieren.

#!/usr/bin/env python3
"""Check if documented public methods still exist in the actual PHP class."""
import re
import sys
from pathlib import Path


def extract_documented_methods(readme_path: Path) -> set[str]:
    text = readme_path.read_text(encoding="utf-8")
    return {m.rstrip("()") for m in re.findall(r"`([a-zA-Z]+\(\))`", text)}


def extract_real_methods(php_path: Path) -> set[str]:
    text = php_path.read_text(encoding="utf-8")
    return set(re.findall(r"function\s+([a-zA-Z_]+)\s*\(", text))


def main() -> int:
    readme = Path("app/code/Mironsoft/SeoSuite/README.md")
    php_file = Path("app/code/Mironsoft/SeoSuite/Model/MetaGenerator.php")

    documented = extract_documented_methods(readme)
    real = extract_real_methods(php_file)

    stale = documented - real
    if stale:
        print(f"[DRIFT] Documented but no longer present: {sorted(stale)}", file=sys.stderr)
        return 1

    print("[OK] Documentation matches current method signatures")
    return 0


if __name__ == "__main__":
    sys.exit(main())

7. Claude Code und CI: Doku-Pflege automatisieren

Automatisierung sollte hier nicht bedeuten, dass Doku-Updates unbeaufsichtigt committet werden, sondern dass Menschen zuverlässig erinnert werden, wenn eine Änderung wahrscheinlich eine Doku-Aktualisierung erfordert. Ein Hook in Claude Code kann nach jeder Bearbeitung von Dateien in einem Api/-Verzeichnis eine Erinnerung ausgeben, dass die zugehörige README geprüft werden sollte. Das kostet keine zusätzliche Interaktion, weil es an einen ohnehin stattfindenden Arbeitsschritt gekoppelt ist, und verhindert, dass eine Schnittstellenänderung unbemerkt an der Dokumentation vorbeiläuft.

In der CI-Pipeline lässt sich derselbe Gedanke auf Pull-Request-Ebene umsetzen: Ein Skript prüft, ob ein PR Dateien in Api/ ändert, ohne die README zu berühren, und lässt bei Bedarf die Anthropic-API einen kurzen, konkreten Kommentar formulieren, der die Autorin oder den Autor bittet, die Doku zu prüfen. Wichtig ist, dass dieser Mechanismus nur einen Hinweis erzeugt und keine automatische Änderung, denn eine automatisch geänderte Doku ohne Review wäre genau das Problem, das dieser Workflow eigentlich vermeiden soll.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"$CLAUDE_TOOL_INPUT\" | grep -q \"Api/\" && echo \"Reminder: update README.md, this change touched a public interface\" >&2 || true'"
          }
        ]
      }
    ]
  }
}

// scripts/check-docs-drift.mjs: flags PRs that change public API without touching README.md
import Anthropic from "@anthropic-ai/sdk";
import { execSync } from "node:child_process";

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const changedFiles = execSync("git diff --name-only origin/main...HEAD")
  .toString()
  .trim()
  .split("\n");

const touchedApi = changedFiles.some((f) => f.includes("/Api/"));
const touchedDocs = changedFiles.some((f) => f.endsWith("README.md"));

if (touchedApi && !touchedDocs) {
  const response = await anthropic.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 300,
    messages: [
      {
        role: "user",
        content: `This PR changes files in an Api/ directory but not README.md. Files changed: ${changedFiles.join(", ")}. Write a short PR comment asking the author to confirm the docs are still accurate.`,
      },
    ],
  });
  console.log(response.content[0].text);
  process.exitCode = 1;
}

8. Grenzen und Risiken von KI-generierter Dokumentation

Claude kennt nur, was aus Code, Tests und den mitgegebenen Textquellen ableitbar ist. Business-Entscheidungen, die nicht im Code stehen, etwa warum eine bestimmte Grenze für Rabattstaffeln gewählt wurde, bleiben unsichtbar und können bestenfalls als offene Frage markiert, nie aber korrekt beantwortet werden. Bei komplexen Plugin-Ketten mit mehreren Interceptors auf derselben Methode kann das Modell die tatsächliche Ausführungsreihenfolge falsch einschätzen, weil sie von der Sequence-Konfiguration in mehreren di.xml-Dateien abhängt, die nicht immer vollständig im Kontext vorliegen.

Ein weiteres, oft unterschätztes Risiko ist die Vertraulichkeit: Wer internen, kundenspezifischen Code an einen gehosteten Dienst schickt, muss die Datenverarbeitungsbedingungen und vertraglichen Vereinbarungen mit dem Kunden kennen, bevor Quellcode oder Konfigurationsdetails geteilt werden. Claude Code, das lokal auf Dateien zugreift, unterscheidet sich hier von der reinen API in Bezug auf Datenfluss und sollte entsprechend eingeordnet werden. Grundsätzlich gilt: Ein überzeugend klingender, aber falscher Dokumentationstext ist gefährlicher als eine sichtbare Lücke, weil Leserinnen und Leser einer Lücke misstrauen, einem flüssigen Text aber tendenziell vertrauen.

9. Gute vs. schlechte KI-generierte Dokumentation im Vergleich

Die folgende Tabelle fasst die häufigsten Fallstricke bei KI-gestützter Dokumentation den empfohlenen Gegenmaßnahmen gegenüber. Der gemeinsame Nenner ist immer derselbe: Ein Generierungsschritt allein reicht nicht, es braucht einen definierten Prüf- und Pflegeschritt danach.

Auffällig ist, dass fast alle unsicheren Muster in der linken Spalte auf denselben Fehler zurückgehen: Der Generierungsschritt wird als Endpunkt statt als Zwischenschritt behandelt. Wer Doku-Generierung von Anfang an als Vorschlag begreift, der Review, Test und Pflege durchläuft, vermeidet die meisten dieser Fallstricke ohne zusätzlichen Werkzeugaufwand.

10. Zusammenfassung

Claude löst das eigentliche Aktivierungsproblem technischer Dokumentation: den Sprung von der leeren Seite zu einem strukturierten, aus dem Code abgeleiteten Entwurf. Wer Modelldateien, Api/Interfaces, Tests und Konfiguration als Kontext bereitstellt und dabei explizit unsichere Aussagen markieren lässt, bekommt einen Entwurf, der als Diskussionsgrundlage taugt und die eigentliche Schreibarbeit erheblich verkürzt. Das ist der Kernnutzen, und er ist real messbar in eingesparter Zeit.

Der Nutzen kippt jedoch, sobald der generierte Text ohne Review als fertig behandelt wird. Genauigkeit, Ton und die fortlaufende Synchronisation mit dem tatsächlichen Code bleiben menschliche Verantwortung, die sich am besten in feste Workflow-Schritte gießen lässt: Diff lesen, Konfigurationspfade automatisiert abgleichen, Doku-Updates als Pflichtteil des PR-Prozesses verankern. Wer diese Schritte konsequent einhält, bekommt aus Claude einen echten Produktivitätsgewinn, ohne die Verlässlichkeit der Dokumentation zu opfern.

11. FAQ: Technische Dokumentation mit Claude schreiben