Claude Code: Projektübergreifendes Gedächtnis in 3 Ebenen

Am 10.08.2026 dokumentiert Claude Code für importierte Anweisungsdateien eine maximale Verschachtelung von fünf Importstufen. Das zeigt bereits die entscheidende Grenze: Claude Code lädt konfigurierte Informationen erneut, besitzt dadurch aber nicht automatisch ein dauerhaftes, menschenähnliches Gedächtnis. Für ein zuverlässiges projektübergreifendes Gedächtnis ist deshalb eine Drei-Ebenen-Architektur die belastbarste Lösung: CLAUDE.md speichert stabile Fakten, Claude Code Skills kapseln wiederholbare Abläufe und ein externes Agent Memory verwaltet veränderliche Präferenzen sowie offene Aufgaben. (docs.anthropic.com)

Zu dieser Anleitung passen persönliche Entwickler, die mehrere Repositories parallel pflegen, sowie technische Verantwortliche, die gemeinsame Regeln und private Arbeitspräferenzen trennen müssen. Auch Teams mit dauerhaft laufenden Coding Agents finden hier eine Grundlage für Isolation, Backups und Wiederanlaufprüfungen.

Letzte Aktualisierung: 10.08.2026. Die technischen Aussagen wurden anhand der offiziellen Claude-Code-Dokumentation zu Memory, Skills, Berechtigungen und CLI-Verhalten geprüft.

Vor dem ersten Befehl: Informationen nach Haltbarkeit sortieren

Viele Konfigurationen scheitern nicht an einem fehlenden Befehl, sondern an einer falschen Zuordnung. Ein Architekturentscheid sollte deshalb vor dem Anlegen der ersten Datei stehen:

Informationstyp	Geeignete Ebene	Beispiele	Darf projektübergreifend gelten?
Stabiler Fakt	CLAUDE.md	Architektur, Testbefehle, Namensregeln	Nur bei wirklich allgemeingültigen Regeln
Wiederholbarer Ablauf	SKILL.md	Deployment, Code-Review, Release-Prüfung	Ja, wenn der Ablauf standardisiert ist
Veränderlicher Zustand	Externes Agent Memory	offene Aufgabe, persönliche Präferenz, letzte Entscheidung	Nur mit Projekt- und Benutzerkennung
Geheimnis oder Kundendaten	Secret Manager beziehungsweise geschützte Umgebung	API-Schlüssel, Zugangsdaten, interne Kundennamen	Nein

In CLAUDE.md gehören beispielsweise die Aussage „Tests werden mit pnpm test gestartet“ oder die Regel „öffentliche Schnittstellen benötigen eine Rückwärtskompatibilitätsprüfung“. Nicht hinein gehören vollständige Chatverläufe, temporäre Fehlermeldungen oder eine Liste aller Entscheidungen aus sechs Monaten.

Ebenso wichtig ist die Negativliste. Niemals in globale oder gemeinsam genutzte Dateien gehören:

• API-Schlüssel, Sitzungstoken und private Zertifikate,
• nicht öffentliche Kundennamen, Vertragsdaten oder Supportfälle,
• Pfade zu exklusiven lokalen Verzeichnissen,
• Annahmen, die nur für ein einzelnes Repository gelten,
• ungeprüfte Erinnerungen aus früheren Aufgaben.

Das schützt nicht nur vor versehentlicher Kontextvermischung. Es verringert auch die Gefahr, dass ein Agent eine veraltete Anweisung gegenüber einer aktuellen Projektdatei bevorzugt.

Erste Phase: CLAUDE.md pro Repository sauber begrenzen

Claude Code merkt sich frühere Projekte nicht automatisch

Claude Code liest verfügbare Konfigurations- und Memory-Dateien entsprechend ihrer Ablage und dem aktuellen Arbeitsverzeichnis. Das ist ein reproduzierbarer Ladevorgang, aber keine Garantie dafür, dass eine frühere Unterhaltung oder jede Entscheidung aus einem anderen Repository dauerhaft verfügbar bleibt. Die offizielle Dokumentation beschreibt Projekt-, Benutzer- und lokale Speicherorte sowie den Befehl /memory, mit dem geladene Memory-Dateien geprüft werden können. (docs.anthropic.com)

