API Documenting

Testrapport

De repo gekloond, geïnstalleerd in een tijdelijke HOME (nooit de echte ~/.claude aangeraakt), en bevestigd dat alle 8 bestanden waarnaar de SKILL.md body verwijst bestaan — PATTERNS.md, STANDARDS.md, EXAMPLES.md, templates/{endpoint,index,openapi}, scripts/{detect_routes.py,validate_openapi.sh} — drie willekeurig opgehaald met HTTP 200. scripts/detect_routes.py gedraaid tegen een 3-route Express bestand dat ik schreef; het retourneerde correct GET /orders, POST /orders en DELETE /orders/:orderId met file+line nummers, dus de helper is echt en niet decoratief. Taak: documenteer datzelfde orders.js. Baseline (46 regels, 968 B) was proza met opsommingstekens zonder types, geen auth sectie, geen curl, geen index; skill run (212 regels, 3992 B) volgde templates/index.md en daarna templates/endpoint.md per route en voegde een base-URL/auth header toe, een endpoint samenvattingstabel, een tabel met veelvoorkomende responsecodes, drie parametertabellen met Location/Type/Required kolommen (0 in baseline), drie uitvoerbare curl request/response voorbeelden (0 in baseline), de 401 case die de baseline weglaten, en een Notes regel die ik alleen schreef omdat de template de sectie afdwong — die 403 wordt gecontroleerd na het bestaan, dus een geldige id die eigendom is van een andere gebruiker retourneert 403 en geen 404. Triggerfraseringen beoordeeld: MOET activeren — "Genereer een API referentie voor de routes in src/api/", "Schrijf een OpenAPI 3.0 spec voor mijn FastAPI app", "Documenteer alle endpoints in deze Express router" (laadde alle drie); MOET NIET — "Ontwerp een REST API voor een boekingssysteem, welke endpoints moet ik hebben?" (API ontwerp, niet documenteren van bestaande code) en "Schrijf een README voor deze CLI tool" (docs maar geen endpoints); beide correct geweigerd, 5/5. Geen beveiligingsproblemen: geen curl|sh, geen base64, geen netwerkoproepen, geen geheime toegang; validate_openapi.sh roept alleen swagger-cli/npx/spectral aan als deze al aanwezig zijn. Docs afgewaardeerd met één punt omdat de skill zich bevindt in een cursusproject zonder eigen standalone README — de omringende README is lesmateriaal over progressieve openbaarmaking, geen gebruiksdocumentatie.

Getest op: 2026-07-21 · Claude Code 2.x (agent harness)