Onboarding-Dokumentation mit KI erstellen

1. Warum Onboarding-Dokumentation in Magento-Projekten schnell veraltet

Onboarding-Dokumentation wird in Magento-Projekten fast immer zu Beginn geschrieben, wenn die Struktur noch übersichtlich ist, und danach kaum noch angefasst, obwohl sich Module, Konventionen und Deploy-Prozesse laufend ändern. Für neue Entwicklerinnen und Entwickler bedeutet das: Die vorhandene Dokumentation beschreibt einen Zustand, der schon lange nicht mehr dem tatsächlichen Repository entspricht, und die einzige verlässliche Quelle wird die Rückfrage bei erfahrenen Kolleginnen und Kollegen. Das bindet Senior-Zeit, verlangsamt den produktiven Start und führt dazu, dass jede Einarbeitung wieder bei null beginnt, statt auf vorheriger Arbeit aufzubauen.

Besonders in Projekten mit einem Dual-Vendor-Workflow, individuellen ViewModels statt Block-Klassen und einer festen Deploy-Sequenz mit mehreren aufeinander abgestimmten Schritten ist der Einstieg ohne aktuelle Doku fehleranfällig: Ein einzelner übersprungener Schritt beim Static-Content-Deploy führt zu stundenlanger Fehlersuche, die mit einer aktuellen Anleitung vermeidbar gewesen wäre. Genau hier setzt der Einsatz von KI an, nicht als Ersatz für Team-Wissen, sondern als Werkzeug, das den ersten, mühsamsten Schritt der Bestandsaufnahme beschleunigt.

2. Codebasis und Konventionen mit Claude systematisch erfassen

Claude Code kann ein Repository eigenständig durchsuchen, ohne dass jede Datei manuell in einen Chat kopiert werden muss. Für die Bestandsaufnahme bedeutet das: Ein einzelner Auftrag genügt, um Verzeichnisstruktur, Modulnamen, Namespace-Konventionen und wiederkehrende Muster wie die Nutzung von ViewModels statt Block-Klassen automatisch zu extrahieren. Der entscheidende Unterschied zu einer manuellen Bestandsaufnahme liegt nicht in der Genauigkeit, sondern in der Geschwindigkeit: Was ein neuer Entwickler in den ersten zwei Wochen mühsam zusammenträgt, liefert Claude in strukturierter Form innerhalb weniger Minuten als Ausgangspunkt.

Wichtig ist, den Auftrag eng zu fassen und um konkrete, überprüfbare Artefakte zu bitten, etwa eine Liste aller Module mit ihren Abhängigkeiten aus den jeweiligen module.xml-Dateien, die verwendeten Design-Patterns aus etc/di.xml, oder die tatsächlich genutzten CLI-Befehle aus dem bin/-Verzeichnis. Eine offene Frage wie „beschreibe die Architektur" führt zu vagen, schwer verifizierbaren Ergebnissen, während eine präzise Anfrage nach überprüfbaren Fakten aus dem Code zu einem Entwurf führt, der sich gezielt gegenprüfen lässt.

#!/usr/bin/env bash
# Ask Claude Code to scan the repository and extract verifiable facts
# for a first onboarding draft, instead of guessing from memory

cd src

claude -p "Scan app/code, app/design/frontend and the etc/ directories.
List every custom module with its namespace, its dependencies from
module.xml, and the design patterns actually used (ViewModel vs Block,
Plugin vs Preference). Also list every wrapper command in bin/ with a
one-line description derived from the script itself.
Mark every claim you cannot verify from the files with 'TODO: verify'." \
  --allowedTools "Read,Grep,Glob" \
  > docs/onboarding-context.md

echo "Draft context written to docs/onboarding-context.md, review before use"

3. Vom Repository zum Onboarding-Guide: Struktur und erste Version

Aus der Bestandsaufnahme lässt sich ein strukturierter Onboarding-Guide ableiten, der feste Abschnitte wie Projektüberblick, lokales Setup, Architektur-Grundlagen, Coding-Konventionen und typische Stolperfallen enthält. Claude kann diese Struktur direkt mit Inhalten aus dem Code befüllen, etwa der Docker-Compose-Konfiguration für das lokale Setup oder den PHPStan-Regeln für die Coding-Konventionen. Der generierte Entwurf ist bewusst nicht die fertige Dokumentation, sondern ein Skelett mit belastbaren, aus dem Code ableitbaren Fakten und klar markierten Lücken an den Stellen, an denen Kontext fehlt.

