Was macht Readme Generator?
Erstellen Sie ansprechende, umfassende README.md-Dateien für interne/unternehmenseigene Code-Repositories, indem Sie die eigentliche Codebasis analysieren und gezielte klärende Fragen stellen.
Warum dieses Skill existiert
Ein gutes README ist die Visitenkarte eines Code-Repositories. Speziell für interne Projekte bedeutet ein fehlendes oder dünnes README, dass jedes neue Teammitglied Stunden damit verbringt, herauszufinden, was ein Projekt tut, wie man es ausführt und wo man suchen muss. Dieses Skill automatisiert die Schwerstarbeit – es liest den Code, leitet ab, was es kann, fragt nach, was es nicht kann, und erstellt ein README, das Entwickler schnell produktiv macht.
Workflow
Schritt 1: Analysieren der Codebasis
Bevor Sie den Benutzer etwas fragen, führen Sie eine strukturierte Vier-Phasen-Analyse durch, um so viel Kontext wie möglich zu sammeln. Dies reduziert die Belastung des Benutzers – er sollte nur Lücken füllen müssen, nicht Dinge beschreiben, die Sie bereits sehen können.
Markieren Sie jede Tatsache mit einem Vertrauensgrad: [bestätigt] (aus der Quelle gelesen), [abgeleitet-hoch] (starke Evidenz), [abgeleitet-niedrig] (teilweise Evidenz) oder [unbekannt]. Erkenntnisse mit niedrigem Vertrauensgrad oder unbekannte Erkenntnisse werden in Schritt 2 zu klärenden Fragen.
Siehe references/analysis-phases.md für detaillierte Tool-Aktionen, Grep-Muster, Extraktions-Checklisten und Vorlagen für Aufzeichnungen.
Phase 1 – Projekt-Metadaten-Scan: Durchsuchen Sie das Dateisystem nach Paketmanager-Dateien (pyproject.toml, package.json usw.), Umgebungsvorlagen, Dockerfiles, CI/CD-Konfigurationen und Toolchain-Dateien. Lesen Sie jede und extrahieren Sie: Projektname/-version, Sprache, Abhängigkeiten (kategorisiert mit Zwecken), Skripte/Befehle, Umgebungsvariablen (erforderlich vs. optional), CI-Stufen, Lizenz.
Phase 2 – Architektur-Scan: Durchsuchen Sie das Dateisystem nach allen Quelldateien, um die Verzeichnisstruktur abzubilden. Suchen Sie mit Grep nach Einstiegspunkt-Markern (if __name__, main(), usw.) und lesen Sie jeden Einstiegspunkt. Erstellen Sie den Import-Graphen, indem Sie mit Grep nach Import-Anweisungen in allen Quelldateien suchen – klassifizieren Sie Module als Kern (hoher Eingangsgrad), Blatt oder Orchestrator. Identifizieren Sie das Architekturmuster (Pipeline, MVC, geschichtet, Microservices, ereignisgesteuert, CLI, Monolith) mithilfe der Indikator-Checkliste. Suchen Sie mit Grep nach Konfigurations-Lade-Mustern, um Laufzeitkonfigurationsdateien zu finden.
Phase 3 – Tiefgehende Modulanalyse: Lesen Sie jede bedeutende Quelldatei (priorisiert: Kern → Einstiegspunkt → Größte → Rest). Extrahieren Sie für jede: Zweck (ein Satz), wichtige Exporte mit Signaturen, Design-Notizen (nicht offensichtliche Entscheidungen, Randfälle, Konventionen) und interne Abhängigkeiten. Verfolgen Sie den primären Workflow Ende-zu-Ende durch den Import-Graphen und beschriften Sie, welche Datentypen zwischen Modulen fließen. Bei Codebasen mit 8+ Quelldateien entsenden Sie parallele Sub-Agenten, gruppiert nach Abhängigkeits-Clustern.
Phase 4 – Unterstützungsinfrastruktur-Scan: Durchsuchen Sie das Dateisystem nach Testdateien und Fixtures. Lesen Sie die ersten 30-50 Zeilen jeder Testdatei, um eine Test-zu-Modul-Zuordnung zu erstellen. Suchen Sie mit Grep nach benutzerdefinierten Ausnahmeklassen und raise-Anweisungen, um die Fehlerhierarchie abzubilden. Scannen Sie Vorlagen, Assets und vorhandene Dokumente. Extrahieren Sie häufige Fehlerszenarien für die Tabelle zur Fehlerbehebung.
Schritt 2: Klärende Fragen stellen
Fragen Sie den Benutzer nach der Analyse nach Dingen, die Sie nicht mit Sicherheit ableiten konnten. Bleiben Sie fokussiert – fragen Sie nicht nach Dingen, die Sie bereits wissen. Häufige Lücken sind:
- Projektzweck: Welches Problem löst dies? Wer nutzt es? (falls nicht offensichtlich aus dem Code)
- Setup-Besonderheiten: Gibt es nicht offensichtliche Voraussetzungen, VPN-Anforderungen, interne Paketregister oder Datenbank-Setup-Schritte?
- Wichtige Workflows: Was sind die 2-3 Dinge, die ein Entwickler mit diesem Projekt am häufigsten tut?
- Bereitstellung: Wie/Wo wird dies bereitgestellt? (falls nicht aus CI/CD-Konfigurationen ersichtlich)
- Team-Konventionen: Gibt es Namenskonventionen, Branching-Strategien oder Muster, die erwähnt werden sollten?
- Kontaktinformationen: Wer besitzt/verwaltet dieses Projekt? (Name + E-Mail für den Kontakt-Abschnitt)
Präsentieren Sie Ihre Fragen prägnant. Wenn die Codebasis unkompliziert ist und Sie mit Ihrer Analyse zuversichtlich sind, benötigen Sie möglicherweise nur 1-2 Fragen – oder sogar keine. Verwenden Sie Ihr Urteilsvermögen.
Schritt 3: README.md generieren
Schreiben Sie das README unter Verwendung der untenstehenden Struktur und Richtlinien.
README-Struktur
Verwenden Sie dies als Ihre Vorlage. Fügen Sie alle Abschnitte ein, aber skalieren Sie die Tiefe entsprechend der Komplexität des Projekts. Verwenden Sie --- horizontale Trennlinien zwischen jedem Hauptabschnitt für visuelle Struktur.
# Projektname
  
