Skill Claude, który audytuje własną specyfikację OpenAPI

Poproś Claude o zaprojektowanie API, a dostaniesz coś, co wygląda dobrze: rzeczowniki w liczbie mnogiej, parametr paginacji, prefiks wersji. Potem czytasz uważniej i widzisz, że jeden endpoint używa page_size, podczas gdy każda inna lista używa limit, błąd walidacji jest udokumentowany jako 500, a specyfikacja zawiera nullable: true, którego nie ma w OpenAPI 3.1. Każdy błąd z osobna jest mały. Razem stanowią różnicę między API, które działa, a API, które pozostaje spójne pod wpływem zmian — a nic w prompcie typu „oto zasady” nie wymusza tego drugiego.

Efektem jest api-discipline, i chodzi nie o to, że zna konwencje REST — zna je każdy skill w tej niszy. Chodzi o to, że sprawdza własny wynik, zanim go odda: czyste w walidatorze OpenAPI 3.1, obowiązkowy przebieg spójności między endpointami i diff breaking changes przy każdej edycji. Jest darmowy, na licencji MIT: github.com/Skillproofdev/api-discipline.

Luka: wszyscy uczą zasad, nikt ich nie egzekwuje

Zanim napisaliśmy pierwszą linijkę, przejrzeliśmy 84 skille do projektowania API i OpenAPI w naszym indeksie 16 682 skilli plus samodzielny ekosystem webowy. Wzorzec jest spójny. Największe repozytorium (37,6 tys. gwiazdek) to podręcznik pojęć bez żadnego egzekwowania. Najlepiej zbudowane (10,5 tys. gwiazdek) wymienia lintera i na tym się kończy.

I to ma znaczenie dla tego, co możemy uczciwie twierdzić. Sam czysty w walidatorze wynik to już rozwiązana, konkurencyjna przestrzeń — skill z 10,5 tys. gwiazdek to zapewnia. Wypuszczenie „my też uruchamiamy lintera” byłoby szumem. Więc szukaliśmy tego, czego nikt nie egzekwuje, i znaleźliśmy cztery rzeczy, których nie było w żadnym z 84:

1. Audyt spójności między endpointami jako obowiązkowy przebieg. Dziesięć zdefiniowanych kontroli — wielkość liter, liczba mnoga, jeden wspólny schemat błędu, identyczne parametry paginacji, jednolite formaty id/timestamp, wzorzec operationId, ta sama akcja = ten sam kod statusu — uruchamianych na każdym endpoincie przed dostarczeniem. Każdy konkurent ma co najwyżej jeden punkt „bądź spójny”.
2. Dyscyplina breaking changes, która uruchamia się przy edycjach. Każda edycja specyfikacji dostaje wyliczony przebieg breaking changes, wsparty mechanicznie przez oasdiff breaking, gdy dostępny. Narzędzia są dojrzałe; żaden przejrzany skill ich nie podłącza.
3. Semantyka HTTP jako reguły, nie ciekawostki. PUT zastępuje, PATCH robi zmiany częściowe, POST tworzy z 201 + Location, DELETE zwraca 204 — egzekwowane tabelą kodów statusu, nie wymienione jako „pojęcia do znania”.
4. Umowa co do wyniku dla review/rozszerzenia. „Review this spec” zwraca znaleziska przypisane do checklisty z lokalizacjami i poprawkami; „add an endpoint” zwraca diff, który dziedziczy konwencje istniejącej specyfikacji plus blok breaking changes. Konkurenci definiują tylko wynik dla projektu od zera.

To jest niezagospodarowany teren: nie walidacja, ale audyt, który uruchamia się po walidacji, plus opublikowany benchmark na poparcie.

Benchmark: zmierzony, z porażkami zostawionymi w środku

Siedem zadań — dwa projekty od zera, dwa rozszerzenia specyfikacji, dwa review'y wadliwych specyfikacji z 22 podrzuconymi naruszeniami między nimi, jedno pytanie o konwencje. Każde uruchomione dwa razy: jeden goły agent Claude Sonnet, jeden czytający najpierw SKILL.md, identyczne prompty. Specyfikacje oceniano mechanicznie za pomocą redocly lint i spectral lint, edycje różnicowano oasdiff breaking, a wyłapanie podrzuconych naruszeń oceniali niezależni agenci-weryfikatorzy.

Metryka (mniej = lepiej)	base	skill
Błędy walidatora, projekt od zera (redocly)	18	0
Naruszenia spójności, wszystkie 4 zadania projektowe	6	0
Błędy semantyki HTTP, wszystkie 4 zadania projektowe	3	0
Wyłapane podrzucone naruszenia, review T6 (więcej = lepiej)	10/10	9/10

Zmierzone 2026-07-10 przy użyciu Redocly CLI 2.38.0, Spectral 6.16.1 i oasdiff 1.23.0. Pełny szczegół dla każdego znaleziska jest w bench/results/verdict.md.

