Thariq Shihipar, Engineer im Claude-Code-Team bei Anthropic, hat auf X einen Artikel veröffentlicht, der in kurzer Zeit extrem viel Aufmerksamkeit bekommen hat. Seine These: Markdown ist als Ausgabeformat für Claude Code an seine Grenzen gekommen. Er lässt sich fast alles als HTML generieren, von Specs über Pläne bis zu Reports, und sieht das zunehmend auch bei Kolleg:innen im Team.
In diesem Artikel schauen wir uns an, was hinter dem Wechsel steckt, welche Vor- und Nachteile HTML hat und wie du dir selbst eine Grundlage für HTML-Dokumente in deinem eigenen Design baust. Am Ende sage ich dir, wo ich HTML nutze und wo ich bewusst bei Markdown bleibe.
Worum geht es in Thariqs Artikel?
Markdown ist in den letzten Jahren zum Standardformat geworden, in dem KI-Modelle ihre Ergebnisse ausgeben. Das Format ist simpel, portabel und für jeden lesbar. Es stößt aber an seine Grenzen, wenn die Ausgaben lang und komplex werden. Dann sind sie schwer lesbar, unübersichtlich und aufwendig zu verwalten. Thariq schreibt, dass er Markdown-Dateien ab etwa 100 Zeilen kaum noch liest.
Stattdessen lässt er die meisten Ausgaben direkt als HTML-Datei erzeugen. Gemeint ist keine Website im klassischen Sinn, sondern ein visuell strukturiertes Dokument: mit Hierarchien, echten Überschriften, Layout und Farben, manchmal auch mit SVG-Diagrammen oder interaktiven Elementen.
Seine Begründung:
- Mehr Information auf weniger Raum: HTML kann Tabellen, Diagramme, Code-Snippets und Interaktion darstellen.
- Bessere Lesbarkeit: Gerade lange Dokumente lassen sich mit Tabs, Abschnitten und Grafiken viel leichter erfassen.
- Interaktivität: Dokumente können Regler, Schalter oder Kopieren-Buttons enthalten.
- Einfaches Teilen: Jeder mit einem Browser kann die Datei öffnen.
Wofür sich HTML laut Thariq eignet
Thariq hat eine eigene Beispielseite mit Use Cases angelegt, für die er HTML statt Markdown nutzt. Ein Überblick über die wichtigsten:
- Exploration und Planung: Immer wenn es mehrere Wege gibt, sei es in der Umsetzung oder im visuellen Design, und für Implementierungspläne.
- Code Review: Pull Requests lassen sich mit Code-Snippets visualisieren. Du siehst direkt, was entfernt wurde und was neu ist, und kannst in Details springen.
- Designsysteme: Farben, Schriften und Komponenten auf einen Blick.
- Präsentationen: Ein Klassiker. Ich baue meine Workshop-Präsentationen regelmäßig als HTML.
- Reports: Zum Beispiel wöchentliche Statusberichte, die du im Team teilst.
Laut Thariq brauchst du dafür keinen speziellen Skill. Es reicht, Claude zu bitten, eine HTML-Datei zu erstellen, und zu wissen, was das Dokument leisten soll. Zwei Beispiel-Prompts angelehnt an seinen Artikel:
Erstell einen ausführlichen Implementierungsplan als HTML-Datei. Füge ein paar Mockups hinzu, zeig den Datenfluss und die wichtigsten Code-Snippets, die ich prüfen sollte. Mach das Dokument leicht lesbar.
Ich bin mir unsicher, welche Richtung der Onboarding-Screen nehmen soll. Erstelle 6 deutlich unterschiedliche Ansätze mit unterschiedlichem Layout, Tonfall und Informationsdichte und stelle sie in einer einzigen HTML-Datei in einem Raster nebeneinander. Beschrifte jeden Ansatz mit dem Kompromiss, den er eingeht.
Vorteile von HTML gegenüber Markdown
Die Vorteile zeigen sich vor allem, wenn du Dokumente mit deinem Team, mit Kolleg:innen oder Kund:innen teilst. Du kannst Tabellen, Grafiken, Code-Snippets und interaktive Elemente einbauen. Konzepte lassen sich visuell vermitteln und werden leichter verständlich. Je länger ein Dokument ist, desto stärker wirkt das.
Verstehen Coding Agents HTML genauso gut?
Eine berechtigte Frage. Eine HTML-Datei enthält ja nicht nur Inhalt, sondern auch Grundstruktur: Tags, CSS-Klassen und Layout. Das erzeugt viel Rauschen rund um den eigentlichen Inhalt.
Hier kann ich dich beruhigen. Claude und auch die Konkurrenzmodelle lesen HTML problemlos. HTML wird seit jeher in der Webentwicklung verwendet, es gibt also extrem viele Trainingsdaten. Die Verständnisqualität leidet nicht.
Nachteile von HTML: Token, Diffs, Bearbeitung, Tempo
1. Höherer Tokenverbrauch
Was leidet, ist dein Kontextfenster. Liest dein Agent regelmäßig HTML-Dokumente ein, füllt es sich deutlich schneller. Mit einem Claude-Abo merkst du das höchstens daran, dass du dein Nutzungslimit schneller erreichst. Arbeitest du über die API, wirkt sich das direkt auf deine Kosten aus.
Ich habe das an einem echten Beispiel gemessen. In einer großen bestehenden Codebase habe ich eine Analyse zu Sicherheit und technischen Schulden erstellen lassen, ein recht langes Dokument mit Befunden aus mehreren Perspektiven. Daraus habe ich eine HTML-Version erzeugen lassen, visuell aufbereitet in meinem Design und mit Reitern für die einzelnen Kategorien.
| Format | Input-Token |
|---|---|
| Markdown | 4.064 |
| HTML | mehr als doppelt so viele |
Der Mehrverbrauch kommt vor allem von der Dokumentstruktur und dem Layout.
2. Schwierige Versionskontrolle
HTML-Diffs sind sehr schwer lesbar. Ein Diff ist die Gegenüberstellung von altem und neuem Stand. Versionierst du Dokumente mit Git und willst nachvollziehen, was sich geändert hat, ist Markdown klar im Vorteil: Dort erkennst du Änderungen auf einen Blick. Bei HTML geht die Lesbarkeit in der Grundstruktur unter. Auch Thariq nennt das als einen der größten Nachteile.
3. Umständliche manuelle Änderungen
In Markdown fügst du schnell eine neue Zeile hinzu. In HTML musst du auf die Struktur achten und prüfen, ob alle Tags korrekt gesetzt sind. Im besten Fall lässt du Claude am Ende noch einmal drüberschauen.
4. Langsamere Generierung
HTML zu erzeugen dauert laut Thariq zwei- bis viermal so lange wie Markdown. Auch das liegt an Struktur und Layout.
HTML oder Markdown: Meine Faustregel
Unterm Strich ergibt sich ein klares Bild:
| Format | Nutze es, wenn … |
|---|---|
| HTML | ein Mensch das Dokument reviewen soll oder du es mit anderen teilst |
| Markdown | das Dokument primär von Coding Agents wie Claude gelesen wird oder du schnell selbst Änderungen machen willst |
So erstellst du HTML-Dokumente in deinem eigenen Design
Du kannst Claude einfach bitten, aus einer Markdown-Datei eine HTML-Datei zu machen. Das Ergebnis sieht dann aber recht unspektakulär aus. Wenn dein eigener Stil drin sein soll, brauchst du zuerst ein Designsystem, also die Sammlung deiner Farben, Schriften und Komponenten.
Schritt 1: Designsystem in Claude Design anlegen
Ein Designsystem erstellst du inzwischen sehr einfach mit Claude Design. Eine ausführliche Einführung findest du in meiner Claude Design Anleitung. Auf dem Startscreen wechselst du auf „Design System“ und klickst auf „Create“. Statt Farben, Schriften und alles Weitere manuell einzupflegen, importierst du deine bestehende Gestaltung:
- per GitHub-Repository,
- per Upload von Code-Dateien, in denen dein Design steckt,
- per Figma-Datei, wenn deine Brand Guidelines dort liegen,
- oder du fügst deine Assets manuell hinzu.
Ich habe das GitHub-Repository meiner Website verlinkt. Claude hat den Code ausgelesen und daraus das Designsystem aufgebaut: Farben, Container, Buttons, ein FAQ-Akkordeon, Eingabefelder mit Validierung. Bei Bedarf kannst du mit weiteren Anweisungen nachschärfen.
Schritt 2: Als Standalone-HTML exportieren
Über „Share“ kannst du das Designsystem in verschiedenen Formaten exportieren, unter anderem als Standalone-HTML. Diese Datei lädst du herunter.
Schritt 3: Einen Skill daraus machen
Mit dieser HTML-Datei bin ich zurück in Claude und habe mir einen Skill erstellen lassen. Ich habe ihm gesagt, dass ich künftig Markdown-Dateien in HTML-Dateien umwandeln möchte und er mir dafür einen Skill anlegen soll.
Wenn ich jetzt eine Markdown-Datei umwandeln will, rufe ich den Skill auf und schreibe dazu:
Bitte wandle die angehängte Markdown-Datei in eine HTML-Datei um. Wähle dafür eine sinnvolle Struktur.
Dann hänge ich die Markdown-Datei an. In meinem Test war das ein Lead-Funnel-Report mit Testdaten. Heraus kam ein übersichtlich aufbereiteter Bericht in meinem Design, den ich direkt im Browser öffnen kann.
Wo ich HTML nutze und wo ich bei Markdown bleibe
Im Gegensatz zum Anthropic-Team setze ich HTML noch nicht überall in Softwareprojekten ein. An vielen Stellen bleibe ich bewusst bei Markdown. Vor allem dort, wo Markdown-Dateien die Single Source of Truth für Coding Agents sind, also die eine verbindliche Quelle: im Product Requirements Document und in Feature-Spezifikationen. Auch CLAUDE.md, Skills und Rules bleiben Markdown.
Abseits der Softwareentwicklung nutze ich HTML dagegen regelmäßig. Ich setze Claude Code als eine Art Business-OS ein, das alle Geschäftsbereiche abdeckt: Angebote, Kooperationsbriefings, Workshop-Präsentationen, Content und Produkterstellung. Überall dort, wo Inhalte für Menschen aufbereitet und visualisiert werden, arbeite ich gerne mit HTML.
Ein Learning dabei: HTML-Dateien werden schnell monolithisch. Gerade größere Präsentationen teile ich irgendwann in kleinere Dateien auf, weil stark wachsende HTML-Dateien ab einer gewissen Größe fehleranfällig werden, wenn Coding Agents sie ändern.
Einordnung: Kein Entweder-oder
HTML ist ein unterschätztes Ausgabeformat für Claude Code, und Thariqs Artikel ist ein guter Anlass, es ernst zu nehmen. Für alles, was Menschen lesen, prüfen oder geteilt bekommen, ist es Markdown deutlich überlegen. Den Preis zahlst du mit mehr Token, längerer Generierung und schwer lesbaren Diffs.
Für die Dateien, mit denen deine Coding Agents arbeiten, bleibt Markdown die bessere Wahl. Gerade in größeren Projekten ist eine saubere, agentenlesbare Dokumentation aus Spezifikationen und Regeln das Fundament eines strukturierten Entwicklungsprozesses. Welche Rolle Spezifikationen, Skills und Rules auf dem Weg vom Vibe Coding zum AI Engineering spielen, zeige ich in meinem Artikel über die 5 Level von Claude Code.
