KI-Agent-Tokens mit hierarchischem Kontext sparen | Lösung

Hierarchischer Kontext: Wie drei Markdown-Dateien 80 % der AI-Agent-Tokens sparen

Entwicklungs-AI-Agenten wie Claude Code oder Cursor verbrauchen bis zu 80 % ihrer Tokens mit dem erneuten Lesen von Dateien und der Navigation in Projekten. Das Problem entsteht durch das Fehlen einer strukturierten Arbeitsbereichsübersicht. Die Lösung ist hierarchischer Kontext aus drei Markdown-Dateien, der Tool-Calls um das 10–20-Fache reduziert und die Genauigkeit der Antworten steigert.

Anatomie des Problems: Wohin gehen die Tokens?

Bei der Frage „Welche Zahlungsmethoden unterstützt mein Bot?“ durchläuft der Agent einen Zyklus: grep im Home-Verzeichnis → Lesen gefundener Dateien → Erkennen des falschen Projekts → Neue Suche → SSH-Verbindung zum Server. Für eine 800-Token-Antwort verbraucht er 15+ Tool-Calls und über 80.000 Tokens. 99 % des Budgets gehen für Navigation drauf, 1 % für die Antwort.

Das ist kein Bug eines bestimmten Agents – es ist ein systemisches Architekturproblem. Alle KI-Coding-Tools (Cursor, Codex, Gemini CLI) starten jede Sitzung mit „blinder Aufklärung“, weil ihnen eine Arbeitsbereichsübersicht fehlt. Bei 15 Projekten werden dadurch stundenlang Kontext täglich für die Dateisuche verschwendet.

Warum RAG und statische Analyse das nicht lösen

Vektordatenbanken (RAG) erfassen semantische Ähnlichkeiten, ignorieren aber die Code-Struktur. Eine Abfrage wie „Wie funktioniert die Authentifizierung?“ liefert 15 Fragmente mit „auth“, zeigt aber nicht die Aufrufkette: middleware.ts → refresh.ts → jwt-config.ts. Dazu kommt bei RAG eine Latenz von 200–500 ms pro Abfrage und Infrastruktur (Embedding-Server, Index).

Tree-sitter und statische Analyse (z. B. Hypergrep) erstellen Abhängigkeitsgraphen innerhalb eines Projekts. Aber sie können Fragen wie „Welche Projekte nutzen Redis?“ oder „Wo ist der VPN-Bot deployed?“ nicht beantworten. Eine CLAUDE.md pro Projekt erledigt interne Aufgaben, hilft aber nicht, wenn der Agent nicht weiß, in welchem Projekt er suchen soll.

Hierarchisches Kontext-Modell: Ebenen 0, 1 und 1.5

Das System deckt drei Abstraktionsebenen ab:

Level 0: Projektkarte — kennt ALLE Projekte und Server (~2KB, immer im Kontext)
Level 1: Projektdetails — Architektur eines spezifischen Projekts (~5KB, auf Anfrage)
Level 1.5: Code-Graph — Struktur der Codebasis (optional, Graphify)
Level 2: Quellcode — echte Dateien (nur wenn nötig)

Prinzip: Der Agent bewegt sich von oben nach unten, nicht von unten nach oben. Zuerst identifiziert er das Projekt aus der Karte, dann liest er dessen Architektur, dann spezifische Dateien.

Level 0: Globale Karte

Abgelegt in ~/.claude/CLAUDE.md (für Claude Code) oder Äquivalent:

## Projektübersicht

| Projekt | Pfad | Server | Status |
|---------|------|--------|--------|
| VPN Bot | ~/projects/vpn-bot/ | prod-1:/opt/vpn/ | LIVE |
| Auth Service | ~/projects/auth/ | prod-1 (Docker) | LIVE |

### Server
| Name | IP | Zweck |
|------|----|-------|
| prod-1 | 178.17.50.45 | Haupt-VPS, 3 Dienste |

### Regel
Bevor du Quellcode liest – lies die CLAUDE.md des Projekts.

Diese Datei (~2KB) lädt sich automatisch in jeder Sitzung. Der Agent sieht sofort die Projektliste, Standorte und Status.

Level 1: Projekt-CLAUDE.md

Im Root-Verzeichnis jedes Projekts:

# VPN Bot — CLAUDE.md

## Status: LIVE (prod-1)
Telegram-Bot für VPN-Service. Abos über Stars und CryptoBot.

## Stack
Python 3.11, python-telegram-bot, WireGuard, aiosqlite

## Wichtige Dateien
- bot/main.py — Einstiegspunkt
- bot/payments.py — Stars + CryptoBot-Verarbeitung

