Un README dove ogni affermazione risale al codice

Un README generato è un trucco di fiducia. Si legge bene, elenca feature che suonano giuste, e ti dà comandi di installazione che sembrano corretti — e non puoi capire leggendolo quali frasi sono vere. Il fallimento è sempre lo stesso: una feature che il codice non ha, un comando ricostruito per pattern dai dati di training invece che copiato dal repo, e una sospetta assenza di qualsiasi limitazione. Gestiamo una directory che testa le skill di Claude sul campo, quindi abbiamo costruito la skill che volevamo e poi misurato se regge davvero.

Il risultato è readme-discipline: nove regole vincolanti il cui contratto è che una feature dichiarata deve essere trovata nel sorgente prima di poter essere dichiarata, ogni comando è copiato dai manifest reali del progetto ed eseguito, e una sezione limitazioni onesta è obbligatoria. È gratis e con licenza MIT: github.com/Skillproofdev/readme-discipline.

Il vuoto: 101 skill per README, nessuna applica la verità

Prima di scrivere una regola abbiamo passato in rassegna il panorama — 101 skill legate ai README in un catalogo di 16.682 skill, più readme-ai e la spec Standard Readme. Ognuna di loro ottimizza qualcosa di diverso dall'accuratezza.

La skill README dedicata più grande (2,2k stelle) è un insieme di template per pubblico diverso. La spec Standard Readme impone l'ordine delle sezioni ma non dice nulla su se i blocchi di codice funzionano davvero. Il generatore CLI dominante produce output curato e poi ti dice, nella sua stessa documentazione, di rivederlo tu per l'accuratezza — l'accuratezza viene scaricata sull'umano. Il resto sono massimizzatori di badge e decoratori di header con emoji. Struttura ed estetica sono risolte cinque volte. "Ogni affermazione risale al codice" e "ogni esempio è verificato eseguibile" non comparivano come regole vincolanti in nessuna di loro.

Questo è l'intera nicchia occupata da questa skill: non rendere i README più belli, renderli veri.

Nove regole, tre delle quali inedite

Le parti familiari ci sono — un ordine di sezioni fisso (cosa+perché → installazione → quickstart → uso → configurazione → limitazioni), calibrazione su un pubblico unico, niente inflazione di badge o emoji. Le tre che nessun altro applica:

1. Divieto di invenzione con ricevuta. Ogni affermazione falsificabile — una feature, un flag, una piattaforma supportata — viene prima cercata con grep nel sorgente. Trovata → puoi dichiararla, nel vocabolario stesso del codice. Non trovata → non entra nel README, non addolcita, non "in genere". Un log di verifica che mappa affermazione → file:riga accompagna ogni README.
2. I comandi si copiano, mai si compongono. Ogni comando in blocco viene da un posto reale: gli script di package.json, un target di Makefile, uno step CI, l'--help della CLI stessa. Mai npm run build solo perché i progetti Node di solito ne hanno uno — controlla prima scripts, poi eseguilo in un checkout pulito.
3. Il quickstart è un contratto. Dal clone a un successo osservabile in circa 60 secondi, ogni passo eseguibile esattamente come scritto, terminando in un risultato che l'utente può verificare — un URL che risponde, un file che compare, un output che combacia con uno snippet mostrato.

Più una sezione limitazioni obbligatoria e sourced (ricavata da commenti TODO/FIXME, rami di errore, stub vuoti) e una modalità audit-first che rimuove le affermazioni obsolete da un README esistente prima di toccarne lo stile.

Il benchmark: 3 repo reali, ogni comando davvero eseguito

Abbiamo scelto tre piccoli progetti OSS con README scarni e congelato ciascuno a uno SHA: una CLI Node (crossplatform-killport), una CLI/libreria Python (python-shaarli-client), e un servizio web Flask (csrgenerator.com). Per repo, due agenti — uno a secco, uno che legge prima la skill — stesso modello, stesso prompt, l'unica differenza è se il SKILL.md era nel contesto. Ogni comando nella tabella qui sotto è stato eseguito su una macchina reale (macOS 14, node v24.7.0, python3 3.13.1); i comandi il cui runtime era assente (Docker) o che richiedevano un servizio esterno live sono stati esclusi dal denominatore di eseguibilità e verificati staticamente.

Metrica (aggregata su 3 repo)	Baseline	Skill
Affermazioni inventate (meno è meglio)	2	1
Eseguibilità dei comandi	20/24 (83%)	15/17 (88%)
Completezza sezioni	14/18	18/18
Preferenza cieca	0/3	3/3
Fiducia media (1–5)	3,67	4,67

La direzione è coerente su tutti e tre i repo per completezza e preferenza. La skill ha raggiunto 6/6 sezioni ogni volta; il baseline non ha prodotto una sezione limitazioni su nessuno dei tre repo — il vuoto di completezza più grande in assoluto. Ed è stata preferita su tutti e tre con un punto pieno in più di fiducia.

Dove la skill se l'è davvero guadagnato — e dove è scivolata

