README, w którym każde twierdzenie wynika z kodu

Wygenerowany README to sztuczka na zaufanie. Czyta się czysto, wymienia funkcje, które brzmią dobrze, i podaje komendy instalacyjne, które wyglądają poprawnie — a czytając go, nie da się rozpoznać, które zdania są prawdziwe. Tryb awarii jest zawsze ten sam: funkcja, której kod nie ma, komenda dokończona wzorcem z danych treningowych zamiast skopiowana z repo, i podejrzany brak jakichkolwiek ograniczeń. Na co dzień prowadzimy katalog, w którym benchmarkujemy skille Claude, więc zbudowaliśmy skill, jakiego chcieliśmy, a potem zmierzyliśmy, czy faktycznie się trzyma.

Efektem jest readme-discipline: dziewięć egzekwowalnych reguł, których umowa mówi, że zgłoszona funkcja musi zostać znaleziona w źródle, zanim będzie można ją zgłosić, każda komenda jest skopiowana z prawdziwych manifestów projektu i wykonana, a uczciwa sekcja ograniczeń jest obowiązkowa. Jest darmowy, na licencji MIT: github.com/Skillproofdev/readme-discipline.

Luka: 101 skilli do README, żaden nie egzekwuje prawdy

Zanim napisaliśmy pierwszą regułę, przejrzeliśmy krajobraz — 101 skilli pokrewnych README w katalogu 16 682 skilli, plus readme-ai i specyfikację Standard Readme. Każdy z nich optymalizuje coś innego niż dokładność.

Największy dedykowany skill do README (2,2 tys. ★) to zestaw szablonów pod różne odbiorców. Specyfikacja Standard Readme narzuca kolejność sekcji, ale nic nie mówi o tym, czy bloki kodu się uruchamiają. Dominujący generator CLI produkuje wypolerowany wynik, a potem, we własnej dokumentacji, mówi ci, żebyś sam zweryfikował dokładność — dokładność jest przerzucana na człowieka. Reszta to maksymalizatory badge'y i dekoratorzy nagłówków emoji. Struktura i wygląd są rozwiązane pięć razy z rzędu. „Każde twierdzenie wynika z kodu” i „każdy przykład jest zweryfikowany jako uruchamialny” pojawiły się jako egzekwowalne reguły w żadnym z nich.

To cała nisza, którą zajmuje ten skill: nie robienie README ładniejszymi, tylko czynienie ich prawdziwymi.

Dziewięć reguł, trzy nowatorskie

Znajome elementy są na miejscu — stała kolejność sekcji (what+why → install → quickstart → usage → config → limitations), kalibracja pod jednego odbiorcę, brak inflacji badge'y czy emoji. Trzy, których nikt inny nie egzekwuje:

1. Zakaz konfabulacji z dowodami. Każde falsyfikowalne twierdzenie — funkcja, flaga, obsługiwana platforma — jest najpierw wyszukiwane grepem w źródle. Znalezione → możesz je zgłosić, w słownictwie samego kodu. Nieznalezione → nie trafia do README, ani jako zastrzeżenie, ani jako „zazwyczaj”. Log weryfikacyjny mapujący twierdzenie → plik:linijka towarzyszy każdemu README.
2. Komendy są kopiowane, nigdy komponowane. Każda komenda w bloku kodu pochodzi z realnego miejsca: skryptów package.json, celu Makefile, kroku CI, własnego --help CLI. Nigdy npm run build, bo projekty Node zwykle je mają — najpierw sprawdź scripts, potem uruchom to na czystym checkout.
3. Quickstart to umowa. Od klonowania do jednego obserwowalnego sukcesu w około 60 sekund, każdy krok wykonywalny dokładnie tak, jak napisany, kończący się wynikiem, który użytkownik może sprawdzić — URL, który odpowiada, plik, który się pojawia, output pasujący do pokazanego fragmentu.

