Kontext Engineering: CLAUDE.md, System-Prompts & Markdown-Doku

Prompt Engineering war gestern — 2026 ist Kontext Engineering der entscheidende Skill. Der Unterschied: Prompt Engineering optimiert einzelne Nachrichten. Kontext Engineering gestaltet das gesamte Kontextfenster eines KI-Agenten — von System-Prompts über Datei-Referenzen bis zu persistenten Regeln. Wer das beherrscht, bekommt konsistent bessere Ergebnisse aus jedem KI-Tool.

Was ist Kontext Engineering?

Eine präzise Definition von Anthropic: "Kontext Engineering ist das Kuratieren dessen, was das Modell sieht, damit du ein besseres Ergebnis bekommst."

Das Kontextfenster eines LLMs ist endlich und teuer. Frontier-Modelle können laut Forschung ca. 150–200 Instruktionen zuverlässig befolgen — danach nimmt die Verlässlichkeit ab. Kleinere Modelle schaffen deutlich weniger. Das bedeutet: Jedes Token im Kontextfenster muss einen Zweck erfüllen.

Das Leitprinzip lautet: Finde den kleinsten Satz hochrelevanter Token, der die Wahrscheinlichkeit des gewünschten Ergebnisses maximiert.

CLAUDE.md — Persistentes Gedächtnis für KI-Agenten

CLAUDE.md ist eine spezielle Datei, die Claude bei jedem Gesprächsstart automatisch liest. Sie ist der einzige Weg, einem Agenten session-übergreifendes Wissen mitzugeben — denn Coding-Agenten kennen zu Beginn jeder Session nichts über dein Projekt.

Was gehört in CLAUDE.md?

# Projekt: MeineSaaS

## Tech-Stack
- Next.js 16 (App Router), TypeScript (strict), Tailwind CSS v4
- SQLite + Drizzle ORM, bcrypt Sessions

## Wichtige Konventionen
- Server Actions nutzen useActionState (React 19, NICHT useFormState)
- Commits: Conventional Commits (feat:/fix:/chore:)
- Files max 300 Zeilen, Funktionen max 30 Zeilen

## Deployment
- VPS: root@meinserver.de, /opt/meinesaas/
- Deploy: bash deploy-remote.sh

Was NICHT in CLAUDE.md gehört

Claude Code enthält bereits ~50 eigene Instruktionen im System-Prompt. Deine CLAUDE.md sollte deshalb so kurz wie möglich bleiben — nur Regeln, die universell für jede Aufgabe im Projekt gelten.

Zu vermeiden:

• Lange Erklärungen, die der Agent aus dem Code ableiten kann
• Informationen, die sich häufig ändern (besser: dynamisch laden)
• Duplikate von Standard-Best-Practices, die der Agent ohnehin kennt

System-Prompts richtig aufbauen

System-Prompts sind die mächtigste Kontroll-Ebene für KI-Agenten in eigenen Applikationen. Ein guter System-Prompt folgt dieser Struktur:

[Rolle & Ziel]
Du bist ein hilfreicher Assistent für [Kontext].
Dein Ziel ist [spezifisches Ziel].

[Kontext & Einschränkungen]
- Du hast Zugriff auf [verfügbare Tools/Daten]
- Du antwortest nur auf Fragen zu [Themenbereich]
- Sprache: Deutsch

[Output-Format]
Strukturiere Antworten als:
1. Kurze Zusammenfassung (1-2 Sätze)
2. Details mit ## Überschriften
3. Code in ```sprachname-Blöcken

[Sicherheitsregeln]
- Keine personenbezogenen Daten in Antworten
- Bei Unsicherheit: nachfragen, nicht raten

Anthropic Best Practices (2026)

Laut den offiziellen Claude Prompting Best Practices:

• Rollen explizit definieren: "Du bist ein Senior Security Engineer" statt "hilfreicher Assistent"
• Beispiele nutzen (Few-Shot): Ein konkretes Beispiel ist wertvoller als eine abstrakte Regel
• Chain of Thought: Für komplexe Aufgaben "Denke Schritt für Schritt" einfügen
• XML-Tags für Struktur: <context>, <instructions>, <examples> helfen dem Modell

Just-in-Time Kontext laden

Statt alles in CLAUDE.md zu laden, empfiehlt Anthropic Just-in-Time Context Loading: Lightweight-Referenzen (Dateipfade, Links) statt fertig geladener Inhalte.

# CLAUDE.md — schlank halten

## API-Dokumentation
Für Auth-Fragen: @src/lib/auth.ts lesen
Für DB-Schema: @src/db/schema.ts lesen
Für API-Routen: @src/app/api/ erkunden

Der Agent lädt Dateien nur dann in den Kontext, wenn er sie tatsächlich braucht. Das spart Token und hält den Kontext fokussiert.

Skills und Rules — Kontext modularisieren

Claude Code unterstützt ein Skills-System: Ordner mit Instruktionen, die dynamisch geladen werden. Statt einer riesigen CLAUDE.md kannst du Wissen aufteilen:

.claude/
  rules/
    security.md      # Nur bei API-Dateien geladen
    testing.md       # Nur bei Test-Dateien
    design.md        # Nur bei UI-Komponenten
  skills/
    deploy.md        # /deploy Befehl
    audit.md         # /audit Befehl

# .claude/rules/security.md
globs: src/app/api/**/*.ts

# API Security Rules
- Jede Route: Auth + Rate-Limit + Zod-Validierung
- Keine Secrets im Code → process.env
- Parameterisierte Queries für alle DB-Operationen

Hooks — Wenn Instruktionen nicht reichen

Instruktionen in CLAUDE.md sind empfehlend. Für Aktionen, die ausnahmslos stattfinden müssen, sind Hooks die richtige Wahl — sie laufen deterministisch als Skripte:

// .claude/hooks/pre-commit.js
// Blockiert Commits mit Secrets im Code
const input = JSON.parse(require("fs").readFileSync("/dev/stdin", "utf8"));
const cmd = input.tool_input?.command || "";

if (cmd.includes("git commit") && /sk-[a-zA-Z0-9]{20,}/.test(getChangedFiles())) {
  console.error("BLOCKED: API-Key im Commit gefunden!");
  process.exit(2);
}

Fazit

Kontext Engineering ist die Kernkompetenz für effektive KI-Entwicklung 2026. Die Hierarchie:

1. CLAUDE.md — projektweite Dauerkontexte (kurz halten!)
2. Rules — dateityp-spezifische Regeln (on-demand geladen)
3. System-Prompts — für eigene KI-Applikationen
4. Hooks — für nicht-verhandelbare Automatisierungen
5. Just-in-Time Loading — für große Wissensbasen

Wie Anthropic es auf den Punkt bringt: "Claude ist klug genug — Intelligenz ist nicht der Engpass, Kontext ist."