API Documenting

Testbericht

Das Repo geklont, in ein temporäres HOME installiert (das echte ~/.claude wurde nie berührt) und bestätigt, dass alle 8 Dateien, die der SKILL.md-Body referenziert, existieren – PATTERNS.md, STANDARDS.md, EXAMPLES.md, templates/{endpoint,index,openapi}, scripts/{detect_routes.py,validate_openapi.sh} – drei davon per Spot-Fetch mit HTTP 200. scripts/detect_routes.py gegen eine von mir geschriebene 3-Route Express-Datei ausgeführt; es gab korrekt GET /orders, POST /orders und DELETE /orders/:orderId mit Datei- und Zeilennummern zurück, sodass der Helfer real und nicht dekorativ ist. Aufgabe: dieselbe orders.js dokumentieren. Baseline (46 Zeilen, 968 B) waren Prosa-Aufzählungen ohne Typen, ohne Auth-Sektion, ohne curl, ohne Index; Skill-Lauf (212 Zeilen, 3992 B) folgte templates/index.md und dann templates/endpoint.md pro Route und fügte einen Basis-URL/Auth-Header, eine Endpunkt-Zusammenfassungstabelle, eine Tabelle mit gängigen Antwortcodes, drei Parametertabellen mit Location/Type/Required-Spalten (0 in Baseline), drei ausführbare curl-Anfrage-/Antwortbeispiele (0 in Baseline), den 401-Fall, den die Baseline wegließ, und eine Notizzeile hinzu, die ich nur schrieb, weil das Template die Sektion erzwang – dass 403 nach Existenz geprüft wird, sodass eine gültige ID, die einem anderen Benutzer gehört, 403 statt 404 zurückgibt. Trigger-Phrasierungen bewertet: SOLLTE auslösen – „Generiere eine API-Referenz für die Routen in src/api/“, „Schreibe eine OpenAPI 3.0 Spezifikation für meine FastAPI-App“, „Dokumentiere alle Endpunkte in diesem Express-Router“ (alle drei geladen); SOLLTE NICHT – „Entwerfe eine REST-API für ein Buchungssystem, welche Endpunkte sollte ich haben?“ (API-Design, nicht Dokumentation bestehenden Codes) und „Schreibe eine README für dieses CLI-Tool“ (Docs, aber keine Endpunkte); beide korrekt abgelehnt, 5/5. Keine Sicherheitsmängel: kein curl|sh, kein base64, keine Netzwerkaufrufe, kein Geheimniszugriff; validate_openapi.sh ruft swagger-cli/npx/spectral nur auf, wenn bereits vorhanden. Docs um einen Punkt abgewertet, weil die Skill in einem Kurslektionsprojekt ohne eigene eigenständige README liegt – die umgebende README ist Lehrmaterial über progressive Offenlegung, nicht Nutzungsdokumentation.

Getestet am: 2026-07-21 · Claude Code 2.x (agent harness)