Für jedes Repository sollte daher zunächst eine eigene Datei angelegt werden:

projekt-aurora/
├── CLAUDE.md
├── .claude/
│   └── skills/
└── src/

Ein minimales, absichtlich begrenztes Beispiel:

# Projekt Aurora

## Architektur
- Backend: TypeScript mit einer getrennten API- und Domänenschicht.
- Persistenzzugriffe liegen ausschließlich unter `src/infrastructure`.

## Standardbefehle
- Abhängigkeiten installieren: `pnpm install`
- Tests ausführen: `pnpm test`
- Statische Prüfung: `pnpm lint`

## Arbeitsregeln
- Vor Änderungen an öffentlichen Schnittstellen zuerst bestehende Tests prüfen.
- Keine Zugangsdaten in Quelldateien oder Beispieldateien eintragen.
- Änderungen an Datenbankmodellen benötigen eine Migrationsdatei.

Die Datei sollte nicht als vollständiges Handbuch missbraucht werden. Lange Deployment-Anleitungen, ausführliche Architekturentscheidungen und Sonderfalllisten gehören in referenzierte Dokumente oder Skills. CLAUDE.md soll dem Agenten vor allem den stabilen Rahmen geben, nicht jede denkbare Handlung vorwegnehmen.

Die offizielle Memory-Dokumentation unterstützt außerdem Importe mit @pfad/zur/datei; Importe können rekursiv verarbeitet werden, wobei die Dokumentation eine maximale Tiefe von fünf Sprüngen nennt. Das erleichtert die Trennung zwischen zentralen Teamregeln und zusätzlichen persönlichen Vorgaben, erhöht aber bei unkontrollierter Verschachtelung die Prüfkosten. (docs.anthropic.com)

So wird die erste Datei überprüft

1. Repository in einem neuen Terminal öffnen.
2. Claude Code im Root-Verzeichnis starten.
3. /memory ausführen und die geladenen Dateien kontrollieren.
4. Eine Regel aus CLAUDE.md abfragen, ohne den Inhalt erneut in den Prompt zu kopieren.
5. Eine widersprüchliche Regel in einem Unterverzeichnis testen.
6. Prüfen, ob eine Änderung außerhalb des Projektbereichs abgelehnt oder ausdrücklich bestätigt wird.

Die Berechtigungsgrenze ist ein eigener Prüfpunkt. Claude Code arbeitet standardmäßig mit restriktiven Berechtigungen und fordert für weitergehende Aktionen wie Dateischreiben oder Shell-Befehle eine Bestätigung an. Für sensible Repositories sollten Projektregeln und Berechtigungen getrennt versioniert und regelmäßig kontrolliert werden. (docs.anthropic.com)

Wichtig: Das erneute Einlesen einer Datei nach einem Neustart beweist nur, dass die Datei geladen wurde. Es beweist nicht, dass Claude Code eine frühere Begründung, einen impliziten Kontext oder eine nicht gespeicherte Entscheidung dauerhaft kennt.

Zweite Phase: Wiederholbare Abläufe in Claude Code Skills verschieben

Sobald ein Abschnitt in CLAUDE.md nicht mehr nur eine Tatsache beschreibt, sondern einen mehrstufigen Ablauf enthält, sollte er in einen Skill verschoben werden. Ein Skill lädt seine ausführlichen Anweisungen erst bei passender Verwendung oder direkter Aktivierung. Dadurch bleibt die Grundkonfiguration übersichtlicher und der Kontext wird nicht mit jedem Auftrag um denselben Prozess erweitert. (code.claude.com)

Ein projektbezogener Skill kann beispielsweise so aussehen:

.claude/
└── skills/
    └── review-change/
        └── SKILL.md

---
name: review-change
description: Prüft Änderungen auf API-Risiken, fehlende Tests und Verstöße gegen die Projektregeln.
---

## Vorgehen

