En README hvor hver påstand spores til koden

En genereret README er et tillidsnummer. Den læser rent, lister de rigtigt-lydende funktioner og giver dig installationskommandoer, der ser korrekte ud — og du kan ikke se ved at læse den, hvilke sætninger der er sande. Fejlmåden er altid den samme: en funktion koden ikke har, en kommando mønstergenereret fra træningsdata i stedet for kopieret fra repoet, og et mistænkeligt fravær af enhver begrænsning. Vi driver et katalog, der benchmark-tester Claude-skills til daglig, så vi byggede skillen, vi ønskede, og målte derefter om den faktisk holder.

Resultatet er readme-discipline: ni håndhævelige regler, hvis kontrakt er, at en påstået funktion skal findes i kildekoden, før den må påstås, hver kommando er kopieret fra projektets rigtige manifester og udført, og et ærligt begrænsningsafsnit er obligatorisk. Den er gratis og MIT-licenseret: github.com/Skillproofdev/readme-discipline.

Hullet: 101 README-skills, ingen håndhæver sandhed

Før vi skrev en regel, gennemgik vi landskabet — 101 README-tilstødende skills inden i et katalog på 16,682 skills, plus readme-ai og Standard Readme-specifikationen. Hver eneste af dem optimerer noget andet end nøjagtighed.

Den største dedikerede README-skill (2.2k stjerner) er et sæt målgruppeskabeloner. Standard Readme-specen påbyder afsnits-rækkefølge, men siger intet om, hvorvidt kodeblokkene kører. Den dominerende CLI-generator producerer poleret output og fortæller dig så, i sin egen dokumentation, at du selv skal gennemgå det for nøjagtighed — nøjagtighed lægges over på mennesket. Resten er badge-maksimerere og emoji-header-dekoratører. Struktur og udseende er løst fem gange over. "Hver påstand spores til kode" og "hvert eksempel er verificeret kørbart" optrådte som håndhævelige regler i ingen af dem.

Det er hele nichen, den her skill besætter: ikke at gøre README'er pænere, at gøre dem sande.

Ni regler, tre af dem nye

De velkendte dele er her — en fast afsnitsrækkefølge (what+why → install → quickstart → usage → config → limitations), enkelt-målgruppe-kalibrering, ingen badge- eller emoji-inflation. De tre, ingen andre håndhæver:

1. Opdigtelsesforbud med kvitteringer. Hver falsificerbar påstand — en funktion, et flag, en understøttet platform — grep'es i kilden først. Fundet → du må påstå det, i kodens eget ordforråd. Ikke fundet → det kommer ikke i README'en, hverken hedget eller som "typically." En verifikationslog, der kortlægger claim → file:line, følger med hver README.
2. Kommandoer kopieres, komponeres aldrig. Hver code-blok-kommando kommer fra et rigtigt sted: package.json-scripts, et Makefile-mål, et CI-trin, CLI'ens eget --help. Aldrig npm run build, fordi Node-projekter normalt har ét — tjek scripts først, kør det så i en ren checkout.
3. Quickstart er en kontrakt. Fra klon til én observerbar succes på omkring 60 sekunder, hvert trin udførbart nøjagtigt som skrevet, endende i et resultat, brugeren kan tjekke — en URL, der svarer, en fil, der dukker op, output, der matcher et vist uddrag.

Plus et obligatorisk, kildebaseret begrænsningsafsnit (hentet fra TODO/FIXME-kommentarer, fejlgrene, tomme stubs) og en audit-first-tilstand, der fjerner forældede påstande fra en eksisterende README, før den rører ved dens stil.

Benchmarken: 3 rigtige repoer, hver kommando faktisk kørt

Vi udvalgte tre små OSS-projekter med tynde README'er og fastfrøs hvert 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 der læste skillen først — samme model, samme prompt, den eneste forskel var, om SKILL.md var i konteksten. Hver kommando i tabellen nedenfor blev udført på en rigtig maskine (macOS 14, node v24.7.0, python3 3.13.1); kommandoer, hvis runtime manglede (Docker), eller som krævede en live ekstern tjeneste, blev udelukket fra den udførbare nævner og i stedet verificeret statisk.

Metrik (samlet over 3 repoer)	Baseline	Skill
Opdigtede påstande (lavere er bedre)	2	1
Kommando-udførbarhed	20/24 (83%)	15/17 (88%)
Afsnitsfuldstændighed	14/18	18/18
Blind præference	0/3	3/3
Gennemsnitlig tillid (1–5)	3.67	4.67

Retningen er konsistent på tværs af alle tre repoer på fuldstændighed og præference. Skillen ramte 6/6 afsnit hver gang; baseline leverede intet begrænsningsafsnit på nogen af de tre repoer — det enkeltstørste fuldstændighedshul. Og den blev foretrukket på alle tre med en hel tillidspoint mere.

Hvor skillen for alvor fortjente det — og hvor den gled

