Claude Code Workflow für Teams etablieren

1. Warum Teams einen einheitlichen Claude Code Workflow brauchen

Sobald mehr als ein Entwickler Claude Code im selben Projekt einsetzt, entstehen fast zwangsläufig unterschiedliche Nutzungsmuster. Der eine lässt Claude Code ganze Feature-Branches im Auto-Accept-Modus umbauen, der andere nutzt es nur für einzelne Funktionssignaturen, ein Dritter kopiert Vorschläge ungeprüft in produktiven Code. Ohne gemeinsame Leitplanken entsteht so ein Flickenteppich aus Codequalität, Commit-Historie und Review-Aufwand, der sich nicht auf die KI zurückführen lässt, sondern auf fehlende Absprachen im Team.

Das Problem verschärft sich, je größer das Team und je älter die Codebasis wird. Ein Modul, das nach den Konventionen eines einzelnen Entwicklers mit Claude Code entstanden ist, kann für Kollegen schwer nachvollziehbar sein, wenn Namensgebung, PHPDoc-Tiefe oder Architekturentscheidungen von den übrigen Modulen abweichen. Ein dokumentierter Workflow löst dieses Problem nicht durch strengere Kontrolle der KI, sondern durch klare, versionierte Regeln, an die sich Mensch und Modell gleichermaßen halten. Die folgenden Abschnitte zeigen, wie ein solcher Workflow konkret aufgebaut wird.

2. CLAUDE.md als gemeinsamer Vertrag für das Team

Die Datei CLAUDE.md im Projekt-Root ist der zentrale Ort, an dem ein Team seine Konventionen für Claude Code festhält. Anders als eine Wiki-Seite wird sie bei jeder Sitzung automatisch geladen und wirkt damit unmittelbar auf jede Interaktion, unabhängig davon, wer sie startet. Das macht sie zu einem lebenden Vertrag zwischen Team und Werkzeug: Tech-Stack, Verzeichnisstruktur, Coding-Standards, verbotene Muster und Deploy-Reihenfolgen stehen an einer Stelle, statt in Slack-Nachrichten oder im Gedächtnis einzelner Entwickler zu verschwinden.

Entscheidend ist, dass CLAUDE.md im Repository versioniert wird und damit denselben Pull-Request-Prozess durchläuft wie jede andere Codeänderung. Eine Ergänzung der Datei, etwa eine neue Regel zu Service Contracts oder eine geänderte Deploy-Reihenfolge, wird von Kollegen geprüft, bevor sie für das gesamte Team wirksam wird. Persönliche Vorlieben, die nicht für alle gelten sollen, gehören stattdessen in nicht versionierte, lokale Konfigurationsdateien. Diese Trennung verhindert, dass die zentrale Konvention durch individuelle Sonderwünsche verwässert wird.

#!/usr/bin/env bash
# setup-dev-environment.sh: verify the shared Claude Code workflow is in place
set -euo pipefail

echo "[1/4] Checking for project CLAUDE.md ..."
if [[ ! -f "CLAUDE.md" ]]; then
  echo "[ERROR] CLAUDE.md is missing at project root. Team conventions are not loaded." >&2
  exit 1
fi

echo "[2/4] Checking for shared permission settings ..."
if [[ ! -f ".claude/settings.json" ]]; then
  echo "[WARN] .claude/settings.json not found, developer runs with default prompts only"
fi

echo "[3/4] Checking for shared slash commands ..."
command_count=$(find .claude/commands -type f -name "*.md" 2>/dev/null | wc -l || echo 0)
echo "Found ${command_count} shared slash commands"

echo "[4/4] Validating CLAUDE.md is tracked by git ..."
git ls-files --error-unmatch CLAUDE.md >/dev/null 2>&1 || {
  echo "[ERROR] CLAUDE.md exists but is not committed to the repository" >&2
  exit 1
}

echo "Workflow setup looks consistent with team conventions."

3. Coding-Standards und Projektkontext dokumentieren

Eine CLAUDE.md, die nur allgemeine Höflichkeitsfloskeln oder vage Zielsetzungen enthält, bringt wenig. Wirksam wird sie erst durch konkrete, überprüfbare Regeln: welche Architekturmuster verpflichtend sind, welche PHPStan-Stufe ohne Ausnahmen erreicht werden muss, welche Magento-Interface-Lücken bekannt sind und wie damit umzugehen ist. Je konkreter eine Regel formuliert ist, desto zuverlässiger hält sich Claude Code daran, und desto einfacher lässt sich im Review prüfen, ob eine Änderung der dokumentierten Konvention entspricht.