1. `git diff` und die betroffenen Dateien lesen.
2. Öffentliche Schnittstellen und Datenmodelländerungen markieren.
3. Vorhandene Tests den geänderten Bereichen zuordnen.
4. Fehlende Tests als konkrete Fälle beschreiben.
5. Keine Dateien verändern, bevor die Risiken zusammengefasst sind.

Die Beschreibung ist nicht bloße Dokumentation. Sie hilft Claude Code zu entscheiden, wann ein Skill automatisch geladen werden soll. Für gefährliche Abläufe wie Deployment oder Migrationen sollte die automatische Aktivierung eingeschränkt werden; der Ablauf wird dann nur über einen expliziten Aufruf gestartet.

Skill-Ebene	Typischer Pfad	Geeignet für	Risiko bei falscher Nutzung
Projekt	.claude/skills/.../SKILL.md	Repository-spezifische Tests, Review-Regeln, Deployment	Gilt nur für dieses Projekt
Persönlich	~/.claude/skills/.../SKILL.md	Eigene Review- oder Dokumentationsabläufe	Kann unpassende Gewohnheiten in jedes Projekt tragen
Plugin	Plugin-eigener Skill-Pfad	Organisierte, verteilbare Erweiterungen	Abhängigkeit und Versionskonflikte

Claude Code unterstützt für Skills unter anderem projektbezogene und persönliche Ablagen. Bei gleichnamigen Skills gelten dokumentierte Prioritätsregeln; zusätzlich können Plugin-Skills über einen eigenen Namensraum angesprochen werden. Die genaue Auflösung sollte nach Updates mit einem festen Testfall überprüft werden, statt sich allein auf die Dateistruktur zu verlassen. (code.claude.com)

Claude Code Skills für mehrere Projekte gemeinsam nutzen

Für mehrere Repositories gibt es drei vertretbare Modelle:

• Kopieren: Ein Skill wird in jedes Repository übernommen. Das ist transparent, erzeugt aber Wartungsarbeit.
• Persönliche Ebene: Ein Skill liegt im Benutzerprofil und steht mehreren Projekten zur Verfügung. Das eignet sich für persönliche Arbeitsweisen.
• Gemeinsame Paketierung: Ein Team verteilt Skills als versioniertes Paket oder Plugin. Das erleichtert Updates, benötigt aber Freigaben und Kompatibilitätstests.

Eine zentrale persönliche Skill-Sammlung darf keine kundenspezifischen Befehle oder projektspezifischen Pfade enthalten. Ein allgemeiner Review-Ablauf ist geeignet; ein Skill mit dem Befehl für die produktive Datenbank von Projekt Aurora ist es nicht.

Die offizielle Dokumentation weist zudem darauf hin, dass Änderungen an bereits überwachten Skill-Verzeichnissen innerhalb der laufenden Sitzung erkannt werden können. Wird ein neues oberstes Skills-Verzeichnis erst während der Sitzung angelegt, kann hingegen ein Neustart erforderlich sein. Das ist ein wichtiger Unterschied zwischen „Datei geändert“ und „Konfigurationsquelle neu entdeckt“. (code.claude.com)

Dritte Phase: Externes Agent Memory nur für dynamische Zustände einsetzen

Ein externes Agent Memory ist sinnvoll, wenn Informationen über einzelne Sitzungen hinweg fortgeschrieben werden müssen. Typische Fälle sind:

• eine persönliche Präferenz, die sich über mehrere Projekte hinweg bewährt hat,
• eine begründete Architekturentscheidung mit Quelle und Datum,
• ein pausierter Aufgabenstand, der später wieder aufgenommen werden soll,
• eine Liste bekannter Fehlversuche, die nicht erneut durchgeführt werden soll.

Das ist eine andere Funktion als CLAUDE.md. Die Datei beschreibt deklarative Regeln. Ein Memory-System verwaltet Zustände, die sich verändern, ergänzt oder gelöscht werden müssen.

Für einen sicheren Aufbau sollte jeder gespeicherte Eintrag mindestens folgende Felder besitzen:

{
  "project_id": "aurora-api",
  "user_id": "developer-07",
  "type": "decision",
  "content": "Die Validierung bleibt vorerst in der API-Schicht.",
  "source": "docs/decisions/2026-07-validation.md",
  "created_at": "2026-08-10",
  "expires_at": null
}