Luka w walidatorze to jedna czysta historia: oba gołe przebiegi wstawiły nullable: true z OpenAPI 3.0 do dokumentów zadeklarowanych jako openapi: 3.1.0 — błąd strukturalny w 3.1, które używa type: [x, 'null']. Dwanaście wystąpień w pierwszym zadaniu od zera, sześć w drugim. Przebieg ze skillem konsekwentnie używał formy 3.1 i zwalidował się czysto. Wygrane w spójności i semantyce mają ten sam kształt: gołe przebiegi wypuściły endpointy z czasownikiem w ścieżce (/tasks/{id}/complete), drugi doraźny schemat błędu obok wspólnego i create, który zwracał 200 zamiast 201. Przebieg ze skillem modelował akcje jako rzeczownikowe podzasoby i wielokrotnie używał jednego schematu błędu — 0 we wszystkich czterech zadaniach projektowych.

Gdzie skill przegrał — i jeden wynik, którego nie przypiszemy sobie

Dwie uczciwe uwagi, bo nasza metodologia wymaga pokazywania porażek obok zwycięstw.

Skill przegrał T6 o jedno podrzucone naruszenie. Przy review skupionym na semantyce swobodny przebieg gołego agenta wyczerpująco przeszedł każdą operację i złapał 201 Created na POST /articles bez nagłówka Location. Review agenta ze skillem, zorganizowany wokół checklisty spójności, oflagował wszystkie cztery defekty metod HTTP i wszystkie pięć podrzuconych naruszeń spójności, ale nie przeskanował każdego 201 pod kątem Location — 9/10 vs 10/10. Ustrukturyzowany review niedostatecznie pokrył to, co złapało wyczerpujące czytanie. Jest to teraz naprawione w checkliście wyraźną linijką „każdy 201 ma Location”.

Jeden wynik dotyczący breaking changes jest wyłączony z nagłówka. Przy zadaniu rozszerzenia specyfikacji agent ze skillem zgłosił, że przed analizą zobaczył wyciek podpowiedzi ze stanu faktycznego do pliku zadania („obie zmiany są breaking”) — poślizg protokołu, bo wariant ze skillem powinien czytać tylko SKILL.md. Więc ten wynik nie jest zgłaszany jako niezależne zwycięstwo, mimo że dobrze wygląda na papierze. Dwie rzeczy i tak czynią leżące u podstaw znalezisko solidnym: goły wariant, który nigdy nie czyta pliku zadania, niezależnie doszedł do wniosku, że obie zmiany są breaking; a oasdiff mechanicznie potwierdził powierzchnię breaking niezależnie od tego, w co wierzył każdy z agentów. Twierdzenia nagłówkowe opierają się na walidacji, spójności i semantyce — których wyciek nie dotyka.

Instalacja

git clone https://github.com/Skillproofdev/api-discipline ~/.claude/skills/api-discipline

Zrestartuj Claude Code. Uruchamia się na „design an API”, „add/extend an endpoint”, „review this OpenAPI spec” i pytania o konwencje REST — i nie wtrąca się przy pracy wyłącznie z GraphQL, generowaniu kodu SDK klienta i testowaniu bezpieczeństwa API. Dołącza do token-discipline, który tnie to, ile kosztuje praca wieloetapowa, i research-discipline, który tnie to, w czym myli się research — ten tnie to, w co dryfują twoje kontrakty API.

FAQ

Skill z 10,5 tys. gwiazdek już produkuje poprawne OpenAPI. Po co ten? Bo poprawne to nie to samo co spójne. Linter złapie zepsute $ref; nie złapie jednego endpointu paginującego przez page_size, podczas gdy reszta używa limit, ani create'a zwracającego 200. Ten audyt spójności między endpointami to niezagospodarowany teren — to, czego popularne skille nie egzekwują, i tam gołe przebiegi nazbierały 6 naruszeń wobec 0 u skilla.

Czy obsługuje edycje istniejącej specyfikacji, nie tylko projekt od zera? Tak, i traktuje je inaczej. Nowe endpointy dodane do istniejącej specyfikacji dziedziczą jej konwencje, nawet gdy kolidują z domyślnymi ustawieniami skilla — spójność z kontraktem, na którym polegają inni ludzie, bije preferencje skilla. Każda edycja dostaje też wyliczony przebieg breaking changes, wsparty przez oasdiff breaking, gdy narzędzie jest dostępne.

Czy potrzebuje zainstalowanego oasdiff albo walidatora, żeby działać? Nie. Gdy redocly/spectral albo oasdiff mogą się uruchomić, skill ich używa i raportuje komendę oraz wynik. Gdy nie mogą, mówi to wprost i uruchamia zdefiniowany fallback samokontroli — wszystkie $ref się rozwiązują, unikalne operationId, każdy parametr ścieżki zadeklarowany, każda odpowiedź ma opis. Nigdy po cichu nie pomija kontroli.

Czy benchmark jest odtwarzalny? Tak. Siedem zadań, dwa warianty, ocena mechaniczna tam, gdzie to możliwe, a z góry zarejestrowany stan faktyczny jest zacommitowany w repozytorium pod bench/ground-truth/. Pełna metoda, szczegóły dla każdego znaleziska oraz porażka T6 i przypis o integralności T4 są w bench/results/verdict.md — nic nie jest ukryte.