HTML or Markdown: The bet

Deep Dive: The Mechanics of Thariq Shihipar’s HTML Bet

We are already familiar with Thariq Shihipar’s provocative stance on replacing Markdown with HTML for AI-generated specs. But looking past the surface-level novelty, the underlying mechanics reveal a fundamental shift in how we need to build, steer, and observe autonomous systems. Here is a deeper breakdown of the engineering philosophy driving the HTML bet.

[embed]

1. The Compute Allocator Framework

When you let an advanced model run for hours on a complex migration or refactor, you aren’t just letting it think — you are spending a hard budget. Modern AI-first developers are effectively “compute allocators.” In this paradigm, compute is a finite resource that necessitates high-fidelity specifications to prevent runaway costs. HTML acts as a richer, denser contract between the engineer and the agent. By validating a highly visual, structured plan upfront, you ensure the subsequent compute cycles are spent executing precisely what was intended.

2. High-Trust Prompting and Interactive Validation

The shift to HTML changes the brainstorming phase from generating flat lists of requirements to defining rich, interactive states. By leaning into high-trust prompting — giving the model a goal and the freedom to define the interface (“whatever is needed to give maximum context”) — developers allow the AI to build its own visual validation tools. Instead of reading a 1,000-line Markdown table to check logic, you interact with a rendered mockup or mini-dashboard that instantly exposes whether the model understands the architecture.

3. Throwaway UIs for Steering Agentic Loops

Perhaps the most powerful mechanic of the HTML bet is the use of “throwaway software.” If a specific set of rules, data models, or rendering logic within an agent’s plan is flawed, editing raw Markdown creates friction. Instead, generating a custom, editable HTML micro-UI to adjust those parameters injects control back into the loop. You manipulate a temporary interface to correct the data structures, and then feed that aligned state back into the agent’s context. It is micro-software built exclusively to steer macro-software.

4. Just-in-Time Documentation and Living Artifacts

This visual-first approach forces a reevaluation of how we maintain system architecture. By maintaining design systems and component libraries as HTML artifacts rather than static Markdown files, teams create “just-in-time” documentation. These living artifacts are natively parsable by the LLM while retaining perfect visual fidelity for the human in the loop. The design system becomes a portable, executable module that can be injected into any new repository’s context.

What to Consider Before Leaning on HTML

While Shihipar’s approach opens up fascinating new workflows, it is not a universal silver bullet. Before completely abandoning Markdown for your AI agent pipelines, here is a deeper analysis of the trade-offs.

1. Unless HTML influences model capability, it is overkill.

The primary allure of HTML in this context is human engagement — it makes it easier for the engineer to observe and interact with the plan. However, from a purely functional standpoint, if the HTML structure does not directly improve the AI’s ability to reason, execute, or understand the problem, it is unnecessary overhead. Wrapping basic instructions or straightforward logic in nested <div> tags just to make them look nice burns through the context window without actually upgrading the model's operational output. If the task doesn't strictly require a throwaway UI or visual validation, HTML is a waste of tokens.

2. Markdown’s flatness minimizes noise and model confusion.

Markdown is intentionally flat and simple, keeping the structural “weight” of the document incredibly light. HTML adds a heavy DOM tree. Distributing that weight — managing nested tags, CSS classes, styling rules, and interactive scripts — requires precision. There is a real danger of getting distracted by building a clever interface and losing sight of the core logic. Any oversight in the HTML structure, or a diversion into interface aesthetics, ultimately adds noise. When the agent ingests that HTML back into its context window later, that excess structural noise can dilute the core message and induce hallucinations. Markdown remains beautifully low-noise, keeping the AI focused strictly on the task.

3. For models, text is still king.

It is worth remembering that Markdown serves as the semantic skeleton of a web page without the presentation bloat. When your primary agenda is making instructions, constraints, or context solidly clear to the model (rather than the human reviewer), text-only Markdown is unmatched. It boasts an extremely high information-density-to-token ratio. By stripping away the presentation layer entirely, Markdown allows the LLM to allocate its entire attention mechanism to solving the core engineering logic, rather than parsing inline styles and formatting code.

My Verdict

• HTML for High-Touch Interactivity: HTML makes perfect sense when you need a sophisticated, visual interface for complex exchanges between the model and the user.
• Markdown for Core Developer Workflows: For the vast majority of developer use cases, Markdown remains the undisputed standard. Because platforms like GitHub, Jira, Slack, and Teams support it natively in descriptions and comments, it is a first-class consideration for any engineering lifecycle.
• An Intentional Foundation: In this view, adopting Markdown for AI specs was never a hasty afterthought or an incorrect choice — it is a highly intentional foundation that meets developers exactly where they already work.