Claude skill, který si audituje vlastní OpenAPI spec

Požádejte Clauda o návrh API a dostanete něco, co vypadá správně: podstatná jména v množném čísle, parametr pro stránkování, prefix verze. Pak si to přečtete pozorně a jeden endpoint používá page_size, zatímco všechny ostatní seznamy limit, chyba validace je zdokumentovaná jako 500 a spec obsahuje nullable: true, které v OpenAPI 3.1 vůbec neexistuje. Každá chyba je malá. Dohromady jsou rozdílem mezi API, které funguje, a API, které zůstává konzistentní i po změně — a nic v promptu typu „tady jsou principy" tu druhou vlastnost nevymáhá.

Výsledkem je api-discipline, a smysl není v tom, že zná konvence REST — to umí každý skill v této nice. Smysl je, že kontroluje vlastní výstup, než ho vrátí zpátky: validátorem čisté OpenAPI 3.1, povinný průchod konzistence napříč endpointy a diff breaking changes u každé úpravy. Je zdarma pod licencí MIT: github.com/Skillproofdev/api-discipline.

Propast: principy učí všichni, nikdo je nevymáhá

Než jsme napsali řádek, prošli jsme 84 skillů na návrh API a OpenAPI v našem indexu 16 682 skillů plus samostatný webový ekosystém. Vzorec je konzistentní. Největší repozitář (37,6 tis. hvězd) je učebnice konceptů s nulovým vymáháním. Nejlépe zpracovaný (10,5 tis. hvězd) pojmenuje linter a tím to končí.

A na tom záleží, co jsme mohli poctivě tvrdit. Validátorem čistý výstup sám o sobě je už vyřešený, konkurenční prostor — 10,5tisícový skill vás tam dostane. Tvrdit „my taky spouštíme linter" by byl jen šum. Tak jsme hledali, co nikdo nevymáhá, a našli čtyři věci, které se neobjevily v žádném z 84:

1. Audit konzistence napříč endpointy jako povinný průchod. Deset definovaných kontrol — velikost písmen, množné číslo, jedno sdílené schéma chyb, identické parametry stránkování, jednotný formát id/timestamp, vzor operationId, stejný status kód pro stejnou akci — spuštěných napříč každým endpointem před dodáním. Každý konkurent má nanejvýš jednu odrážku „buď konzistentní".
2. Disciplína breaking changes, která se spouští při úpravách. Každá úprava spec dostane vyjmenovaný průchod breaking changes, mechanicky podpořený oasdiff breaking, když je dostupný. Nástroj je zralý; žádný zkoumaný skill ho nemá zapojený.
3. HTTP sémantika jako pravidla, ne jako trivia. PUT nahrazuje, PATCH upravuje částečně, POST vytváří s 201 + Location, DELETE vrací 204 — vymáhané tabulkou status kódů, ne vypsané jako „koncepty k znalosti".
4. Výstupní smlouva pro review/rozšíření. „Zkontroluj tuhle spec" vrátí nálezy navázané na checklist s lokacemi a opravami; „přidej endpoint" vrátí diff, který přebírá konvence existující spec plus blok breaking changes. Konkurenti definují jen greenfield výstup.

To je neobsazená půda: ne validace, ale audit, který běží po validaci, plus zveřejněný benchmark, který to podporuje.

Benchmark: měřeno, i s prohrami

Sedm úkolů — dva greenfield návrhy, dvě rozšíření spec, dva review vadných spec s 22 nastraženými porušeními dohromady, jedna otázka na konvence. Každý běžel dvakrát: jeden agent Claude Sonnet bez pomoci, jeden s načteným SKILL.md, identické promty. Spec byly skórované mechanicky přes redocly lint a spectral lint, úpravy diffované přes oasdiff breaking a zachycení nastražených porušení posuzovali nezávislí ověřovací agenti.

Metrika (nižší = lepší)	base	skill
Chyby validátoru, greenfield (redocly)	18	0
Porušení konzistence, všechny 4 návrhové úkoly	6	0
Chyby HTTP sémantiky, všechny 4 návrhové úkoly	3	0
Zachycená nastražená porušení, T6 review (vyšší = lepší)	10/10	9/10

Měřeno 2026-07-10 s Redocly CLI 2.38.0, Spectral 6.16.1 a oasdiff 1.23.0. Kompletní detail za každým nálezem je v bench/results/verdict.md.