Die Projekterkennung verhindert, dass eine Entscheidung aus aurora-api in orion-dashboard auftaucht. Die Benutzerkennung trennt persönliche Präferenzen von Teamwissen. Die Quellenangabe macht eine Erinnerung überprüfbar. Ein Lösch- oder Ablaufdatum verhindert, dass temporäre Annahmen zu scheinbar ewigen Regeln werden.

Schutz vor Codelecks und falscher Wiederaufnahme

Ein dynamisches Memory sollte nicht automatisch den vollständigen Quelltext, Diff-Ausgaben oder Kundendaten speichern. Besser sind kurze, abstrahierte Einträge wie „Die API nutzt eine getrennte Validierungsschicht“ statt kompletter Dateien. Für personenbezogene oder vertrauliche Inhalte sind Aufbewahrung, Zugriff und Löschung nach DSGVO-Grundsätzen zu prüfen.

Zusätzlich müssen Abrufe begrenzt werden:

1. Zuerst project_id und user_id filtern.
2. Danach nur passende Eintragstypen zulassen.
3. Treffer mit Quelle und Aktualisierungsdatum anzeigen.
4. Veraltete Einträge markieren, nicht still überschreiben.
5. Vor dem Schreiben eine explizite Speicherregel anwenden.
6. Löschanfragen und Audit-Ereignisse protokollieren.

Externe Werkzeuge und Datenquellen erweitern den Zugriff von Claude Code, erhöhen aber auch die Angriffsfläche. Für MCP-Server dokumentiert die offizielle Anleitung lokale, projektbezogene und benutzerbezogene Geltungsbereiche sowie deren Priorisierung. Sensible Server und Zugangsdaten sollten deshalb nicht in gemeinsam versionierten Konfigurationsdateien landen. (docs.anthropic.com)

Prüfphase: Konfiguration, Skills und Memory getrennt testen

Ein stabiler Aufbau ist erst dann erreicht, wenn ein Neustart, ein Projektwechsel und ein Versionsupdate denselben erwarteten Zustand erzeugen. Dafür eignet sich ein fester Regressionstest mit zwei fiktiven Repositories:

aurora-api/
orion-dashboard/

Die folgenden Prüfungen sollten als wiederholbare Checkliste dokumentiert werden:

• [ ] CLAUDE.md enthält nur stabile Fakten und projektbezogene Regeln.
• [ ] Persönliche Vorgaben liegen nicht versehentlich im Team-Repository.
• [ ] Ein Skill wird bei passender Beschreibung automatisch erkannt.
• [ ] Ein kritischer Skill verlangt einen expliziten Aufruf.
• [ ] Skills im Projekt und im Benutzerprofil erzeugen keine unerwartete Überschreibung.
• [ ] Ein Memory-Eintrag aus aurora-api erscheint nicht in orion-dashboard.
• [ ] Ein Benutzerwechsel liefert keine privaten Einträge des vorherigen Benutzers.
• [ ] Jeder dynamische Eintrag besitzt Quelle, Zeitstempel und Löschregel.
• [ ] Nach einem Neustart werden Regeln und Skills erneut gefunden.
• [ ] Nach einem Claude-Code-Update wird derselbe feste Testauftrag ausgeführt.
• [ ] Backup und Wiederherstellung der Konfiguration wurden praktisch getestet.

Für die Diagnose stehen unter anderem /memory, ausführliche CLI-Ausgaben sowie das Fortsetzen oder Wiederaufnehmen von Sitzungen zur Verfügung. Die CLI-Dokumentation führt dafür Befehle wie --verbose, --continue und --resume auf. Diese Funktionen helfen bei der Wiederaufnahme einer Sitzung, ersetzen jedoch kein externes, strukturiertes Memory für langfristige Projektzustände. (docs.anthropic.com)

Die drei Ebenen im täglichen Betrieb

Die folgende Zuordnung verhindert, dass jede neue Erkenntnis automatisch in die falsche Datei geschrieben wird:

