Projekt-README
Eine README ist weder ein Parameter-Handbuch noch eine Werbung. Sie ist der kürzeste Weg, einem neuen Leser Vertrauen in ein Projekt zu geben und ein erstes Ergebnis zu liefern.
Fülle keine Abschnitte um ihrer selbst willen. Ein Leser sollte drei Fragen beantworten können: Was ist das? Ist es das Richtige für mich? Kann ich ein erstes Ergebnis erzielen und die Risikogrenzen verstehen?
Kernprinzipien
- Jede Behauptung braucht einen Beleg. Verzichte auf Behauptungen, die nicht im Repository oder durch den Benutzer bestätigt werden können; formuliere eine Vermutung nicht in vage Prosa um.
- Eine Kurzanleitung ist Pflicht: Gib den kürzesten tatsächlichen Weg von der Installation zu einem nützlichen Ergebnis an. Wenn dessen Befehle nicht verifiziert werden können, frage nach, anstatt Lücken zu lassen oder sie zu erfinden.
- Wenn eine README bereits existiert, frage, ob sie ersetzt, ausgewähltes Material erhalten oder an Ort und Stelle erweitert werden soll. Rate nicht und überschreibe nicht den vom Benutzer geschriebenen Inhalt.
- Etabliere Identität und einen Einstiegspunkt "above the fold". Verwende für öffentliche Projekte den Projektnamen/das Logo, eine einzeilige Beschreibung, echte Badges und eine Navigation und platziere die Kurzanleitung unmittelbar danach. Verwende ein GIF/Screenshot nur, wenn es mehr aussagt als Text.
- Zeige statt zu behaupten: Terminalausgaben, Screenshots, Code und verifizierte Zahlen sind stärker als Adjektive.
- Organisiere nach Aufgaben, nicht nach Parametern. Erkläre "Was möchte ich tun → welcher Befehl macht es"; überlasse vollständige Optionslisten
--help. - Lösche jede Zeile, die dem Leser nicht hilft, zu entscheiden, zu vertrauen oder zu handeln.
- Wenn das Projekt lokale Dateien, Datenbanken, Anmeldeinformationen, Netzwerke oder Modellaufrufe betrifft, erkläre, was es liest, schreibt und außerhalb des Geräts sendet, sowie seine standardmäßige Nur-Lese-/Bestätigungs-/Backup-/Fail-geschlossen-Haltung. Mache kein Sicherheitsversprechen ohne Code-Belege.
- Behalte die READM als Eingangstür; verlinke tiefe Details in
docs/oderCONTRIBUTING.md, anstatt die README in ein Handbuch zu verwandeln. - Passe dich dem Projekt an; erzwinge keine Vorlage für CLI, MCP, Bibliotheken, Apps und Forschungs-Repositories.
- Vermeide unbewiesene Prahlerei wie "branchenführend", "produktionsreif" oder "extreme Leistung". Siehe die Richtlinien in
content-writing.
Zielgruppe wählen
Klassifiziere den Leser der README, um den Detaillierungsgrad festzulegen:
- Solo (persönliches Projekt, internes Werkzeug oder persönliches Skript): Der Leser bist hauptsächlich du selbst, einschließlich deines zukünftigen Ichs. Erforderlich: eine einzeilige Beschreibung, Kurzanleitung und bekannte Einschränkungen. Badges, Beitragsanleitung, Community-Kanäle, Stern-Verlauf und Roadmap sind optional. Die Grundlage ist, dass du es in drei Monaten noch ausführen kannst.
- Öffentlich (Open Source, verteilte Software oder teamgenutzt): Der Leser ist ein Fremder. Enthalte Beschreibung, Nutzen, Kurzanleitung, Verwendung, Konfiguration, Dokumentationsindex, Beiträge und Lizenz. Füge Badges und Community-Informationen nur hinzu, wenn sie tatsächlich existieren.
Standardmäßig öffentlich, wenn das Repository öffentlich ist, über einen Paketmanager veröffentlicht wird oder externe Benutzer hat; standardmäßig Solo für private persönliche Projekte und einmalige Arbeiten. Bei gemischten Fällen verwende öffentliche Details.
Modus wählen
| Modus | Wann verwenden | Erster Schritt |
|---|---|---|
| create | Keine README vorhanden, oder der Benutzer fordert explizit eine Neufassung an | Untersuche das Repository und sammle Fakten. |
| improve | Eine README ist vorhanden und benötigt Arbeit | Lese sie, frage, wie mit dem vorhandenen Inhalt umgegangen werden soll, und fahre dann fort. |
| audit | Der Benutzer fordert nur eine Diagnose an | Überprüfe jede README-Behauptung anhand des Repositorys und berichte die Ergebnisse. |
Torwächter: Wenn eine README existiert, pausiere für die Wahl des Benutzers: (1) komplett ersetzen, (2) unter Beibehaltung bestimmter Inhalte umschreiben oder (3) an Ort und Stelle erweitern. "Hilf mir, eine README zu schreiben" impliziert nicht Option 1.
Above the Fold und Entwicklerwerkzeug-Stil (Öffentliche Projekte)
Leser entscheiden nach einem Bildschirm, ob sie fortfahren. Der erste Bildschirm sollte zeigen, was das Projekt tut.
Für CLI-, MCP- und lokale Entwicklerwerkzeuge bevorzuge zurückhaltende, verifizierbare Entwicklerdokumentation:
<div align="center">
Optionales Logo
# Projektname
**Einzeilige Beschreibung**
Nur echte Badges
Sprachumschalter (nur wenn die andere README existiert)
Ankernavigation (wenn das Dokument 100 Zeilen überschreitet)
</div>
---
Fähigkeitsübersicht: tatsächliche Befehle/Werkzeuge, Eingaben, Ausgaben und standardmäßige Sicherheitshaltung
Drei Regeln:
- Einzeilige Beschreibung: Halte sie einprägsam und ungefähr eine Zeile: was es ist, für wen es ist und seine wichtigste sachliche Besonderheit. Hebe dir Prinzipien und Hintergrund für später auf.
- Fähigkeitsübersicht: Liste tatsächliche Befehle/Werkzeuge, Eingaben, Ausgaben, Lese-/Schreibobjekte und die standardmäßige Sicherheitshaltung auf. Vermeide allgemeine Behauptungen wie "schnell, sicher und intelligent".
- Kurzanleitung als Nächstes: Bevorzuge 1–3 kürzeste Schritte. Der letzte Schritt muss die Installation oder Dienstfindung verifizieren. Komplexe Konfiguration nach hinten verschieben.
Visuelles Material ist optional. Wähle GIFs/asciinema, Screenshots und echte Terminalausgaben nur, wenn sie Informationen hinzufügen. Wenn es kein Demo-Asset gibt, erfinde keins; gib stattdessen echte Befehle, erwartete Ausgabe und Verifizierungsschritte an.
Solo-Projekte können Logos, Badges und Navigation weglassen, aber eine einzeilige Beschreibung und sichtbare Ausgabe sind dennoch nützlich.
Belegleiter
Bevor du jede Behauptung schreibst, klassifiziere ihren Beleg:
| Stufe | Quelle | Verwendung |
|---|---|---|
| 1 | Im Repository: Quellcode, Tests, Beispiele, Konfiguration, CI, Tags, Screenshots | Schreibe sie direkt. |
| 2 | Vom Benutzer bestätigt: Positionierung, Differenzierung, Metriken, Screenshots, Fälle | Schreibe sie direkt. |
| 3 | Extern verifizierbar: Paketseite, Release, öffentlicher Benchmark | Schreibe sie mit einem Link. |
| 4 | Keine Quelle | Weglassen. Frage, wenn wichtig; andernfalls löschen. |
Erfinde niemals Installationsbefehle, CLI-Parameter, API-Signaturen, Konfigurationsschlüssel, Umgebungsvariablen, Pfade, Leistungszahlen, Kompatibilitätsbehauptungen, Lizenzbedingungen oder Community-Links.
Siehe references/evidence.md für den Repository-Scan und die Belegregeln.
Arbeitsablauf
- Klassifiziere Zielgruppe und Modus: Solo/Öffentlich und Erstellen/Verbessern/Prüfen. Wenn eine README existiert, frage, wie damit umgegangen werden soll, bevor du sie änderst.
- Sammle Repository-Belege: Überprüfe Paketmetadaten, Einstiegspunkte, Struktur, Konfiguration, Doku, Git/CI, Assets, Lese-/Schreibpfade, Anmeldeinformationen, Netzwerke, Modellaufrufe und Fehlercodes. Diese Stufe sammelt Fakten, keine Schlussfolgerungen; siehe
references/evidence.md. - Klassifiziere das Projekt und den Leser: CLI, MCP, Bibliothek, App, Forschungsprojekt, Agenten-Skill oder Monorepo. Verwende dies, um Abschnitte auszuwählen; siehe
references/structure.md. - Verifiziere die Kurzanleitung: Finde und verifiziere den ersten Befehl, der nach der Installation ein nützliches Ergebnis liefert. Wenn er nicht verifiziert werden kann, frage nach und fahre nicht über dieses Tor hinaus fort.
- Plane die Abschnitte: Wähle Abschnitte für den Projekttyp aus und identifiziere Belege für jeden. Lasse nicht unterstützte Abschnitte weg. Entscheide auch über das Layout "above the fold", die Verifizierung der Kurzanleitung und ob Sicherheits-/Datenfluss, Fehlercodes oder Fehlerbehebung benötigt werden.
- Erstelle einen Entwurf: Identität und Fähigkeiten → Kurzanleitung → Funktionen → Installation/Konfiguration → aufgabenbasierte Nutzung → Begründung/Hintergrund → Sicherheits-/Datenschutzgrenzen → Fehler/Fehlerbehebung → bekannte Einschränkungen → Entwicklung/tiefere Doku. Erkläre die Begründung, nachdem der Leser einen funktionierenden Pfad hat, nicht davor.
- Führe das Qualitätstor aus: Überprüfe jeden Punkt in
references/checklist.md, insbesondere die sachliche Richtigkeit und ausführbaren Schritte. - Liefere: Standardmäßig einen Entwurf im Gespräch bereitstellen; nur auf explizite Anfrage auf die Festplatte schreiben. Führe die Checkliste vor dem Schreiben erneut aus.
Ausgabe
Gib kurz an: (1) Zielgruppe und Modus; (2) Projekttyp und Zielgruppe des Lesers; (3) Abschnittsplan und Belegquelle für jeden Abschnitt; (4) den README-Entwurf; (5) Behauptungen, die eine Benutzerbestätigung erfordern, weil Belege fehlen; und (6) bekannte Auslassungen. Kennzeichne niemals eine Vermutung als verifiziert. Liste nicht unterstützte Behauptungen explizit auf, anstatt sie mit vager Sprache zu verschleiern.
Warnsignale
- Fehlende oder leere Kurzanleitung oder erfundene Befehle ohne Repository-Einstiegspunkt.
- Überschreiben einer vorhandenen README ohne Nachfrage, wie damit umzugehen ist.
- Unbestätigte Leistungs-, Kompatibilitäts-, Benutzeranzahl- oder Stern-Anzahl-Behauptungen.
- Badges, die auf nicht vorhandene CI, Pakete oder Lizenzen verweisen.
- Füllen von Vorlagenabschnitten mit leeren Überschriften oder "TODO/demnächst".
- Einbetten eines vollständigen API-Handbuchs anstatt darauf zu verlinken.
- Wiedergeben einer langen
--help-Tabelle anstatt aufgabenbasierte Befehle zu zeigen. - Ein Eröffnungsbildschirm mit nur Slogans oder Prinzipien und keinem tatsächlichen Einstiegspunkt oder verifizierbarem Ergebnis.
- Weglassen von Sicherheits-/Datenflussinformationen für Werkzeuge, die lokale Daten, Anmeldeinformationen, Netzwerke oder Modellaufrufe berühren.
- Versprechen von Nur-Lese-Betrieb, keinem Datenleck, Fail-geschlossen-Verhalten oder Null-Konfiguration ohne Code-/Testbelege.
- Fehlerbehebung, die nur "Neustart" sagt, ohne Symptom, Fehlercode, Ursache und Abhilfe.
- Eine einzeilige Beschreibung, die ein Absatz ist, oder Begründung, die vor dem ersten ausführbaren Pfad erscheint.
- Adjektive wie "leistungsstark", "elegant", "extrem" oder "out of the box", die Belege ersetzen.
- Erzwingen von Beitragsleitfäden, Verhaltenskodizes oder Community-Links für ein Solo-Projekt, wenn keine existieren.
- Architekturdiagramme mit nicht vorhandenen Komponenten oder Aufrufbeziehungen.
- Schreiben von Dateien ohne Benutzerautorisierung.
Referenzen
Lies nur, was benötigt wird:
references/structure.md: Lesefluss, Abschnittsauswahl nach Projekttyp und Anleitung zum Schreiben von Abschnitten.references/evidence.md: Repository-Scan, Belegstufen und Behauptungen, die nicht erfunden werden dürfen.references/checklist.md: Qualitätstor vor dem Schreiben für Fakten, Benutzerfreundlichkeit, Präsentation und Sprache.