Developer-Onboarding mit Claude Code: von Monaten auf 2 Wochen

Onboarding neuer Entwickler endet nicht mit einem Laptop. Es beschreibt den Weg von “ich kann das Repository öffnen” bis zu “ich kann eine kleine, prüfbare Änderung einreichen, die zu den Teamregeln passt”. Langsam wird dieser Prozess meistens durch wiederholte Setup-Fragen, eine große Codebasis, unklare Review-Erwartungen und Wissen, das nur erfahrene Teammitglieder im Kopf haben.

Claude Code sollte Mentoren nicht ersetzen. Der praktische Nutzen liegt darin, ein sicheres Gerüst zu schaffen: Projektregeln in CLAUDE.md, ein wiederholbares Setup-Skript, klare Berechtigungen, eine Checkliste für die erste Aufgabe, eine PR-Vorlage und verständliche CI-Nachweise. Einfach gesagt: Die Codebasis ist der gesamte Quellcode der Anwendung, ein PR ist eine Änderungsanfrage zur Prüfung, und CI ist das System, das vor dem Merge automatisch Tests und Builds ausführt.

Da sich Claude Code ändern kann, sollten die offiziellen Dokumente maßgeblich bleiben: Claude Code setup, CLI reference, memory und settings. Passende Vertiefungen sind codebase navigation, code review und CLAUDE.md templates.

flowchart LR
  A["Day 1: setup"] --> B["Day 2: codebase map"]
  B --> C["Day 3-5: first task"]
  C --> D["Week 2: PR review"]
  D --> E["Retrospective and docs update"]

1. Mit CLAUDE.md beginnen

CLAUDE.md ist der Projektspeicher, den Claude Code als gemeinsame Anleitung liest. Für Onboarding zählen konkrete Kommandos, Grenzen und Eskalationsregeln mehr als allgemeine Prinzipien.

cat > CLAUDE.md <<'EOF'
# Project instructions for Claude Code

## Goal
Help new engineers make small, reviewable changes without bypassing tests or team rules.

## Daily commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test -- --runInBand
- Lint: npm run lint
- Build: npm run build

## Boundaries
- Do not edit files under migrations/ without human approval.
- Do not read .env, .env.*, secrets/, or production credentials.
- Do not push, commit, deploy, or publish packages.
- Prefer small diffs under 150 lines for first tasks.

## First PR rules
- Explain the intent before editing.
- Reuse existing patterns before adding dependencies.
- Add or update tests for behavior changes.
- Include command output in the PR description.

## When stuck
Ask the engineer to provide:
1. What they tried
2. The exact error
3. The file or command involved
4. What Claude Code inferred and what still needs human judgment
EOF

Das Ziel ist nicht, Claude Code zu einem magischen Senior zu machen. Es geht darum, den Arbeitsumfang so klein zu halten, dass neue Teammitglieder Standards lernen und Reviewer einen nachvollziehbaren Diff bekommen.

2. Setup reproduzierbar machen

Die erste Hürde sind oft Node-Version, Abhängigkeiten, lokale Umgebungsvariablen, Testdaten und die Frage, welcher Befehl Erfolg beweist. Ein Skript macht daraus einen klaren Pfad.

mkdir -p scripts
cat > scripts/onboarding-setup.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

echo "== Checking required tools =="
node --version
npm --version
git --version

if ! command -v claude >/dev/null 2>&1; then
  echo "Claude Code is not installed."
  echo "Install with: npm install -g @anthropic-ai/claude-code"
  exit 1
fi

echo "== Installing dependencies =="
npm ci

if [ ! -f .env ] && [ -f .env.example ]; then
  cp .env.example .env
  echo "Created .env from .env.example. Fill in local-only values before running the app."
fi

echo "== Running baseline checks =="
npm run lint
npm run typecheck
npm test -- --runInBand

echo "== Ask Claude Code for a local map =="
claude -p "Read README.md, package.json, and CLAUDE.md. Explain how to start this project locally, which checks just ran, and what a new engineer should verify before opening the first PR."
EOF
chmod +x scripts/onboarding-setup.sh

Für ein typisches npm-Projekt ist das direkt ausführbar. Teams mit pnpm, Yarn, Docker Compose oder Makefile ersetzen nur die Befehle. Wichtig ist: ein Setup-Pfad, ein Prüfpfad und eine Erklärung durch Claude Code.

3. Berechtigungen absichern

Claude Code kann Dateien lesen, Code suchen, Befehle ausführen und bei Erlaubnis editieren. Das ist hilfreich, aber gefährlich, wenn .env gelesen, destructive Commands ausgeführt oder zu große Änderungen erzeugt werden.

mkdir -p .claude
cat > .claude/settings.json <<'EOF'
{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(npm test:*)"
    ],
    "ask": [
      "Edit",
      "Write",
      "Bash(npm install:*)",
      "Bash(git checkout:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push:*)",
      "Bash(git commit:*)",
      "Bash(rm:*)",
      "Bash(curl:*)",
      "Bash(npm publish:*)"
    ]
  }
}
EOF

