Un README où chaque affirmation remonte au code

Un README généré est un tour de confiance. Ça se lit bien, ça liste des fonctionnalités qui sonnent juste, et ça vous donne des commandes d'installation qui ont l'air correctes — et vous ne pouvez pas savoir en le lisant quelles phrases sont vraies. Le mode d'échec est toujours le même : une fonctionnalité que le code n'a pas, une commande complétée par motif à partir des données d'entraînement au lieu d'être copiée du dépôt, et une absence suspecte de toute limitation. Nous dirigeons un annuaire qui teste les skills Claude à longueur de journée, alors nous avons construit le skill que nous voulions, puis mesuré s'il tenait vraiment la route.

Le résultat s'appelle readme-discipline : neuf règles applicables dont le contrat est qu'une fonctionnalité revendiquée doit être trouvée dans la source avant de pouvoir être revendiquée, que chaque commande est copiée depuis les vrais manifestes du projet puis exécutée, et qu'une section limitations honnête est obligatoire. Il est gratuit et sous licence MIT : github.com/Skillproofdev/readme-discipline.

Le vide : 101 skills README, aucun n'impose la vérité

Avant d'écrire une règle, nous avons étudié le paysage — 101 skills liés au README dans un catalogue de 16 682 skills, plus readme-ai et la spec Standard Readme. Chacun optimise autre chose que l'exactitude.

Le plus gros skill README dédié (2 200 étoiles) est un ensemble de modèles par audience. La spec Standard Readme impose l'ordre des sections mais ne dit rien sur le fait que les blocs de code s'exécutent ou non. Le générateur en ligne de commande dominant produit une sortie soignée puis vous dit, dans sa propre documentation, de la relire vous-même pour vérifier l'exactitude — l'exactitude est déléguée à l'humain. Le reste, ce sont des maximiseurs de badges et des décorateurs d'en-têtes à emoji. La structure et l'apparence sont résolues cinq fois plutôt qu'une. « Chaque affirmation remonte au code » et « chaque exemple est vérifié exécutable » n'apparaissaient comme règles applicables dans aucun d'entre eux.

C'est tout le créneau qu'occupe ce skill : pas rendre les README plus jolis, les rendre vrais.

Neuf règles, dont trois inédites

Les éléments familiers sont là — un ordre de section fixe (quoi+pourquoi → installation → démarrage rapide → usage → configuration → limitations), un calibrage à audience unique, aucune inflation de badges ou d'emojis. Les trois qu'aucun autre n'impose :

1. Interdiction de fabrication, avec preuves. Chaque affirmation falsifiable — une fonctionnalité, un flag, une plateforme supportée — est d'abord recherchée par grep dans la source. Trouvée → vous pouvez l'affirmer, dans le vocabulaire propre du code. Pas trouvée → elle n'entre pas dans le README, ni nuancée, ni en « généralement ». Un journal de vérification qui associe affirmation → fichier:ligne est livré avec chaque README.
2. Les commandes sont copiées, jamais composées. Chaque commande en bloc de code vient d'un endroit réel : les scripts de package.json, une cible de Makefile, une étape de CI, le propre --help du CLI. Jamais npm run build parce que les projets Node en ont généralement un — on vérifie d'abord scripts, puis on l'exécute dans un environnement propre.
3. Le démarrage rapide est un contrat. Du clonage à un succès observable en environ 60 secondes, chaque étape exécutable exactement telle qu'écrite, aboutissant à un résultat que l'utilisateur peut vérifier — une URL qui répond, un fichier qui apparaît, une sortie qui correspond à un extrait montré.

