En README där varje påstående spårar till koden

En genererad README är ett förtroendetrick. Den läses rent, listar rätt-klingande funktioner och ger dig installationskommandon som ser korrekta ut — och du kan inte avgöra genom att läsa den vilka meningar som är sanna. Felmönstret är alltid detsamma: en funktion koden inte har, ett kommando mönster-kompletterat från träningsdata istället för kopierat från repot, och en misstänkt frånvaro av begränsningar. Vi driver en katalog som benchmarkar Claude-skills på heltid, så vi byggde skillen vi ville ha och mätte sedan om den faktiskt håller.

Resultatet är readme-discipline: nio tvingande regler vars kontrakt är att en påstådd funktion måste hittas i källkoden innan den får påstås, att varje kommando är kopierat från projektets riktiga manifest och körts, och att en ärlig begränsningssektion är obligatorisk. Den är gratis och MIT-licensierad: github.com/Skillproofdev/readme-discipline.

Luckan: 101 README-skills, ingen tvingar fram sanning

Innan vi skrev en regel kartlade vi landskapet — 101 README-närliggande skills i en katalog på 16 682 skills, plus readme-ai och Standard Readme-specifikationen. Var och en av dem optimerar något annat än korrekthet.

Den största dedikerade README-skillen (2 200 stjärnor) är en uppsättning målgruppsmallar. Standard Readme-specifikationen kräver sektionsordning men säger inget om huruvida kodblocken faktiskt går att köra. Den dominerande CLI-generatorn producerar polerad utdata och säger sedan, i sin egen dokumentation, att du ska granska den för korrekthet själv — korrekthet läggs över på människan. Resten är badge-maximerare och emoji-rubrikdekoratörer. Struktur och utseende är lösta fem gånger om. "Varje påstående går att spåra till koden" och "varje exempel är verifierat körbart" fanns som tvingande regler i ingen av dem.

Det är hela nischen den här skillen tar: inte att göra README-filer snyggare, utan att göra dem sanna.

Nio regler, tre av dem nya

Det välbekanta finns här — en fast sektionsordning (vad+varför → installation → snabbstart → användning → konfiguration → begränsningar), kalibrering för en enda målgrupp, ingen badge- eller emoji-inflation. De tre ingen annan tvingar fram:

1. Förbud mot fabrikation, med kvitto. Varje falsifierbart påstående — en funktion, en flagga, en plattform som stöds — grep:as i källkoden först. Hittad → du får påstå den, med kodens eget ordval. Inte hittad → den kommer inte med i README, inte försiktigt formulerad, inte "vanligtvis." En verifieringslogg som mappar påstående → fil:rad levereras med varje README.
2. Kommandon kopieras, komponeras aldrig. Varje kommando i ett kodblock kommer från en verklig plats: package.json-skript, ett Makefile-mål, ett CI-steg, CLI:ns egen --help. Aldrig npm run build bara för att Node-projekt brukar ha ett — kolla scripts först, kör det sedan i en ren checkout.
3. Snabbstarten är ett kontrakt. Från klon till ett observerbart resultat på ungefär 60 sekunder, varje steg körbart exakt som skrivet, som slutar i ett resultat användaren kan kontrollera — en URL som svarar, en fil som dyker upp, utdata som matchar ett visat exempel.

Plus en obligatorisk, källbelagd begränsningssektion (hämtad från TODO/FIXME-kommentarer, felgrenar, tomma stubbar) och ett granskningsläge som strippar bort föråldrade påståenden ur en befintlig README innan den rör vid dess stil.

Benchmarket: 3 riktiga repon, varje kommando faktiskt kört

Vi valde tre små open source-projekt med tunna README-filer och fastställde varje vid en commit-SHA: en Node-CLI (crossplatform-killport), ett Python CLI/bibliotek (python-shaarli-client) och en Flask-webbtjänst (csrgenerator.com). Per repo, två agenter — en baslinje, en som läste skillen först — samma modell, samma prompt, enda skillnaden var om SKILL.md fanns i kontext. Varje kommando i tabellen nedan kördes på en riktig maskin (macOS 14, node v24.7.0, python3 3.13.1); kommandon vars körtid saknades (Docker) eller som krävde en levande extern tjänst uteslöts från nämnaren för körbarhet och verifierades statiskt istället.

Mått (summa över 3 repon)	Baslinje	Skill
Fabricerade påståenden (lägre bättre)	2	1
Kommandokörbarhet	20/24 (83%)	15/17 (88%)
Sektionsfullständighet	14/18	18/18
Blind preferens	0/3	3/3
Medelförtroende (1–5)	3,67	4,67

Riktningen är konsekvent över alla tre repon på fullständighet och preferens. Skillen träffade 6/6 sektioner varje gång; baslinjen levererade ingen begränsningssektion i något av de tre repona — det enskilt största fullständighetsgapet. Och den föredrogs på alla tre med en hel poängenhet mer förtroende.

Där skillen verkligen förtjänade det — och där den halkade