In der ersten Woche reichen Lesen, Suche, Diff, Log und Tests. Edits können Bestätigung verlangen. Push, Commit, Deploy, Publish und Secret-Zugriff gehören nicht in den Onboarding-Pfad.

4. Checkliste für den ersten PR

Der erste PR ist eine Lernaufgabe. Geeignet sind ein fehlender Unit-Test für bestehendes Verhalten, ein kleiner UI-Textfix, eine bessere Fehlermeldung oder das Entfernen doppelter Helper-Logik in einem Ordner. Ungeeignet sind Auth, Billing, Permissions, Migrationen, Massenformatierung und Dependency-Upgrades.

mkdir -p docs/onboarding
cat > docs/onboarding/first-task-checklist.md <<'EOF'
# First task checklist

## Before editing
- [ ] I can run `npm ci`.
- [ ] I can run `npm run lint`.
- [ ] I can run `npm run typecheck`.
- [ ] I can run the nearest test for the area I will touch.
- [ ] I understand the user-visible behavior being changed.

## Good first task examples
- [ ] Add a missing unit test around existing behavior.
- [ ] Fix a small UI copy typo with screenshot evidence.
- [ ] Replace duplicated helper logic in one folder.
- [ ] Improve one error message without changing API contracts.

## Not good for the first task
- [ ] Authentication, billing, permissions, or migrations.
- [ ] Broad formatting changes.
- [ ] Dependency upgrades.
- [ ] Refactors across multiple packages.

## PR evidence
- [ ] Summary of the change.
- [ ] Test commands and results.
- [ ] Screenshot or log if behavior changed.
- [ ] Open question for reviewer, if any.
EOF

Damit decken Sie mehrere reale Fälle ab: selbstständiges Setup, Codebasis verstehen, erste Aufgabe wählen und vor dem PR selbst prüfen.

5. Review-Anfragen standardisieren

Viele erste PRs kommen zurück, weil Reviewer nicht sehen, was geprüft wurde. Eine Vorlage zwingt zu Ziel, Sicherheit, Verifikation und Review-Fokus.

mkdir -p .github
cat > .github/pull_request_template.md <<'EOF'
## Summary
- TODO

## Why this is safe for a first PR
- Scope:
- Files changed:
- Behavior changed:

## Verification
- [ ] `npm run lint`
- [ ] `npm run typecheck`
- [ ] `npm test -- --runInBand`

## Claude Code self-review prompt used
Ask Claude Code:
"Review git diff origin/main...HEAD for naming, tests, security, and consistency with CLAUDE.md. Return only actionable issues."

## Reviewer focus
- TODO

## Screenshots or logs
- TODO
EOF

Auch Mentoren profitieren: Sie erkennen schnell, ob Design, Tests, Verhalten, Screenshots oder Prozessverständnis geprüft werden sollen.

6. CI ab Tag eins erklären

CI bedeutet Continuous Integration. Das System führt Checks aus, bevor ein PR gemerged wird. Neue Entwickler sollten lernen, Fehler lokal zu reproduzieren, nicht nur einen roten Status zu sehen.

name: onboarding-checks

on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --runInBand
      - run: npm run build

Auch mit einem anderen CI-System sollten diese Befehle in die Onboarding-Dokumentation. Claude Code kann anschließend ein fehlgeschlagenes Log lesen und den ersten lokalen Reproduktionsschritt erklären.

Typische Fehler

Erstens: Geschäftsentscheidungen an Claude Code delegieren. Code und Historie liefern Hinweise, aber Kundenversprechen, Ausnahmen und Compliance bleiben menschliche Verantwortung.

Zweitens: Der erste PR ist zu groß. Halten Sie ihn möglichst unter 150 Zeilen, mit Tests und leichtem Rollback.

Drittens: Secrets werden offengelegt. Sperren Sie .env, Credentials und Produktionsdateien in den Settings und verwenden Sie in Dokumenten nur Beispielwerte.

Viertens: Menschliche Fragen werden zu stark blockiert. “Frag zuerst Claude” funktioniert nur, wenn es in den ersten zwei Wochen häufige Mentor-Check-ins gibt.

CTA

Für Teams sollten CLAUDE.md, Berechtigungen, PR-Nachweise und CI-Checks gemeinsam standardisiert werden. Einzelne Entwickler starten mit der kostenlosen Cheatsheet. Wiederverwendbare Vorlagen finden Sie unter ClaudeCodeLab products. Für Training, Permissions und Rollout in echten Repositories nutzen Sie Claude Code training and consultation.

Ergebnis im Praxistest

Bei ClaudeCodeLab-Artikeln und kleinen Codeänderungen war der wichtigste Hebel, Regeln vor der Implementierungsanfrage zu schreiben. Mit CLAUDE.md, begrenzten Berechtigungen, Prüfkommandos und PR-Vorlage war der Diff deutlich leichter zu prüfen. Wenn Claude Code falsch lag, machten gespeicherte Annahmen und Befehle das Missverständnis schnell sichtbar.