Context Engineering

Aktive Steuerung des Context-Budgets durch strukturierte MD-Dateien.

Das Problem mit CLAUDE.md

Eine gewachsene CLAUDE.md von 400+ Zeilen wird bei jeder Session vollständig geladen – MTU-Troubleshooting-Anleitungen, Migrations-Guides, Security-Architektur – egal ob du nur eine Variable in einem Playbook änderst.

Typischer Ist-Zustand:
CLAUDE.md: 6.900 Tokens (bei jeder Session)
→ Davon tatsächlich gebraucht: ~15%

Context Engineering löst das: Minimaler Persistent-Context, Rest on-demand.

---

Dispatcher-Pattern

Statt einer monolithischen CLAUDE.md wird sie zum schlanken Dispatcher:

projekt/
├── CLAUDE.md                          # Dispatcher – max 40 Zeilen / ~500 Tokens
└── .claude/
    └── context/
        ├── always/
        │   └── infrastructure.md      # Immer geladen – Quick Reference
        └── lazy/
            ├── architecture.md        # On-demand: Design-Entscheidungen
            ├── coding.md              # On-demand: Konventionen, Patterns
            ├── security.md            # On-demand: Firewall, Auth, Certs
            └── troubleshooting.md     # On-demand: Debug-Commands

CLAUDE.md als Dispatcher

# Projektname – Claude Code

Ein Satz was das Projekt macht.

## Deployment
ansible-playbook -i inventory/hosts.yml deploy.yml --ask-vault-pass

## Quick Reference
@.claude/context/always/infrastructure.md

## Lazy-Load – bei Bedarf lesen
| Aufgabe                      | Datei                                   |
|------------------------------|-----------------------------------------|
| Architektur / Design-Fragen  | .claude/context/lazy/architecture.md    |
| Code-Konventionen            | .claude/context/lazy/coding.md          |
| Security / Firewall          | .claude/context/lazy/security.md        |
| Debugging / Fehlersuche      | .claude/context/lazy/troubleshooting.md |

## Verhalten
- Deutsch immer
- Commits nur auf explizite Anfrage
- Patches only – kein Rewrite außer bei "Baseline"

Der @-Operator lädt infrastructure.md direkt beim Start. Die lazy-Dateien werden nur geladen wenn der Task es erfordert – Claude Code liest sie per Read-Tool-Call on-demand.

---

always/ vs. lazy/

Kriterium	always/	lazy/
Wird in >50% aller Sessions gebraucht	✅	❌
Ändert sich selten (< 1x/Monat)	✅	–
Fakten, keine Erklärungen	✅	–
Domänen-spezifisches Wissen	❌	✅
Debug-Anleitungen, Runbooks	❌	✅

Faustregel: Im Zweifel → lazy/.

always/infrastructure.md – Inhalt

Nur Fakten, keine Erklärungen. Ziel: ≤ 1.500 Tokens.

# Infrastructure Quick Reference

## Hosts
| ID  | Hostname   | Funktion         | IP (Frontend) | IP (Mgmt)     | Port      |
|-----|------------|------------------|---------------|---------------|-----------|
| 210 | wg1        | WireGuard server | 10.10.0.1     | 172.16.0.210  | 51515/UDP |
| 220 | jumphost   | Admin            | 10.11.0.1     | 172.16.0.220  | 51516/UDP |

## Netzwerke
| Netz       | Subnetz          | Zweck      |
|------------|------------------|------------|
| Frontend   | 10.10.0.0/24     | Daten      |
| Management | 172.16.0.0/24    | Admin      |

## Wichtige Pfade
- Configs: /etc/projekt/
- Vault:   ansible/vault/secrets.yml

---

Token-Ersparnis messen

Nach dem Umbau Verifikation in einer frischen Session (kein /resume):

/context

Erwartetes Ergebnis:

Kategorie	Vorher	Nachher	Ersparnis
CLAUDE.md	~6.900	~500	-6.400
Memory files	~7.000	~1.800	-5.200
Pro Session	–	–	~5k Tokens

---

Lazy-Loading testen

Neue Session starten, dann eine Frage stellen die nur mit einer lazy-Datei beantwortet werden kann:

"Wie muss die MTU bei den Clients eingestellt sein?"

Erwartetes Verhalten:

Read 1 file (ctrl+o to expand)   ← lazy/troubleshooting.md wird gezogen
→ Antwort mit konkreten Werten

Gegenteil-Test: Frage die aus always/infrastructure.md beantwortet wird:

"Welche IP hat der Jumphost?"
→ Antwort kommt direkt, kein Read

---

Agents vs. lazy/ Dateien

Für komplexere Domänen ist ein Sub-Agent die sauberere Lösung:

	lazy/ Dateien	Sub-Agents
Eigenes Context Window	❌	✅
Kontext-Isolation	❌	✅
Parallelisierbar	❌	✅
Overhead	minimal	Agent-Spawn
Gut für	kurze Referenz-Infos	komplexe, abgeschlossene Tasks

Entscheidung: Ist die Domäne groß genug für einen eigenen Agent (z.B. doc-generator, playbook-builder)? → Agent mit eigenem Context Window. Alles andere → lazy/ Datei.

Projekt-Override für globale Agents

Globale Agents kennen keine projektspezifischen Dateipfade. Lösung: Projekt-Override in .claude/agents/<name>.md:

---
name: doc-generator
---

# doc-generator – Projekt-Override

## Projekt-Dateien
- SECURITY.md, FIREWALL.md, POC.md – Ziel-Dateien für Updates

## Regeln
- Nur exakte Deltas: "Alt: X → Neu: Y"
- Bei Sicherheitsänderungen: .claude/context/lazy/security.md lesen

## Priorität
SECURITY.md + FIREWALL.md zuerst bei sicherheitsrelevanten Änderungen

---

Token-Budget Richtwerte

Datei	Ziel	Warnschwelle
CLAUDE.md	≤ 500 Tokens	> 800 → kürzen
always/infrastructure.md	≤ 1.500 Tokens	> 2.000 → aufteilen
lazy/*.md	≤ 1.000 Tokens je	> 1.500 → aufteilen
agents/*.md (Override)	≤ 300 Tokens	> 500 → kürzen

---

Anti-Patterns

Anti-Pattern	Problem	Besser
Code-Style in CLAUDE.md	Linter-Job, frisst Tokens	.editorconfig / Linter
Komplette Playbooks als Kontext	Viel zu groß	Nur Rollenübersicht in lazy/
Duplicate Content in mehreren Dateien	Veraltet schnell	Eine Quelle, Rest referenziert
Changelogs in CLAUDE.md	History gehört in Git	Weglassen
"Always be helpful"	Bringt nichts	Weglassen

---

Praktischer Einstieg

Den Umbau muss man nicht manuell machen. In Claude Code (Plan Mode):

Analyze the current project structure and CLAUDE.md.
Design a context engineering setup:
- Lean CLAUDE.md as dispatcher (<40 lines)
- always/ for genuine quick reference
- lazy/ for domain-specific context
Present the proposed structure first, implement after confirmation.

Claude Code analysiert die bestehende CLAUDE.md, schlägt die Aufteilung vor und setzt sie nach Bestätigung um – inklusive Token-Analyse vorher/nachher.