Do tego obowiązkowa sekcja ograniczeń oparta na źródle (wyciągnięta z komentarzy TODO/FIXME, gałęzi błędów, pustych zaślepek) i tryb audytu-najpierw, który usuwa nieaktualne twierdzenia z istniejącego README, zanim tknie jego styl.

Benchmark: 3 prawdziwe repo, każda komenda faktycznie uruchomiona

Wybraliśmy trzy małe projekty OSS z ubogimi README i zamroziliśmy każdy przy SHA commita: CLI w Node (crossplatform-killport), CLI/bibliotekę w Pythonie (python-shaarli-client) i usługę webową Flask (csrgenerator.com). Na repo dwóch agentów — jeden baseline, jeden czytający najpierw skill — ten sam model, ten sam prompt, jedyna różnica to obecność SKILL.md w kontekście. Każda komenda w poniższej tabeli została wykonana na realnej maszynie (macOS 14, node v24.7.0, python3 3.13.1); komendy, których runtime był nieobecny (Docker) albo które potrzebowały żywej usługi zewnętrznej, zostały wyłączone z mianownika wykonalności i zamiast tego zweryfikowane statycznie.

Metryka (suma dla 3 repo)	Baseline	Skill
Sfabrykowane twierdzenia (mniej = lepiej)	2	1
Wykonalność komend	20/24 (83%)	15/17 (88%)
Kompletność sekcji	14/18	18/18
Ślepa preferencja	0/3	3/3
Średnie zaufanie (1–5)	3,67	4,67

Kierunek jest spójny we wszystkich trzech repo, jeśli chodzi o kompletność i preferencję. Skill trafiał 6/6 sekcji za każdym razem; baseline nie dostarczył sekcji ograniczeń w żadnym z trzech repo — pojedyncza największa luka kompletności. I był preferowany we wszystkich trzech, z pełnym punktem więcej zaufania.

Gdzie skill faktycznie na to zasłużył — i gdzie się poślizgnął

Liczba fabrykacji zasługuje na uczciwość, bo to nagłówek, po którym spodziewałbyś się miażdżącej przewagi, a jej nie ma. 2 wobec 1 to wąska luka, i oto dlaczego: oba agenty baseline mocno oparły się na istniejącej, dokładnej prozie USAGE.md/docs/ repozytoriów, więc odziedziczyły poprawną treść za darmo. Dwa przeoczenia baseline'u to dokładnie ta porażka, w którą celuje ten skill — nieaktualny wymóg Python 3.4+ sprzeczny z własną macierzą testów projektu i dwa zmyślone środowiska tox (py34/py36), których nie ma w tox.ini. Twierdzenia dokończone wzorcem, sprowadzalne do „projektu takiego jak ten”, nie do kodu. Wariant ze skillem złapał to samo twierdzenie o 3.4 i zdegradował je do udokumentowanego ograniczenia zamiast je stwierdzać.

A skill zachował własną jedyną fabrykację w raporcie, zamiast ją ukryć. W csrgenerator jego tabela pól twierdziła, że pusta wartość CN zwraca HTTP 400. Brakująca CN faktycznie daje 400 — ale pusta trafia we własne raise KeyError("CN cannot be empty") kodu, które jest nieobsłużone i zwraca HTTP 500 (zweryfikowane na żywo). Jeden błędny szczegół behawioralny w komórce tabeli, w przebiegu, który poza tym wykonał pytest (23 zaliczone, dokładna zgodność) i prawdziwe generowanie CSR przez curl. Skill to nie magia; to dyscyplina, a dyscyplina ma resztkowy wskaźnik błędów. Zapisaliśmy go.

Skill był jednoznacznie ostrzejszy w zweryfikowanych szczegółach: „pip install -e . zainstalował requests==2.34.2 / PyJWT==2.13.0” dokładnie pasowało do świeżego venv; ograniczenia killport (dopasowanie tylko LISTENING na Windows, bezwarunkowy SIGKILL, jeden port na wywołanie) wszystkie wynikały ze źródła, z przepływem zabijania zweryfikowanym od początku do końca. Twierdzenia, które wzięły się z uruchomienia, nie z przeczucia.

