En README der hver påstand spores til koden

En generert README er et tillitstriks. Den leser rent, lister opp funksjoner som høres riktige ut, og gir deg installasjonskommandoer som ser korrekte ut — og du kan ikke se ved å lese den hvilke setninger som er sanne. Feilmåten er alltid den samme: en funksjon koden ikke har, en kommando mønster-fullført fra treningsdata i stedet for kopiert fra repoet, og et mistenkelig fravær av begrensninger. Vi driver en katalog som benchmarker Claude-skills til daglig, så vi bygde skillen vi ønsket oss og målte så om den faktisk holder.

Resultatet er readme-discipline: ni håndhevbare regler hvis kontrakt er at en påstått funksjon må finnes i kildekoden før den kan påstås, hver kommando er kopiert fra prosjektets ekte manifester og kjørt, og en ærlig begrensninger-seksjon er obligatorisk. Den er gratis og MIT-lisensiert: github.com/Skillproofdev/readme-discipline.

Gapet: 101 README-skills, ingen håndhever sannhet

Før vi skrev en eneste regel kartla vi hele feltet — 101 README-tilstøtende skills inne i en katalog på 16 682 skills, pluss readme-ai og Standard Readme-spesifikasjonen. Hver eneste én optimerer noe annet enn nøyaktighet.

Den største dedikerte README-skillen (2 200 stjerner) er et sett med målgruppe-maler. Standard Readme-spesifikasjonen pålegger seksjons-rekkefølge, men sier ingenting om kodeblokkene faktisk kjører. Den dominerende CLI-generatoren produserer polert resultat og forteller deg så, i sin egen dokumentasjon, å sjekke det for nøyaktighet selv — nøyaktigheten flyttes over på mennesket. Resten er badge-maksimerere og emoji-header-dekoratører. Struktur og utseende er løst fem ganger om. «Hver påstand spores til koden» og «hvert eksempel er verifisert kjørbart» fantes som håndhevbare regler i ingen av dem.

Det er hele nisjen denne skillen okkuperer: ikke å gjøre README-er penere, men å gjøre dem sanne.

Ni regler, tre av dem nye

De kjente delene er her — en fast seksjonsrekkefølge (hva+hvorfor → installasjon → hurtigstart → bruk → konfigurasjon → begrensninger), kalibrering mot én målgruppe, ingen badge- eller emoji-inflasjon. De tre ingen andre håndhever:

1. Oppdiktingsforbud med kvittering. Hver falsifiserbar påstand — en funksjon, et flagg, en støttet plattform — grepes i kildekoden først. Funnet → du kan påstå det, i kodens eget vokabular. Ikke funnet → det går ikke inn i README-en, ikke tvetydig, ikke «typisk». En verifiseringslogg som kobler påstand → fil:linje følger med hver README.
2. Kommandoer kopieres, komponeres aldri. Hver kodeblokk-kommando kommer fra et ekte sted: package.json-scripts, et Makefile-mål, et CI-steg, CLI-ens eget --help. Aldri npm run build fordi Node-prosjekter vanligvis har ett — sjekk scripts først, kjør det så i en ren utsjekking.
3. Hurtigstart er en kontrakt. Fra klone til ett observerbart resultat på rundt 60 sekunder, hvert steg kjørbart nøyaktig som skrevet, og ender i et resultat brukeren kan sjekke — en URL som svarer, en fil som dukker opp, resultat som matcher et vist utdrag.

Pluss en obligatorisk, kildesporet begrensninger-seksjon (hentet fra TODO/FIXME-kommentarer, feilgrener, tomme stubber) og en revisjon-først-modus som fjerner utdaterte påstander fra en eksisterende README før den rører ved stilen.

Benchmarken: 3 ekte repoer, hver kommando faktisk kjørt

Vi valgte tre små OSS-prosjekter med tynne README-er og fastlåste hver ved en commit-SHA: en Node-CLI (crossplatform-killport), et Python-CLI/-bibliotek (python-shaarli-client), og en Flask-webtjeneste (csrgenerator.com). Per repo, to agenter — én baseline, én som leser skillen først — samme modell, samme prompt, den eneste forskjellen var om SKILL.md var i kontekst. Hver kommando i tabellen under ble kjørt på en ekte maskin (macOS 14, node v24.7.0, python3 3.13.1); kommandoer der kjøretiden manglet (Docker) eller som trengte en levende ekstern tjeneste, ble utelatt fra kjørbarhets-nevneren og i stedet verifisert statisk.

Metrikk (samlet over 3 repoer)	Baseline	Skill
Oppdiktede påstander (lavere bedre)	2	1
Kommando-kjørbarhet	20/24 (83 %)	15/17 (88 %)
Seksjonsfullstendighet	14/18	18/18
Blind preferanse	0/3	3/3
Snitt-tillit (1–5)	3.67	4.67

Retningen er konsistent på tvers av alle tre repoer på fullstendighet og preferanse. Skillen traff 6/6 seksjoner hver gang; baseline leverte ingen begrensninger-seksjon på noen av de tre repoene — det enkeltstore fullstendighetsgapet. Og den ble foretrukket på alle tre, med et helt poeng mer tillit.

Der skillen faktisk fortjente det — og der den glapp

