Das Token-Dilemma: Warum HTML für technische Agenten-Specs oft Overkill ist
Markdown vs. HTML als Agenten-Kontext: Ein Token-Vergleich mit Google Gemini und Claude Sonnet zeigt, warum schlanke Dokumentation im KI-Engineering trumpft.
Ein pragmatischer Reality-Check zum aktuellen "Effectiveness of HTML"-Trend aus Sicht der Pipeline-Effizienz und Kontext-Optimierung.
In der AI-Engineering-Welt wird aktuell viel darüber diskutiert, wie überraschend effektiv das Generieren und Nutzen von nativem HTML im Umgang mit LLMs sein kann. Anthropic hat dazu vor Kurzem einen interessanten Blog-Post veröffentlicht: Using Claude Code: The unreasonable effectiveness of HTML.
Ich nutze in meiner lokalen Umgebung selbst einen kleinen LLM-gestützten PDF Intelligence & Renaming Agent, um Scans nach dem Einlesen einen Dateinamen zu geben, der meiner bevorzugten Wahl entspricht. Das funktioniert hervorragend.
Aus Neugier habe ich dann zwei aktuelle Frontier-Modelle gebeten, meine schlanke Markdown-Spezifikation (AGENTS.md) in ein hochgradig durchgestyltes HTML-Dokument zu übersetzen – so, wie es in dem Blogpost vorgeschlagen wird. Das optische Ergebnis ist bei beiden zweifellos schick. Aber als DevOps- und Software-Engineer schaut man eben auch auf die Metriken unter der Haube. Und die sprechen eine ganz andere Sprache.
Der nackte Zahlenvergleich: Markdown vs. HTML
Schauen wir uns an, was passiert, wenn man identische logische Anweisungen von Markdown in ein modernes HTML-Skelett gießt. Ich habe dafür zwei Generierungen durchgeführt: einmal mit Google Gemini (kompakteres Output, Print-CSS-Fokus) und einmal mit Claude Sonnet (vollständiges interaktives Layout mit aufklappbaren Sektionen, CSS-Grid, Animationen).
| Metrik | Original (AGENTS.md) |
Gemini HTML | Claude Sonnet HTML |
|---|---|---|---|
| Zeichen | 3.648 | 10.181 | 19.365 |
| Wörter | 391 | 746 | ~1.500 |
| Geschätzte Tokens | ~490–960 | ~2.000–2.200 | ~5.100 |
| Faktor ggü. Markdown | 1× | ~4× | ~5,3× |
Hinweis zur Token-Schätzung: Die GPT-4o-Zahlen (Gemini-Spalte) basieren auf dem OpenAI-Tokenizer; die Claude-Schätzung auf ~3,8 Zeichen/Token (claude-sonnet-4-6).
Warum explodiert der Token-Count so massiv?
Die zugrundeliegende Programmlogik, die Systemgrenzen und die Verzeichnisstrukturen sind identisch geblieben. Der Mehrverbrauch resultiert ausschließlich aus syntaktischem Overhead: Inline-CSS-Klassen, verschachtelte <div>- und <table>-Strukturen, CSS-Variablen, JavaScript für Interaktionen und HTML-Entities wie → oder •. Das alles landet vollständig im Kontextfenster – kein Modell kann da "wegschauen".
Je ambitionierter das visuelle Design, desto schlimmer die Bilanz. Die Claude-Variante, die wirklich hübsch geworden ist (dunkles Terminal-Theme, aufklappbare Phasen, farbcodierte Blöcke), kostet über 5× so viele Tokens wie das Original.
Der funktionale Blueprint des Agenten
Damit wir vom selben Inhalt sprechen, hier die Kurzfassung dessen, was die Spezifikation regelt:
- Zweck: Nimmt PDFs aus
new/, jagt sie durch ein Python-OCR-Skript (pdf-extract.py), liest die Extraktion aus einem Bufferoutput.txtund generiert ein finales, sicheres Batch-Skript (rename.shoderrename.ps1). - Sicherheitsgrenze: Der Agent darf niemals selbst Dateien verschieben oder löschen, sondern schreibt ausschließlich idempotente Befehle (wie
mv -n) in das Skript. - Naming-Schema:
yyyy-mm-dd--[category]--[sender]--[subject].pdf(Strict Lowercase, Kebab-Case, Umlaut-Sanitizing). - Klassifizierung: Striktes Mapping auf elf vordefinierte Kategorien (z. B.
amt-behoerde,arbeitgeber,haendler-shop,versicherungen).
Mein Fazit: Markdown bleibt King im Core-Engineering
Versteht mich nicht falsch: Man könnte das CSS auslagern, wenn man solche UI-Strukturen standardisiert und häufiger abruft. Aber warum sollten wir das im Entwicklungsalltag überhaupt erzwingen?
Heutzutage schickt doch niemand mehr lose, rohe Markdown-Dateien per E-Mail oder Chat durch die Gegend. Wir arbeiten in Git-Ökosystemen. Sobald du einen Link zu einer .md-Datei in GitHub, GitLab oder Codeberg teilst, übernimmt das Web-Interface das saubere Rendering für das menschliche Auge – ganz ohne eine einzige Zeile mitgeschlepptes CSS.
Wenn dieser Prompt oder diese Dokumentation nun Teil des Kontextfensters eines AI-Agenten wird (sei es lokal via Ollama/vLLM oder über externe APIs), zahlen wir bei HTML einen 400–430% Token-Aufschlag für reines visuelles Lametta, das die LLM-Logik kein bisschen verbessert. Das ist kein akademisches Detail: Bei langen Agentenläufen mit vielen eingelesenen Dateien summiert sich das direkt in höhere Kosten und kürzere effektive Kontextfenster.
Der Thariq-Blogpost hat übrigens durchaus seinen Punkt – aber er beschreibt primär einen Output-Workflow: Claude Code erzeugt HTML-Berichte, die Menschen lesen. Für diesen Anwendungsfall ist HTML tatsächlich überlegen. Das Problem entsteht, wenn man HTML auch als Input für Agenten einsetzt, also als Systemkontext, Spec oder Instruktionsdatei. Da dreht sich der Vorteil um.
Mein Fazit für schlanke Dokumentation: Für menschliche Interfaces im Browser ist HTML nett; im Herzstück meiner/unserer Engineering- und Automatisierungsumgebungen ist GitHub-Flavored-Markdown nach wie vor das ungeschlagene Optimum aus Lesbarkeit, Versionierbarkeit und Token-Effizienz.