HTML as the New Markdown

Sources#

• A Field Guide to Fable: Finding Your Unknowns
• Codex from 0 to 10M Users: Building ChatGPT Work - Akshay Nathan, OpenAI
• How I AI: Thariq Shihipar on Replacing Markdown with HTML for AI-Powered Development
• The new rules of context engineering for Claude 5 models

Summary#

Thariq Shihipar's thesis, delivered to Claire Vo at Code with Claude (May 2026): "HTML is the new markdown." Markdown has been the lingua franca for human–LLM interaction — simple, structured, readable by both sides. But as models get more capable and projects more complex, thousand-line markdown plans overwhelm the human. We glaze over, stop reading, stop engaging, and collaboration quality collapses. The fix is a richer communication medium: HTML artifacts that are visual, scrollable, and interactive, pulling the human back in from passive reviewer to active collaborator.

The load-bearing observation: the model isn't the limiter — human attention is.

"It's not that the models struggle with Markdown — they're brilliant at it — but that HTML makes it easier for us, the humans in the loop, to visualize, interact with, and stay connected to the work being done."

The failure mode it fixes#

Thariq's own confession names the problem precisely: faced with a plan thousands of lines long, "he'd just ask Claude to edit the plan instead of reading it himself." A plan the human no longer reads is a plan the human no longer steers — the alignment that planning exists to produce evaporates. The goal becomes "create a plan you actually want to read."

This is the human-attention analog of the model's Context Window Smart Zone: just as a model degrades past ~100K tokens regardless of advertised window, a human reviewer degrades past some volume of undifferentiated markdown regardless of how complete it is. HTML raises the human's effective smart zone by spending tokens on legibility (mockups, structure, color, interaction) rather than raw text.

What HTML buys#

Asked to "brainstorm some ideas in HTML file," Claude returns not a list but a visual, scrollable page — eight demo ideas, each with a mockup, description, and risk assessment. The full-plan prompt:

create a HTML file as a plan that helps me visualize what the implementation plan is.
Include excerpts, mockups, code, whatever is needed to give me like maximum context

yields a single-file website: scripted intro, file-structure diagrams, code snippets, a visual mood board. A document you can read, explore, and share with a teammate — who is far more likely to engage with it than with a giant markdown file. The artifact bridges not just human↔AI but engineering↔the rest of the company.

The prompting move: constraint plus latitude#

Two details from the plan prompt are deliberate:

• He misspelled "excerpts" and it didn't matter — models are robust to surface noise.
• "whatever is needed to give me like maximum context" gives the model an out. The philosophy: provide enough constraint to get what you want, but leave room for the model to surprise you. As Thariq puts it, "I always needed to be like, 'Hey, Claude, like I trust you here.'"

This is a small, repeatable instance of The Bitter Lesson applied at the prompt level — under-specify the structure and let scaled capability fill it — and it pairs with the Compute Allocator role: the human sets direction and trusts the model with the rest.

The harness tension this resolves#

At first glance this contradicts the wiki's running Harness Shrinkage as Models Improve thesis (Cat Wu / Boris Cherny: scaffolding shrinks each release) and Interaction Models (Thinking Machines Lab: the harness dissolves into the model). Thariq says the opposite — only ~1% of his tokens ship; 99% go to scaffolding.

The resolution: these are two different harnesses.

• The shrinking harness is model-facing — prompts, instructions, verification that exist to make the model behave. As models improve, this contracts.
• The growing harness is human-facing — artifacts (HTML plans, micro-apps, design systems) that exist to keep the human aligned, engaged, and able to decide. As models improve, this expands, because the binding constraint shifts from "can the model do it" to "can the human stay in the loop and allocate compute well."

The Bitter Lesson dissolves model-facing structure; it does not dissolve the human-facing structure whose entire purpose is human comprehension. That's the side of the line HTML artifacts sit on. See Compute Allocator for the role this implies.

What the artifacts are for (July 2026 update)#

The original interview establishes the medium; Thariq's field guide, two months later, states the job the medium does. "I've previously written about using HTML with Claude — in almost all of these cases, a HTML artifact is the best way to visualize and represent it." The it is an unknown: a blindspot pass, a set of wildly different design directions to react to, an implementation plan ordered by what you're most likely to change, a post-merge explainer with a quiz at the bottom. HTML is the medium; surfacing what you never wrote down is the purpose.

