# shihipar-claude-code-html-unreasonable-effectiveness-markdown-2026-05-10

## Veille

Manifesto-style article by **Thariq Shihipar** (Engineer & serial entrepreneur, Claude Code team at Anthropic) announcing a **change in the default output format for agents**: replacing **Markdown with HTML**. Thesis: Markdown has been the dominant format between humans and agents (simple, portable, editable, readable) but has become **a bottleneck** as agents produce longer and richer artifacts (specs, plans, reports, code review). Beyond ~100 lines, no one reads a Markdown file anymore. HTML solves six limitations simultaneously: **information density** (tables, CSS, SVG, scripts, canvas, images), **visual clarity** (navigable, mobile-responsive layout), **ease of sharing** (an S3 link directly openable in a browser), **two-way interactivity** (sliders, knobs, "copy as JSON/prompt" buttons to loop back into Claude Code), **native contextual ingestion** (Claude Code reads the codebase + MCP Slack/Linear + git history + Chrome) and **enjoyment** (the author explicitly claims *"it's joyful"*). Five canonical uses detailed: (1) **specs/plans/exploration** in a comparative grid, (2) **PR review** with inline annotated diff, (3) **design & prototypes** with animation sliders, (4) **reports/research/learning** (the author had a prompt-caching explainer generated from git history), (5) **custom throwaway editors** (drag-and-drop of Linear tickets, feature-flag editors, side-by-side prompt-tuner) that produce a re-injectable "copy as markdown/diff/JSON" export. Explicit anti-pattern: *"I'm a little bit afraid that people will read this article and turn it into a /html skill"* — the author **rejects premature skill-ification**, recommending prompting from scratch ("make a HTML file"). Pragmatic FAQ: token cost absorbed by **Opus 4.7**'s 1MM context, 2-4× longer generation, noisy HTML diffs (a real downside), style kept in check via a reference HTML design system.

## Titre Article

Using Claude Code: The Unreasonable Effectiveness of HTML

## Date

2026-05-10

## URL

https://x.com/i/status/2052809885763747935

## Keywords

HTML, Markdown, output format, Claude Code, agentic artifacts, Thariq Shihipar, Anthropic, Opus 4.7, 1MM context, information density, SVG, CSS, canvas, responsive layout, two-way interactivity, copy as JSON, copy as prompt, contextual ingestion, MCP, Slack, Linear, git history, Chrome, specs, plans, exploration, code review, PR review, annotated diff, design system, prototypes, animations, sliders, reports, research, explainer, throwaway editors, throwaway editor, feature flags, prompt tuning, joyful, anti-skill-ification, prompt from scratch, S3, sharing, token efficiency, noisy diff, design drift, frontend design plugin, taste, design memory, html-effectiveness, gallery, playgrounds, two-way interaction, judgment, comprehension debt, in-the-loop, design system file, illustrations vs ASCII, color via unicode anti-pattern, mobile responsive, tabs, illustrations, custom UI throwaway

## Authors

Thariq Shihipar (Engineer & serial entrepreneur, équipe Claude Code chez Anthropic — site : thariqs.github.io/html-effectiveness ; X : @trq212)

## Ton

**Profile**: Personal manifesto article (~1500 words) published on X / a personal blog, unabashedly first-person, practitioner-evangelist register. Target audience: advanced Claude Code users, designers, PMs, engineers who produce specs/plans/reports with an agent. Technical level: intermediate — no code, plenty of lived practice (concrete examples: his article on prompt caching, his day-to-day PRs, his onboarding brainstorms).

**Style**: **Pedagogical-demonstrative**. Opens with a concession ("Markdown has become the dominant file format used by agents… *But* as agents have become more and more powerful, I have felt that markdown has become a restricting format"). Then a classic rhetorical structure: *why → how → use cases → FAQ → wrap*. Each section backed by a **lived example** ("when writing this article, I asked Claude Code to read through my code folder…") rather than an abstract demonstration. Pre-empts objections ("Isn't it less token efficient?", "How do I view the HTML file?", "What about version control?") in the form of an honest FAQ (conceding the noisy HTML diff as *"one of the biggest downsides"*).

Epistemic position: **Anthropic Claude Code insider** formalizing a practice already adopted by his team (*"I increasingly see this being used by others on the Claude Code team"*). Emotional tone: enthusiastic but non-proselytizing. Signal phrases planted for virality: *"the unreasonable effectiveness of HTML"* (a nod to Wigner-Karpathy), *"it's joyful"*, *"the chance of someone actually reading your spec is much much higher if it's in HTML"*, *"I'm a little bit afraid that people will read this article and turn it into a /html skill"*. Notable meta-move: **explicit anti-skill-ification** — the author, despite belonging to the ecosystem pushing Claude Skills, refuses to canonize his practice into a skill. *"You don't need to do much to get Claude to do this. You can just ask it to 'make a HTML file' or 'make a HTML artifact'."*

