Ein README, dessen Aussagen sich im Code belegen lassen

Ein generiertes README ist ein Vertrauenstrick. Es liest sich sauber, listet die richtig klingenden Features und liefert Install-Befehle, die korrekt aussehen – und du kannst beim Lesen nicht erkennen, welche Sätze stimmen. Das Fehlermuster ist immer gleich: ein Feature, das der Code nicht hat, ein Befehl, der aus Trainingsdaten weitervervollständigt statt aus dem Repo kopiert wurde, und eine verdächtige Abwesenheit jeglicher Einschränkungen. Wir betreiben ein Verzeichnis, das Claude-Skills beruflich benchmarkt, also haben wir das Skill gebaut, das wir wollten, und dann gemessen, ob es wirklich hält.

Das Ergebnis heißt readme-discipline: neun durchsetzbare Regeln, deren Vertrag lautet, dass ein behauptetes Feature erst im Quellcode gefunden werden muss, bevor es behauptet werden darf, jeder Befehl aus den echten Manifesten des Projekts kopiert und ausgeführt wird, und ein ehrlicher Einschränkungsabschnitt Pflicht ist. Kostenlos und MIT-lizenziert: github.com/Skillproofdev/readme-discipline.

Die Lücke: 101 README-Skills, keines setzt Wahrheit durch

Bevor wir eine Regel geschrieben haben, haben wir das Feld gesichtet – 101 README-nahe Skills in einem 16.682-Skills-Katalog, plus readme-ai und die Standard-Readme-Spec. Jedes davon optimiert etwas anderes als Genauigkeit.

Das größte dedizierte README-Skill (2,2k Stars) ist ein Satz Zielgruppen-Vorlagen. Die Standard-Readme-Spec schreibt die Reihenfolge der Abschnitte vor, sagt aber nichts dazu, ob die Codeblöcke laufen. Der dominierende CLI-Generator liefert poliertes Ergebnis und sagt dir dann in seiner eigenen Dokumentation, du sollst es selbst auf Richtigkeit prüfen – Genauigkeit wird an den Menschen ausgelagert. Der Rest sind Badge-Maximierer und Emoji-Header-Dekorateure. Struktur und Optik sind fünffach gelöst. „Jede Aussage lässt sich im Code belegen“ und „jedes Beispiel ist verifiziert lauffähig“ tauchten als durchsetzbare Regel in keinem davon auf.

Genau das ist die ganze Nische, die dieses Skill besetzt: nicht READMEs hübscher machen, sondern wahr.

Neun Regeln, drei davon neu

Die bekannten Teile sind da – eine feste Abschnittsreihenfolge (Was+Warum → Install → Quickstart → Nutzung → Konfiguration → Einschränkungen), Kalibrierung auf eine Zielgruppe, kein Badge- oder Emoji-Overkill. Die drei, die sonst niemand durchsetzt:

1. Fabrikationsverbot mit Beleg. Jede falsifizierbare Aussage – ein Feature, ein Flag, eine unterstützte Plattform – wird zuerst im Quellcode gegrept. Gefunden → darf behauptet werden, im Vokabular des Codes selbst. Nicht gefunden → kommt nicht ins README, nicht abgeschwächt, nicht als „typischerweise“. Ein Verifizierungsprotokoll, das jede Aussage auf Datei:Zeile abbildet, wird mit jedem README mitgeliefert.
2. Befehle werden kopiert, nie komponiert. Jeder eingerahmte Befehl stammt aus einer echten Quelle: package.json-Scripts, ein Makefile-Target, ein CI-Schritt, die eigene --help der CLI. Nie npm run build, nur weil Node-Projekte meist eines haben – erst scripts prüfen, dann in einem sauberen Checkout ausführen.
3. Quickstart ist ein Vertrag. Vom Klonen bis zu einem beobachtbaren Erfolg in rund 60 Sekunden, jeder Schritt exakt wie geschrieben ausführbar, endend in einem Ergebnis, das der Nutzer prüfen kann – eine URL, die antwortet, eine Datei, die erscheint, ein Output, der zu einem gezeigten Snippet passt.

