Een README waar elke claim herleidt naar de code

Een gegenereerde README is een vertrouwenstrucje. Hij leest vlot, somt de goedklinkende features op en geeft je installcommando's die correct ogen — en je kunt niet aan de tekst zien welke zinnen waar zijn. Het faalpatroon is altijd hetzelfde: een feature die de code niet heeft, een commando dat uit trainingsdata is aangevuld in plaats van uit de repo gekopieerd, en een verdachte afwezigheid van beperkingen. Wij runnen een directory die Claude-skills benchmarkt voor de kost, dus bouwden we de skill die we zelf wilden en maten toen of hij ook echt standhoudt.

Het resultaat is readme-discipline: negen afdwingbare regels waarvan het contract is dat een geclaimde feature eerst in de broncode gevonden moet zijn voordat hij geclaimd mag worden, elk commando gekopieerd wordt uit de echte manifesten van het project en uitgevoerd, en een eerlijke beperkingensectie verplicht is. Gratis en MIT-licensed: github.com/Skillproofdev/readme-discipline.

Het gat: 101 README-skills, geen enkele dwingt waarheid af

Voordat we een regel schreven, bekeken we het landschap — 101 README-verwante skills in een catalogus van 16.682 skills, plus readme-ai en de Standard Readme-spec. Elk daarvan optimaliseert iets anders dan nauwkeurigheid.

De grootste toegewijde README-skill (2,2k sterren) is een set doelgroepsjablonen. De Standard Readme-spec schrijft de volgorde van secties voor maar zegt niets over of de codeblokken draaien. De dominante CLI-generator levert gepolijste output en vertelt je dan, in zijn eigen docs, om die zelf te controleren op nauwkeurigheid — nauwkeurigheid wordt afgeschoven naar de mens. De rest zijn badge-maximizers en emoji-header-decorateurs. Structuur en uiterlijk zijn al vijf keer opgelost. "Elke claim herleidt naar code" en "elk voorbeeld is geverifieerd uitvoerbaar" kwamen als afdwingbare regels in geen enkele van hen voor.

Dat is de hele niche waar deze skill zit: niet READMEs mooier maken, ze waar maken.

Negen regels, drie ervan nieuw

De bekende onderdelen staan er — een vaste sectievolgorde (wat+waarom → installatie → snelstart → gebruik → configuratie → beperkingen), afstemming op één doelgroep, geen badge- of emoji-inflatie. De drie die niemand anders afdwingt:

1. Fabricatieverbod met bewijs. Elke falsifieerbare claim — een feature, een flag, een ondersteund platform — wordt eerst in de broncode gegrept. Gevonden → je mag hem claimen, in het eigen vocabulaire van de code. Niet gevonden → hij gaat de README niet in, niet afgezwakt, niet "doorgaans". Een verificatielog dat claim → bestand:regel koppelt, komt bij elke README mee.
2. Commando's zijn gekopieerd, nooit samengesteld. Elk commando in een codeblok komt van een echte plek: package.json-scripts, een Makefile-target, een CI-stap, de eigen --help van de CLI. Nooit npm run build omdat Node-projecten er meestal een hebben — check eerst scripts, draai het dan in een schone checkout.
3. Snelstart is een contract. Van clone tot één waarneembaar succes in ongeveer 60 seconden, elke stap exact zoals geschreven uitvoerbaar, eindigend in een resultaat dat de gebruiker kan controleren — een URL die reageert, een bestand dat verschijnt, output die overeenkomt met een getoonde snippet.

Plus een verplichte, onderbouwde beperkingensectie (gehaald uit TODO/FIXME-commentaar, foutpaden, lege stubs) en een audit-eerst-modus die verouderde claims uit een bestaande README strippt voordat de stijl wordt aangepakt.

De benchmark: 3 echte repo's, elk commando echt uitgevoerd

We kozen drie kleine OSS-projecten met dunne READMEs en bevroren elk bij een commit-SHA: een Node-CLI (crossplatform-killport), een Python CLI/library (python-shaarli-client), en een Flask-webservice (csrgenerator.com). Per repo: twee agents — één baseline, één die eerst de skill leest — zelfde model, zelfde prompt, het enige verschil is of de SKILL.md in context zat. Elk commando in onderstaande tabel is echt uitgevoerd op een echte machine (macOS 14, node v24.7.0, python3 3.13.1); commando's waarvan de runtime ontbrak (Docker) of die een live externe service nodig hadden, zijn uitgesloten van de uitvoerbaarheidsnoemer en in plaats daarvan statisch geverifieerd.