One technique sharpens the constraint-plus-latitude move below into a rule for plan structure: order the plan by likelihood of change, not by execution order. "Lead with the decisions I'm most likely to tweak: data model changes, new type interfaces, and anything user-facing. Bury the mechanical refactoring at the bottom, I trust you on that part." The human's scarce attention lands on the decisions that are cheap now and expensive later.

The thesis completes its arc in Thariq's context-engineering post (July 2026): "simple specs → rich references" is now one of the official then→now rules for Claude 5 models. Markdown plan files — the very artifact plan mode "heavily relied on" — are named the then; the now is HTML artifacts, plus the wider reference family: a detailed test suite as the spec, a function in another codebase to port, and rubrics handed to spun-up verifier agents. What began as one engineer's workflow preference is restated as vendor context-engineering guidance, with the general rule "an HTML mockup of a design will generally produce better results than a description of the design or a screenshot."

The independent arrival: OpenAI Sites (July 2026)#

The thesis was, until now, a single practitioner's — one Anthropic engineer, refined by the same engineer twice. OpenAI's Sites (part of the July 2026 ChatGPT Work launch) is the first non-Anthropic arrival at the same conclusion, and Akshay Nathan states the premise in almost Thariq's words, unprompted, while looking at a sprawling research dashboard on a podcast (Codex from 0 to 10M Users: Building ChatGPT Work - Akshay Nathan, OpenAI, practitioner-opinion):

"I think Markdown just isn't that optimal for people to read, right? Might as well just write HTML website."

The corroboration is stronger than the quote, because it comes with a usage claim rather than a workflow preference. Nathan reports that inside OpenAI, the canonical artifact for recurring team work is migrating off decks and spreadsheets onto Sites: a corporate-finance team's month-to-month reports "historically were in slide decks and in spreadsheets, and now they're just in Sites… Sites is the mechanism that they collaborate across the team." His reason is the flexibility ceiling, not the format: "PowerPoint and Excel are infinitely flexible, but at some point you reach the boundary — either as a human you may not know how to use some feature, or the product itself doesn't support it. But with a site you can do anything." OpenAI's own model-configuration slider "was developed almost fully in a Site." (vendor-claim-tier anecdotes inside a practitioner-opinion source — no measurement.)

Two things this adds beyond confirmation:

• The medium generalizes past plans. Thariq's cases are all engineering artifacts (plans, brainstorms, blindspot passes, explainers). Nathan's are knowledge-work artifacts — finance reports, research dashboards, prototypes for design review — reached without reference to Thariq's work. The claim survives leaving the engineering context that produced it.
• The bloat ceiling is corroborated in the same breath. swyx on his own generated research site: "there's also a huge sprawl. Like look at how long this thing is. There's so many numbers. It is pretty overwhelming, so then I have to start pruning it from there." Nathan agrees the artifacts are "long and verbose, could be broken up… I'm sure that there's still something to do there." That is Does the Human-Facing Harness (HTML Artifacts) Hit Its Own Bloat Ceiling?'s conclusion observed live at a second vendor: HTML relocates the human-attention ceiling, it does not remove it.

The three workflows#

1. Brainstorming and planning in interactive HTML (this page) — visual plans you want to read.
2. Disposable Micro-Apps — throwaway custom UIs to edit parts of the plan, answering the "HTML isn't editable" objection.
3. Living Design System — a design_system.html as a portable, human- and machine-readable source of truth.

All three center the human; none is about automating the developer away.

Connections#

