Claude Code in bestehende Projekte einbinden

1. Warum Onboarding in Bestandsprojekten anders funktioniert

Claude Code liest keine Projektdokumentation im klassischen Sinn, sondern den Code selbst, ergänzt um die Datei CLAUDE.md als projektspezifischen Kontext. Bei einem neuen, leeren Projekt ist das unproblematisch: Es gibt kaum Altlasten, die Konventionen entstehen gemeinsam mit dem Modell. Bei einem gewachsenen Magento-Shop mit mehreren Jahren Historie, verschiedenen Entwicklerteams und tausenden Dateien inklusive vendor/ und generated/ sieht die Ausgangslage vollkommen anders aus. Das Kontextfenster ist endlich, und ungefiltert eingelesener Code aus verschiedenen Epochen des Projekts führt dazu, dass Claude Code widersprüchliche Muster als gleichwertig behandelt.

Der zentrale Unterschied zu einem Neuprojekt: In einer Bestandscodebase existieren oft mehrere Lösungen für dasselbe Problem nebeneinander, weil sich Standards über die Zeit verändert haben. Ein altes Modul nutzt vielleicht noch Preferences statt Plugins, ein neueres Modul bereits ViewModels statt Blockklassen. Ohne explizite Steuerung kann Claude Code nicht zuverlässig erkennen, welches Muster der aktuelle Standard ist und welches technische Schuld darstellt. Genau diese Unterscheidung muss die erste CLAUDE.md leisten, bevor produktiv am Code gearbeitet wird.

2. Die ersten 30 Minuten: Claude Code im Bestandsprojekt starten

Der eingebaute Befehl /init scannt das Repository und erzeugt einen ersten Entwurf einer CLAUDE.md automatisch. Das ist ein brauchbarer Ausgangspunkt, aber kein fertiges Ergebnis: Der generierte Entwurf beschreibt meist nur, was im Code sichtbar ist, nicht die Gründe hinter Entscheidungen oder die Wrapper-Skripte, mit denen im Team tatsächlich gearbeitet wird. Sinnvoller ist es, Claude Code zunächst mit rein lesenden Aufgaben zu beauftragen, bevor irgendetwas geschrieben wird: Verzeichnisstruktur auflisten, Commit-Historie sichten, Abhängigkeiten prüfen. So entsteht ein gemeinsames Bild der Codebase, bevor Änderungen vorgeschlagen werden.

In der Praxis lohnt sich ein kurzer Explorationslauf direkt im Projekt-Root, noch bevor die CLAUDE.md überhaupt existiert. Claude Code kann gezielt gebeten werden, wiederkehrende Namenskonventionen, Verzeichnistiefen und die am häufigsten verwendeten Design Patterns zusammenzufassen. Diese Zusammenfassung dient anschließend als Rohmaterial für die manuell kuratierte CLAUDE.md, statt dass das Modell bei jeder neuen Sitzung erneut rät.

#!/usr/bin/env bash
# First exploration pass in an existing Magento project, read-only
set -euo pipefail

# Top-level module and directory structure, two levels deep
find app/code -maxdepth 2 -type d | sort

# Recent history to understand active areas of the codebase
git log --oneline -20

# Installed dependencies and versions actually in use
composer show --direct

# Detect mixed conventions: Preference vs Plugin usage across modules
grep -rl "preference" app/code --include="di.xml" | wc -l
grep -rl "<plugin " app/code --include="di.xml" | wc -l

# Rough size of the context surface Claude Code would face unfiltered
du -sh vendor generated var pub/static node_modules 2>/dev/null || true

3. Eine effektive CLAUDE.md schreiben

Die CLAUDE.md wird bei jeder Sitzung in den Kontext geladen und wirkt damit ähnlich wie eine projektspezifische Systemanweisung. Genau deshalb sollte sie knapp und handlungsleitend sein, nicht eine Kopie des README oder der Composer-Abhängigkeiten. Wichtig ist, Dinge zu dokumentieren, die sich nicht allein aus dem Code ableiten lassen: Warum wird ein bestimmter Wrapper statt des direkten CLI-Aufrufs verwendet, welche Deploy-Reihenfolge ist zwingend, welche Interface-Lücken sind bekannt und müssen mit einem bestimmten Kommentar umgangen werden. Diese Informationen sparen bei jeder Sitzung erneutes Nachfragen oder, schlimmer, falsches Raten.