Gleichzeitig sollte die Datei nicht zu einem unüberschaubaren Nachschlagewerk anwachsen, das bei jeder Anfrage vollständig in den Kontext geladen wird und dadurch wertvollen Platz für den eigentlichen Code beansprucht. Bewährt hat sich eine schlanke CLAUDE.md mit den wichtigsten, projektweit gültigen Regeln, ergänzt um modul- oder verzeichnisspezifische CLAUDE.md-Dateien in Unterordnern, die nur dann geladen werden, wenn Claude Code tatsächlich in diesem Bereich arbeitet. So bleibt der Kontext relevant, ohne dass Teams ständig zwischen Vollständigkeit und Kontextgröße abwägen müssen.

4. Review-Erwartungen für KI-unterstützte Änderungen festlegen

Eine der häufigsten Fehlannahmen in Teams ist, dass mit Claude Code erstellter Code weniger Review benötigt, weil er "bereits von einer KI geprüft" wurde. Das Gegenteil ist der Fall: Ein Reviewer muss weiterhin die fachliche Korrektheit, die Sicherheitsimplikationen und die Architekturentscheidungen bewerten, unabhängig davon, wer oder was den Code geschrieben hat. Ein klar formulierter Review-Standard hält deshalb fest, dass KI-Herkunft die Prüftiefe nicht reduziert, sondern in bestimmten Bereichen sogar erhöhen sollte, etwa bei generierten Datenbank-Migrationen oder sicherheitsrelevanten Prüfungen.

Praktisch bewährt sich eine Kennzeichnungspflicht: Commits, die überwiegend mit Claude Code entstanden sind, tragen eine erkennbare Markierung in der Commit-Message, etwa einen Co-Authored-By-Trailer. Das schafft Transparenz, ohne einen Stempel des Misstrauens zu setzen, und erlaubt es, im Nachhinein zu untersuchen, ob KI-unterstützte Änderungen andere Fehlerquoten aufweisen als rein manuell geschriebene. Reviewer sollten zudem gezielt nach typischen KI-Mustern suchen, etwa überflüssig breiten Try-Catch-Blöcken, plausibel klingenden, aber falschen API-Aufrufen oder Kommentaren, die den Code nur beschreiben, statt seine Begründung zu liefern.

{
  "commitConventions": {
    "aiAssistedTrailer": "Co-Authored-By: Claude <noreply@anthropic.com>",
    "requireTrailerWhenAiGenerated": true,
    "reviewChecklist": [
      "Fachliche Korrektheit unabhängig von der Code-Herkunft prüfen",
      "Generierte Datenbank-Migrationen manuell gegen das Schema verifizieren",
      "Sicherheitsrelevante Änderungen (Auth, Payment, Zugriffsrechte) nie ungeprüft mergen",
      "Kommentare auf reine Wiederholung des Codes statt Begründung prüfen",
      "PHPStan Level 5 und phpcs müssen lokal grün sein vor dem Review"
    ],
    "escalation": {
      "highRiskPaths": [
        "app/code/*/Model/Payment/**",
        "app/code/*/Setup/Patch/Data/**",
        "app/code/*/Observer/**"
      ],
      "requiresSecondReviewer": true
    }
  }
}

5. Onboarding: neue Entwickler in den Workflow einführen

Neue Teammitglieder bringen häufig eigene, in früheren Projekten gewachsene Gewohnheiten im Umgang mit KI-Assistenten mit. Ohne strukturiertes Onboarding übertragen sie diese Gewohnheiten unreflektiert auf das neue Projekt, was schnell wieder zu den uneinheitlichen Mustern führt, die eine gemeinsame CLAUDE.md eigentlich verhindern soll. Ein kurzer, verbindlicher Einstieg lohnt sich deshalb: Repository klonen, CLAUDE.md lesen, geteilte Permission-Regeln in .claude/settings.json verstehen und an einer kleinen, risikoarmen Aufgabe den Workflow einmal vollständig durchlaufen, bevor produktive Änderungen anstehen.

Sinnvoll ist außerdem ein kurzes Pairing zwischen neuem und erfahrenem Teammitglied direkt mit Claude Code: gemeinsam eine Aufgabe bearbeiten, dabei zeigen, wann der Plan-Modus sinnvoll ist, wie ein Prompt so präzisiert wird, dass er die Projektkonventionen berücksichtigt, und wo ein Vorschlag trotz plausibler Formulierung kritisch hinterfragt werden muss. Dieses praktische Erlebnis vermittelt die im Dokument stehenden Regeln deutlich nachhaltiger als reines Lesen und verkürzt die Zeit, bis neue Entwickler produktiv im gemeinsamen Standard arbeiten.

#!/usr/bin/env bash
# onboard-developer.sh: guided first run for a new team member
set -euo pipefail

echo "Welcome. This script walks through the shared Claude Code workflow."

read -rp "Have you read CLAUDE.md end to end? [y/N] " read_claude_md
[[ "$read_claude_md" == "y" ]] || { echo "Please read CLAUDE.md before continuing."; exit 1; }