Kurze, klare Beschreibung. Verwenden Sie **fett** für die wichtigste Technologie oder den Produkttyp.
---
## Inhaltsverzeichnis
Erstellen Sie ein gründliches, verschachteltes Inhaltsverzeichnis, das ALLE ## und ### Überschriften enthält. Rückeln Sie Unterabschnitte unter ihre übergeordneten Abschnitte ein, damit Leser die vollständige Struktur auf einen Blick sehen können. Dies ist besonders wichtig für längere READMEs – das Inhaltsverzeichnis dient sowohl als Navigationswerkzeug als auch als Gliederung des gesamten Dokuments.
Beispiel der erwarteten Tiefe:
- [Übersicht](#übersicht)
- [Architektur](#architektur)
- [Hochrangige Architektur](#hochrangige-architektur)
- [Verzeichnisstruktur](#verzeichnisstruktur)
- [Modul-Abhängigkeitsgraph](#modul-abhängigkeitsgraph)
- [Erste Schritte](#erste-schritte)
- [Voraussetzungen](#voraussetzungen)
- [Installation](#installation)
- [Ausführen von Tests](#ausführen-von-tests)
- [Umgebungsvariablen](#umgebungsvariablen)
- [Nutzung](#nutzung)
- [Beispiel: Primärer Anwendungsfall](#beispiel-primärer-anwendungsfall)
- [Beispiel: Sekundärer Anwendungsfall](#beispiel-sekundärer-anwendungsfall)
- [API-Referenz](#api-referenz)
- [Ressource A](#ressource-a)
- [Ressource B](#ressource-b)
- [Fehlerbehebung](#fehlerbehebung)
- [Kontakt](#kontakt)
- [Lizenz](#lizenz)
Jede ### Überschrift im Dokument sollte als eingerückter Eintrag unter ihrer übergeordneten ## Überschrift erscheinen. Überspringen Sie keine Unterabschnitte – der ganze Sinn eines gründlichen Inhaltsverzeichnisses ist, dass Leser direkt zu jedem Teil des Dokuments springen können.
---
## Übersicht
Erweitern Sie die Beschreibung. Machen Sie Schlüsselbegriffe fett. Verwenden Sie nummerierte Listen für mehrschrittige Prozesse.
---
## Architektur
### Hochrangige Architektur
```mermaid
graph TD
...
```
Verzeichnisstruktur
projekt-root/
├── src/ # Kurze Anmerkung
├── tests/ # Kurze Anmerkung
└── ...
[Datenfluss / Pipeline / Modul-Abhängigkeiten – zusätzliche Diagramme]
...
Erste Schritte
Voraussetzungen
Installation
Ausführen von Tests
Umgebungsvariablen
| Variable | Erforderlich | Beschreibung |
|---|---|---|
DB_URL | Ja | PostgreSQL-Verbindungszeichenfolge |
Nutzung
Reale Codebeispiele für die 2-3 häufigsten Operationen.
API-Referenz
Fehlerbehebung
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
Fehlermeldung | Was ist falsch | Wie man es behebt |
Kontakt
Bei Fragen oder Support kontaktieren Sie:
- Name — [email protected]
Lizenz
Nur für internen Gebrauch – Firmenname Proprietäre Software. © [Jahr] [Firma]. Alle Rechte vorbehalten.
## Shield.io Badges
Fügen Sie immer Shield.io-Badges direkt nach der `# Titel`-Überschrift ein (3-6 Badges, die Sprache, Framework, Schlüsselbibliothek, Paketmanager, Datenbank, Infrastruktur abdecken). Siehe [references/badge-reference.md](references/badge-reference.md) für Format, Beispiele und Farbvorschläge nach Kategorie.
## Mermaid-Diagramm-Richtlinien
Verwenden Sie Mermaid-Diagramme großzügig – sie machen Architektur, Datenflüsse und Prozesse sofort verständlich. Ein typisches README sollte **3-6 Diagramme** enthalten; komplexe Projekte (Datenpipelines, Multiservice-Systeme) könnten **6-10+** haben. Siehe [references/mermaid-guidelines.md](references/mermaid-guidelines.md) für Informationen, wann welcher Diagrammtyp verwendet werden sollte, Best Practices und projektspezifische Empfehlungen.
## Schreibrichtlinien
- **Seien Sie spezifisch statt allgemein.** „Führen Sie `npm run dev` aus“ ist besser als „Starten Sie den Entwicklungsserver“. Fügen Sie tatsächliche Befehle, Dateipfade und Variablennamen ein.
- **Schreiben Sie für das neue Teammitglied.** Gehen Sie von allgemeinen Ingenieurfähigkeiten aus, aber ohne Projektkontext.
- **Machen Sie Schlüsselbegriffe und Produktnamen fett** bei der ersten Erwähnung und in Übersichten. Dies hilft Lesern beim Scannen.
- **Verwenden Sie nummerierte Listen für sequenzielle Prozesse.** „1. **Extrahiert** Daten aus X. 2. **Transformiert** sie. 3. **Lädt** in Y.“ – machen Sie das Verb fett.
- **Codebeispiele sollten ausführbar sein.** Kopieren Sie nach Möglichkeit aus der tatsächlichen Codebasis.
- **Umgebungsvariablen-Tabellen sind nicht verhandelbar.** Listen Sie jede einzelne auf.
- **Fehlerbehebung im Tabellenformat** (Symptom | Wahrscheinliche Ursache | Lösung) – scannbar und konsistent.
- **Anmerkungen zur Verzeichnisstruktur sollten kurz sein.** Ein kurzer Satz pro Verzeichnis.
- **Fügen Sie immer einen Kontaktabschnitt ein.** Fragen Sie den Benutzer, wer das Projekt verwaltet. Format: `**Name** — [email protected]`.
- **Verwenden Sie `---` horizontale Trennlinien** zwischen allen Hauptabschnitten für visuelle Struktur.
## Ausgabe
Speichern Sie das README als `README.md` im Stammverzeichnis des Repositories (oder im aktuellen Arbeitsverzeichnis, wenn kein Repository-Stamm identifizierbar ist). Wenn bereits eine README.md existiert, bestätigen Sie mit dem Benutzer, bevor Sie überschreiben – er möchte möglicherweise Teile davon behalten.