Mezera ve validátoru je jeden čistý příběh: oba běhy bez skillu vložily OpenAPI 3.0 nullable: true do dokumentů deklarovaných jako openapi: 3.1.0 — strukturální chyba ve 3.1, které používá type: [x, 'null']. Dvanáct výskytů v prvním greenfield úkolu, šest ve druhém. Běh se skillem používal formu 3.1 důsledně a validoval čistě. Výhry v konzistenci a sémantice mají stejný tvar: běhy bez skillu poslaly endpointy se slovesem v cestě (/tasks/{id}/complete), druhé provizorní schéma chyb vedle sdíleného a create, který vracel 200 místo 201. Běh se skillem modeloval akce jako podřazené zdroje se jmény a znovupoužil jedno schéma chyb všude — 0 napříč všemi čtyřmi návrhovými úkoly.

Kde skill prohrál — a jeden výsledek, za který si nepřipisujeme zásluhy

Dvě poctivé poznámky, protože naše metodika vyžaduje ztráty vedle výher.

Skill prohrál T6 o jedno nastražené porušení. Na review zaměřeném na sémantiku prošel agent bez pomoci volnou formou každou operaci vyčerpávajícím způsobem a zachytil 201 Created u POST /articles bez hlavičky Location. Review agenta se skillem, organizované kolem checklistu konzistence, označilo všechny čtyři chyby HTTP metod a všech pět nastražených porušení konzistence, ale neproskenovalo každý 201 na Location — 9/10 vs. 10/10. Strukturovaný review nedostatečně pokryl to, co zachytilo vyčerpávající čtení. To je teď opravené v checklistu explicitním řádkem „každý 201 má Location".

Jeden výsledek u breaking changes je z hlavního čísla vyloučený. Na úkolu rozšíření spec agent se skillem nahlásil, že před analýzou viděl v souboru úkolu uniklou nápovědu ground truth („obě změny jsou breaking") — proklouznutí protokolu, protože větev se skillem má číst jen SKILL.md. Takže tenhle výsledek není nárokovaný jako nezávislá výhra, i když na papíře vypadá dobře. Dvě věci dělají podkladové zjištění přesto robustním: agent bez pomoci, který soubor úkolu nikdy nečte, došel nezávisle ke stejnému závěru, že obě změny jsou breaking; a oasdiff mechanicky potvrdil rozsah breaking changes bez ohledu na to, čemu věřil kterýkoli agent. Hlavní tvrzení stojí na validaci, konzistenci a sémantice — ničeho z toho se únik netýká.

Instalace

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

Restartujte Claude Code. Spouští se na „navrhni API", „přidej/rozšiř endpoint", „zkontroluj tuhle OpenAPI spec" a otázky na konvence REST — a nezasahuje do čistě GraphQL práce, generování klientských SDK a bezpečnostního testování API. Patří vedle token-discipline, který snižuje, co vícekroková práce stojí, a research-discipline, který snižuje, co si výzkum splete — tenhle snižuje, kam se vaše API kontrakty rozjíždějí.

FAQ

Skill s 10,5 tis. hvězdami už produkuje validní OpenAPI. Proč tenhle? Protože validní není totéž co konzistentní. Linter zachytí rozbitý $ref; nezachytí, že jeden endpoint stránkuje s page_size, zatímco zbytek používá limit, nebo že create vrací 200. Tenhle audit konzistence napříč endpointy je neobsazená půda — je to to, co populární skilly nevymáhají, a je to místo, kde běhy bez skillu nasbíraly 6 porušení proti nule u skillu.

Zvládá úpravy existující spec, nejen greenfield návrh? Ano, a zachází s nimi jinak. Nové endpointy přidané do existující spec přebírají její konvence, i když jsou v rozporu s výchozím nastavením skillu — konzistence s kontraktem, na kterém závisí ostatní lidé, vyhrává nad preferencemi skillu. Každá úprava taky dostane vyjmenovaný průchod breaking changes, podpořený oasdiff breaking, když je nástroj dostupný.

Potřebuje k fungování oasdiff nebo nainstalovaný validátor? Ne. Když redocly/spectral nebo oasdiff můžou běžet, skill je použije a nahlásí příkaz i výsledek. Když nemůžou, řekne to výslovně a spustí definovanou záložní vlastní kontrolu — všechny $ref se rozřeší, unikátní operationId, každý parametr cesty deklarovaný, každá odpověď má popis. Nikdy kontrolu potichu nepřeskočí.

Je benchmark reprodukovatelný? Ano. Sedm úkolů, dvě větve, mechanické skórování, kde to jde, a předem zapsaný ground truth je zapsaný v repozitáři pod bench/ground-truth/. Celá metoda, detail za nálezy a poznámka o prohře T6 a integritě T4 jsou všechny v bench/results/verdict.md — nic se neschovává.