A few days ago, Thariq Shihipar (an engineer on the Claude Code team at Anthropic) publicly articulated on a podcast what we at onext have been observing in client work for months: HTML is now the superior format for the artifacts that live, get edited and get consumed the most. What follows is the decision table we apply artifact by artifact in the AI Engine method — what migrates to HTML, what stays in Markdown, and why the decision matters more in some cases than in others.
Why Markdown becomes friction at scale
Markdown was popular for a decade for two reasons that mattered a great deal: it was human-readable without rendering and, at the same time, machine-processable. That dual compatibility gave it the edge over Word, Confluence, Notion and any closed format. In small teams with short specs, Markdown is still perfect: a fifty-line spec-feature-x.md file in the repo is exactly what the team needs.
The problem shows up at scale. When a Tech Lead receives a fifteen-hundred-line implementation plan in Markdown, what happens in practice is one of two behaviors: either they skim it by scrolling quickly, or they hand the whole thing to the agent to edit. Both are failures of the format. The first because the human stops governing the content. The second because the human drops out of the loop.
Thariq puts it this way: "I stopped reading thousand-line Markdown plans and started asking Claude to edit them directly, which made me less involved in the work. HTML changed that: by turning plans into visual, scrollable, interactive artifacts, Claude makes the output easier to read, critique and improve." The lesson isn't to read less. It's to make the work legible enough that you actually read it.
The four reasons HTML beats Markdown in the right cases
The argument, distilled from the original podcast and from what we see in client work, fits into four points:
Information density
HTML embeds images, mockups, horizontally scrollable tables, code blocks with real syntax highlighting, collapsible sections. Markdown can show tables, but it can't show a mockup next to the functional description. When the artifact needs that kind of context, Markdown forces you to separate what should go together.
Interactivity
HTML lets you navigate the artifact: a collapsible table of contents, anchors, collapsible sections, forms to edit specific parts. Markdown is flat. In a thousand-line plan, navigation matters.
Living documents
An HTML file can be updated, reloaded and always show the current version of the design system or the project state. Markdown is static by construction. The difference matters when the artifact lives six months or more.
Human + machine readable parity
This is the genuinely new part versus 2020. Five years ago, HTML was hard for a human to read raw, without rendering. Today a Claude or a Cursor parses HTML as easily as Markdown, and a human opens it in any browser with one click. The historical tradeoff no longer exists.
Those four points don't apply to every artifact equally. The operational question is: which ones do, and which ones don't?
The decision table · 14 Spec-Driven Development artifacts in onext's AI Engine method
The AI Engine program generates on the order of fifteen distinct artifacts across a full transformation cycle. The Markdown-or-HTML decision isn't made on taste — it's made against three questions: how large is the artifact at full size? Is it consumed once or lived with for months? Does it need visual representation to be understood?
With those three axes, this is the current onext method table as of June 2026:
| Artifact | Decision | Why |
|---|---|---|
| Project constitution | Markdown | Plain text, stable rules, versionable in the repo, simple to audit |
| Lean Canvas / JTBD / empathy maps | Visual quadrants, personas with photos, navigable flows | |
| User flows / behavior flows | Embedded SVG diagrams, interactive navigation | |
| Acceptance criteria (short list, <20 items) | Markdown | Short text, simple checklist, fits the PR description |
| Acceptance criteria + edge cases (large table) | Scrollable table, embedded code per case, better density | |
| Business rules | Decision matrices, flowcharts, complex conditionals | |
| Per-feature specs (<500 lines) | Markdown | Compact, navigable, fits the PR flow |
| Per-feature specs (>500 lines) | Scroll + density + collapsible sections (Thariq's case) | |
| Implementation plans (plans thousands of lines long) | The canonical case — Markdown becomes unmanageable beyond 800 lines | |
| Weekly status updates | "More likely to actually get read" — Thariq | |
| Living design system | The "killer app" case — beats Figma per Thariq, aligned with what we see | |
| ADRs (Architecture Decision Records) | Markdown | Short historical records, append-only, not edited after writing |
| Transformation progress dashboards | Interfaces, not documents — live figures, comparisons, drill-down | |
| Technical onboarding for new developers | Interactive, navigable, embeds mockups and runnable code |
Of 14 artifacts: 8 HTML · 5 Markdown · 1 depends on size
Of the fourteen artifacts in the method, eight migrate to HTML, five stay in Markdown, one depends on size. The distribution isn't ideological — it's operational: the larger the size and the longer the shelf life, the more sense HTML makes. The smaller the size and the greater the textual stability, the better Markdown fits.
The operational reframe · the Tech Lead's role as "compute allocator"
Thariq introduces a reframe on the podcast worth putting on the table at your next planning session. The argument is that when a Claude can run eight hours on a single task, what you decide is no longer "what code do I write" — it's "how do I spend five hundred dollars of compute." The critical skill stops being writing code and becomes deciding what's worth building, defining the limits of what you need to know, and staying in sync with the agent throughout the process. That happens primarily in the spec and plan phase.
For a Tech Lead coming from the classic discipline of code review, the shift is subtle but important: code review becomes partially automatable, while "plan review" becomes the highest-impact activity of the role. And plans — when they're large — need a format that lets you actually review them. Hence the table.
Another data point from the podcast that's rarely cited, and cited badly: Thariq estimates that only around 1% of the tokens his Claude instance generates end up in production code. The other 99% goes to dashboards, status updates, micro-apps for editing plans, comprehension tools, data visualizations. That's not waste — it's what makes the method work. When tokens are cheap, you can afford to make every single thing you're going to interact with beautiful and bespoke. Compute stops being the bottleneck; the bottleneck is human attention.
How onext's AI Engine method evolves as a result
The AI Engine program doesn't change its philosophy: the three canonical claims still hold — the model is not the source of truth, the chat is not the system, the code is not the only artifact. What changes is the medium of some of those artifacts.
Concretely, in the method update we've been applying since mid-May:
The update is backward-compatible. A client team that entered the AI Engine program with Markdown artifacts keeps working — the migration to HTML where it fits happens gradually during phase 4 (Handover), without pausing sprints, at the team's own pace.
What does NOT change
It's worth closing with the honest part. This isn't a piece about HTML's victory over Markdown. It's a piece about knowing when to use each one. Three things that don't change:
- Our manifesto still holds. The medium of some artifacts changes; what doesn't change is that the model is not the source of truth, that the chat is not the system, that the code is not the only artifact. If your team hasn't internalized those three before migrating formats, migrating formats won't solve anything.
- The project constitution stays Markdown by default. It's the most stable, most audited and simplest artifact in the method. HTML adds no advantage there.
- The method isn't bought with either HTML or Markdown. 70% of AI success in a team is organizational — defined human-agent lanes, a real metrics framework, quality-gate governance, dual training and a sustainment plan. Migrating artifacts to HTML without having that in place is changing the document's typography while the team burns out.
The format choice — HTML here, Markdown there — is one concrete component of that method. It isn't the most important thing. But when the team scales beyond three or four active specs, the decision does make a difference.
If you'd like to review how the table applies to your specific team — which artifacts are yours, how large they are, what migrating the ones that fit would change — let's talk: info@onext.es — subject "HTML/Markdown decision." A thirty-minute conversation, no strings attached.