Plus ein verpflichtender, belegter Einschränkungsabschnitt (gezogen aus TODO-/FIXME-Kommentaren, Fehlerzweigen, leeren Stubs) und ein Audit-First-Modus, der veraltete Behauptungen aus einem bestehenden README entfernt, bevor er dessen Stil anfasst.

Der Benchmark: 3 echte Repos, jeder Befehl wirklich ausgeführt

Wir haben drei kleine OSS-Projekte mit dünnen READMEs ausgewählt und jedes auf einem Commit-SHA fixiert: eine Node-CLI (crossplatform-killport), eine Python-CLI/-Library (python-shaarli-client) und einen Flask-Webservice (csrgenerator.com). Pro Repo zwei Agenten – einer Baseline, einer mit vorher gelesenem Skill – gleiches Modell, gleicher Prompt, einziger Unterschied, ob die SKILL.md im Kontext war. Jeder Befehl in der Tabelle unten wurde auf einer echten Maschine ausgeführt (macOS 14, node v24.7.0, python3 3.13.1); Befehle, deren Laufzeitumgebung fehlte (Docker) oder die einen laufenden externen Dienst brauchten, wurden aus dem Ausführbarkeits-Nenner ausgeschlossen und stattdessen statisch geprüft.

Metrik (Summe über 3 Repos)	Baseline	Skill
Erfundene Behauptungen (niedriger ist besser)	2	1
Befehls-Ausführbarkeit	20/24 (83%)	15/17 (88%)
Abschnittsvollständigkeit	14/18	18/18
Blinde Präferenz	0/3	3/3
Mittleres Vertrauen (1–5)	3,67	4,67

Die Richtung ist bei Vollständigkeit und Präferenz über alle drei Repos konsistent. Das Skill traf 6/6 Abschnitte in jedem Lauf; die Baseline lieferte auf keinem der drei Repos einen Einschränkungsabschnitt – die größte Vollständigkeitslücke überhaupt. Und es wurde bei allen drei bevorzugt, mit einem vollen Punkt mehr Vertrauen.

Wo das Skill es sich verdient hat – und wo es ausgerutscht ist

Die Fabrikationszahl verdient Ehrlichkeit, denn genau das ist die Schlagzeile, die du als Kantersieg erwarten würdest, und ist sie nicht. 2 gegen 1 ist eine knappe Lücke, und hier ist warum: Beide Baseline-Agenten stützten sich stark auf die vorhandene, korrekte USAGE.md/docs/-Prosa der Repos und erbten damit gratis richtigen Inhalt. Die zwei Fehltritte der Baseline waren genau der Fehler, gegen den dieses Skill antritt – eine veraltete Anforderung „Python 3.4+“, die der eigenen Testmatrix des Projekts widerspricht, und zwei erfundene tox-Umgebungen (py34/py36), die in tox.ini nicht existieren. Musterhaft vervollständigte Behauptungen, rückführbar auf „ein Projekt wie dieses“, nicht auf den Code. Der Skill-Arm erkannte dieselbe 3.4-Behauptung und stufte sie zu einer belegten Einschränkung herab, statt sie zu behaupten.

Und das Skill behielt seine eigene einzige Fabrikation im Bericht, statt sie zu verstecken. Bei csrgenerator behauptete seine Feldtabelle, ein leerer CN-Wert liefere HTTP 400. Ein fehlendes CN ist tatsächlich 400 – aber ein leeres trifft den eigenen raise KeyError("CN cannot be empty") des Codes, der unbehandelt bleibt und HTTP 500 liefert (live verifiziert). Ein falsches Verhaltensdetail in einer Tabellenzelle, in einem Lauf, der sonst pytest ausführte (23 bestanden, exakte Übereinstimmung) und eine echte curl-CSR-Erzeugung. Das Skill ist keine Magie; es ist Disziplin, und Disziplin hat eine Restfehlerquote. Wir haben sie protokolliert.

Wo das Skill eindeutig schärfer war, sind verifizierte Details: „pip install -e . installierte requests==2.34.2 / PyJWT==2.13.0“ passte exakt zu einer frischen venv; die killport-Einschränkungen (Windows nur LISTENING-Match, bedingungsloses SIGKILL, ein Port pro Aufruf) ließen sich alle im Quellcode belegen, mit dem Kill-Ablauf Ende-zu-Ende verifiziert. Behauptungen, die aus einem Lauf kamen, nicht aus einer Vermutung.