• Outsource Your Thinking, Not Your Understanding — HTML artifacts keep the human understanding what the agent did
• Design by Selection — the independent arrival, from the design side: Nate Parrott hit the same reframe ("HTML is also a rich, interactive visual medium — anything you can make in a slide deck, a video file, or a PDF, you can make in a web page") while looking for a way to get usable design output, and built Claude Design on it. Two Anthropic practitioners, plans vs. visuals, neither citing the other
• Thariq Shihipar — author of the thesis
• Claire Vo — interviewer; runs a parallel component-visualization practice
• Claude Code — the product these HTML-artifact workflows run in, demonstrated from inside the Claude Code team
• Compute Allocator — the role this medium serves: human as decider, 99% of tokens spent on scaffolding like this
• Disposable Micro-Apps — the editability answer to HTML plans
• Living Design System — the same HTML-first move applied to design
• Harness Shrinkage as Models Improve — the model-facing harness shrinks while this human-facing harness grows; the key contrast
• Interaction Models — a sibling answer to "better human–AI collaboration": dissolve the real-time interface into the model, where this enriches the asynchronous artifact; opposite mechanisms, same goal of keeping humans in the loop
• The Bitter Lesson — "leave room for the model to surprise you" is the prompt-level form; the caveat is that human-facing legibility doesn't migrate inward
• Context Window Smart Zone — HTML raises the human's effective smart zone the way clearing context restores the model's
• Design Concept Grilling — brainstorm → let Claude interview you → plan is the grilling shape; the HTML plan is the richer destination artifact
• AI Native Product Cadence — Cat Wu makes PRDs lighter; Thariq makes them richer — different bets on what keeps the human aligned at speed
• Software 3.0 — HTML-first plans and Disposable Micro-Apps are Software-3.0-native: per-task UIs spun up from a prompt, MenuGen-style "apps that barely exist"
• Prototype Over PRD — the third bet on keeping humans aligned at speed: Thariq makes the plan richer, Cat Wu makes it lighter, Dan Carey replaces it with a prototype
• Shared Harness, Differentiated Surfaces — where OpenAI's Sites sits: a shared-harness primitive whose legibility is dosed per surface, making the human-facing harness the thing that varies by audience
• Unknowns as the Agentic Bottleneck — what the HTML artifacts are for: every brainstorm, interview, plan and explainer is an instrument for surfacing unknowns before they get expensive

Open Questions#

• Does this generalize past one expert practitioner, or does it require Thariq-level fluency with Claude to be worth the overhead?

Resolved Questions#

• Does the human-facing harness keep growing without bound, or does it hit its own bloat ceiling (an HTML plan too elaborate to read, like the markdown it replaced)? Answered: Does the Human-Facing Harness (HTML Artifacts) Hit Its Own Bloat Ceiling? — yes; HTML raises and reshapes the human-attention ceiling but can't remove it, and the bloat relocates from document-length to artifact-sprawl/rubber-stamping.
• HTML is heavier to diff and version than markdown — what happens to plan history and review when artifacts are single-file websites? Answered: The HTML Artifact Lifecycle: Where Plan History Lives, and When Disposable Becomes Durable — the artifact is a compiled view, not a record: version the content layer (the copy-back round-trip and the extract-from-code pattern already do this), regenerate the presentation on demand, and reattach review to decisions rather than diffs (the plan-ordered-by-likelihood-of-change technique puts the reviewable delta at the top). Presentation history is deliberately discarded — regenerable at abundance prices, it isn't worth versioning — and a presentation choice that becomes load-bearing has by definition graduated to durable tooling with real versioning obligations. Residual (tracked above): no source yet documents team-scale multi-author HTML-plan review.

Derived#

• Does the Human-Facing Harness (HTML Artifacts) Hit Its Own Bloat Ceiling? — whether this human-facing harness hits its own bloat ceiling (it does; the ceiling moves and reshapes but doesn't vanish)
• The HTML Artifact Lifecycle: Where Plan History Lives, and When Disposable Becomes Durable — the versioning answer: HTML plans as compiled views whose content layer carries the history and whose review binds to decisions, not diffs

Sources#

• How I AI: Thariq Shihipar on Replacing Markdown with HTML for AI-Powered Development
• A Field Guide to Fable: Finding Your Unknowns — Thariq Shihipar, 2026-07-04 (practitioner-opinion): HTML as the default medium for unknown-elicitation; plans ordered by likelihood of change
• The new rules of context engineering for Claude 5 models — Thariq Shihipar, 2026-07-25 (practitioner-opinion): "simple specs → rich references" as official guidance; HTML mockup > description or screenshot; test-suites-as-specs and rubrics for verifier agents
• Codex from 0 to 10M Users: Building ChatGPT Work - Akshay Nathan, OpenAI — Latent Space, 2026-07-28 (practitioner-opinion): the non-Anthropic arrival — OpenAI Sites, "Markdown just isn't that optimal for people to read," decks-and-spreadsheets → Sites for a corporate-finance team, and live corroboration of the sprawl ceiling