Diese Markierung ist der praktisch wichtigste Teil des Prompts: Claude soll jede Aussage, die nicht direkt aus dem gelesenen Code hervorgeht, explizit als offene Frage kennzeichnen, statt eine plausibel klingende Vermutung als Fakt darzustellen. So entsteht ein Dokument, das zwei Kategorien von Inhalten sauber trennt, verifizierte technische Fakten und offene Fragen für das Team, was die anschließende Ergänzung durch Menschen erheblich beschleunigt.

{
  "generated_by": "claude-code-analysis",
  "generated_at": "2026-06-18T08:40:00Z",
  "project": "mironsoft.de",
  "sections": [
    {
      "title": "Projektüberblick",
      "status": "verified",
      "source": "composer.json, docker-compose.yaml"
    },
    {
      "title": "Lokales Setup",
      "status": "verified",
      "source": "bin/start, compose.dev.yaml"
    },
    {
      "title": "Architektur und Modulübersicht",
      "status": "verified",
      "source": "app/code/*/etc/module.xml"
    },
    {
      "title": "Deploy-Sequenz",
      "status": "verified",
      "source": "CLAUDE.md"
    },
    {
      "title": "Warum Mironsoft_Core als Basisabhängigkeit gewählt wurde",
      "status": "needs_human_input",
      "source": null
    },
    {
      "title": "Ansprechpartner pro Modul",
      "status": "needs_human_input",
      "source": null
    }
  ],
  "open_questions_count": 2
}

4. Erste-Woche-Checkliste: Setup, Zugänge und erste Aufgabe

Eine der wertvollsten Komponenten jeder Onboarding-Dokumentation ist eine konkrete Erste-Woche-Checkliste: Welche Zugänge werden benötigt, welche Docker-Container müssen laufen, welcher Befehl startet die lokale Umgebung, und welche erste, klar abgegrenzte Aufgabe eignet sich, um das Setup zu verifizieren. Claude kann eine solche Checkliste direkt aus den vorhandenen Setup-Skripten, der Docker-Compose-Datei und den Wrapper-Skripten im bin/-Verzeichnis ableiten, statt sie aus dem Gedächtnis zu formulieren.

Der Vorteil gegenüber einer von Hand geschriebenen Checkliste zeigt sich vor allem bei Abweichungen: Wenn ein neues bin/-Skript hinzukommt oder ein Compose-Service umbenannt wird, veraltet eine manuell gepflegte Liste unbemerkt, während eine aus dem tatsächlichen Repository-Zustand generierte Checkliste diese Änderung automatisch mitträgt, sobald sie neu erzeugt wird. Die Checkliste ersetzt keine persönliche Einweisung, reduziert aber die Zahl der Rückfragen zu reinen Mechanik-Fragen wie „Welcher Befehl startet den Container" spürbar.

#!/usr/bin/env bash
# First-day setup checklist derived directly from the actual repo state,
# not from a hand-written list that quietly drifts out of sync

set -euo pipefail

echo "1. Clone the repository and copy the local env file"
echo "   cp env/dev.env.dist env/dev.env"

echo "2. Start the Docker stack (Mark Shust setup)"
echo "   bin/start"

echo "3. Import a sanitized database dump"
echo "   bin/mysql < var/backups/latest-sanitized.sql"

echo "4. Verify the storefront responds"
until curl -sf http://localhost/ > /dev/null; do
  echo "   waiting for the container to become healthy..."
  sleep 3
done
echo "   storefront reachable, setup verified"

echo "5. First task: fix the failing test in tests/Unit/ExampleTest.php"

5. Was nur das Team weiß: Entscheidungsgeschichte und stille Regeln

So gründlich die Codebasis-Analyse auch ausfällt, es bleibt eine ganze Kategorie von Wissen, die kein Sprachmodell aus dem Code ableiten kann: Warum wurde eine bestimmte technische Entscheidung getroffen, welche Lösung wurde bewusst verworfen, und welcher Kunde hat welche Sonderregel durchgesetzt, die jetzt als scheinbar willkürliche Ausnahme im Code steht. Dieses Wissen existiert oft nur in den Köpfen einzelner Teammitglieder, in alten Ticket-Kommentaren oder in Slack-Threads, die kein automatisierter Scan erfasst.

