In mei schreef ik dat een HTML-pagina van je coding agent in plaats van Markdown mooi was, maar duur en wegwerpspul. Ik noemde er zelfs een getal bij, 3 tot 5 keer zoveel tokens, zonder het te meten. Ik schreef ook dat HTML je diffs zou slopen, en ook dat had ik niet getest.
Vier maanden later is het idee niet verdwenen. Het is een feature geworden. Dus heb ik alsnog gemeten wat ik toen alleen beweerde.
Wat er sinds mei veranderde
Het essay van Thariq Shihipar over hoe het Claude Code-team HTML gebruikt, verscheen op 20 mei opnieuw op de blog van Claude, een week na mijn post. Die versie is zorgvuldiger dan het stuk op X waar ik op reageerde. De kosten geeft hij zelf toe: "While Markdown often uses fewer tokens, I've found that the added expressiveness of HTML and the much higher likelihood of me actually reading it means I get overall better output." Zijn punt is dat een document dat je echt leest meer waard is dan een document dat je doorbladert, en dat dat de extra tokens waard is.
Op 18 juni voegde Anthropic artifacts toe aan Claude Code. De agent schrijft een op zichzelf staande pagina en publiceert die op een privé-URL. Elke publicatie is een nieuwe versie, collega's in je organisatie kunnen erop reageren, en een pagina kan je MCP-connectors aanroepen zodra iemand hem opent. De documentatie zegt, zonder getal, dat "a styled page is more token-intensive than the same content as terminal text."
Antigravity van Google volgde op 26 augustus met agents die "interactive HTML/CSS/JS components" maken. Cursor had al sinds april canvases.
Daarmee vervalt mijn wegwerpargument. Een pagina met versiegeschiedenis, reacties en een vaste URL gooi je niet weg. Wat overblijft zijn de kosten, en daar had nog niemand een getal voor gepubliceerd. De veelgeciteerde besparing van 80% bij Cloudflare gaat over pagina's die een agent leest. Ik wilde weten wat de pagina's kosten die hij zelf schrijft.
De meting
Twee taken, elk in beide formaten, drie runs per combinatie, op Claude Code 2.1.273 met Opus 5. Geen tools, geen projectinstellingen, geen MCP-servers, één beurt. Het enige verschil tussen de formaten is de laatste regel van de prompt.
Task A: Write an implementation plan for adding per-user rate limiting to an
Express.js REST API with five endpoints: auth, users, orders, payments and
webhooks. Include the steps, the risks, and a rollout checklist.
Task B: Review this diff as a senior engineer and write the code review summary
for the author: what is wrong, how severe, and what to change.
[a fixed 30-line TypeScript diff: a coupon path with an empty catch, a mail
call after the insert, and a refund without a guard]
Markdown: Return the document as Markdown.
HTML: Return the document as a single self-contained HTML file.claude -p "$PROMPT" --model claude-opus-5 --tools "" --setting-sources "" \
--strict-mcp-config --no-session-persistence --output-format jsonOutput tokens, kosten en duur komen uit de JSON die claude -p teruggeeft. De kosten zijn berekend tegen lijstprijs. "Zichtbare woorden" is het aantal woorden na het weghalen van tags, styles en scripts: een grove controle of beide formaten evenveel zeiden.
| taak | formaat | output tokens, gemiddeld (bereik) | kosten | tijd | zichtbare woorden |
|---|---|---|---|---|---|
| plan | Markdown | 6.205 (4.739–6.948) | $0,16 | 64 s | 2.171 |
| plan | HTML | 11.783 (10.605–13.517) | $0,30 | 104 s | 2.100 |
| review | Markdown | 3.110 (2.890–3.244) | $0,08 | 35 s | 1.131 |
| review | HTML | 6.812 (6.600–6.977) | $0,17 | 64 s | 1.362 |
Voor het plan kostte HTML 1,9 keer zoveel output tokens, voor de review 2,2 keer. De zichtbare inhoud was ongeveer even groot. Elke pagina begon met zo'n 2.400 tekens CSS voordat er één woord inhoud stond.
HTML kost dus echt meer, ongeveer het dubbele. Mijn 3 tot 5 keer was overdreven. Op één document scheelt het hooguit vijftien cent en veertig seconden. Die veertig seconden merk je als eerste, en allebei tellen ze op in een loop die de pagina elke ronde opnieuw maakt.
Eén run staat niet in de tabel. Een HTML-plan kreeg ondanks --tools "" toch tools, verbrandde 65.250 tokens en $2,13 aan een reeks lege shell calls, en leverde nooit een pagina op. Ik kon het niet reproduceren, en een sessie met de verkeerde tools zegt niets over het formaat, dus die run heb ik overgedaan. Het laat wel zien dat een gemiddelde over drie runs verbergt wat één ontspoorde run kost.
De diff die niet ontplofte
Ik beweerde dat HTML-diffs onleesbaar zouden worden. Om dat te testen nam ik het eerste document uit elke combinatie en vroeg om een kleine revisie, met het hele document terug in hetzelfde formaat. Voor het plan: voeg een risico toe over een onbereikbare Redis, en begin de uitrol bij 5% van het verkeer. Voor de review: verlaag de ernst van de bevinding over e-mail met één niveau, en voeg een zin toe over idempotentie van de refund. De toelichting die het model onder de HTML zette, telde ik niet mee.
| revisie | Markdown-diff | HTML-diff |
|---|---|---|
| plan | +9 / −1 regels | +6 / −1 regels |
| review | +5 / −5 regels | +8 / −8 regels |
Allebei goed te reviewen. Bij het plan was de HTML-diff zelfs kleiner dan die in Markdown. Het grotere verschil bij de HTML-review komt doordat het model de hele bevinding van de sectie Major naar Minor verplaatste, en dat is precies de goede wijziging. In een pull request is die gewoon te volgen. Als het model in het bestaande document werkt, zijn de diffs in beide formaten ongeveer even groot. Mijn bewering overleeft deze test niet.
Wat de test niet dekt, is het geval waar ik eigenlijk bang voor was: een pagina helemaal opnieuw laten genereren in plaats van hem te laten aanpassen. Dan kan elke regel veranderen, en dat geldt voor Markdown net zo goed. Documenten die je bewaart laat je dus aanpassen in plaats van opnieuw genereren.
Waar Markdown nog wint: wat agents lezen
Het sterkste argument voor Markdown zit in 2026 aan de invoerkant.
Mintlify liet Claude Code en Codex los op 20 documentatiesites, 2.400 runs, en publiceerde de uitkomst op 17 juli. Agents liepen gemiddeld 2,23 keer per taak tegen een dode link aan op HTML-docs, 1,42 keer op Markdown, en 0,11 keer op Markdown met een llms.txt-index. Cloudflare serveert Markdown aan elke client die Accept: text/markdown meestuurt, en mat een eigen pagina op 16.180 tokens als HTML en 3.150 als Markdown. llms.txt v2, van 10 augustus, raadt nu aan om met een rel="alternate"-link naar de Markdown-versie van een pagina te verwijzen.
Daar maakt de keuze van het formaat echt verschil. Een plan dat een mens één keer leest, kost als HTML twee keer zoveel. Bij Cloudflare was een pagina als HTML vijf keer zo groot als in Markdown, en een agent leest documentatie bij elke taak opnieuw. In de runs van Mintlify raakte hij op HTML ook nog vaker de weg kwijt.
Wanneer de pagina zijn prijs waard is
Na het meten is mijn advies preciezer dan in mei.
- Vraag om HTML als een mens structuur moet zien om een beslissing te nemen. Een migratieplan met afhankelijkheden, een review met een stuk of twaalf bevindingen op ernst gesorteerd, een vergelijking waar iemand voor moet tekenen. Hier heeft Thariq gelijk: een pagina die gelezen wordt, is meer waard dan een Markdown-bestand dat wordt doorgebladerd, en twee keer zestien cent is nog steeds weinig geld.
- Gebruik Markdown voor alles wat een agent terugleest. Specs,
CLAUDE.md, docs, het plan waar de volgende sessie mee begint. Daar betaal je bij elke keer lezen, in tokens en in verkeerde afslagen. En lees die spec zelf, in welk formaat hij ook binnenkomt. - Gebruik Markdown in loops. Een pagina die elke iteratie opnieuw wordt gemaakt, betaalt elke keer het dubbele en laat je er elke keer op wachten.
- Pas pagina's die je bewaart aan, genereer ze nooit opnieuw. Dat houdt de diff klein, in beide formaten.
De titel van deze post werkt nog steeds als provocatie, alleen niet als advies. Laat je agents HTML schrijven als de lezer een mens is die iets moet beslissen. Laat ze Markdown schrijven als de lezer een andere agent is.