Uczciwe zastrzeżenia

Nasza metodologia wymaga wydrukowania słabości obok zwycięstw, a tutaj są prawdziwe.

Jeden oceniający, nie panel trzech deweloperów. Wiersze preferencji i zaufania to jedna ekspercka ocena autora benchmarku, wydana przy otwartym źródle. Protokół wymaga ≥3 niezależnych oceniających-deweloperów; ten panel nie był dostępny w tym harnessie. Czytaj te dwa wiersze jako orientacyjne, nie jako wynik wielu oceniających, jakiego wymaga projekt.

Luka w fabrykacji jest wąska z definicji. Ponieważ oba baseline'y ponownie użyły dokładnej dokumentacji repo, baseline miał mniej okazji do zmyślania. W repo bez istniejącej dokumentacji luka prawdopodobnie by się powiększyła — ale raportujemy to, co pokazały te trzy repo, czyli 2 wobec 1, a N=3 jest tylko kierunkowe.

Wykonanie komend zależy od środowiska. Gdy maszyna agenta nie może uruchomić projektu, komendy są weryfikowane statycznie względem manifestów i oznaczane w logu jako niewykonane — słabsze niż prawdziwe uruchomienie, i tak to oznaczamy.

Instalacja

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

Zrestartuj Claude Code. Uruchamia się na „write a README”, „document this repo”, „create/rewrite README.md” i prośby o review lub audyt README — i nie wtrąca się przy pełnych serwisach dokumentacji, generowaniu referencji API i changelogach. Dołącza do naszej serii dyscyplin: token-discipline tnie to, ile zadanie kosztuje, research-discipline tnie to, w czym myli się research, a ten tnie to, co twoja dokumentacja fabrykuje.

FAQ

Czym różni się to od generatora README jak readme-ai? Generatory produkują strukturę i przerzucają dokładność na ciebie — ich własna dokumentacja mówi ci, żebyś zweryfikował wynik. Ten skill to odwraca: najpierw czyta kod, wyszukuje grepem każde falsyfikowalne twierdzenie w źródle, uruchamia każdą udokumentowaną komendę na czystym checkout i daje ci log weryfikacyjny, żebyś mógł sprawdzić jego pracę. Struktura to łatwa część; skill wkłada wysiłek w prawdę.

Czym dokładnie jest log weryfikacyjny? Osobny artefakt w odpowiedzi (nie commitowany), który mapuje każdą zgłoszoną funkcję na plik:linijka w źródle i oznacza każdą komendę jako ran ✓ albo not executed — verified against <manifest>, plus wszystko celowo pominięte z braku dowodów. Jeśli ten log byłby pusty, skill pominął swoje własne pierwsze trzy reguły. To paragon, który pozwala zaufać prozie.

Czy reguła zakazu fabrykacji czyni README krótszym i nudniejszym? Nie — reguły są napisane, żeby dodawać użyteczną treść, nie ją ciąć. Obowiązkowa sekcja ograniczeń i quickstart ze zweryfikowanymi komendami to rzeczy, które ogólne README pomijają. W benchmarku README skilla były bardziej kompletne (18/18 sekcji) niż baseline'u, nie cieńsze.

Czy jedna fabrykacja w trzech repo to wystarczająco dobrze? To lepiej niż dwie u baseline'u, i jest uczciwe co do reszty — zachowanie przy pustym CN błędne o jeden kod statusu HTTP, zapisane, nie zakopane. Jeśli twój README stoi za decyzją, przy której pomyłka dużo kosztuje, log weryfikacyjny mówi ci dokładnie, które twierdzenia sprawdzić wyrywkowo, co zajmuje minuty zamiast ponownego czytania całego kodu.