Die ehrlichen Vorbehalte

Unsere Methodik verlangt, dass Schwächen neben den Gewinnen stehen, und hier gibt es echte.

Ein einzelner Bewerter, kein Drei-Entwickler-Panel. Die Präferenz- und Vertrauenszeilen sind ein Expertenurteil des Benchmark-Autors, gefällt mit offener Quelle. Das Protokoll verlangt ≥3 unabhängige Entwickler-Bewerter; dieses Panel stand in diesem Setup nicht zur Verfügung. Lies diese zwei Zeilen als Anhaltspunkt, nicht als das im Design vorgesehene Multi-Bewerter-Ergebnis.

Die Fabrikationslücke ist konstruktionsbedingt schmal. Weil beide Baselines auf echte Repo-Doku zurückgriffen, hatten sie weniger Gelegenheit zum Erfinden. Bei einem Repo ohne bestehende Dokumentation würde die Lücke sich vermutlich vergrößern – aber wir berichten, was diese drei Repos gezeigt haben, nämlich 2 gegen 1, und N=3 ist nur richtungsweisend.

Befehlsausführung hängt von der Umgebung ab. Kann die Maschine des Agenten das Projekt nicht ausführen, werden Befehle statisch gegen Manifeste verifiziert und im Protokoll als nicht ausgeführt markiert – schwächer als ein echter Lauf, und so kennzeichnen wir es auch.

Installation

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

Claude Code neu starten. Es greift bei „write a README“, „document this repo“, „create/rewrite README.md“ und README-Review- oder Audit-Anfragen – und hält sich raus bei kompletten Docs-Sites, API-Referenzgenerierung und Changelogs. Es reiht sich in unsere Discipline-Serie ein: token-discipline senkt, was eine Aufgabe kostet, research-discipline senkt, was Recherche falsch macht, und dieses hier senkt, was deine Dokumentation erfindet.

FAQ

Wie unterscheidet sich das von einem README-Generator wie readme-ai? Generatoren liefern Struktur und lagern Genauigkeit an dich aus – ihre eigene Dokumentation sagt dir, du sollst das Ergebnis selbst prüfen. Dieses Skill dreht das um: Es liest zuerst den Code, grept jede falsifizierbare Aussage gegen den Quellcode, führt jeden dokumentierten Befehl in einem sauberen Checkout aus und gibt dir ein Verifizierungsprotokoll, mit dem du seine Arbeit prüfen kannst. Struktur ist der leichte Teil; das Skill investiert seinen Aufwand in Wahrheit.

Was genau ist das Verifizierungsprotokoll? Ein separates Artefakt in der Antwort (nicht committed), das jedes behauptete Feature auf ein Datei:Zeile im Quellcode abbildet und jeden Befehl mit ran ✓ oder not executed — verified against <manifest> markiert, plus alles, was mangels Beleg bewusst weggelassen wurde. Wäre dieses Protokoll leer, hätte das Skill seine eigenen ersten drei Regeln übersprungen. Es ist der Beleg, der dir erlaubt, der Prosa zu vertrauen.

Macht die Fabrikationsregel READMEs kürzer und blasser? Nein – die Regeln sind darauf ausgelegt, nützlichen Inhalt hinzuzufügen, nicht zu streichen. Der verpflichtende Einschränkungsabschnitt und der verifizierte Quickstart sind Dinge, die generische READMEs weglassen. Im Benchmark waren die READMEs des Skills vollständiger (18/18 Abschnitte) als die der Baseline, nicht dünner.

Ist eine Fabrikation bei drei Repos gut genug? Besser als die zwei der Baseline, und ehrlich zum Rest – ein leerer CN-Fall, um eine HTTP-Statuszahl daneben, protokolliert statt verschwiegen. Wenn dein README eine teure Entscheidung stützt, sagt dir das Verifizierungsprotokoll genau, welche Aussagen du stichprobenartig prüfen solltest – das dauert Minuten statt die ganze Codebase neu zu lesen.