Wiki-Onboarding-Leitfaden-Generator

Erstellen Sie vier auf die jeweilige Zielgruppe zugeschnittene Onboarding-Dokumente im Ordner „onboarding/“, wobei jedes Dokument einem anderen Beteiligten genau die Informationen liefert, die er benötigt.

Festlegung des Quell-Repositorys (MUSS ZUERST ERFOLGEN)

Bevor Sie Anleitungen erstellen, MÜSSEN Sie den Kontext des Quell-Repositorys ermitteln:

1. Auf „git remote“ prüfen: Führen Sie „git remote get-url origin“ aus, um festzustellen, ob ein Remote vorhanden ist
2. Fragen Sie den Benutzer: „Handelt es sich um ein rein lokales Repository oder haben Sie eine URL für das Quell-Repository (z. B. GitHub, Azure DevOps)?“
   • Remote-URL angegeben → als `REPO_URL` speichern, verknüpfte Verweise verwenden: [Datei:Zeile](REPO_URL/blob/BRANCH/file#Lline)
   • Nur lokal → lokale Zitate verwenden: (Dateipfad:Zeilennummer)
3. Standardzweig ermitteln: „git rev-parse --abbrev-ref HEAD“ ausführen
4. Fahren Sie NICHT fort, bis der Kontext des Quell-Repositorys geklärt ist

Wann aktivieren?

• Der Benutzer fragt nach Onboarding-Dokumenten oder Einführungsanleitungen
• Der Benutzer führt den Befehl ` /deep-wiki:onboard ` aus
• Der Benutzer möchte neuen Teammitgliedern helfen, eine Codebasis zu verstehen

Ausgabestruktur

Erzeuge einen Ordner „onboarding/“ mit folgenden Dateien:

onboarding/
├── index.md                    # Onboarding-Hub – Links zu allen 4 Leitfäden mit Zielgruppenbeschreibungen
├── contributor-guide.md        # Für neue Mitwirkende (setzt Python- oder JS-Kenntnisse voraus)
├── staff-engineer-guide.md     # Für Staff- und Principal-Engineers
├── executive-guide.md          # Für technische Führungskräfte auf VP-/Direktorenebene
└── product-manager-guide.md    # Für Produktmanager und nicht-technische Stakeholder

index.md — Onboarding-Hub

Eine Landingpage mit:

• Ein Absatz mit einer Projektzusammenfassung
• Tabelle zur Auswahl der Leitfäden:

Spracherkennung

Das Repository wird nach Build-Dateien durchsucht, um die Hauptsprache für Code-Beispiele zu ermitteln:

• package.json / tsconfig.json → TypeScript/JavaScript
• *.csproj / *.sln → C# / .NET
• Cargo.toml → Rust
• pyproject.toml / setup.py / requirements.txt → Python
• go.mod → Go
• pom.xml / build.gradle → Java

Leitfaden 1: Leitfaden für Mitwirkende

Datei: onboarding/contributor-guide.md Zielgruppe: Entwickler, die dem Projekt beitreten. Setzt Kenntnisse in Python oder JavaScript sowie allgemeine Erfahrung in der Softwareentwicklung voraus. Umfang: 1000–2500 Zeilen. Aufbauend – jeder Abschnitt baut auf dem vorherigen auf.

Erforderliche Abschnitte

Teil I: Grundlagen (überspringen, wenn das Repo Python oder JS verwendet)

1. {Primärsprache} für Python-/JS-Entwickler – Tabellen zum Syntaxvergleich, asynchrones Modell, Sammlungen, Typsystem, Paketverwaltung. Konkrete Code-Beispiele im direkten Vergleich, KEINE abstrakten Beschreibungen.
2. Grundlagen des {Primär-Frameworks} – Vergleich mit entsprechenden Python-/JS-Frameworks (z. B. FastAPI, Express). Request-Pipeline, Routing, DI, Konfiguration.

Teil II: Diese Codebasis 3. Was dieses Projekt leistet – 2–3-sätziger Elevator Pitch 4. Projektstruktur – Kommentierter Verzeichnisbaum (was befindet sich wo und warum). Füge eine grafische Übersicht über die TB-Architektur bei. 5. Kernkonzepte – Domänenspezifische Terminologie, erklärt anhand von Code-Beispielen. Verwende ein EDIagramm für das Datenmodell. 6. Lebenszyklus einer Anfrage – Sequenzdiagramm (mit automatischer Nummerierung), das eine typische Anfrage von Anfang bis Ende nachverfolgt. 7. Wichtige Muster – Vorlagen nach dem Motto „Wenn du X hinzufügen möchtest, folge diesem Muster“ mit echtem Code

Teil III: Produktiv werden 8. Voraussetzungen & Einrichtung – Tabelle: Tool, Version, Installationsbefehl. Schritt-für-Schritt-Anleitung mit erwarteter Ausgabe bei jedem Schritt. 9. Ihre erste Aufgabe – Durchgängige Anleitung zum Hinzufügen einer einfachen Funktion 10. Entwicklungs-Workflow – Branch-Strategie, Commit-Konventionen, PR-Prozess. Verwendung von Flussdiagrammen. 11. Tests ausführen – Alle Tests, einzelne Datei, einzelner Test, Befehle zur Testabdeckung 12. Debugging-Leitfaden – Tabelle mit häufigen Problemen: Symptom, Ursache, Lösung 13. Häufige Fallstricke – Fehler, die jeder neue Mitwirkende macht, und wie man sie vermeidet

Anhänge

• Glossar (über 40 Begriffe)
• Wichtige Dateireferenz – Tabelle: Pfad, Zweck, Bedeutung, Quelle
• Schnellreferenzkarte – Spickzettel mit den am häufigsten verwendeten Befehlen und Mustern

Regeln

• Alle Code-Beispiele in der erkannten Hauptsprache
• Jeder Befehl muss kopierbar und einfügbar sein und die erwartete Ausgabe enthalten
• Mindestens 5 Mermaid-Diagramme (Architektur, ER, Sequenz, Flussdiagramm, Zustandsdiagramm)
• Verwende Mermaid für Workflow-Diagramme (Farben im Dunkelmodus) – füge Kommentarblock nach jedem
• Alle Aussagen müssen durch tatsächlichen Code belegt sein – zitieren Sie im verlinkten Format

Leitfaden 2: Leitfaden für Staff Engineers

Datei: onboarding/staff-engineer-guide.md Zielgruppe: Staff-/Principal-Engineers, die das „Warum“ hinter jeder Entscheidung benötigen. Umfassende Systemerfahrung, kennen möglicherweise die Sprache dieses Repos nicht. Umfang: 800–1200 Zeilen. Dicht, meinungsstark, architektonisch ausgerichtet.

Erforderliche Abschnitte

1. Zusammenfassung – Was das System ist, in einem prägnanten Absatz. Was es selbst übernimmt und was es delegiert.
2. Die zentrale architektonische Erkenntnis — Das EINZIGE wichtigste Konzept. Füge Pseudocode in einer ANDEREN Sprache als der des Repos ein.
3. Systemarchitektur – Vollständiges Mermaid -TB -Diagramm. Heben Sie das „Herzstück“ des Systems hervor.
4. Domänenmodell – Mermaid-ER-Diagramm der Kernentitäten. Tabelle der Dateninvarianten: Entität, Invariante, Durchgesetzt von, Quelle.
5. Wichtige Abstraktionen und Schnittstellen — Klassendiagramm, das die tragenden Abstraktionen zeigt.
6. Anfrage-Lebenszyklus – Sequenzdiagramm (mit automatischer Nummerierung), das eine typische Anfrage vom Eingang bis zur Antwort darstellt.
7. Zustandsübergänge – „stateDiagram-v2“ für Entitäten mit aussagekräftigen Lebenszykluszuständen.
8. Entscheidungsprotokoll – Tabelle: Entscheidung, in Betracht gezogene Alternativen, Begründung, Quelle.
9. Begründung der Abhängigkeiten – Tabelle: Abhängigkeit, Zweck, Was sie ersetzt hat, Quelle.
10. Datenfluss und Zustand — Wie Daten durch das System fließen. Vergleichstabelle für Speicherorte.
11. Fehlermodi und Fehlerbehandlung – Flussdiagramm für Fehlerausbreitungswege.
12. Leistungsmerkmale – Engpässe, Skalierungsgrenzen, Hot-Paths.
13. Sicherheitsmodell – Authentifizierung, Autorisierung, Vertrauensgrenzen, Datensensibilität.
14. Teststrategie – Was getestet wird, was nicht, Testphilosophie.
15. Bekannte technische Schulden – Tabelle: Problem, Risikostufe, betroffene Dateien, Quelle.
16. Wo man tiefer einsteigen sollte – Empfohlene Lesereihenfolge der Quelldateien, Links zu Wiki-Abschnitten.

Regeln

• Verwende Pseudocode in einer anderen Sprache, um Konzepte zu erklären
• Verwende Vergleichstabellen, um unbekannte Konzepte abzubilden (z. B. Task = Awaitable[T])
• Dichte Prosa mit Tabellen, KEINE oberflächlichen Aufzählungen
• Jede Behauptung muss durch einen verlinkten Verweis untermauert sein
• Mindestens 5 Mermaid-Diagramme (Architektur, ER, Klasse, Sequenz, Zustand, Flussdiagramm)
• Auf jedes Diagramm folgt Kommentarblock
• Tabellen großzügig einsetzen – Entscheidungen, Abhängigkeiten und technische Schulden sollten ALLE in Tabellen mit „Quelle“-Spalten dargestellt werden
• Konzentrieren Sie sich darauf, WARUM Entscheidungen getroffen wurden, nicht nur darauf, WAS vorhanden ist

Leitfaden 3: Leitfaden für Führungskräfte

Datei: onboarding/executive-guide.md Zielgruppe: VP/Leiter der Entwicklungsabteilung. Benötigt einen Überblick über die Funktionen, eine Risikobewertung und den Investitionskontext – KEINE Details auf Code-Ebene. Umfang: 400–800 Zeilen. Strategisch, prägnant, entscheidungsorientiert.

Erforderliche Abschnitte

1. Systemübersicht – Was es leistet, wer es nutzt, geschäftlicher Nutzen in 2–3 Sätzen
2. Funktionsübersicht – Tabelle: Funktion, Status (implementiert/teilweise/geplant), Reifegrad, Abhängigkeiten. Was das System heute leisten kann und was nicht.
3. Architektur im Überblick – Mermaid-Diagramm auf hoher Ebene (LR-Diagramm ). Dienste, Datenspeicher, externe Integrationen – KEINE internen Code-Details. Fokus auf Bereitstellungseinheiten und Teamgrenzen.
4. Teamtopologie – Welches Team/welche Person ist für welche Komponenten verantwortlich? Tabelle: Komponente, Verantwortlicher, Kritikalität, Bus-Faktor.
5. Technologie-Investitionskonzept – Warum diese Technologien ausgewählt wurden. Tabelle: Technologie, Zweck, in Betracht gezogene Alternativen, Risikostufe.
6. Risikobewertung – Tabelle: Risiko, Eintrittswahrscheinlichkeit, Auswirkung, Risikominderung, Verantwortlicher. Bezieht Zuverlässigkeit, Sicherheit, Skalierbarkeit und Compliance ein.
7. Kosten- und Skalierungsmodell – Wie skalieren die Kosten mit der Nutzung? Wo liegen die Engpässe? Wann ist die nächste Skalierungsinvestition erforderlich?
8. Abhängigkeitskarte – TB-Diagramm, das kritische externe Abhängigkeiten darstellt. Tabelle: Abhängigkeit, Typ (Dienst/Bibliothek/Plattform), Risiko bei Nichtverfügbarkeit.
9. Wichtige Kennzahlen und Überwachbarkeit – Was gemessen wird, welche Dashboards vorhanden sind, Abdeckung durch Warnmeldungen. Tabelle: Kennzahl, aktueller Wert, Zielwert, Quelle.
10. Abgleich der Roadmap — Zuordnung der technischen Arbeitsströme zu den geschäftlichen Prioritäten. Was ist in Arbeit, was ist geplant, was ist blockiert?
11. Zusammenfassung der technischen Schulden – Die 5 wichtigsten Schuldenposten mit geschäftlichen Auswirkungen. Tabelle: Problem, geschäftliche Auswirkungen, Aufwand für die Behebung, Priorität.
12. Empfehlungen – 3–5 umsetzbare Empfehlungen für das nächste Quartal, priorisiert nach Auswirkungen.

Regeln

• KEINE Code-Schnipsel – dieser Leitfaden richtet sich an technische Führungskräfte, nicht an Programmierer
• Diagramme auf Service-/Teamebene, nicht auf Klassen-/Funktions-Ebene
• Jede Aussage muss durch Belege gestützt werden – zitieren Sie Wiki-Abschnitte, Architekturdokumente oder Quelldateien
• Mindestens 3 Mermaid-Diagramme (Architekturübersicht, Abhängigkeitskarte, Funktionen/Roadmap)
• Tabellen für jede strukturierte Erkenntnis – diese Zielgruppe liest Tabellen, keine Prosa
• Geschäftssprache – technische Konzepte in Auswirkungen übersetzen (Zuverlässigkeit, Geschwindigkeit, Kosten, Risiko)

Leitfaden 4: Leitfaden für Produktmanager

Datei: onboarding/product-manager-guide.md Zielgruppe: Produktmanager und nicht-technische Stakeholder. Sie müssen verstehen, was das System leistet, was möglich ist und wo die Grenzen liegen – NICHT, wie es aufgebaut ist. Umfang: 400–800 Zeilen. Nutzerorientiert, funktionsfokussiert, unter Berücksichtigung von Einschränkungen.

Erforderliche Abschnitte

1. Was dieses System leistet – 2–3-zeiliger Elevator Pitch in nutzerorientierter Sprache (ohne Fachjargon)
2. User-Journey-Map – Mermaid -Diagramm (LR ) oder Journey -Diagramm, das die primären Nutzerabläufe durch das System darstellt
3. Funktionsübersicht – Tabelle: Funktion, Status (Live/Beta/Geplant/Nicht möglich), benutzerseitiges Verhalten, Einschränkungen. Umfassende Übersicht darüber, was implementiert ist und was nicht.
4. Datenmodell (Produktsicht) – Vereinfachtes Mermaid-erDiagram, das die Entitäten darstellt, mit denen Nutzer interagieren. Erläutern Sie dies in geschäftlichen Begriffen (z. B. „Ein Projekt hat viele Dokumente“ statt „FK-Beziehung“).
5. Konfiguration & Feature-Flags — Tabelle: Flag/Konfiguration, Was es steuert, Standardwert, Wer kann es ändern. Was ohne technische Arbeit umgeschaltet werden kann.
6. API-Funktionen – Welche Integrationen sind möglich? Tabelle: Funktion, Endpunkt/Methode, Authentifizierung, Ratenbegrenzungen. Für Integrationspartner verfasst, nicht für Entwickler.
7. Leistung & SLAs – Antwortzeiten, Durchsatzgrenzen, Verfügbarkeitsziele. Tabelle: Vorgang, erwartete Latenz, Durchsatzgrenze, aktuelles SLA.
8. Bekannte Einschränkungen & Grenzen – Ehrliche Auflistung dessen, was das System nicht kann oder nur schlecht beherrscht. Tabelle: Einschränkung, Auswirkungen auf den Nutzer, Workaround, geplante Behebung.
9. Daten & Datenschutz – Welche Daten werden erfasst, wo werden sie gespeichert, Aufbewahrungsrichtlinien, Compliance-Status. Tabelle: Datentyp, Speicherort, Aufbewahrungsfrist, Compliance.
10. Glossar – Fachbegriffe in verständlicher Sprache erklärt (kein technischer Jargon)
11. FAQ – Über 10 häufig gestellte Fragen, die ein Projektmanager stellen würde, prägnant beantwortet

Regeln

• KEIN Fachjargon – kein „Middleware“, „Dependency Injection“, „ORM“. Verwende einfache Sprache.
• Nutzerorientierte Darstellung – Beschreiben Sie alles aus der Perspektive der Nutzererfahrung, nicht aus der Perspektive der Funktionsweise des Codes
• Mindestens 3 Mermaid-Diagramme (User Journey, Datenmodell, Feature Map/Funktionsübersicht)
• Tabellen für jede strukturierte Erkenntnis – Produktmanager überfliegen Tabellen, nicht Prosatexte
• Wenn ein technisches Konzept erwähnt werden muss, erkläre es in einem Satz (z. B. „Feature-Flags – Schalter, mit denen wir Funktionen aktivieren/deaktivieren können, ohne Code bereitzustellen“)
• Jede Behauptung muss durch Belege untermauert sein – zitieren Sie zur Überprüfung Wiki-Abschnitte oder Quelldateien

Regeln für Mermaid-Diagramme (ALLE Leitfäden)

ALLE Diagramme müssen Farben im Dark-Mode verwenden:

• Knotenfüllung: #2d333b, Rahmen: #6d5dfc, Text: #e6edf3
• Hintergründe von Teilgraphen: #161b22, Rahmen: #30363d
• Linien: #8b949e
• Bei Verwendung von Inline -Stil -Anweisungen dunkle Füllfarben mit `color:#e6edf3` verwenden
• Verwende KEINE
in Mermaid-Beschriftungen (verwenden Sie stattdessen
oder Zeilenumbrüche)

Validierung

Überprüfen Sie nach der Erstellung jedes Leitfadens Folgendes:

• Alle genannten Dateipfade tatsächlich im Repo vorhanden sind
• Alle Klassen- und Methodennamen korrekt sind (keine Fantasieangaben)
• Mermaid-Diagramme werden korrekt gerendert (keine Syntaxfehler)
• Es gibt keine bloßen HTML-ähnlichen Tags (Generika wie „List“) außerhalb von Code-Blöcken – diese müssen in Backticks eingeschlossen werden
• Jeder Leitfaden ist für seine Zielgruppe geeignet – kein Code in Leitfäden für Führungskräfte/Projektmanager