Claude Code Output Format: Why HTML Beats Markdown

Key takeaways

1. Author. Thariq Shihipar — Engineer & serial entrepreneur, Claude Code team at Anthropic. X: @trq212. Site: thariqs.github.io/html-effectiveness (gallery of HTML examples generated by Claude Code, organized by use category).
2. Date. ~2026-05-10 (recent article, mentions Opus 4.7 with 1MM context, X snowflake ID ~ May 2026). URL: https://x.com/i/status/2052809885763747935.
3. Thesis in one line. "I've started preferring HTML as an output format instead of Markdown" — the default output format for agentic artifacts should shift from Markdown to HTML.
4. Why now?. three converging factors: 1. Agents produce longer and richer specs/plans than before. 2. The author (and those around him) no longer manually edits these files — he prompts Claude to edit them → the "hand-editable Markdown" advantage disappears. 3. Opus 4.7 + 1MM context painlessly absorbs HTML's extra tokens.
5. The 6 reasons (why HTML). 1. Information density — tables, CSS, SVG, scripts, canvas, images, absolute positioning, spatial data. "Almost no set of information that Claude can read that you cannot fairly efficiently represent with HTML." 2. Visual clarity & ease of reading — tabs, illustrations, links, mobile responsive. Beyond 100 lines of Markdown, no one reads it anymore. 3. Ease of sharing — S3 upload → direct link. "The chance of someone actually reading your spec is much much higher if it's in HTML." 4. Two-way interaction — sliders, knobs, "copy as prompt" buttons to loop back into Claude Code. 5. Data ingestion — Claude Code aggregates codebase + MCP (Slack, Linear) + git history + Chrome → broader context than ClaudeAI or Claude Design. 6. It's joyful — "makes me feel more involved and invested in the creation, and that by itself is enough".
6. Observed Markdown anti-pattern. the model, deprived of visual expressiveness, produces ASCII diagrams or approximates colors with Unicode characters (the article includes a screenshot of Claude Code trying to "show a color" in Unicode → an absurd signal of the format's inadequacy).
7. Rhetorical reference. "The Unreasonable Effectiveness of HTML" is a nod to "The Unreasonable Effectiveness of Mathematics" (Wigner, 1960) and to the lineage of "unreasonable effectiveness of X" titles in ML (Karpathy 2015 on RNNs).
8. 5 detailed canonical use cases. 1. Specs, Planning & Exploration — "a web of HTML files": brainstorming 6 directions in a comparative grid, expanding one option, mockups, code snippets, implementation plan. Sample prompt: "Generate 6 distinctly different approaches — vary layout, tone, and density — and lay them out as a single HTML file in a grid so I can compare them side by side." 2. Code Review & Understanding — attaching an HTML explainer to each PR. Diff rendered inline with marginal annotations, severity-based code-coloring. Sample prompt: "Render the actual diff with inline margin annotations, color-code findings by severity." 3. Design & Prototypes — Claude Design is itself HTML-based. Prototyping animations with sliders and a "copy parameters" button to export tuned values. 4. Reports, Research & Learning — the author had his prompt-caching article generated by reading git history. Long-form HTML, interactive explainer, slideshow. 5. Custom Editing Interfaces (throwaway editors) — a single-file throwaway editor for a specific piece of data, always ending with an export (copy as JSON/markdown/prompt) re-injectable into Claude Code. Examples: drag-and-drop of 30 Linear tickets into Now/Next/Later/Cut columns, a feature-flag editor with dependencies and warnings, a side-by-side prompt-tuner with a token counter. "Not a product, or a reusable tool, but a single HTML file, purpose-built for this one piece of data."
9. Major anti-pattern made explicit. "I'm a little bit afraid that people will read this article and turn it into a /html skill or something. While there might be some value in that, I want to emphasize that you don't need to do much to get Claude to do this." → Anti-skill-ification: the practice is too context-dependent to be fixed into a skill; prompting "make a HTML file" is enough.
10. Honest FAQ. (explicit concessions):
11. Token efficiency. HTML uses more tokens but Opus 4.7's 1MM context absorbs it.
12. Generation. 2-4× slower than Markdown — "but I've found the results are worth it".
13. Version control. "this is honestly one of the biggest downsides of HTML, HTML diffs are noisy and hard to review compared to Markdown" — an unresolved downside the author openly acknowledges.
14. Style / avoiding ugliness. use the frontend design plugin or create a single HTML design system by pointing Claude at the codebase, then reference it for other generated HTML files.
15. Final meta-thesis (in-the-loop). "I had begun to fear that because I had stopped reading plans in depth I would simply have to leave Claude to make its choices. But I am happy to say instead that I feel more in the loop than ever before when using HTML." → HTML as an antidote to cognitive surrender (Osmani) / comprehension debt: regained readability allows staying in the decision loop.
16. Connections with the tech-watch corpus.
17. Direct convergence with Isenberg × Meng To's design.md (2026-05-06): Meng explicitly states "HTML = finished dish, MD file = recipe, skills = ingredients". Shihipar validates HTML's primacy for the finished dish delivered to the human.
18. Operational response to Osmani — Cognitive Surrender / Comprehension Debt (2026-05-05): Shihipar names exactly the same problem ("I had stopped reading plans in depth") and proposes HTML as a solution to "stay in the loop".
19. Tension with Lattice / Vincent / Karpathy "skills-maxi": Shihipar adopts the opposite stance on skill-ification ("don't turn this into a /html skill"). Compromise: skills for stable patterns, bare prompting for emerging practices.
20. Confirmation of Opus 4.7 + 1MM context as an architectural shift that makes more verbose formats (HTML, design systems, extended brainstorms) economically sustainable.
21. Part of the Compounding engineering / Cherny lineage: HTML as a new layer of artifactual output between agent and human, on par with PR descriptions, release notes, and commit messages.
22. Meta example. to write this article, the author asked Claude Code to read through his code folder, find all generated HTML files, group/categorize them, and produce an HTML file with all the diagrams by type → the article's illustrations are themselves a product of the pattern it describes.
23. Resulting workflow for firm practice.
24. Any spec, plan, or report > 100 lines → shift to HTML.
25. Critical PRs → attach an HTML explainer.
26. File onboarding, design explorations, reorderings → HTML throwaway editor with structured export.
27. Keep Markdown for: commit messages, short fiche notes, .md config files (CLAUDE.md, agents.md, etc.).