Eine bewährte Struktur gliedert die CLAUDE.md in klar abgegrenzte Abschnitte: Projektüberblick mit Tech-Stack-Versionen, Coding-Standards mit konkreten Beispielen, eine Liste verbotener Patterns, die verfügbaren CLI-Wrapper-Befehle und die exakte Deploy-Sequenz. Lange Fließtext-Abschnitte werden von Sprachmodellen zuverlässig verarbeitet, aber kurze, imperative Regeln mit Codebeispielen setzen sich in der Praxis stärker durch als narrative Beschreibung. Ein Abschnitt mit fünf klaren Verboten wirkt zuverlässiger als ein Absatz, der dieselben Verbote nur beiläufig erwähnt.

#!/usr/bin/env bash
# Bootstrap a curated CLAUDE.md instead of relying only on the auto-generated draft
cat > CLAUDE.md <<'EOF'
# Project: mironsoft.de Magento 2 Shop

## Stack
- Magento 2.4.8-p4, PHP 8.4, Hyva Theme, Tailwind CSS v4, Alpine.js

## Hard rules
- Never call `php bin/magento` directly, always use `bin/magento` wrapper
- Prefer ViewModels (ArgumentInterface) over Block classes
- Use Plugins, not Preferences, for extending core behavior
- declarative schema (db_schema.xml), never InstallSchema/UpgradeSchema

## Known interface gaps (always add // @phpstan-ignore-next-line)
- PageInterface::getData() is missing from the interface but exists on the model

