Team-Onboarding in Claude Code

Problem: Du hast drei Monate damit verbracht, ein maßgeschneidertes Claude Code-Harness zu bauen. Dutzende von Skills. Eine Handvoll eigener Slash-Befehle. Zwei oder drei Subagenten. Deine eigene Nutzung ist zur zweiten Natur geworden. Jedes neue Teammitglied, das es zu nutzen versucht, ist innerhalb der ersten Stunde verloren.

Schnelle Lösung: Neu in v2.1.101. Führe den Befehl einmal im Root deines Projekts aus, und er schreibt einen vollständigen Einarbeitungsdoc basierend darauf, wie du wirklich arbeitest:

claude -p "/team-onboarding"

Claude liest deine letzten 30 Tage lokaler Nutzung, scannt den .claude/-Ordner, prüft CLAUDE.md, läuft durch die Projektstruktur, und legt eine Markdown-Datei ab, die du einem neuen Teammitglied geben kannst. Kein manuelles README. Kein "Stammwissen"-Spreadsheet. Kein quartalsweises Onboarding-Audit.

Was /team-onboarding eigentlich ist

Es ist ein eingebauter Slash-Befehl, der einen Einarbeitungsguide aus zwei sehr unterschiedlichen Datenquellen generiert. Strukturelle Daten: deine .claude/commands/, .claude/skills/, .claude/agents/, CLAUDE.md, konfigurierte MCP-Server, Nachbar-Repos. Verhaltensdaten: wie oft du jeden Befehl in den letzten 30 Tagen ausgeführt hast, welchen Arbeitstypen diese Befehle zugeordnet sind, welche MCP-Server du berührt hast.

Die beiden Quellen werden in einem einzigen Markdown-Doc zusammengefasst, das sich liest wie ein Senior-Engineer, der einen First-Day-Guide für den neuen Mitarbeiter schreibt, der bei ihm hospitiert.

Es ist keine Echtzeit-Onboarding-Oberfläche. Es ist kein Chat. Es läuft einmal, schreibt eine Datei, und beendet sich. Die Datei, die du bekommst, ist ein Snapshot, wie das Tool innerhalb deines Repos genutzt wurde.

Was es liest

Sechs Inputs speisen den Guide. Jeder Input ist lokal. Nichts verlässt deinen Rechner außer den Calls an Claude selbst.

Die Nutzungshistorie ist der Grund, warum dieses Feature interessant ist. Jedes Tool kann Dateien auflisten. Nur wenige können einem neuen Mitarbeiter sagen, dass der Senior-Dev /claude-scout siebenmal im Monat ausführt und MCP nie angefasst hat. Diese zweite Schicht ist das, was aus einer Dateiliste einen Einarbeitungsdoc macht.

Wie der Output aussieht

Hier ist ein echter, unbearbeiteter Sample aus einem Content-Factory-Repo, das einen Monat aktiv genutzt wurde:

# Welcome to Build This Now

## How We Use Claude

Based on speedy_devv's usage over the last 30 days:

Work Type Breakdown:
  Write Docs        █████████░░░░░░░░░░░  44%
  Build Feature     ███████░░░░░░░░░░░░░  33%
  Plan Design       ████░░░░░░░░░░░░░░░░  22%

Top Skills & Commands:
  /claude-scout     ████████████████████  7x/month
  /carousel         ██████░░░░░░░░░░░░░░  2x/month
  /compact          ██████░░░░░░░░░░░░░░  2x/month
  /claude-research  ███░░░░░░░░░░░░░░░░░  1x/month
  /resume           ███░░░░░░░░░░░░░░░░░  1x/month

Top MCP Servers:
  _None configured yet_

## Your Setup Checklist

### Codebases
- [ ] btn-content-factory (this repo, content generation pipeline)
- [ ] claude-code-seo-machine, sibling repo (blog paraphrase + SEO)
- [ ] build-kit-template, the framework itself

### MCP Servers to Activate
- [ ] _None in use yet_

### Skills to Know About
- /claude-scout: hourly scout for Anthropic/Claude Code news. Most-used
  command on the team.
- /carousel: builds an Instagram carousel via the carousel-designer +
  carousel-evaluator GAN loop.
- /blog-post: turns a carousel into a /blog/guide/ MDX page + hero image.

