06-reference

thariq unreasonable effectiveness html

Thu May 07 2026 20:00:00 GMT-0400 (Eastern Daylight Time) ·reference ·source: X (Thariq @trq212 long-form article) ·by Thariq Shihipar
claude-codehtml-vs-markdownagent-output-formatanthropicthariqartifactsfounder-in-the-loophyperframes-validation

“Using Claude Code: The Unreasonable Effectiveness of HTML” — Thariq Shihipar

Why this is in the vault

Founder shared 2026-05-08 ~15:50 ET as a “quick article side quest.” Thariq is on the Claude Code team at Anthropic; his prior pieces (context-rot, “How We Use Skills,” “Seeing like an Agent”) are already vault-canonical and one is cited in CLAUDE.md hard rule #4. This piece argues a substantial format shift in how he uses Claude Code — Markdown → HTML for artifacts — and the argument has direct, asymmetric implications for RDCO’s stack: skill ecosystem, vault structure, build-subagent return shapes, design-critic verdicts, deep-research briefs.

The core argument

Thariq has shifted from Markdown to HTML as his preferred output format for artifacts Claude Code generates for him to read. Not for files Claude reads (skills, references) — for deliverables Claude produces FOR the human in the loop.

His thesis: the more powerful the agent, the more restricting Markdown becomes as the human-facing output. “>100-line markdown files don’t get read.” HTML gets read.

Five reasons HTML beats Markdown for agent artifacts

  1. Information density — HTML carries tables, CSS, SVG, embedded code, interactions, spatial layout, images. Markdown carries headers + lists + code blocks + ASCII diagrams. The expressiveness gap is large.
  2. Visual clarity & ease of reading — HTML can be navigated with tabs, illustrations, links. Mobile-responsive. Markdown collapses to a wall of text past ~100 lines.
  3. Ease of sharing — Upload to S3, share a link. Colleagues open it in a browser. Markdown attachments are friction.
  4. Two-way interaction — HTML can include sliders/knobs/forms with a “copy as prompt” button that feeds adjustments back to Claude Code. Markdown can’t.
  5. Data ingestion — Claude Code can pull from MCPs, browser, git history, codebase into the HTML output. Native to its strengths.

Plus: it’s joyful. Thariq names this explicitly. Markdown is utilitarian; HTML feels invested.

Use cases with example prompts (lifted)

Specs, planning & exploration

“I’m not sure what direction to take the onboarding screen. 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. Label each with the tradeoff it’s making.”

Code review & understanding

“Help me review this PR by creating an HTML artifact that describes it. I’m not very familiar with the streaming/backpressure logic so focus on that. Render the actual diff with inline margin annotations, color-code findings by severity…”

Design & prototypes

“I want to prototype a new checkout button, when clicked it does a play animation and then turns purple quickly. Create a HTML file with several sliders and options for me to try different options on this animation, give me a copy button to copy the parameters that worked well.”

Reports, research & learning

“I don’t understand how our rate limiter actually works. Read the relevant code and produce a single HTML explainer page: a diagram of the token-bucket flow, the 3-4 key code snippets annotated, and a ‘gotchas’ section at the bottom. Optimize it for someone reading it once.”

Custom editing interfaces (throwaway, single-use)

“I need to reprioritize these 30 Linear tickets. Make me an HTML file with each ticket as a draggable card across Now / Next / Later / Cut columns. Pre-sort them by your best guess. Add a ‘copy as markdown’ button that exports the final ordering with a one-line rationale per bucket.”

The pattern: throwaway HTML purpose-built for one piece of data, ALWAYS ending with an export button (copy-as-JSON, copy-as-prompt, copy-as-markdown) that turns the human’s UI interaction back into something pasteable.

Honest tradeoffs (Thariq names them)

Closing thesis (the load-bearing line)

“The real reason I use HTML is that I feel much more in the loop with Claude. 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.”

The point isn’t HTML. The point is keeping the human in the verification loop. HTML beats Markdown for that specific job because the human actually reads it.

Mapping against Ray Data Co

Strong on multiple axes — but DON’T convert everything. The right move is artifact-class selectivity.

Where this argument applies STRONGLY at RDCO

  1. Build-subagent return shapes. The SC v3 fresh-build subagent today returned a 30-line structured-text report. That’s exactly the use case Thariq names — a deliverable-for-founder that would land harder as a single HTML report with embedded preview screenshots, design-token swatches, GEO-compliance checklist with green/red dots, contrast-measurement tables, per-page critic verdict cards, and a “copy as decision-needed prompt” button. Worth a /improve task: build-subagent return shape becomes HTML artifact.
  2. Decision documents surfaced to founder. Today the SC variant choice (A/B/C) was a Markdown bullet list. As HTML side-by-side comparisons with embedded mockups + interactive palette swatches + a “lock my pick” button that exports to the build-dispatch prompt, the decision lands faster and chef-mode reasoning is more visible.
  3. /deep-research briefs. The /deep-research skill outputs Markdown briefs at 06-reference/research/. Per Thariq: the founder reads ~0% of these in depth. As HTML explainers with embedded SVG diagrams, citation-network visualization, and interactive controls, they would actually be read.
  4. /design-critic verdicts. Currently structured Markdown text. As HTML with embedded screenshots, per-tell scoring cards, contrast measurements rendered as bars, and a single PASS/ITERATE/SCRAP verdict at the top, the critic loop tightens.
  5. Discovery + voice-profile + positioning docs. Today’s session produced three Markdown docs (~1500 lines combined). Founder confirmed he didn’t deep-read them — answered phase-by-phase via iMessage. That’s the failure mode Thariq names. If those had been HTML with collapsible phase sections, embedded mockups, voice-sample carousels, decision toggles, the answer-rate would have been higher.

Where this argument does NOT apply at RDCO

  1. SKILL.md files. Claude reads these. Markdown structure is right. Don’t migrate.
  2. Vault knowledge base (06-reference/, 02-sops/, etc.). QMD indexing + graph extraction + wikilink resolution all assume Markdown. Don’t migrate.
  3. iMessage / Discord channel responses. Text-only constraint. Markdown-lite is the format.
  4. Sanity Check newsletter content itself. Issues go to email subscribers; HTML email rendering is a different beast than browser HTML. Stay Markdown source, render to HTML email separately.
  5. Memory files (~/.claude/projects/-Users-ray/memory/). Plain text/Markdown is the right format for Claude to recall facts.

Specific RDCO action candidates (for /improve queue)

What the article validates

What the article complicates

Notable quotes (≤15 words each, in quotation marks)

Open follow-ups

Source caveat

Article body retrieved via xmcp getPostsById with tweet.fields: ["article", ...] + expansions: ["article.cover_media", "article.media_entities", ...] — the article.plain_text field returned the full ~9.5K-word body. Initial WebFetch attempt on the X article URL hit HTTP 402; WebSearch found no public mirror. The xmcp path is the canonical fetch route for X long-form articles going forward.