Der ehrliche Umgang mit dieser Grenze ist entscheidend für die Glaubwürdigkeit der gesamten Dokumentation: Ein KI-Entwurf, der bei fehlendem Kontext eine plausible, aber erfundene Begründung liefert, ist gefährlicher als eine sichtbare Lücke, weil neue Entwickler der erfundenen Begründung vertrauen und falsche Annahmen weitertragen. Deshalb gehört zu jedem guten Prompt die explizite Anweisung, Entscheidungsgründe, die nicht im Code oder in mitgelieferten Dokumenten stehen, als offene Frage für das Team zu markieren statt sie zu erfinden.

6. Der Hybrid-Workflow: KI-Entwurf, Review und menschliche Ergänzung

Ein belastbarer Workflow verbindet KI-Entwurf und Team-Wissen in einer festen Reihenfolge statt beides zu vermischen. Zuerst erstellt Claude aus der Codebasis einen Entwurf mit klar markierten offenen Fragen. Danach sichtet ein erfahrenes Teammitglied den Entwurf, korrigiert technische Ungenauigkeiten und beantwortet die markierten Fragen in einem kurzen, dedizierten Termin, statt sie über Wochen verteilt in Chat-Nachrichten zu beantworten. Erst danach wird das Dokument im Repository versioniert und als Teil des Onboarding-Prozesses verwendet.

Dieser Ablauf funktioniert am besten als kleiner Workshop mit zwei bis drei erfahrenen Teammitgliedern, die den KI-Entwurf gemeinsam durchgehen: Die Diskussion darüber, ob eine vom Modell formulierte Aussage stimmt, deckt oft zusätzliche, bisher unausgesprochene Annahmen auf, die sonst nie dokumentiert worden wären. Der KI-Entwurf wirkt hier als Gesprächsanker, der konkrete Aussagen zur Diskussion stellt, statt mit einer leeren Seite zu beginnen, vor der Teams erfahrungsgemäß besonders lange zögern.

#!/usr/bin/env node
// Flags PRs that add a new Magento module without touching the
// onboarding guide, so the module list does not silently go stale

const { execSync } = require("child_process");

const base = process.env.GITHUB_BASE_REF || "main";
const changed = execSync(`git diff --name-only origin/${base}...HEAD`)
  .toString()
  .trim()
  .split("\n");

const newModule = changed.some((f) =>
  f.match(/^src\/app\/code\/[^/]+\/[^/]+\/registration\.php$/)
);
const onboardingUpdated = changed.some((f) => f === "docs/ONBOARDING.md");

if (newModule && !onboardingUpdated) {
  console.error(
    "This PR adds a new module but docs/ONBOARDING.md was not updated. " +
    "Add the module to the overview or confirm it needs no onboarding entry."
  );
  process.exitCode = 1;
}

7. CLAUDE.md als lebendiges Onboarding-Dokument für Mensch und KI

Für Projekte, die bereits mit Claude Code arbeiten, liegt eine naheliegende Doppelnutzung nahe: Die CLAUDE.md-Datei, die Claude bei jeder Sitzung als Systemkontext liest, kann gleichzeitig als zentrales Onboarding-Dokument für neue menschliche Teammitglieder dienen. Coding-Standards, die Deploy-Sequenz, CLI-Wrapper-Befehle und Modul-Konventionen, die für die KI-Instruktion ohnehin präzise formuliert sein müssen, sind in genau dieser präzisen Form auch für Menschen nützlich, die neu ins Projekt kommen.

Der praktische Vorteil dieser Doppelnutzung liegt in einem eingebauten Frühwarnsystem: Wenn die CLAUDE.md veraltete Befehle oder falsche Pfade enthält, fällt das nicht erst auf, wenn ein Mensch danach sucht, sondern schon vorher, weil Claude Code mit den falschen Angaben sichtbar falsche Vorschläge macht oder Befehle vorschlägt, die im aktuellen Repository nicht mehr existieren. Diese Rückkopplung, die eine reine Menschen-Dokumentation nicht hat, macht Abweichungen zwischen Dokument und Realität schneller sichtbar als in einem klassischen Wiki, das niemand aktiv testet.

8. Onboarding-Doku aktuell halten statt einmalig schreiben

