README, kde každé tvrzení vede zpátky ke kódu

Vygenerované README je důvěryhodnostní trik. Čte se čistě, vyjmenovává funkce, které zní správně, a dá vám instalační příkazy, které vypadají korektně — a podle čtení nepoznáte, které věty jsou pravdivé. Selhání je pokaždé stejné: funkce, kterou kód nemá, příkaz doplněný podle vzoru z trénovacích dat místo zkopírovaný z repozitáře, a podezřele chybějící sekce omezení. Provozujeme katalog, který testuje Claude skilly na reálných datech, takže jsme postavili skill, jaký jsme chtěli, a pak změřili, jestli se skutečně drží.

Výsledkem je readme-discipline: devět vymahatelných pravidel, jejichž smlouva zní, že tvrzená funkce se musí najít ve zdroji dřív, než se smí tvrdit, každý příkaz je zkopírovaný ze skutečných manifestů projektu a spuštěný, a poctivá sekce omezení je povinná. Je zdarma pod licencí MIT: github.com/Skillproofdev/readme-discipline.

Propast: 101 skillů na README, žádný nevymáhá pravdu

Než jsme napsali pravidlo, prošli jsme trh — 101 skillů souvisejících s README v katalogu 16 682 skillů, plus readme-ai a specifikaci Standard Readme. Každý z nich optimalizuje něco jiného než přesnost.

Největší specializovaný README skill (2,2 tis. hvězd) je sada šablon podle publika. Specifikace Standard Readme nařizuje pořadí sekcí, ale neříká nic o tom, jestli bloky kódu vůbec běží. Dominantní CLI generátor produkuje uhlazený výstup a pak vám ve vlastní dokumentaci řekne, ať si to sami zkontrolujete kvůli přesnosti — přesnost je přehozená na člověka. Zbytek jsou maximalizátoři badgí a dekoratéři emoji nadpisů. Struktura a vzhled jsou vyřešené pětkrát dokola. „Každé tvrzení vede ke kódu" a „každý příklad je ověřeně spustitelný" se jako vymahatelné pravidlo neobjevily v žádném z nich.

To je celá nika, kterou tenhle skill obsazuje: neudělat README hezčí, udělat je pravdivé.

Devět pravidel, tři z nich nová

Známé části tu jsou — pevné pořadí sekcí (co+proč → instalace → quickstart → použití → konfigurace → omezení), kalibrace na jedno publikum, žádná inflace badgí ani emoji. Tři, které nikdo jiný nevymáhá:

1. Zákaz vymýšlení s dokladem. Každé ověřitelné tvrzení — funkce, flag, podporovaná platforma — se nejdřív vyhledá ve zdroji. Nalezeno → smíte to tvrdit, ve slovníku samotného kódu. Nenalezeno → nejde to do README, nezmírněné, ne jako „obvykle". Ke každému README jde ověřovací log mapující tvrzení → soubor:řádek.
2. Příkazy se kopírují, nikdy se neskládají. Každý příkaz v bloku kódu pochází z reálného místa: skripty v package.json, cíl v Makefile, krok CI, vlastní --help CLI nástroje. Nikdy npm run build jen proto, že Node projekty ho obvykle mají — nejdřív zkontrolovat scripts, pak ho spustit na čistém checkoutu.
3. Quickstart je smlouva. Od klonování k jednomu pozorovatelnému úspěchu za zhruba 60 vteřin, každý krok spustitelný přesně tak, jak je napsaný, končící výsledkem, který uživatel může ověřit — URL, která odpoví, soubor, který se objeví, výstup odpovídající ukázanému úryvku.

Plus povinná, zdrojovaná sekce omezení (vytažená z komentářů TODO/FIXME, chybových větví, prázdných zaslepovačů) a režim audit-first, který z existujícího README nejdřív odstraní zastaralá tvrzení, teprve pak sáhne na styl.

Benchmark: 3 reálné repozitáře, každý příkaz skutečně spuštěný

Vybrali jsme tři malé OSS projekty s tenkými README a zamkli každý na commit SHA: Node CLI (crossplatform-killport), Python CLI/knihovnu (python-shaarli-client) a Flask webovou službu (csrgenerator.com). Na repozitář dva agenti — jeden baseline, jeden s nejdřív přečteným skillem — stejný model, stejný promt, jediný rozdíl v tom, jestli byl SKILL.md v kontextu. Každý příkaz v tabulce níže byl spuštěný na reálném stroji (macOS 14, node v24.7.0, python3 3.13.1); příkazy, jejichž runtime chyběl (Docker) nebo potřebovaly živou externí službu, byly vyloučené z jmenovatele spustitelnosti a ověřené staticky místo toho.

Metrika (součet za 3 repozitáře)	Baseline	Skill
Vymyšlená tvrzení (nižší = lepší)	2	1
Spustitelnost příkazů	20/24 (83 %)	15/17 (88 %)
Kompletnost sekcí	14/18	18/18
Slepá preference	0/3	3/3
Průměrná důvěra (1–5)	3,67	4,67

Směr je konzistentní napříč všemi třemi repozitáři u kompletnosti a preference. Skill zasáhl 6/6 sekcí pokaždé; baseline neposlala sekci omezení na žádném ze tří repozitářů — jednoznačně největší mezera v kompletnosti. A byla preferovaná na všech třech, s celým bodem důvěry navrch.

Kde si to skill skutečně zasloužil — a kde uklouzl