## Deployment
- Service: vpn-bot.service
- Logs: journalctl -u vpn-bot -f

Größe 3–5KB. Der Agent liest sie, wenn das Projekt erwähnt wird, und erhält die komplette Architektur ohne grep.

Level 1.5: Graphify (Optional)

Für Code-Navigation:

pip install graphify
cd ~/projects/auth
graphify claude install

Wandelt die Codebasis in einen Wissensgraphen um und spart 30–50 % der Calls in großen Projekten.

Ergebnisse: Effizienzmessungen

Tests mit Haiku (günstigstes Modell) unter identischen Bedingungen:

• Test 1: „Was ist die Architektur von Projekt A?“

Blinder Agent: 12 Tool-Calls, 100 % Genauigkeit.

Mit Hierarchie: 1 Tool-Call, 100 % Genauigkeit.

• Test 2: „Welche Projekte nutzen Bibliothek X?“

Blinder Agent: 44 Tool-Calls, 1 von 3 Projekten verpasst.

Mit Hierarchie: 2 Tool-Calls, alle Projekte gefunden.

• Test 3: „Wo ist Projekt B deployed?“

Blinder Agent: 9 Tool-Calls, SSH nötig.

Mit Hierarchie: 0 Tool-Calls, Antwort aus Kontext.

Test 2 ist entscheidend: Der blinde Agent hat nicht nur 22-mal mehr Ressourcen verbraucht, sondern auch eine falsche Antwort gegeben. Strukturierter Kontext steigert nicht nur Effizienz, sondern auch Genauigkeit.

Warum drei Dateien RAG für Navigation schlagen

• Null Latenz. Markdown-Dateien lesen ist instant; RAG fügt 200–500 ms pro Abfrage hinzu.
• Deterministisch. Du kontrollierst den Dateiinhalt, kein Verlass auf Reranker.
• Echtzeit. CLAUDE.md aktualisieren ist eine Zeile; RAG braucht vollständiges Reindexing.
• Universell. Funktioniert mit jedem Agent (Claude Code, Cursor, Gemini CLI), keine Custom-Infrastruktur.
• Skalierbar. 15 Projekte = 15 CLAUDE.md (75KB) + Karte (2KB) = 77KB vs. 500KB–1MB Raw-Dateien.

RAG ist super für semantische Dokusuche, aber für Projektnavigation gewinnt die Markdown-Hierarchie.

Bonus: Indexierung vergangener Sitzungen

Parser wandelt Sitzungslogs (.jsonl) und Chats in Markdown mit YAML-Frontmatter um:

---
title: "Webhook für Zahlungen repariert"
date: 2026-04-14
project: vpn-bot
topics: ["webhook", "cryptocloud", "cloudflare"]
files_touched: ["payments.py", "webhook.py"]
---

Durch Indexierung via Graphify findet der Agent vergangene Lösungen ohne erneute Erklärungen. Das schafft persistente Erinnerung über Dialoge hinweg.

Eine Million Tokens ist kein Allheilmittel

Selbst mit einem 1M-Token-Kontextfenster bleibt das Problem. LLMs gehen mit irrelevanten Infos schlechter um („lost in the middle“-Phänomen: Daten in der Kontextmitte werden oft ignoriert). Hierarchischer Kontext sorgt dafür, dass der Agent nur benötigte Dateien in der richtigen Reihenfolge bekommt und Noise minimiert.

So implementierst du es in 10 Minuten

• Erstelle eine globale Projektkarte in ~/.claude/CLAUDE.md (5 Minuten) – liste Projekte, Pfade, Server auf.
• Füge CLAUDE.md zum Root deines Hauptprojekts hinzu (5 Minuten) – gib Stack, wichtige Dateien, Deploy-Befehle an.
• Starte eine neue Agent-Sitzung und frage nach einem Projekt.
• Bestätige, dass der Agent ohne blinde Suche antwortet.

Wichtige Erkenntnisse

• AI-Agenten verschwenden bis zu 99 % der Tokens für Navigation, nicht für Antwortgenerierung.
• Eine Drei-Dateien-Markdown-Hierarchie reduziert Tool-Calls um das 10–20-Fache und verbessert Genauigkeit.
• Level 0 (globale Karte) und Level 1 (Projekt-CLAUDE.md) lösen Navigation zwischen Projekten.
• Keine Infrastruktur nötig; funktioniert mit jedem Coding-Agent.
• Strukturierter Kontext schlägt RAG bei Datei- und Projekterkennung.

— Editorial Team