echo "Starting Claude Code in plan mode for a small warm-up task ..."
claude --permission-mode plan -p "Explain the module structure under src/app/code/Mironsoft and suggest where a new logging service belongs, following CLAUDE.md conventions"

echo "Review the plan output above with a senior team member before making edits."
echo "Once comfortable, switch to the default permission mode for actual changes."

6. Prompt-Konventionen und geteilte Skills und Slash-Commands

Neben Dateikonventionen lohnt sich in Teams auch eine Angleichung der Prompt-Praxis selbst. Wenn jeder Entwickler dieselbe wiederkehrende Aufgabe, etwa "Erzeuge ein neues Magento-Modul nach unserem Dual-Vendor-Schema", unterschiedlich formuliert, entstehen trotz identischer CLAUDE.md unterschiedliche Ergebnisse, weil Detailgrad und Reihenfolge der Anweisungen variieren. Wiederverwendbare Slash-Commands im Verzeichnis .claude/commands lösen dieses Problem: Ein Team definiert einmal einen Befehl wie /new-module, der die vollständige Checkliste aus Namespace, ACL, system.xml und Abrams-Kopie in einem festen Prompt kapselt.

Diese geteilten Commands werden wie Code behandelt: im Repository versioniert, im Pull Request geprüft und bei Bedarf weiterentwickelt. Das reduziert nicht nur Varianz zwischen Entwicklern, sondern auch den Wiederholungsaufwand, da niemand denselben ausführlichen Kontext jedes Mal neu formulieren muss. Ergänzend hilft eine kurze interne Konvention zur Prompt-Struktur, etwa erst Ziel, dann Kontext, dann Einschränkungen zu nennen, damit auch freie, nicht in einem Command gekapselte Anfragen im Team ähnlich aufgebaut sind und vergleichbare Ergebnisse liefern.

#!/usr/bin/env python3
"""validate_commands.py: check that shared slash commands follow team conventions.
Run in CI to catch undocumented or malformed commands before merge.
"""
import pathlib
import re
import sys

COMMANDS_DIR = pathlib.Path(".claude/commands")
REQUIRED_SECTIONS = ["## Purpose", "## Context", "## Constraints"]

errors = []

for command_file in sorted(COMMANDS_DIR.glob("*.md")):
    content = command_file.read_text(encoding="utf-8")

    for section in REQUIRED_SECTIONS:
        if section not in content:
            errors.append(f"{command_file.name}: missing required section '{section}'")

    if not re.match(r"^# /[a-z][a-z0-9-]*\n", content):
        errors.append(f"{command_file.name}: missing a valid '# /command-name' heading")

if errors:
    print("Shared slash command validation failed:", file=sys.stderr)
    for error in errors:
        print(f"  - {error}", file=sys.stderr)
    sys.exit(1)

print(f"All shared slash commands in {COMMANDS_DIR} follow team conventions.")

7. Konsistenz über CLI, IDE-Plugins und CI hinweg

Claude Code wird in vielen Teams nicht nur über die Kommandozeile genutzt, sondern zusätzlich über IDE-Integrationen und gelegentlich über automatisierte Aufrufe in CI-Pipelines. Jede dieser Nutzungsformen liest grundsätzlich dieselbe CLAUDE.md und dieselben .claude/settings.json-Regeln, doch in der Praxis unterscheiden sich Standardwerte je nach Integration, etwa beim Umgang mit automatisch akzeptierten Edits oder bei der sichtbaren Diff-Vorschau vor einer Änderung. Ein Team sollte deshalb explizit festlegen, welche Permission-Stufe in welcher Umgebung als Minimum gilt, statt sich auf die jeweiligen Werkzeug-Standardwerte zu verlassen.

Besonders in CI-Pipelines, in denen Claude Code headless im Plan-Modus oder mit einer eng begrenzten Allow-Liste läuft, muss die Konfiguration exakt der lokalen Team-Policy entsprechen, damit automatisierte Reviews dieselben Maßstäbe anlegen wie ein manueller Aufruf am Entwickler-Rechner. Ein einfacher, aber wirksamer Test: Dieselbe Aufgabe einmal lokal und einmal über die CI-Konfiguration stellen und die Ergebnisse vergleichen. Weichen sie strukturell voneinander ab, liegt meist eine Diskrepanz in den geladenen Regeln vor, die vor dem produktiven Einsatz behoben werden sollte.

8. Metriken und Feedback-Schleifen für den Workflow

