Why Plain HTML Wins for Claude Code and AI Agents

The Observation That Got Everyone Talking

A post by @trq212 on Twitter sparked a lively Hacker News thread in early May 2026 with a simple but provocative claim: when using Claude Code for real work, plain HTML produces unreasonably good results. Not React. Not Next.js. Not Svelte. Just HTML, maybe a sprinkle of vanilla JavaScript, and some CSS.

This resonates with a growing number of practitioners who have noticed the same pattern. AI coding agents, and Claude in particular, seem to have a qualitatively different relationship with HTML than they do with modern JavaScript frameworks. The outputs are cleaner. The errors are fewer. The iterations are faster. And the final results often work on the first or second try.

This article goes deep on why that happens, what it means for your day-to-day work with AI agents, and how to structure your prompts and projects to take full advantage of it.

Why AI Agents Struggle With Modern JS Frameworks

To understand why HTML works so well, you first need to understand where modern frameworks create friction for AI agents.

Frameworks like React, Next.js, and Vue introduce several layers of abstraction that compound in ways that confuse even capable models.

State management complexity. React’s mental model of unidirectional data flow, hooks, effects, and memoisation requires the model to reason about time and mutation simultaneously. A single misplaced useEffect dependency array produces bugs that are notoriously hard to diagnose even for experienced human engineers.

Toolchain assumptions. Framework code rarely runs without a bundler, a package manager, environment variables, and often a backend runtime. Claude Code can write perfect JSX and still produce something that does not run because node_modules is missing or the Vite config needs a flag.

Version fragmentation. React 18 vs 19, Next.js 13 App Router vs Pages Router, Tailwind v3 vs v4. The training data contains all of these simultaneously. The model hedges or makes assumptions that may not match your setup.

Error surfaces. When something goes wrong in a framework project, the error could originate in transpilation, hydration, routing, a server component boundary, or a CSS module scope. More places for things to go wrong means more iteration cycles.

Why HTML Is Different

HTML is the opposite of all of that. It has a single runtime that has been stable for decades: the browser. There is no build step. There is no hydration. There is no version fragmentation for core elements. You write a file, open it, and it works.

For an AI agent, this means:

• The model’s confidence about what a given tag or attribute does is extremely high, because the behaviour has not changed since the training data was collected.
• The feedback loop is immediate. Claude Code can generate a file, the user opens it, something is wrong, the user describes the problem, and the next iteration fixes it.
• Errors are visible and semantically meaningful. A broken layout looks broken. A missing <form> action is obvious. There is no cryptic stack trace pointing into a minified bundle.

A Side-by-Side Comparison

Here is a practical comparison of asking Claude Code to build the same feature in two ways.

Task: Build a simple customer feedback form with a star rating widget and a text input.

The productivity gap is not subtle. For prototyping, internal tools, quick demos, or anything that does not need to scale to a production SaaS app, the HTML path is faster by a large margin.

Concrete Prompt Patterns That Work

Here are prompt structures that consistently get excellent results from Claude Code when using HTML-first workflows.

Pattern 1: The Self-Contained Single File

Create a single HTML file that does the following:
- Shows a sortable table of sales data
- Allows filtering by region using a dropdown
- Uses no external libraries. Inline all CSS and JS.

The file should open directly in a browser with no build step.

The phrase “single HTML file” and “no build step” are load-bearing. They constrain the solution space in a way that plays to the model’s strengths.

Pattern 2: Progressively Enhanced HTML

<!-- Start with this structure and add interactivity -->
<form id="feedback-form">
  <label for="rating">Rating</label>
  <select id="rating" name="rating">
    <option value="1">1 star</option>
    <option value="2">2 stars</option>
    <option value="3">3 stars</option>
  </select>
  <textarea name="comment" placeholder="Your comment"></textarea>
  <button type="submit">Submit</button>
</form>

Giving Claude Code a structural scaffold to enhance produces far fewer hallucinated APIs than asking it to create from scratch. The model fills in JavaScript around markup it can already see, rather than inventing component hierarchies.

Pattern 3: The Debug Loop Instruction

If the result does not work when opened directly in Chrome, 
diagnose using browser console errors and revise. 
Do not add a build step to fix the problem.

This instruction prevents Claude Code from defaulting to “add a bundler” as a solution to its own mistakes. It keeps the complexity flat.

When HTML-First Is the Wrong Choice

Being honest about tradeoffs matters. HTML-first workflows are not always appropriate.

Large application state. If you are building something with deeply nested, shared, reactive state across many views, a proper state management solution is worth the overhead. Vanilla JS state in a large single file becomes spaghetti.

Team consistency. If your team already uses React and has established patterns, introducing ad-hoc HTML files creates inconsistency that creates maintenance cost.

Type safety requirements. TypeScript in a React or Svelte project gives you refactoring safety that matters in production codebases. HTML files have none of that.

Reusable components. If you need the same UI component in 30 places, a component model is genuinely valuable. Copy-pasting HTML is not.

The sweet spot for HTML-first AI agent work is: prototypes, internal tools, reports, dashboards, one-off automations, and anything where the primary consumer is you or a small team.

Connecting This to MCP and Agentic Workflows

This pattern connects naturally to a broader movement in agentic tooling. The devcontainer-mcp project on GitHub explores sandboxed, reproducible environments for agentic coding workflows using the Model Context Protocol.

The insight there is adjacent: the more deterministic and constrained the environment, the more reliably an AI agent can operate within it. A devcontainer with a locked set of dependencies is to Node.js what plain HTML is to browser runtimes. Reduce the variables, reduce the failure modes.

For teams building agentic pipelines, combining MCP-managed sandboxes with HTML-first output targets creates a workflow where the agent operates in a known-good environment and produces artefacts that require zero runtime setup to evaluate. The human-in-the-loop can review a generated HTML report by simply opening a file. No Docker container, no npm install, no environment variable configuration.

Practical Takeaways

1. Default to HTML for internal tools and prototypes. Unless you have a specific reason to use a framework, start with a single HTML file and add complexity only when you hit a genuine limitation.

2. Phrase your prompts to close off the framework escape hatch. Explicitly say “no build tools,” “no npm,” “inline everything.” Claude Code will respect these constraints.

3. Use HTML as a scaffolding language first. Write the structure, have the agent fill in behaviour. This produces better output than asking for behaviour and structure simultaneously.

4. Pair with reproducible environments for larger agents. If your agent is doing more than generating a single file, tools like devcontainer-mcp give you the same determinism benefits at the environment level.

5. Evaluate outputs by running them. The best thing about HTML outputs is that you can immediately judge correctness. Build the habit of opening every generated file in a browser before feeding feedback back to the agent.

The “unreasonable effectiveness” framing captures something real. It is not that HTML is magic. It is that the constraints of plain web technology align almost perfectly with where AI coding agents are currently strong: broad knowledge of stable specifications, good at generating complete self-contained artefacts, and most reliable when the feedback loop is short and unambiguous. That alignment is worth exploiting deliberately.