How I AI: Thariq Shihipar on Replacing Markdown with HTML for AI-Powered Development

Anthropic engineer Thariq Shihipar has mostly stopped asking Claude Code for giant Markdown plans. Instead, he asks for interactive HTML files with mockups, diagrams, controls, and rendered examples he can actually review. The change sounds cosmetic until you watch the workflow: better presentation keeps him engaged with the work long enough to catch bad assumptions, refine decisions, and steer the agent before implementation starts. See Create Interactive HTML Project Plans with AI for Better Visualization.

In this episode of How I AI, Thariq argues that Markdown broke down as agents became capable of running for much longer stretches. A fifty line plan is manageable. A thousand line implementation document is something most people skim, ignore, or hand back to the model for another rewrite without really inspecting it.

HTML changes the review experience. A plan can include visual hierarchy, tabs, diagrams, mockups, expandable sections, editable controls, and embedded examples instead of raw text blocks. Thariq frames the human role as compute allocation: deciding which problems deserve expensive agent runs, then staying involved enough to verify the direction before more tokens get spent.

The workflows build on each other. First, Claude brainstorms and plans in HTML instead of Markdown. Then those plans become temporary editing tools tailored to one decision. Finally, the same approach turns a design system into a portable HTML artifact that travels with the codebase and gives both humans and models a shared visual reference.

Turn planning documents into interactive artifacts

Thariq's core idea is simple: plans should optimize for human review, not just model readability. Claude already understands Markdown. The bottleneck is whether the person supervising the work can stay engaged long enough to notice gaps, ask better questions, and make meaningful edits.

Brainstorm visually instead of generating text lists

Before the recording, Thariq asked Claude Code to brainstorm demo ideas for the show as an HTML file. The prompt was intentionally lightweight. He told Claude he was appearing on my podcast, wanted demo concepts, and asked for them in HTML.

I was literally like, look, I'm on a Claire Vo podcast. I want to do a demo, you know, and can you brainstorm some ideas in HTML file?

Claude generated a scrollable webpage with eight concepts, complete with small visual mockups, descriptions, and risk notes. Instead of reading a long bulleted brainstorm in the terminal, Thariq could quickly scan, compare, and react to the ideas visually. He mentioned that he rarely reads outputs longer than a single Claude Code screen, but he will scroll through a well designed HTML artifact.

Expand the selected idea into a full implementation plan

After choosing a CSV-to-dashboard concept, Thariq had Claude interview him about the idea to surface requirements and unknowns. Once that conversation clarified the direction, he asked Claude to create the implementation plan as an HTML file instead of a Markdown spec.

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

The prompt deliberately mixed constraints with flexibility. Thariq explicitly requested things he cared about, like excerpts, mockups, and code samples, but avoided over-specifying the structure. He wants Claude to fill in useful context he may not have anticipated rather than rigidly obeying a giant planning template.

The resulting artifact looked more like a lightweight internal website than a spec document. It included a podcast intro section, file structure diagrams, implementation notes, code excerpts, helper scripts, UI references, and a visual mood board. Thariq's point was not that every team needs prettier documentation. It was that people are far more likely to review and understand a rich interactive plan than a massive Markdown file buried in a repo.

Build throwaway interfaces for difficult decisions

The tradeoff with HTML is editing. Markdown is easy to tweak directly in a text editor. Rich HTML plans are easier to consume but harder to revise manually, especially when the content becomes structured or repetitive.

Instead of dropping back into chat and negotiating every edit conversationally, Thariq asks Claude to generate tiny purpose-built interfaces for the exact part of the plan he wants to change. He describes these as temporary layers of software built on top of the larger artifact.

It's like this is not even personal software. This is like sub... it's like micro-software on top of micro-software.

Find the section where chat editing becomes tedious

In the dashboard demo, Claude proposed a set of rules for mapping CSV data types to visualizations. Some of the rules felt arbitrary to Thariq, and revising them through repeated chat messages sounded painful. He wanted structure, but also flexibility to experiment.

Ask Claude to design the editing experience

Rather than requesting another prose rewrite, Thariq asked Claude to create an editable HTML interface specifically for adjusting those rules. He told Claude to design the ideal UI for the problem instead of prescribing exactly what the interface should look like.

I want to create an editable HTML artifact to help me define the decision rules. I don't like the ones we have right now. Make this a custom UI that helps me with structure but gives me flexibility. Design the ideal interface for this problem.

Edit visually, then export back into the workflow

Claude generated a standalone webpage with editable fields, dropdowns, add and remove controls, hide toggles, and a button that copied the resulting configuration back out as Markdown. The interface was polished enough to feel like a real product despite existing for one narrow task.

This was one of the more interesting shifts in the episode. The goal was not to build permanent software. The UI only needed to exist long enough to help a human make one decision well. Once the rules were finalized, Thariq could paste the output back into the broader plan and continue implementation.

Use HTML as a living design system

Thariq applies the same pattern to design systems. Instead of treating design tokens and component references as scattered documentation, he creates a rendered HTML artifact that both humans and Claude can inspect directly.

The file usually lives alongside the codebase as design_system.html. Because it is visual and portable, the same artifact can guide implementation, reviews, marketing assets, and future projects.

Extract the design language from existing projects

Claude can inspect one repository or several related projects, including a product app and marketing site, to infer recurring design patterns. It identifies colors, typography, spacing conventions, reusable components, and shared visual rules.

Render the design system as a browsable reference

The generated HTML file displays the palette, typography scale, spacing system, border radius values, and component examples such as buttons, cards, and inputs. Because the reference is rendered instead of purely token-based, reviewers can evaluate how the system actually feels instead of interpreting raw configuration values.

When starting a new feature or application, the team can hand Claude the design_system.html file as context. Thariq compared this favorably to relying on disconnected screenshots or static docs because the artifact gives Claude a compressed but highly legible understanding of the intended interface language.

Add playground controls and share beyond engineering

The design system can also behave like a lightweight component playground. Controls for padding, borders, colors, and other properties let reviewers experiment visually without editing source code. I mentioned using a similar approach to generate realistic component states for decks, videos, and marketing materials.

That broader accessibility mattered throughout this episode of How I AI. HTML artifacts are easier to share across functions because anyone can open a link and interact with the result. Thariq even mentioned generating weekly status updates in HTML so collaborators are more likely to read them.

Across all three workflows, the pattern stays consistent: generate the interface that helps the next decision happen. HTML plans improve review. Disposable micro-apps improve editing. Living design systems improve consistency and verification. The artifact is valuable as long as it keeps humans meaningfully in the loop. You can follow the full implementation in Generate a Living HTML Design System with AI for UI Consistency. See Generate a Living HTML Design System with AI for UI Consistency. See Build Disposable Micro-Apps with AI to Edit Complex Plans.

One of Thariq's more revealing comments was that only a tiny fraction of the tokens he generates become production code. Most of the output goes toward planning, communication, references, interfaces, mockups, and verification. The surrounding scaffolding is what helps the final implementation improve.

The most useful part of this workflow is not replacing Markdown with HTML everywhere. It is recognizing when text stops being an effective review surface. If a plan is long enough that nobody really reads it, rendering the work as an interactive artifact can keep humans engaged long enough to catch mistakes early. The throwaway editors are especially compelling for solo builders and small teams making fast product decisions. What still requires judgment is deciding which details deserve structure and which should stay flexible. A beautiful interface can make weak thinking easier to overlook if nobody challenges the assumptions underneath it.