Opdigtelsestallet fortjener ærlighed, for det er den overskrift, du ville forvente var en jordskredssejr, og det er den ikke. 2 mod 1 er et smalt gab, og her er hvorfor: begge baseline-agenter lænede sig kraftigt op ad repoernes eksisterende nøjagtige USAGE.md/docs/-prosa, så de arvede korrekt indhold gratis. Baselines to fejl var præcis den fejlmåde, den her skill sigter mod — et forældet Python 3.4+-krav modsagt af projektets egen testmatrix, og to opfundne tox-miljøer (py34/py36), der ikke findes i tox.ini. Mønstergenererede påstande, der kan spores til "et projekt som det her," ikke til koden. Skill-armen fangede samme 3.4-påstand og nedgraderede den til en kildebaseret begrænsning i stedet for at påstå den.

Og skillen beholdt sin egen ene opdigtelse i rapporten frem for at skjule den. På csrgenerator påstod dens felttabel, at en tom CN-værdi returnerer HTTP 400. En manglende CN er ganske rigtigt 400 — men en tom rammer kodens egen raise KeyError("CN cannot be empty"), som er uhåndteret og returnerer HTTP 500 (verificeret live). Én forkert adfærdsdetalje i en tabelcelle, i en kørsel, der ellers udførte pytest (23 beståede, eksakt match) og en rigtig curl-CSR-generering. Skillen er ikke magi; det er disciplin, og disciplin har en resterende fejlrate. Vi loggede den.

Hvor skillen var utvetydigt skarpere, var verificerede detaljer: "pip install -e . installed requests==2.34.2 / PyJWT==2.13.0" matchede en frisk venv præcist; killport-begrænsningerne (Windows LISTENING-kun-match, ubetinget SIGKILL, én-port-per-kald) sporede alle til kilden med drab-forløbet verificeret ende til ende. Påstande, der kom fra en kørsel, ikke fra en anelse.

De ærlige forbehold

Vores metode kræver, at svaghederne trykkes ved siden af sejrene, og der er reelle her.

Én bedømmer, ikke et 3-udvikler-panel. Præference- og tillidsrækkerne er én ekspertvurdering af benchmark-forfatteren, foretaget med kilden åben. Protokollen kalder på ≥3 uafhængige udviklerbedømmere; det panel var ikke tilgængeligt i den her ramme. Læs de to rækker som vejledende, ikke som det multi-bedømmer-resultat, designet foreskriver.

Opdigtelsesgabet er smalt af konstruktion. Fordi begge baselines genbrugte nøjagtig repo-dokumentation, havde baseline færre chancer for at opfinde. På et repo uden eksisterende dokumentation ville gabet sandsynligvis udvide sig — men vi rapporterer, hvad de her tre repoer viste, hvilket er 2 mod 1, og N=3 er kun retningsgivende.

Kommandoudførelse afhænger af miljøet. Når agentens maskine ikke kan køre projektet, verificeres kommandoer statisk mod manifester og flages som ikke-udført i loggen — svagere end en rigtig kørsel, og vi markerer det som sådan.

Installation

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

Genstart Claude Code. Den udløses af "write a README", "document this repo", "create/rewrite README.md" og README-review- eller audit-anmodninger — og holder sig væk fra fulde dokumentationssider, API-referencegenerering og changelogs. Den slutter sig til vores disciplin-serie: token-discipline skærer i, hvad en opgave koster, research-discipline skærer i, hvad research tager fejl om, og den her skærer i, hvad din dokumentation opdigter.

FAQ

Hvordan adskiller det her sig fra en README-generator som readme-ai? Generatorer producerer struktur og lægger nøjagtighed over på dig — deres egen dokumentation fortæller dig at gennemgå outputtet. Den her skill vender det om: den læser koden først, grep'er hver falsificerbar påstand mod kilden, kører hver dokumenteret kommando i en ren checkout og giver dig en verifikationslog, så du kan tjekke dens arbejde. Struktur er den lette del; skillen bruger sin indsats på sandhed.

Hvad er verifikationsloggen, helt præcist? Et separat element i svaret (ikke committet), der kortlægger hver påstået funktion til en file:line i kilden og markerer hver kommando som ran ✓ eller not executed — verified against <manifest>, plus alt bevidst udeladt af mangel på bevis. Hvis den log ville være tom, sprang skillen sine egne første tre regler over. Det er kvitteringen, der lader dig stole på prosaen.

Gør opdigtelsesreglen README'en kortere og mere kedelig? Nej — reglerne er skrevet til at tilføje nyttigt indhold, ikke skære det. Det obligatoriske begrænsningsafsnit og den verificerede quickstart er ting, generiske README'er udelader. I benchmarken var skillens README'er mere komplette (18/18 afsnit) end baselines, ikke tyndere.

Er én opdigtelse i tre repoer godt nok? Det er bedre end baselines to, og det er ærligt om resten — en tom-CN-adfærd forkert med én HTTP-statuskode, logget frem for begravet. Hvis din README understøtter en beslutning, der er dyr at tage fejl på, fortæller verifikationsloggen dig præcis, hvilke påstande du skal stikprøvetjekke, hvilket tager minutter i stedet for at genlæse hele kodebasen.