Il numero delle invenzioni merita onestà, perché è il dato che ti aspetteresti fosse una vittoria schiacciante e non lo è. 2 contro 1 è un divario stretto, ed ecco perché: entrambi gli agenti baseline si sono appoggiati pesantemente alla prosa accurata già esistente nei USAGE.md/docs/ dei repo, quindi hanno ereditato contenuto corretto gratis. I due errori del baseline erano esattamente il fallimento che questa skill combatte — un requisito obsoleto Python 3.4+ contraddetto dalla matrice di test del progetto stesso, e due ambienti tox inventati (py34/py36) che non esistono in tox.ini. Affermazioni ricostruite per pattern, riconducibili a "un progetto come questo", non al codice. Il braccio con skill ha colto la stessa affermazione 3.4 e l'ha declassata a limitazione sourced invece di darla per certa.

E la skill ha tenuto la propria unica invenzione nel report invece di nasconderla. Su csrgenerator, la sua tabella dei campi affermava che un valore CN vuoto restituisce HTTP 400. Un CN mancante è davvero 400 — ma un CN vuoto colpisce il raise KeyError("CN cannot be empty") del codice stesso, non gestito, che restituisce HTTP 500 (verificato live). Un dettaglio comportamentale sbagliato in una cella di tabella, in un run che per il resto ha eseguito pytest (23 passati, corrispondenza esatta) e una generazione CSR reale via curl. La skill non è magia; è disciplina, e la disciplina ha un tasso di errore residuo. L'abbiamo registrato.

Dove la skill è stata inequivocabilmente più affilata è sugli specifici verificati: "pip install -e . ha installato requests==2.34.2 / PyJWT==2.13.0" ha combaciato esattamente con un venv appena creato; le limitazioni di killport (corrispondenza solo-LISTENING su Windows, SIGKILL incondizionato, una porta per invocazione) risalgono tutte al sorgente con il flusso di kill verificato end to end. Affermazioni nate da un'esecuzione, non da un'intuizione.

Gli avvertimenti onesti

La nostra metodologia richiede che i punti deboli siano stampati accanto alle vittorie, e qui ce ne sono di reali.

Un solo valutatore, non un panel di 3 sviluppatori. Le righe di preferenza e fiducia sono un giudizio esperto singolo dell'autore del benchmark, fatto a codice aperto. Il protocollo prevede ≥3 valutatori sviluppatori indipendenti; quel panel non era disponibile in questo harness. Leggi quelle due righe come indicative, non come il risultato multi-valutatore che il design prevede.

Il divario sulle invenzioni è stretto per costruzione. Poiché entrambi i baseline hanno riusato documentazione accurata del repo, il baseline ha avuto meno occasioni di inventare. Su un repo senza documentazione esistente il divario probabilmente si allargherebbe — ma stiamo riportando quello che questi tre repo hanno mostrato, cioè 2 contro 1, e N=3 è solo indicativo.

L'esecuzione dei comandi dipende dall'ambiente. Quando la macchina dell'agente non può eseguire il progetto, i comandi sono verificati staticamente contro i manifest e segnalati come non eseguiti nel log — più debole di un'esecuzione reale, e lo marchiamo come tale.

Installazione

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

Riavvia Claude Code. Si attiva su "scrivi un README", "documenta questo repo", "crea/riscrivi README.md", e richieste di revisione o audit del README — e resta fuori dai piedi per siti di documentazione completi, generazione di riferimenti API, e changelog. Fa parte della nostra serie discipline: token-discipline taglia quanto costa un task, research-discipline taglia quanto la ricerca sbaglia, e questa taglia quanto la tua documentazione inventa.

FAQ

In cosa è diverso da un generatore di README come readme-ai? I generatori producono struttura e scaricano l'accuratezza su di te — la loro stessa documentazione ti dice di rivedere l'output. Questa skill ribalta l'approccio: legge prima il codice, cerca con grep ogni affermazione falsificabile contro il sorgente, esegue ogni comando documentato in un checkout pulito, e ti consegna un log di verifica per controllare il suo lavoro. La struttura è la parte facile; la skill spende il suo sforzo sulla verità.

Cos'è esattamente il log di verifica? Un artefatto separato nella risposta (non committato) che mappa ogni feature dichiarata a un file:riga nel sorgente e marca ogni comando come eseguito ✓ o non eseguito — verificato contro <manifest>, più tutto ciò che è stato deliberatamente escluso per mancanza di prove. Se quel log risultasse vuoto, la skill avrebbe saltato le sue prime tre regole. È la ricevuta che ti permette di fidarti della prosa.

La regola anti-invenzione rende i README più corti e spenti? No — le regole sono scritte per aggiungere contenuto utile, non per tagliarlo. La sezione limitazioni obbligatoria e il quickstart con comandi verificati sono cose che i README generici omettono. Nel benchmark i README della skill erano più completi (18/18 sezioni) di quelli del baseline, non più scarni.

Una sola invenzione su tre repo è abbastanza? È meglio delle due del baseline, ed è onesta sul residuo — un comportamento HTTP sbagliato di un codice su un CN vuoto, registrato invece che nascosto. Se il tuo README sostiene una decisione costosa da sbagliare, il log di verifica ti dice esattamente quali affermazioni controllare a campione, il che richiede minuti invece di rileggere l'intera codebase.