API Documenting

Raport z testu

Sklonowano repozytorium, zainstalowano w tymczasowym HOME (nigdy nie dotknięto prawdziwego ~/.claude) i potwierdzono, że wszystkie 8 plików, do których odwołuje się treść SKILL.md, istnieje — PATTERNS.md, STANDARDS.md, EXAMPLES.md, templates/{endpoint,index,openapi}, scripts/{detect_routes.py,validate_openapi.sh} — trzy z nich pobrano z HTTP 200. Uruchomiono scripts/detect_routes.py na napisanym przeze mnie pliku Express z 3 trasami; poprawnie zwrócił GET /orders, POST /orders i DELETE /orders/:orderId z numerami plików+linii, więc pomocnik jest prawdziwy, a nie dekoracyjny. Zadanie: udokumentować ten sam orders.js. Bazowy (46 linii, 968 B) to punkty prozy bez typów, sekcji autoryzacji, curl, indeksu; uruchomienie umiejętności (212 linii, 3992 B) podążało za templates/index.md, a następnie templates/endpoint.md dla każdej trasy i dodało nagłówek base-URL/auth, tabelę podsumowania endpointów, tabelę wspólnych kodów odpowiedzi, trzy tabele parametrów z kolumnami Location/Type/Required (0 w bazowym), trzy wykonywalne przykłady żądań/odpowiedzi curl (0 w bazowym), przypadek 401, który bazowy pominął, i linię Notes, którą napisałem tylko dlatego, że szablon wymusił tę sekcję — że 403 jest sprawdzane po istnieniu, więc prawidłowy identyfikator należący do innego użytkownika zwraca 403, a nie 404. Frazy wyzwalające oceniono: POWINNO uruchomić — „Generate an API reference for the routes in src/api/”, „Write an OpenAPI 3.0 spec for my FastAPI app”, „Document all the endpoints in this Express router” (załadowano wszystkie trzy); NIE POWINNO — „Design a REST API for a booking system, what endpoints should I have?” (projektowanie API, nie dokumentowanie istniejącego kodu) i „Write a README for this CLI tool” (dokumentacja, ale bez endpointów); oba poprawnie odrzucone, 5/5. Brak oznak bezpieczeństwa: brak curl|sh, base64, wywołań sieciowych, dostępu do tajemnic; validate_openapi.sh wywołuje swagger-cli/npx/spectral tylko, jeśli są już obecne. Dokumentacja obniżona o jeden punkt, ponieważ umiejętność znajduje się w projekcie lekcji kursu bez własnego samodzielnego README — otaczające README to materiał dydaktyczny o progresywnym ujawnianiu, a nie dokumentacja użytkowania.

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