API Documenting

Rapporto di test

Clonato il repo, installato in una HOME temporanea (mai toccato il vero ~/.claude), e confermato che tutti gli 8 file referenziati nel corpo di SKILL.md esistono — PATTERNS.md, STANDARDS.md, EXAMPLES.md, templates/{endpoint,index,openapi}, scripts/{detect_routes.py,validate_openapi.sh} — tre recuperati al volo con HTTP 200. Ho eseguito scripts/detect_routes.py su un file Express a 3 route che ho scritto; ha restituito correttamente GET /orders, POST /orders e DELETE /orders/:orderId con numeri di file+riga, quindi l'helper è reale e non decorativo. Task: documentare lo stesso orders.js. La baseline (46 righe, 968 B) era un elenco puntato in prosa senza tipi, senza sezione di autenticazione, senza curl, senza indice; l'esecuzione della skill (212 righe, 3992 B) ha seguito templates/index.md e poi templates/endpoint.md per route e ha aggiunto un header base-URL/auth, una tabella riassuntiva degli endpoint, una tabella dei codici di risposta comuni, tre tabelle di parametri con colonne Location/Type/Required (0 nella baseline), tre esempi di richiesta/risposta curl eseguibili (0 nella baseline), il caso 401 che la baseline aveva omesso, e una riga Notes che ho scritto solo perché il template imponeva la sezione — quel 403 viene controllato dopo l'esistenza, quindi un ID valido posseduto da un altro utente restituisce 403 non 404. Frasi di attivazione giudicate: DOVREBBE attivarsi — "Genera un riferimento API per le route in src/api/", "Scrivi una specifica OpenAPI 3.0 per la mia app FastAPI", "Documenta tutti gli endpoint in questo router Express" (caricati tutti e tre); NON DOVREBBE attivarsi — "Progetta un'API REST per un sistema di prenotazione, quali endpoint dovrei avere?" (progettazione API, non documentazione di codice esistente) e "Scrivi un README per questo strumento CLI" (documentazione ma non endpoint); entrambi correttamente rifiutati, 5/5. Nessuna vulnerabilità di sicurezza: nessun curl|sh, nessuna chiamata di rete, nessun accesso a segreti; validate_openapi.sh esegue solo swagger-cli/npx/spectral se già presenti. Documentazione penalizzata di un punto perché la skill si trova all'interno di un progetto di lezione di corso senza un proprio README autonomo — il README circostante è materiale didattico sulla divulgazione progressiva, non documentazione d'uso.

Testato il: 2026-07-21 · Claude Code 2.x (agent harness)