Číslo vymyšlených tvrzení si zaslouží poctivost, protože je to titulek, u kterého byste čekali drtivou převahu, a ta se nekoná. 2 versus 1 je úzká mezera, a tady je proč: oba agenti bez skillu se silně opírali o existující přesnou prózu v USAGE.md/docs/, takže zdědili správný obsah zadarmo. Dvě chyby baseline byly přesně to selhání, na které skill cílí — zastaralý požadavek Python 3.4+, který si odporuje s vlastní testovací maticí projektu, a dvě vymyšlená prostředí tox (py34/py36), která v tox.ini neexistují. Tvrzení doplněná podle vzoru „takový projekt to obvykle má", ne podle kódu. Agent se skillem stejné tvrzení 3.4 zachytil a přeřadil ho na zdrojované omezení místo tvrzení.

A skill si nechal vlastní jediný výmysl v reportu, místo aby ho skryl. U csrgenerator jeho tabulka polí tvrdila, že prázdná hodnota CN vrací HTTP 400. Chybějící CN je skutečně 400 — ale prázdná narazí na vlastní raise KeyError("CN cannot be empty") kódu, které je neošetřené a vrací HTTP 500 (ověřeno živě). Jedna špatná behaviorální podrobnost v buňce tabulky, v běhu, který jinak spustil pytest (23 prošlo, přesná shoda) a reálné vygenerování CSR přes curl. Skill není kouzlo; je to disciplína, a disciplína má zbytkovou chybovost. Zapsali jsme ji.

Kde byl skill jednoznačně ostřejší, bylo v ověřených konkrétních detailech: „pip install -e . nainstaloval requests==2.34.2 / PyJWT==2.13.0" přesně sedělo v čerstvém venv; omezení killportu (Windows shoduje jen LISTENING, bezpodmínečný SIGKILL, jeden port na spuštění) všechna vedla ke zdroji a průběh kill byl ověřený od začátku do konce. Tvrzení, která vzešla z běhu, ne z odhadu.

Poctivé výhrady

Naše metodika vyžaduje slabiny vytištěné vedle výher, a reálné tu jsou.

Jeden hodnotitel, ne panel tří vývojářů. Řádky preference a důvěry jsou jeden expertní úsudek autora benchmarku, provedený s otevřeným zdrojem. Protokol počítá s panelem ≥3 nezávislých hodnotitelů; ten v tomhle harness nebyl dostupný. Berte ty dva řádky jako orientační, ne jako výsledek s víc hodnotiteli, který design specifikuje.

Mezera ve vymýšlení je úzká svou podstatou. Protože oba baseliny znovupoužily přesnou dokumentaci repozitáře, měla baseline méně příležitostí něco vymyslet. U repozitáře bez existující dokumentace by se mezera pravděpodobně rozšířila — ale reportujeme, co ukázaly tyhle tři repozitáře, což je 2 vs. 1, a N=3 je jen orientační.

Spouštění příkazů závisí na prostředí. Když agentův stroj projekt nemůže spustit, příkazy se ověří staticky proti manifestům a označí jako nespuštěné v logu — slabší než reálný běh, a takhle to označujeme.

Instalace

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

Restartujte Claude Code. Spouští se na „napiš README", „zdokumentuj tenhle repozitář", „vytvoř/přepiš README.md" a žádosti o review nebo audit README — a nezasahuje do celých dokumentačních webů, generování API referencí a changelogů. Patří do naší disciplinární série: token-discipline snižuje, co úkol stojí, research-discipline snižuje, co si výzkum splete, a tenhle snižuje, co vaše dokumentace vymýšlí.

FAQ

Čím se to liší od generátoru README, jako je readme-ai? Generátory produkují strukturu a přesnost přehazují na vás — jejich vlastní dokumentace vám řekne, ať výstup zkontrolujete. Tenhle skill to obrací: nejdřív čte kód, každé ověřitelné tvrzení vyhledá proti zdroji, spustí každý zdokumentovaný příkaz na čistém checkoutu a dá vám ověřovací log, abyste si mohli jeho práci zkontrolovat. Struktura je snadná část; skill věnuje úsilí pravdě.

Co přesně je ten ověřovací log? Samostatný artefakt v odpovědi (necommitovaný), který mapuje každou tvrzenou funkci na soubor:řádek ve zdroji a označí každý příkaz jako spuštěno ✓ nebo nespuštěno — ověřeno proti <manifestu>, plus cokoli záměrně vynechané kvůli chybějícím dokladům. Pokud by byl tenhle log prázdný, skill přeskočil svá vlastní první tři pravidla. Je to potvrzenka, díky které můžete próze věřit.

Nedělá pravidlo proti vymýšlení README kratší a fádnější? Ne — pravidla jsou napsaná tak, aby přidávala užitečný obsah, ne aby ho krátila. Povinná sekce omezení a ověřený quickstart jsou věci, které obyčejná README vynechávají. V benchmarku byla README skillu kompletnější (18/18 sekcí) než u baseline, ne tenčí.

Stačí jeden výmysl ve třech repozitářích? Je to lepší než dva u baseline, a je to poctivé ohledně zbytku — chování u prázdného CN špatně o jeden HTTP status kód, zapsané, ne schované. Pokud za vaším README stojí rozhodnutí, které je drahé zkazit, ověřovací log vám přesně řekne, která tvrzení zkontrolovat, což zabere minuty místo opětovného čtení celé codebase.