Fabrikationssiffran förtjänar ärlighet, för det är den siffra du väntat dig skulle bli en jordskredsseger, och det blev den inte. 2 mot 1 är ett smalt gap, och här är varför: båda baslinjeagenterna lutade sig tungt mot repots befintliga, korrekta USAGE.md/docs/-prosa, så de ärvde korrekt innehåll gratis. Baslinjens två missar var exakt det felmönster den här skillen siktar på — ett föråldrat krav på Python 3.4+ som motsägs av projektets egen testmatris, och två uppfunna tox-miljöer (py34/py36) som inte finns i tox.ini. Mönster-kompletterade påståenden som spårar till "ett projekt som det här," inte till koden. Skillgrenen fångade samma 3.4-påstående och nedgraderade det till en källbelagd begränsning istället för att påstå det.

Och skillen behöll sin egen enda fabrikation i rapporten istället för att gömma den. På csrgenerator påstod dess fälttabell att ett tomt CN-värde returnerar HTTP 400. Ett saknat CN är faktiskt 400 — men ett tomt ett träffar kodens egen raise KeyError("CN cannot be empty"), som är ohanterad och returnerar HTTP 500 (verifierat live). En felaktig beteendedetalj i en tabellcell, i en körning som annars körde pytest (23 godkända, exakt match) och en riktig curl-generering av CSR. Skillen är ingen magi; den är disciplin, och disciplin har en kvarvarande felfrekvens. Vi loggade den.

Där skillen var otvetydigt vassare var verifierade specifikationer: "pip install -e . installerade requests==2.34.2 / PyJWT==2.13.0" matchade en ny venv exakt; begränsningarna för killport (Windows LISTENING-bara matchning, ovillkorlig SIGKILL, en port per anrop) spårade alla till källkoden med kill-flödet verifierat ände till ände. Påståenden som kom från en körning, inte en gissning.

De ärliga förbehållen

Vår metodik kräver att svagheterna skrivs ut bredvid vinsterna, och det finns riktiga sådana här.

En enda bedömare, ingen panel med 3 utvecklare. Rad för preferens och förtroende är ett enda expertomdöme från benchmarkets författare, gjort med källkoden öppen. Protokollet kräver ≥3 oberoende utvecklarbedömare; den panelen fanns inte tillgänglig i den här riggen. Läs de två raderna som vägledande, inte som det panelresultat designen specificerar.

Fabrikationsgapet är smalt av konstruktion. Eftersom båda baslinjerna återanvände korrekt repo-dokumentation hade baslinjen färre chanser att hitta på. På ett repo utan befintlig dokumentation skulle gapet troligen bli bredare — men vi rapporterar vad de här tre repona visade, vilket är 2 mot 1, och N=3 är enbart riktningsgivande.

Kommandokörning beror på miljön. När agentens maskin inte kan köra projektet verifieras kommandon statiskt mot manifest och flaggas som okörda i loggen — svagare än en riktig körning, och vi markerar det som sådant.

Installation

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

Starta om Claude Code. Den triggas av "skriv en README", "dokumentera det här repot", "skapa/skriv om README.md" och begäranden om README-granskning eller -revision — och håller sig undan från fullständiga dokumentationssajter, generering av API-referens och changelogs. Den ansluter till vår disciplinserie: token-discipline minskar vad en uppgift kostar, research-discipline minskar vad research har fel om, och den här minskar vad din dokumentation hittar på.

FAQ

Hur skiljer sig det här från en README-generator som readme-ai? Generatorer producerar struktur och lägger över korrekthet på dig — deras egen dokumentation säger åt dig att granska utdata. Den här skillen vänder på det: den läser koden först, grep:ar varje falsifierbart påstående mot källkoden, kör varje dokumenterat kommando i en ren checkout och ger dig en verifieringslogg så du kan kontrollera dess arbete. Struktur är den enkla delen; skillen lägger sin ansträngning på sanning.

Vad är verifieringsloggen, exakt? En separat artefakt i svaret (inte incheckad) som mappar varje påstådd funktion till en fil:rad i källkoden och märker varje kommando som körd ✓ eller ej körd — verifierad mot <manifest>, plus allt som medvetet utelämnades i brist på bevis. Om den loggen skulle vara tom hoppade skillen över sina egna tre första regler. Det är kvittot som låter dig lita på prosan.

Gör fabrikationsregeln README:n kortare och blekare? Nej — reglerna är skrivna för att lägga till användbart innehåll, inte skära bort det. Den obligatoriska begränsningssektionen och den verifierade snabbstarten är sådant generiska README-filer utelämnar. I benchmarket var skillens README-filer mer kompletta (18/18 sektioner) än baslinjens, inte tunnare.

Räcker en fabrikation i tre repon? Det är bättre än baslinjens två, och det är ärligt om resten — ett tomt CN-beteende fel med en HTTP-statuskod, loggat istället för begravt. Om din README backar upp ett beslut som är dyrt att få fel talar verifieringsloggen om exakt vilka påståenden du ska stickprovskontrollera, vilket tar minuter istället för att läsa om hela kodbasen.