Metriek (totaal over 3 repo's)	Baseline	Skill
Verzonnen claims (lager beter)	2	1
Commando-uitvoerbaarheid	20/24 (83%)	15/17 (88%)
Sectievolledigheid	14/18	18/18
Blinde voorkeur	0/3	3/3
Gemiddeld vertrouwen (1–5)	3,67	4,67

De richting is consistent over alle drie de repo's op volledigheid en voorkeur. De skill haalde 6/6 secties elke keer; de baseline leverde op geen van de drie repo's een beperkingensectie — het grootste volledigheidsgat. En hij werd op alle drie verkozen, met een volle punt meer vertrouwen.

Waar de skill het echt verdiende — en waar hij uitgleed

Het fabricatiecijfer verdient eerlijkheid, want het is het cijfer waarvan je een ruime overwinning zou verwachten en dat is het niet. 2 tegenover 1 is een smal verschil, en dit is waarom: beide baseline-agents leunden zwaar op de bestaande, accurate USAGE.md/docs-teksten van de repo's, dus kregen ze correcte inhoud cadeau. De twee missers van de baseline waren precies het faalpatroon waar deze skill op mikt — een verouderde Python 3.4+-eis die de eigen testmatrix van het project tegenspreekt, en twee verzonnen tox-omgevingen (py34/py36) die niet in tox.ini bestaan. Claims aangevuld op patroon van "een project zoals dit," niet herleidbaar tot de code. De skill-arm ving diezelfde 3.4-claim en degradeerde hem tot een onderbouwde beperking in plaats van hem te beweren.

En de skill hield zijn eigen enige fabricatie in het rapport in plaats van hem te verbergen. Bij csrgenerator claimde zijn veldtabel dat een lege CN-waarde HTTP 400 teruggeeft. Een ontbrekende CN is inderdaad 400 — maar een lege raakt de eigen raise KeyError("CN cannot be empty") van de code, die onafgehandeld blijft en HTTP 500 teruggeeft (live geverifieerd). Eén verkeerd gedragsdetail in een tabelcel, in een run die verder pytest draaide (23 geslaagd, exacte match) en een echte curl-CSR-generatie. De skill is geen magie; het is discipline, en discipline heeft een resterend foutpercentage. We hebben het gelogd.

Waar de skill onbetwist scherper was: geverifieerde specifieke details. "pip install -e . installeerde requests==2.34.2 / PyJWT==2.13.0" kwam exact overeen met een verse venv; de killport-beperkingen (Windows LISTENING-only match, onvoorwaardelijke SIGKILL, één poort per aanroep) herleiden allemaal naar de code, met de kill-flow end-to-end geverifieerd. Claims die uit een run kwamen, niet uit een vermoeden.

De eerlijke kanttekeningen

Onze methodologie eist dat de zwaktes naast de winsten staan afgedrukt, en die zijn er hier echt.

Eén beoordelaar, geen panel van 3 developers. De voorkeurs- en vertrouwensregels zijn één expertoordeel van de benchmark-auteur, geveld met de bron open. Het protocol schrijft ≥3 onafhankelijke developer-beoordelaars voor; dat panel was niet beschikbaar in deze opzet. Lees die twee regels als indicatief, niet als het multi-beoordelaarsresultaat dat het ontwerp voorschrijft.

Het fabricatiegat is smal door constructie. Omdat beide baselines bestaande, accurate repo-docs hergebruikten, had de baseline minder kans om te verzinnen. Bij een repo zonder bestaande documentatie zou het gat waarschijnlijk breder zijn — maar we rapporteren wat deze drie repo's lieten zien, en dat is 2 tegen 1, en N=3 is alleen richtinggevend.

Commando-uitvoering hangt af van de omgeving. Als de machine van de agent het project niet kan draaien, worden commando's statisch geverifieerd tegen manifesten en als niet-uitgevoerd gemarkeerd in het log — zwakker dan een echte run, en we markeren het als zodanig.

Installatie

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

Herstart Claude Code. Hij triggert op "schrijf een README", "documenteer deze repo", "maak/herschrijf README.md", en README-review- of auditverzoeken — en blijft weg bij volledige docssites, API-referentiegeneratie en changelogs. Hij hoort bij onze discipline-reeks: token-discipline verlaagt wat een taak kost, research-discipline verlaagt wat research fout heeft, en deze verlaagt wat je documentatie verzint.

FAQ

Hoe verschilt dit van een README-generator zoals readme-ai? Generators leveren structuur en schuiven nauwkeurigheid naar jou af — hun eigen docs zeggen dat je de output moet controleren. Deze skill draait dat om: hij leest eerst de code, grept elke falsifieerbare claim tegen de broncode, draait elk gedocumenteerd commando in een schone checkout, en geeft je een verificatielog om zijn werk te controleren. Structuur is het makkelijke deel; de skill steekt zijn moeite in waarheid.

Wat is dat verificatielog precies? Een apart artefact in het antwoord (niet gecommit) dat elke geclaimde feature koppelt aan een bestand:regel in de broncode en elk commando markeert als gedraaid ✓ of niet uitgevoerd — geverifieerd tegen <manifest>, plus alles wat bewust is weggelaten wegens gebrek aan bewijs. Zou dat log leeg zijn, dan sloeg de skill zijn eigen eerste drie regels over. Het is het bewijs waarmee je het proza kunt vertrouwen.

Maakt de fabricatieregel READMEs korter en saaier? Nee — de regels zijn geschreven om nuttige inhoud toe te voegen, niet te schrappen. De verplichte beperkingensectie en de geverifieerde-commando-snelstart zijn dingen die generieke READMEs weglaten. In de benchmark waren de READMEs van de skill vollediger (18/18 secties) dan die van de baseline, niet dunner.

Is één fabricatie in drie repo's goed genoeg? Het is beter dan de twee van de baseline, en het is eerlijk over het restant — een leeg-CN-gedrag fout met één HTTP-statuscode, gelogd in plaats van verborgen. Als je README een beslissing onderbouwt die duur is om fout te doen, vertelt het verificatielog je precies welke claims je moet steekproefsgewijs controleren, wat minuten kost in plaats van de hele codebase herlezen.