Der größte praktische Unterschied zwischen einer einmalig geschriebenen und einer dauerhaft nützlichen Onboarding-Dokumentation liegt nicht in der Erstqualität, sondern in der Pflege über die gesamte Projektlaufzeit. Ein Dokument, das nach dem ersten Onboarding nie wieder angefasst wird, ist nach einem größeren Refactoring, einem neuen Modul oder einer geänderten Deploy-Sequenz bereits potenziell irreführend, und irreführende Dokumentation ist für neue Entwickler oft schädlicher als gar keine, weil sie falsches Vertrauen erzeugt.

Ein wirksamer, aber wenig aufwendiger Mechanismus ist ein automatisierter Abgleich, der prüft, ob wesentliche strukturelle Änderungen im Code, etwa ein neu hinzugekommenes Modul, ihre Entsprechung im Onboarding-Dokument haben. Ergänzend hilft ein fester Termin, etwa vierteljährlich, an dem Claude beauftragt wird, den aktuellen Code-Stand erneut zu scannen und den bestehenden Text auf Abweichungen zu prüfen, statt auf zufällige Zeitpunkte zu warten, an denen jemand die Veralterung bemerkt.

#!/usr/bin/env python3
"""Warn when the onboarding guide is older than the newest module."""

import subprocess
from pathlib import Path
from datetime import datetime, timezone


def last_commit_date(path: str) -> datetime:
    output = subprocess.check_output(
        ["git", "log", "-1", "--format=%cI", "--", path]
    ).decode().strip()
    return datetime.fromisoformat(output) if output else datetime.min.replace(
        tzinfo=timezone.utc
    )


def main() -> int:
    doc_date = last_commit_date("docs/ONBOARDING.md")
    module_root = Path("src/app/code")

    newest_module_date = doc_date
    newest_module_name = None
    for module_xml in module_root.glob("*/*/etc/module.xml"):
        commit_date = last_commit_date(str(module_xml))
        if commit_date > newest_module_date:
            newest_module_date = commit_date
            newest_module_name = module_xml.parent.parent.name

    if newest_module_name:
        print(
            f"[STALE] {newest_module_name} changed on "
            f"{newest_module_date.date()}, onboarding guide is older"
        )
        return 1

    print("[OK] Onboarding guide is up to date with all modules")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

9. Onboarding-Ansätze im Vergleich

Die folgende Übersicht vergleicht typische Vorgehensweisen bei der Erstellung und Pflege von Onboarding-Dokumentation und zeigt, wo der Hybrid-Ansatz aus KI-Entwurf und menschlicher Ergänzung gegenüber den beiden reinen Varianten steht.

In der Praxis zeigt sich, dass die reinen Varianten an entgegengesetzten Enden scheitern: Rein manuelle Doku bleibt oft unvollständig, weil niemand Zeit für den ersten Entwurf findet, während rein KI-generierte Doku ohne Review-Schritt falsche Sicherheit erzeugt. Der Hybrid-Ansatz kombiniert die Geschwindigkeit der KI-Analyse mit der Verlässlichkeit menschlicher Prüfung und ist in der Praxis der einzige Ansatz, der über mehrere Monate hinweg tatsächlich aktuell bleibt.

10. Zusammenfassung

Onboarding-Dokumentation mit KI zu erstellen löst vor allem ein Aktivierungsproblem: den Sprung von der leeren Seite zu einem strukturierten, aus dem tatsächlichen Code abgeleiteten Entwurf. Claude kann Codebasis, Konventionen und Setup-Skripte systematisch durchsuchen und liefert innerhalb weniger Minuten ein Skelett, das Wochen manueller Zusammentragung ersetzt. Der Nutzen ist real und in eingesparter Senior-Zeit messbar, sobald der Entwurf als Diskussionsgrundlage statt als fertiges Dokument behandelt wird.

Der Nutzen kippt jedoch, sobald Entscheidungsgründe, Team-Wissen und offene Fragen unkommentiert bleiben oder der Text ohne Review veröffentlicht wird. Ein belastbarer Prozess trennt klar zwischen verifizierten technischen Fakten und markierten offenen Fragen, bindet erfahrene Teammitglieder für die Ergänzung ein und verankert regelmäßige Aktualisierung als festen Bestandteil des Projektalltags, nicht als einmalige Aktion nach dem ersten Onboarding.

11. FAQ: Onboarding-Dokumentation mit KI erstellen