Oppdiktingstallet fortjener ærlighet, fordi det er hovedtallet du ville forventet var et skred, og det er det ikke. 2 mot 1 er et smalt gap, og her er hvorfor: begge baseline-agentene lente seg tungt på repoenes eksisterende, nøyaktige USAGE.md/docs/-prosa, så de arvet korrekt innhold gratis. Baselinens to bommer var nøyaktig den feilmåten denne skillen retter seg mot — et utdatert Python 3.4+-krav som motsies av prosjektets egen testmatrise, og to oppfunne tox-miljøer (py34/py36) som ikke finnes i tox.ini. Mønster-fullførte påstander som spores til «et prosjekt som dette», ikke til koden. Skill-armen fanget den samme 3.4-påstanden og nedgraderte den til en kildesporet begrensning i stedet for å slå den fast.

Og skillen holdt sin egen ene oppdikting i rapporten i stedet for å skjule den. På csrgenerator påsto felttabellen dens at en tom CN-verdi returnerer HTTP 400. En manglende CN er riktignok 400 — men en tom en treffer kodens egen raise KeyError("CN cannot be empty"), som er uhåndtert og returnerer HTTP 500 (verifisert live). Én feil oppførselsdetalj i en tabellcelle, i en kjøring som ellers utførte pytest (23 bestått, eksakt match) og en ekte curl-CSR-generering. Skillen er ikke magi; den er disiplin, og disiplin har en gjenværende feilrate. Vi logget den.

Der skillen var utvetydig skarpere, var på verifiserte detaljer: «pip install -e . installerte requests==2.34.2 / PyJWT==2.13.0» matchet et ferskt venv eksakt; killport-begrensningene (Windows LISTENING-only-match, ubetinget SIGKILL, én port per kjøring) sporet alle til koden med kill-flyten verifisert fra ende til annen. Påstander som kom fra en kjøring, ikke en magefølelse.

De ærlige forbeholdene

Vår metodikk krever at svakhetene trykkes ved siden av seirene, og det er reelle her.

Én bedømmer, ikke et panel på 3 utviklere. Preferanse- og tillitsradene er én ekspertvurdering av benchmark-forfatteren, gjort med kilden åpen. Protokollen krever ≥3 uavhengige utvikler-bedømmere; det panelet var ikke tilgjengelig i dette oppsettet. Les de to radene som veiledende, ikke som det multi-bedømmer-resultatet designet spesifiserer.

Oppdiktingsgapet er smalt av natur. Fordi begge baseline-agentene gjenbrukte nøyaktig repo-dokumentasjon, hadde baseline færre sjanser til å dikte opp. På et repo uten eksisterende dokumentasjon ville gapet trolig bli bredere — men vi rapporterer det disse tre repoene viste, som er 2 mot 1, og N=3 er kun retningsgivende.

Kommandokjøring avhenger av miljøet. Når agentens maskin ikke kan kjøre prosjektet, verifiseres kommandoer statisk mot manifester og flagges som ikke-kjørt i loggen — svakere enn en ekte kjøring, og vi merker det som sådan.

Installasjon

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

Start Claude Code på nytt. Den trigger på «skriv en README», «dokumenter dette repoet», «lag/skriv om README.md», og README-review- eller revisjonsforespørsler — og holder seg unna fullstendige dokumentasjonsnettsteder, API-referansegenerering og changelogs. Den inngår i vår disiplin-serie: token-discipline kutter hva en oppgave koster, research-discipline kutter hva research bommer på, og denne kutter hva dokumentasjonen din dikter opp.

Ofte stilte spørsmål

Hvordan skiller dette seg fra en README-generator som readme-ai? Generatorer produserer struktur og flytter nøyaktigheten over på deg — deres egen dokumentasjon ber deg sjekke resultatet selv. Denne skillen snur det: den leser koden først, greper hver falsifiserbar påstand mot kilden, kjører hver dokumentert kommando i en ren utsjekking, og gir deg en verifiseringslogg så du kan sjekke arbeidet dens. Struktur er den enkle delen; skillen bruker innsatsen sin på sannhet.

Hva er verifiseringsloggen, egentlig? Et separat artefakt i svaret (ikke committet) som kobler hver påstått funksjon til en fil:linje i kildekoden og merker hver kommando som kjørt ✓ eller ikke kjørt — verifisert mot <manifest>, pluss alt bevisst utelatt av mangel på bevis. Hvis den loggen ville vært tom, brøt skillen sine egne tre første regler. Det er kvitteringen som lar deg stole på prosaen.

Gjør oppdiktingsregelen README-en kortere og blassere? Nei — reglene er skrevet for å legge til nyttig innhold, ikke kutte det. Den obligatoriske begrensninger-seksjonen og den verifiserte-kommando-hurtigstarten er ting generiske README-er utelater. I benchmarken var skillens README-er mer fullstendige (18/18 seksjoner) enn baselinens, ikke tynnere.

Er én oppdikting i tre repoer godt nok? Det er bedre enn baselinens to, og det er ærlig om resten — en tom-CN-oppførsel feil med én HTTP-statuskode, logget i stedet for skjult. Hvis README-en din støtter en beslutning som er kostbar å ta feil, forteller verifiseringsloggen deg nøyaktig hvilke påstander du bør stikkprøve, noe som tar minutter i stedet for å lese hele kodebasen på nytt.