## Team Tips
_TODO_

## Get Started
_TODO_

Fünf Abschnitte kommen zurück. Der Header zieht den Team-Namen aus CLAUDE.md. "How We Use Claude" ist die Verhaltensschicht. "Your Setup Checklist" ist strukturell. "Team Tips" und "Get Started" sind interaktive Platzhalter, die der Befehl dich nach dem ersten Durchlauf zu füllen bittet.

Die Balkendiagramme sind kein Schmuck. Sie sind Shell-sicheres ASCII, sodass du die Datei überall einfügen kannst und der Rhythmus der Team-Arbeit auf einen Blick sichtbar ist. Ein neues Teammitglied, das es überfliegt, weiß in zehn Sekunden, dass dieses Team mehr dokumentiert als es baut, in /claude-scout lebt, und kein MCP verdrahtet hat. Das ist besserer Kontext als die meisten Onboarding-Decks.

Wie man es ausführt

Zwei Wege, es aufzurufen. Beide landen beim gleichen Output.

Headless ausführen, in eine Datei pipen:

claude -p "/team-onboarding" > ONBOARDING.md

Oder in einer interaktiven Session ausführen:

/team-onboarding

Die interaktive Version stellt drei Folgefragen nach dem ersten Entwurf. Wie das Team heißt. Ob es einen guten ersten Task für den neuen Mitarbeiter gibt. Welche Team-Tipps du aufschreiben willst, die noch nicht in CLAUDE.md sind. Beantworte sie und die _TODO_-Abschnitte werden gefüllt. Überspringst du sie, wird die Datei mit den Platzhaltern ausgegeben.

Die Headless-Version fragt nicht. Sie schreibt den Entwurf so, wie er ist, _TODO_-Abschnitte und alles.

Tag eins vs. Woche eins

Hier ist das, was die meisten übersehen. Der Befehl mischt strukturelle Daten mit Verhaltensdaten. Die strukturellen Daten existieren am Tag eins. Die Verhaltensdaten nicht.

Ein frischer Clone deines Repos ohne Nutzungshistorie gibt dir ein halb gefülltes Doc. Du bekommst die Setup-Checkliste, das Skills-Inventar, die MCP-Liste. Du bekommst nicht die Arbeitstyp-Aufschlüsselung, die Häufigkeitsbalken oder das Signal, das dem neuen Mitarbeiter sagt, welcher Befehl am meisten genutzt wird.

Führe den Befehl zu früh aus, und der Output liest sich wie eine trockene Dateiliste. Führe ihn nach einer Woche echter Arbeit aus, und er liest sich wie ein Senior-Engineer, der ihn für dich geschrieben hat.

Der richtige Weg ist nicht "neues Teammitglied führt es am ersten Tag aus." Der richtige Weg ist "der erfahrene Engineer führt es auf seiner eigenen Umgebung aus, bearbeitet den Output, und übergibt die kuratierte Datei dem neuen Mitarbeiter."

Mit deinem Harness ausliefern

Wenn du ein Framework, Template oder ein internes Toolkit pflegst, das andere nutzen, wird der Befehl zu einem Distributionsfeature.

Führe /team-onboarding in deiner Haupt-Entwicklungsumgebung aus. Deine Nutzungshistorie ist inzwischen reich. Du bekommst die vollständige Verhaltensschicht. Bearbeite persönliche Pfade, die du nicht teilen willst, heraus. Committe das Ergebnis in dein Repo als docs/how-we-use-claude-code.md. Liefere es mit deinem nächsten Release aus.

Deine Nutzer bekommen jetzt etwas, das kein Boilerplate oder Starter-Kit jemals gegeben hat. Einen Snapshot, wie die Leute, die das Framework gebaut haben, es tatsächlich täglich nutzen. Nicht die Marketing-Version. Nicht die Feature-Liste. Die echten Nutzungsmuster.

Aktualisiere es bei jedem Release. Neue Befehle, die du hinzugefügt hast, tauchen automatisch auf, weil du sie genutzt hast. Neue Skills, die du verdrahtet hast, tauchen auf, weil der strukturelle Scan sie findet. Alte Befehle, die du aufgehört hast zu nutzen, verschwinden aus der Top-Liste. Der Doc entwickelt sich mit dem Tool mit, ohne dass du einen einzigen Satz von Hand schreibst.