Entscheidung im Arbeitsalltag	Speicherort	Beispiel	Änderungsrhythmus
„Welche Testbefehle gelten?“	Projekt-CLAUDE.md	pnpm test und pnpm lint	Bei Projektänderung
„Wie läuft ein Review ab?“	Projekt- oder persönlicher Skill	Diff prüfen, Risiken markieren, Tests zuordnen	Nach Prozessänderung
„Was war die letzte offene Entscheidung?“	Externes Agent Memory	Entscheidung mit Quelle und Status	Nach jedem relevanten Arbeitsschritt
„Welcher Schlüssel wird verwendet?“	Secret-Verwaltung	Umgebungsvariable ohne Klartext	Nach Rotation
„Welche Datei darf nicht verändert werden?“	Projektregel plus Berechtigung	geschütztes Migrationsverzeichnis	Bei Sicherheitsänderung

Eine gute Praxis ist, jede neue Information zunächst als Entwurf zu behandeln. Bleibt sie über mehrere Aufgaben hinweg gültig, kann sie in CLAUDE.md oder einen Skill überführt werden. Ist sie nur für den aktuellen Zustand relevant, gehört sie in das externe Memory und benötigt eine Ablauf- oder Löschlogik.

Wann eine dauerhafte Remote-Umgebung sinnvoller ist

Für einzelne lokale Sitzungen reicht meist die Repository-Struktur. Schwieriger wird es, wenn mehrere Personen denselben Coding Agent verwenden, Sitzungen nach einem Rechnerausfall fortgesetzt werden sollen oder ein Agent dauerhaft in einer isolierten Umgebung läuft. Dann entstehen zusätzliche Anforderungen: getrennte Benutzerkonten, gesicherte Secrets, nachvollziehbare Backups, stabile Netzwerkzugänge und reproduzierbare Neustarts.

Eine Remote-Entwicklungsumgebung kann diese Aufgaben bündeln, ersetzt aber nicht die Drei-Ebenen-Architektur. Wer eine solche Umgebung plant, sollte zunächst den Leitfaden zur Claude-Code-Remoteentwicklung prüfen und anschließend festlegen, welche Daten im Repository, im Benutzerprofil und in einem externen Memory-System liegen. Für eine temporäre Mac-Arbeitsumgebung ist außerdem die Übersicht zum Mac mini mieten relevant; maßgeblich sind dabei nicht nur Rechenleistung, sondern auch Zugriffsschutz, Aufbewahrung und die saubere Trennung der Projekte.

Die derzeitige Alternative — ein gemeinsam genutzter lokaler Rechner oder eine ungeprüfte Standard-Cloudumgebung — hat in diesem Szenario drei reale Nachteile: Projektgrenzen werden schnell durch lokale Pfade und globale Dateien vermischt, Neustart- und Wiederherstellungszustände sind häufig nicht dokumentiert, und persönliche Erinnerungen können ohne Benutzertrennung in Teamkontexte gelangen. Für kurzfristige Tests oder kontinuierlich laufende Agenten ist eine gemietete, isolierte Mac-Umgebung von Zutcloud daher oft die kontrollierbarere Lösung, sofern kein langfristiger Dauerbetrieb mit eigener Hardware und physischen Schnittstellen erforderlich ist. Für Teams mit speziellen Compliance-Vorgaben sollten vorab die Support- und Sicherheitsanforderungen geklärt werden.

Die belastbare Vorlage bleibt dabei einfach: stabile Regeln in CLAUDE.md, wiederholbare Prozesse in Claude Code Skills, dynamische Präferenzen und Aufgabenstände in einem externen Agent Memory — jeweils mit klarer Reichweite, Quelle und Löschregel. so bleibt projektübergreifendes Gedächtnis nachvollziehbar, testbar und bei einem Wechsel der Entwicklungsumgebung wiederherstellbar.

Weiterlesen

• Agent-Dateisysteme mit getrennten Arbeitsbereichen, Speicherschichten und Richtlinien sicher über mehrere Projekte hinweg strukturieren.
• Architekturen für langfristiges Agent-Gedächtnis: Speicherbereiche, Zugriffskontrolle, Datenschutz und geeignete Betriebsmodelle im Vergleich.