Plus une section limitations obligatoire et sourcée (tirée des commentaires TODO/FIXME, des branches d'erreur, des ébauches vides) et un mode audit-d'abord qui retire les affirmations obsolètes d'un README existant avant même de toucher à son style.

Le benchmark : 3 vrais dépôts, chaque commande vraiment exécutée

Nous avons choisi trois petits projets open source aux README minces et figé chacun à un SHA de commit : un CLI Node (crossplatform-killport), un CLI/bibliothèque Python (python-shaarli-client), et un service web Flask (csrgenerator.com). Par dépôt, deux agents — un de base, un lisant le skill d'abord — même modèle, même prompt, la seule différence étant si le SKILL.md était en contexte. Chaque commande du tableau ci-dessous a été exécutée sur une vraie machine (macOS 14, node v24.7.0, python3 3.13.1) ; les commandes dont l'environnement d'exécution était absent (Docker) ou nécessitant un service externe en direct ont été exclues du dénominateur d'exécutabilité et vérifiées de façon statique à la place.

Métrique (agrégée sur 3 dépôts)	Base	Skill
Affirmations fabriquées (moins = mieux)	2	1
Exécutabilité des commandes	20/24 (83 %)	15/17 (88 %)
Complétude des sections	14/18	18/18
Préférence en aveugle	0/3	3/3
Confiance moyenne (1–5)	3.67	4.67

La direction est cohérente sur les trois dépôts en complétude et en préférence. Le skill a atteint 6/6 sections à chaque fois ; la base n'a livré aucune section limitations sur aucun des trois dépôts — le plus gros écart de complétude. Et il a été préféré sur les trois, avec un point entier de confiance en plus.

Là où le skill l'a vraiment mérité — et là où il a glissé

Le chiffre de fabrication mérite l'honnêteté, parce que c'est le résultat qu'on attendrait en raz-de-marée et ça n'en est pas un. 2 contre 1, c'est un écart étroit, et voici pourquoi : les deux agents de base se sont lourdement appuyés sur les USAGE.md/docs/ existants et exacts des dépôts, ils ont donc hérité gratuitement de contenu correct. Les deux ratés de la base étaient exactement l'échec que ce skill cible — une exigence obsolète Python 3.4+ contredite par la propre matrice de test du projet, et deux environnements tox inventés (py34/py36) qui n'existent pas dans tox.ini. Des affirmations complétées par motif, rattachées à « un projet comme celui-ci », pas au code. Le bras avec skill a attrapé cette même affirmation « 3.4 » et l'a rétrogradée en limitation sourcée plutôt que de l'affirmer.

Et le skill a gardé sa propre fabrication unique dans le rapport plutôt que de la cacher. Sur csrgenerator, son tableau de champs affirmait qu'une valeur CN vide renvoie HTTP 400. Un CN absent renvoie bien 400 — mais un CN vide déclenche le propre raise KeyError("CN cannot be empty") du code, non géré, qui renvoie HTTP 500 (vérifié en direct). Un détail de comportement erroné dans une cellule de tableau, dans une exécution qui a par ailleurs lancé pytest (23 réussis, correspondance exacte) et une vraie génération de CSR via curl. Le skill n'est pas magique ; c'est de la discipline, et la discipline a un taux d'erreur résiduel. Nous l'avons consigné.

Là où le skill s'est montré nettement plus affûté, c'est sur les détails vérifiés : « pip install -e . a installé requests==2.34.2 / PyJWT==2.13.0 » correspondait exactement à un venv neuf ; les limitations de killport (correspondance Windows LISTENING uniquement, SIGKILL inconditionnel, un port par invocation) remontaient toutes à la source, avec le flux de kill vérifié de bout en bout. Des affirmations issues d'une exécution, pas d'une intuition.

Les réserves honnêtes

Notre méthodologie exige que les faiblesses soient imprimées à côté des gains, et il y en a de réelles ici.

Un seul évaluateur, pas un panel de 3 développeurs. Les lignes de préférence et de confiance sont un jugement expert unique de l'auteur du benchmark, fait source ouverte. Le protocole prévoit ≥3 évaluateurs développeurs indépendants ; ce panel n'était pas disponible dans ce harnais. Lisez ces deux lignes comme indicatives, pas comme le résultat multi-évaluateurs que le design prévoit.

L'écart de fabrication est étroit par construction. Parce que les deux bases ont réutilisé une documentation de dépôt exacte, la base avait moins d'occasions d'inventer. Sur un dépôt sans documentation existante, l'écart se creuserait probablement — mais nous rapportons ce que ces trois dépôts ont montré, soit 2 contre 1, et N=3 est directionnel uniquement.

L'exécution des commandes dépend de l'environnement. Quand la machine de l'agent ne peut pas exécuter le projet, les commandes sont vérifiées de façon statique contre les manifestes et signalées comme non exécutées dans le journal — plus faible qu'une vraie exécution, et nous le marquons comme tel.

Installation

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

Redémarrez Claude Code. Il se déclenche sur « write a README », « document this repo », « create/rewrite README.md », et les demandes de relecture ou d'audit de README — et reste en retrait pour les sites de documentation complets, la génération de référence d'API et les changelogs. Il rejoint notre série discipline : token-discipline réduit ce qu'une tâche coûte, research-discipline réduit ce qu'une recherche se trompe, et celui-ci réduit ce que votre documentation fabrique.

FAQ

En quoi est-ce différent d'un générateur de README comme readme-ai ? Les générateurs produisent de la structure et délèguent l'exactitude à l'utilisateur — leur propre documentation dit de relire la sortie. Ce skill inverse la logique : il lit le code d'abord, recherche par grep chaque affirmation falsifiable contre la source, exécute chaque commande documentée dans un environnement propre, et vous remet un journal de vérification pour contrôler son travail. La structure est la partie facile ; le skill dépense son effort sur la vérité.

Qu'est-ce que le journal de vérification, exactement ? Un artefact séparé dans la réponse (non commité) qui associe chaque fonctionnalité revendiquée à un fichier:ligne dans la source et marque chaque commande comme exécutée ✓ ou non exécutée — vérifiée contre <manifeste>, plus tout ce qui a été délibérément omis faute de preuve. Si ce journal devait être vide, le skill aurait manqué à ses trois premières règles. C'est le reçu qui vous permet de faire confiance à la prose.

La règle anti-fabrication rend-elle le README plus court et plus fade ? Non — les règles sont écrites pour ajouter du contenu utile, pas pour couper. La section limitations obligatoire et le démarrage rapide aux commandes vérifiées sont des choses que les README génériques omettent. Dans le benchmark, les README du skill étaient plus complets (18/18 sections) que ceux de la base, pas plus minces.

Une fabrication sur trois dépôts, est-ce suffisant ? C'est mieux que les deux de la base, et c'est honnête sur le résiduel — un comportement de CN vide faux d'un code de statut HTTP, consigné plutôt que caché. Si votre README appuie une décision coûteuse à mal prendre, le journal de vérification vous dit exactement quelles affirmations vérifier ponctuellement, ce qui prend des minutes au lieu de relire toute la base de code.