Overall tone: **doctrinal yet humble**. Emotional conclusion ("I feel much more in the loop than ever before when using HTML. I hope you do too.") — brings the technical question back to the lived problem of **loss of cognitive control** in the face of agents producing plans too long to read (strongly resonating with Osmani's *cognitive surrender* / *comprehension debt*).

## Pense-betes

- **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).
- **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`.
- **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.
- **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.
- **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"*.
- **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).
- **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).
- **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."*
- **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.
- **Honest FAQ** (explicit concessions):
- **Token efficiency**: HTML uses more tokens but Opus 4.7's 1MM context absorbs it.
- **Generation**: 2-4× slower than Markdown — *"but I've found the results are worth it"*.
- **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.
- **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.
- **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.
- **Connections with the tech-watch corpus**:
- 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**.
- 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".
- 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.
- Confirmation of **Opus 4.7 + 1MM context** as an **architectural shift** that makes more verbose formats (HTML, design systems, extended brainstorms) economically sustainable.
- 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.
- **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.
- **Resulting workflow for firm practice**:
- Any spec, plan, or report > 100 lines → shift to HTML.
- Critical PRs → attach an HTML explainer.
- File onboarding, design explorations, reorderings → HTML throwaway editor with structured export.
- Keep Markdown for: commit messages, short fiche notes, .md config files (CLAUDE.md, agents.md, etc.).

## RésuméDe400mots

**Thariq Shihipar** (Claude Code team at Anthropic) publishes a manifesto-style article announcing a change in the default output format for agents: replacing **Markdown with HTML**. The diagnosis: Markdown reigned as the dominant format between human and agent (simple, portable, editable) but has become **restrictive** as agents produce longer and richer artifacts. Beyond ~100 lines, no one reads a Markdown file anymore — and since the author no longer manually edits his specs (he prompts Claude to edit them), Markdown's historical advantage disappears.

**Six reasons** justify the shift to HTML: (1) **information density** — tables, CSS, SVG, scripts, canvas, images; *"almost no set of information that Claude can read that you cannot represent with HTML"*; (2) **visual clarity** — tabs, illustrations, mobile responsive; (3) **sharing** — S3 upload → direct link, read-through rate multiplied; (4) **two-way interactivity** — sliders, knobs, "copy as prompt" buttons to loop back; (5) **contextual ingestion** native to Claude Code (codebase + MCP + git + Chrome); (6) **enjoyment** — *"it's joyful"*.

The author formalizes **five canonical uses**: (a) **specs/plans/exploration** in a comparative grid; (b) **PR review** with inline annotated diff and severity-based code-coloring; (c) **design & prototypes** with animation sliders; (d) **reports/research** (his prompt-caching explainer generated from git history); (e) **custom throwaway editors** — single-file HTML purpose-built for one piece of data (drag-and-drop of Linear tickets, feature-flag editor, side-by-side prompt-tuner) always ending with a re-injectable "copy as JSON/markdown/prompt" export.

Explicit anti-pattern: **the author rejects skill-ification** of his practice. *"I'm a little bit afraid that people will read this article and turn it into a /html skill. You don't need to do much — just ask it to 'make a HTML file'."* The practice is too context-dependent to be fixed in place.

Honest FAQ: HTML costs more tokens but **Opus 4.7's 1MM context** absorbs it; generation is 2-4× slower; **noisy HTML diffs** = an unresolved downside, acknowledged as such.

Final meta-thesis: HTML as an **antidote to cognitive surrender**. *"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 feel more in the loop than ever before when using HTML."* Regained readability allows staying decision-capable in the face of increasingly powerful agents.

The article connects directly with **Meng To's `design.md`** (HTML = "finished dish") and with **Osmani's comprehension debt**, to which it offers an operational response.

## GrapheDeConnaissance

- Thariq Shihipar —travaille_chez→ Anthropic (ORGANISATION, 0.97)
- Thariq Shihipar —fait_partie_de→ équipe Claude Code (ORGANISATION, 0.97)
- Thariq Shihipar —recommande→ HTML (format de sortie agent) (METHODOLOGIE, 0.98)
- HTML (format de sortie agent) —remplace→ Markdown pour artefacts agentiques longs (METHODOLOGIE, 0.95)
- Thariq Shihipar —affirme_que→ Markdown devient restrictif au-delà de ~100 lignes (AFFIRMATION, 0.92)
- HTML (format de sortie agent) —permet→ densité d'information (tables, CSS, SVG, scripts, canvas) (CONCEPT, 0.97)
- HTML (format de sortie agent) —permet→ interactivité bidirectionnelle (sliders, copy as prompt) (CONCEPT, 0.96)
- HTML (format de sortie agent) —améliore→ taux de lecture des specs et rapports (CONCEPT, 0.93)
- HTML (format de sortie agent) —résout→ Cognitive surrender (réponse) (CONCEPT, 0.9)
- Claude Code —utilise→ codebase + MCP + git history + Chrome (CONCEPT, 0.95)
- Opus 4.7 —utilise→ 1MM context window (CONCEPT, 0.97)
- 1MM context Opus 4.7 —permet→ HTML (format de sortie agent) (CONCEPT, 0.93)
- Throwaway HTML editor —utilise→ export copy as JSON / markdown / prompt (CONCEPT, 0.96)
- Thariq Shihipar —s_oppose_à→ Anti-skill-ification (CONCEPT, 0.95)
- Thariq Shihipar —affirme_que→ les diffs HTML sont bruyants et difficiles à reviewer (downside assumé) (AFFIRMATION, 0.92)
- HTML (format de sortie agent) —mesure→ 2-4× plus lente que Markdown (MESURE, 0.88)
- Frontend design plugin —permet→ HTML (format de sortie agent) (CONCEPT, 0.85)
- Design system HTML de référence —permet→ cohérence stylistique cross-fichiers (CONCEPT, 0.88)
- Unreasonable effectiveness —converge_avec→ design.md de Meng To (HTML = finished dish) (CONCEPT, 0.93)
- Unreasonable effectiveness —résout→ comprehension debt d'Osmani (réponse opérationnelle) (CONCEPT, 0.9)
- Claude Code —permet→ HTML (format de sortie agent) (METHODOLOGIE, 0.96)
- Anthropic —emploie→ Thariq Shihipar (PERSONNE, 0.97)

---
Canonical: https://www.thekb.eu/en/fiches/shihipar-claude-code-html-unreasonable-effectiveness-markdown-2026-05-10/