## Deploy sequence (always in this order)
1. bin/npm --prefix <theme>/web/tailwind run build
2. rm -rf var/view_preprocessed/* pub/static/frontend/*
3. bin/magento setup:static-content:deploy de_DE -f
4. bin/magento cache:flush
EOF

4. Projekt-Konventionen und verbotene Patterns explizit machen

In einer gewachsenen Codebase reicht es nicht, nur zu beschreiben, was gemacht werden soll. Mindestens genauso wichtig ist eine explizite Liste dessen, was nicht gemacht werden soll, obwohl es an anderer Stelle im selben Projekt sichtbar vorkommt. Claude Code orientiert sich stark an vorhandenem Code als Vorbild. Enthält die Codebase noch jQuery-Reste aus einer Migration von Luma zu Hyvä, wird das Modell diese Muster ohne explizites Verbot unter Umständen als gültiges Vorbild interpretieren und fortsetzen, statt sie als Altlast zu erkennen.

Ein konkretes Beispiel aus Hyvä-Projekten: Kein Knockout.js, kein jQuery, keine UI-Components, sondern konsequent Alpine.js für Interaktivität. Diese Regel als einzelner Satz in der CLAUDE.md reicht selten aus. Wirksamer ist ein kurzes Vorher-Nachher-Beispiel, das genau zeigt, wie ein typisches Interaktionsmuster im Projekt aussehen soll. Codebeispiele wirken als Anker stärker als abstrakte Regeln, weil sie dem Modell eine konkrete Zielform liefern, an der es sich orientieren kann, statt nur eine Verbotsliste ohne Kontext.

// FORBIDDEN in this project: legacy jQuery pattern from the old Luma theme
$('#qty-input').on('change', function () {
  $.ajax({
    url: '/checkout/cart/updateQty',
    data: { qty: $(this).val() }
  });
});

// REQUIRED pattern: Alpine.js component, no jQuery, no extra script tags
// x-data component defined in the phtml template, CSP-safe inline script
document.addEventListener('alpine:init', () => {
  Alpine.data('qtyUpdater', () => ({
    qty: 1,
    async updateQty() {
      await fetch('/checkout/cart/updateQty', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ qty: this.qty })
      });
    }
  }));
});

5. Kontextfenster schützen: Was ausgeschlossen werden muss

Ein Magento-2-Repository enthält neben dem eigentlichen Anwendungscode große Mengen an generiertem und heruntergeladenem Material: vendor/, generated/, var/, pub/static/ und node_modules/ können zusammen mehrere Gigabyte und hunderttausende Dateien umfassen. Keine dieser Dateien enthält Informationen, die für Entscheidungen im eigenen Code relevant sind, sie kosten aber Tokens und lenken das Modell potenziell auf kompilierte oder minifizierte Versionen statt auf die eigentliche Quelle. Eine .claudeignore-Datei nach Gitignore-Syntax filtert solche Pfade konsequent aus der automatischen Kontextaufnahme heraus.

Zusätzlich zur reinen Größe gibt es einen inhaltlichen Grund für den Ausschluss: generated/ enthält automatisch erzeugte Factory- und Proxy-Klassen, die bei jedem setup:di:compile neu geschrieben werden. Verweist Claude Code auf Code in diesem Verzeichnis, bezieht es sich auf ein flüchtiges Artefakt statt auf die eigentliche Quelle im Modul. Neben der Ignore-Datei lohnt sich ein zweiter Blick auf die Permission-Konfiguration: Schreibrechte lassen sich gezielt auf bestimmte Verzeichnisse einschränken, sodass selbst versehentliche Schreibversuche in vendor/ von vornherein blockiert werden, statt nur unerwünscht zu sein.

#!/usr/bin/env bash
# Create .claudeignore to keep build artifacts and vendor code out of context
cat > .claudeignore <<'EOF'
vendor/
generated/
var/
pub/static/
node_modules/
*.min.js
*.min.css
.git/
EOF

# Restrict write access via Claude Code permission settings
cat > .claude/settings.json <<'EOF'
{
  "permissions": {
    "allow": [
      "Bash(bin/magento:*)",
      "Bash(bin/composer:*)",
      "Bash(bin/npm:*)",
      "Edit(app/code/**)",
      "Edit(app/design/**)"
    ],
    "deny": [
      "Edit(vendor/**)",
      "Edit(generated/**)",
      "Edit(.env)",
      "Bash(rm -rf:*)"
    ]
  }
}
EOF

6. Praxisbeispiel: Onboarding eines Magento-2-Projekts

Ein realistisches Szenario: Eine Agentur übernimmt einen bestehenden Magento-2.4.8-Shop mit Hyvä-Theme, der über drei Jahre von wechselnden Entwicklern gepflegt wurde. Ziel ist, Claude Code am selben Tag produktiv einzusetzen, ohne dass es riskante Änderungen an kritischen Bereichen vorschlägt. Der erste Schritt ist /init im Projekt-Root, gefolgt von einer manuellen Überarbeitung des generierten Entwurfs: Wrapper-Skripte aus bin/ ergänzen, die Dual-Vendor-Struktur des Projekts erklären und bekannte PHPStan-Interface-Lücken auflisten, die sonst bei jedem Lauf erneut als Fehler auftauchen würden.

Danach folgt ein Verifikationsschritt, der sich in der Praxis bewährt hat: Claude Code wird gebeten, die erkannten Konventionen in eigenen Worten zusammenzufassen, bevor der erste Schreibauftrag folgt. Weicht die Zusammenfassung von der Realität ab, zeigt das sofort eine Lücke in der CLAUDE.md, die sich mit geringem Aufwand schließen lässt. Die ersten tatsächlichen Aufgaben sollten bewusst risikoarm gewählt werden, etwa fehlende PHPDoc-Blöcke ergänzen oder PHPCS-Verstöße beheben, statt direkt an der Datenbankschicht oder an Zahlungsprozessen zu arbeiten.

7. CLAUDE.md iterativ verfeinern statt einmalig schreiben

Die häufigste Fehleinschätzung beim Onboarding ist, die CLAUDE.md als einmaliges Setup-Dokument zu behandeln. In der Praxis zeigt sich erst durch tatsächliche Arbeit am Code, welche Annahmen fehlen. Verwendet Claude Code beispielsweise wiederholt php bin/magento statt des projektspezifischen Wrappers, ist das kein Zufall, sondern ein Signal, dass die Regel in der CLAUDE.md entweder fehlt oder nicht deutlich genug formuliert ist. Solche Korrekturen sollten direkt als neue Regel nachgetragen werden, statt sie bei jeder Sitzung erneut manuell zu wiederholen.

Sinnvoll ist, die CLAUDE.md wie regulären Code unter Versionskontrolle zu behandeln und Änderungen im Code-Review zu betrachten, statt sie informell im Chat zu verhandeln. Korrekturen, die im Review häufiger auftauchen, sind gute Kandidaten für eine explizite Regel. Genauso wichtig ist das Gegenteil: Veraltete Regeln, die sich aus einer inzwischen abgeschlossenen Migration ergeben haben, sollten entfernt werden, damit die Datei nicht auf Dauer wächst und an Präzision verliert.

8. Sicherheit und Berechtigungen in Bestandsprojekten

Ein zentraler Unterschied zwischen der CLAUDE.md und den Permission- beziehungsweise Hook-Mechanismen von Claude Code: Die CLAUDE.md ist eine Anweisung, der das Modell in aller Regel folgt, aber keine harte technische Grenze. Für wirklich kritische Bereiche, etwa produktionsnahe Konfigurationsdateien, Zugangsdaten oder das vendor/-Verzeichnis, reicht eine Textregel allein nicht aus. Hier greifen Permission-Einstellungen und Hooks, die bestimmte Werkzeugaufrufe technisch verweigern, unabhängig davon, was das Modell in der jeweiligen Sitzung vorschlägt.

Ein PreToolUse-Hook kann beispielsweise jeden Schreibversuch prüfen und Änderungen an geschützten Pfaden hart ablehnen, bevor sie überhaupt ausgeführt werden. Das ist besonders in Bestandsprojekten relevant, in denen sensible Dateien wie .env oder Deployment-Skripte mit Produktivzugang im selben Repository liegen wie der eigentliche Anwendungscode. Die Kombination aus CLAUDE.md für weiche Konventionen und Hooks für harte Grenzen liefert insgesamt ein deutlich verlässlicheres Sicherheitsmodell als eine reine Anweisung im Prompt.

#!/usr/bin/env python3
# PreToolUse hook: hard-block writes to vendor/, generated/ and .env
# regardless of what the CLAUDE.md instructions say
import json
import sys

BLOCKED_PATH_PREFIXES = ("vendor/", "generated/", ".env")

def main() -> int:
    payload = json.load(sys.stdin)
    tool_input = payload.get("tool_input", {})
    file_path = tool_input.get("file_path", "")

    for prefix in BLOCKED_PATH_PREFIXES:
        if prefix in file_path:
            print(json.dumps({
                "decision": "block",
                "reason": f"Writes to '{prefix}' are hard-blocked by project policy"
            }))
            return 0

    print(json.dumps({"decision": "allow"}))
    return 0

if __name__ == "__main__":
    sys.exit(main())

9. Onboarding-Praxis im direkten Vergleich

Die meisten Onboarding-Probleme mit Claude Code in Bestandsprojekten lassen sich auf eine kleine Zahl wiederkehrender Entscheidungen zurückführen. Die folgende Übersicht stellt unzureichende Praxis der empfohlenen Vorgehensweise gegenüber.

Keine dieser Maßnahmen ist für sich genommen aufwendig, aber ihre Wirkung summiert sich. Ein Projekt, das .claudeignore, eine kuratierte CLAUDE.md und harte Permission-Regeln gleichzeitig einsetzt, reduziert sowohl die Fehlerquote als auch das Risiko unbeabsichtigter Änderungen an kritischen Dateien deutlich stärker als jede einzelne Maßnahme allein.

10. Zusammenfassung

Claude Code in ein bestehendes Projekt einzubinden ist keine einmalige Konfigurationsaufgabe, sondern ein Prozess, der mit gezielter Exploration beginnt und sich über die gesamte Projektlaufzeit fortsetzt. Eine kuratierte CLAUDE.md mit klaren, imperativen Regeln schlägt eine automatisch generierte Doku-Kopie deutlich. Ausschlussregeln für vendor/, generated/ und weitere Build-Artefakte halten das Kontextfenster fokussiert auf tatsächlich relevanten Code. Explizite Verbotslisten mit Vorher-Nachher-Beispielen verhindern, dass Claude Code historisch gewachsene Anti-Patterns unbeabsichtigt als aktuellen Standard fortsetzt.

Der wichtigste strukturelle Punkt bleibt die Trennung zwischen weicher Steuerung über die CLAUDE.md und harter technischer Durchsetzung über Permissions und Hooks. Textregeln lenken das Verhalten des Modells zuverlässig in den allermeisten Fällen, ersetzen aber keine technische Grenze für wirklich kritische Pfade wie Zugangsdaten oder Drittanbieter-Code. Wer beides kombiniert und die CLAUDE.md als lebendiges, versioniertes Dokument pflegt, bekommt ein Setup, das mit dem Projekt mitwächst statt nach der ersten Sitzung zu veralten.

11. FAQ: Claude Code in bestehende Projekte einbinden