Das gleiche Muster funktioniert innerhalb eines Unternehmens. Führe es auf der Umgebung des Staff-Engineers aus. Committe den Output als die kanonische "how we use Claude Code"-Datei deines Teams. Überprüfe es einmal pro Quartal. Aktualisiere, wenn es driftet.

Konfiguration und Steuerung

Drei Regler, die es sich zu kennen lohnt.

Output-Ziel. Pipe den Headless-Run wohin du willst. In eine Repo-Datei, in ein Team-Wiki, in ein geteiltes Doc. Der Output ist plain Markdown mit ASCII-sicheren Balken.

Rückblick-Fenster. Der Standard ist 30 Tage. Für einen Senior-Engineer, der seit Monaten im Repo ist, ist das das richtige Fenster. Für ein kurzes Projekt kann 30 Tage alles abdecken, was du je getan hast.

Interaktive Folgefragen. Die interaktive Version stellt Fragen. Die Headless-Version überspringt sie. Wenn du den gesamten Flow skripten willst, nutze Headless und fülle die _TODO_-Abschnitte von Hand aus. Wenn du willst, dass Claude dir hilft, die Team-Tipps zu formulieren, nutze interaktiv.

Es gibt auch ein verstecktes Signal am Ende der Datei. Ein HTML-Kommentar mit dem Text onboarding buddy mode. Das ist ein Follow-up-Hook. Das nächste Mal, wenn ein Teammitglied eine Claude Code-Session im gleichen Repo öffnet, behandelt Claude sich selbst als Onboarding-Buddy für diese Datei. Du übergibst dem neuen Mitarbeiter das Markdown-Doc und Claude Code selbst. Claude führt sie durch den Doc, einen Abschnitt nach dem anderen, und beantwortet unterwegs Fragen.

Best Practices

Führe es auf der Umgebung mit der reichsten Nutzung aus. Die Verhaltensschicht zahlt sich nur aus, wenn der Befehl echte Daten zu lesen hat. Führe es nicht auf einem frischen Clone aus. Führe es auf dem Laptop aus, auf dem die Arbeit wirklich passiert.

Bearbeite es vor dem Ausliefern. Der erste Entwurf hat persönliche Pfade, Nachbar-Repo-Referenzen und manchmal den GitHub-Handle eines Teammitglieds eingebaut. Bereinige diese, bevor du die Datei committest. Behandle den Output als ersten Entwurf, nicht als fertiges Doc.

Regeneriere bei jedem Release. Richte ein just onboarding oder npm-Skript ein. Eine Zeile, ein Befehl. Nochmal ausführen, wenn du eine neue Version herausgibst. Der Doc bleibt aktuell, ohne dass du ihn anfassen musst.

Kombiniere es mit CLAUDE.md. CLAUDE.md sind deine Regeln für die KI. Der Onboarding-Doc sind deine Regeln für den Menschen. Sie ergänzen sich. Einer sagt Claude, wie es sich verhalten soll. Der andere sagt dem neuen Mitarbeiter, wie das Team arbeitet.

Lies den Output selbst. Das erste Mal, wenn du es ausführst, nimm fünf Minuten und lies, was Claude über deine eigene Arbeit bemerkt hat. Du wirst etwas lernen. Die meisten Engineers kennen ihre eigenen drei meistgenutzten Befehle nicht, bis sie das Balkendiagramm sehen.

Nächste Schritte

• Richte CLAUDE.md ein, um die Regeln deines Teams für Claude zu verankern
• Erkunde Auto-Memory für projektbezogenes Wissen, das Claude selbst schreibt
• Lerne das .claude/rules/-Verzeichnis für modulare Projektanweisungen kennen
• Lies über eigene Skills, um zu verstehen, was dein Onboarding-Doc inventarisiert
• Schau dir Agenten-Teams an, wenn dein Workflow mehrere parallele Subagenten umfasst

Team-Onboarding schließt die Lücke zwischen dem, was du gebaut hast, und dem, was dein Team wirklich nutzen kann. Dein Harness hört auf, ein persönliches Cockpit zu sein, und wird zur geteilten Werkbank. Führe es einmal aus, gib die Datei dem neuen Mitarbeiter, und geh zurück zum Ausliefern.