Ein Team-Workflow für Claude Code ist kein einmalig festgelegtes Dokument, sondern ein Regelwerk, das sich mit den Erfahrungen des Teams weiterentwickeln sollte. Hilfreich ist dafür ein regelmäßiger, kurzer Rückblick, etwa alle zwei Sprints: Welche mit Claude Code erstellten Änderungen mussten im Review mehrfach nachgebessert werden, welche Regeln in CLAUDE.md werden erkennbar ignoriert oder missverstanden, und welche neuen Muster tauchen wiederholt in Prompts auf, ohne bereits als Slash-Command erfasst zu sein. Diese Beobachtungen fließen direkt in Anpassungen der Konfiguration zurück.

Wo verfügbar, liefern Session-Logs und einfache Zählungen von Tool-Aufrufen zusätzliche, objektivere Signale als der reine Eindruck aus Reviews: eine auffällig hohe Zahl abgelehnter Bash-Befehle kann auf zu enge Deny-Regeln hindeuten, eine hohe Zahl manueller Nacharbeiten an generiertem Code auf eine lückenhafte CLAUDE.md. Wichtig ist, diese Auswertung nicht als Leistungsbewertung einzelner Entwickler misszuverstehen, sondern als Werkzeug, um den gemeinsamen Workflow gezielt zu verbessern, statt ihn unverändert fortzuschreiben.

// analyze-sessions.js: summarize Claude Code session logs for the team retro
const fs = require('node:fs');
const path = require('node:path');

const logDir = process.argv[2] || '.claude/logs';
const files = fs.readdirSync(logDir).filter((f) => f.endsWith('.jsonl'));

const stats = { totalSessions: 0, deniedBashCommands: 0, manualEditsAfterAi: 0 };

for (const file of files) {
  const lines = fs.readFileSync(path.join(logDir, file), 'utf-8').trim().split('\n');
  stats.totalSessions += 1;

  for (const line of lines) {
    const event = JSON.parse(line);
    if (event.type === 'tool_denied' && event.tool === 'Bash') {
      stats.deniedBashCommands += 1;
    }
    if (event.type === 'manual_edit' && event.followsAiEdit) {
      stats.manualEditsAfterAi += 1;
    }
  }
}

console.log(`Sessions analyzed: ${stats.totalSessions}`);
console.log(`Denied Bash commands: ${stats.deniedBashCommands}`);
console.log(`Manual edits after AI edits: ${stats.manualEditsAfterAi}`);
console.log('High denial counts suggest overly strict deny rules.');
console.log('High manual-edit counts suggest gaps in CLAUDE.md conventions.');

9. Typische Stolperfallen und Anti-Patterns im Team-Einsatz

Der häufigste Fehler ist eine CLAUDE.md, die einmal geschrieben und danach nie wieder aktualisiert wird, während sich die tatsächlichen Projektkonventionen längst weiterentwickelt haben. Claude Code hält sich zuverlässig an das, was dokumentiert ist, nicht an das, was im Team stillschweigend inzwischen üblich ist. Ein zweites verbreitetes Muster: Einzelne Entwickler pflegen eigene, nicht geteilte Regeln in lokalen Konfigurationsdateien, die faktisch von der Team-Policy abweichen, ohne dass dies im Review sichtbar wird, weil lokale Einstellungen nicht Teil des Commits sind.

Ebenso riskant ist das andere Extrem: ein Team, das jede KI-unterstützte Änderung pauschal misstraut und deshalb doppelt so streng reviewt wie manuell geschriebenen Code, unabhängig vom tatsächlichen Risiko der jeweiligen Änderung. Das verlangsamt den Workflow, ohne die Codequalität nachweislich zu verbessern, und untergräbt die Akzeptanz klarer Regeln im Team. Die folgende Übersicht stellt verbreitete Anti-Patterns den empfohlenen Alternativen gegenüber.

10. Zusammenfassung

Ein belastbarer Claude Code Workflow für Teams entsteht nicht durch strengere Kontrolle der KI, sondern durch klare, versionierte Regeln, an die sich alle Beteiligten halten. Eine gemeinsame CLAUDE.md im Repository dokumentiert Tech-Stack, Coding-Standards und Projektkontext und wird über den regulären Pull-Request-Prozess gepflegt statt einmal geschrieben und vergessen. Review-Erwartungen für KI-unterstützte Änderungen stellen sicher, dass Herkunft des Codes die Prüftiefe nicht senkt, sondern je nach Risiko sogar erhöht.

Strukturiertes Onboarding, geteilte Slash-Commands und eine konsistente Konfiguration über CLI, IDE-Integrationen und CI-Pipelines hinweg verhindern, dass jedes Teammitglied Claude Code auf eigene Weise einsetzt. Regelmäßige Rückblicke auf Basis von Session-Daten und Review-Erfahrungen halten den Workflow lebendig, statt ihn als statisches Dokument zu behandeln. Der größte Hebel liegt dabei nicht in einem einzelnen Werkzeug-Feature, sondern in der konsequenten, gemeinsamen Anwendung über das gesamte Team hinweg.

11. FAQ: Claude Code Workflow für Teams