Stop Writing Markdown for Claude Code. Try HTML Tags Instead.

If you’ve spent any real time with Claude Code or Cursor, you know the feeling. You wrote a clean Markdown brief, hit enter, and the agent still drifted, skipped a rule, or invented a step. Now a small but loud corner of dev Twitter and YouTube is pushing a fix that sounds backwards: stop using Markdown for your agent instructions and use HTML tags instead. It feels wrong until you try it.

“Markdown killed my workflow”

The provocation comes from a May 9 video by DIY Smart Code titled “Markdown Killed My AI Workflow (HTML Fixed It)” — 4,475 views and 166 likes in a few days, which is fast traction for a niche prompt-engineering take.

The argument is simple. Markdown is great for humans and terrible at marking edges. A ## Task List followed by five bullets is a section to you, but to a model staring at tokens, where exactly does that section end? At the next ##? Implicitly. Probabilistically. By convention. Compare that with <task_list>...</task_list>. The closing tag is not a hint. It’s a hard boundary.

Anthropic basically told us this years ago

This isn’t really new. Anthropic’s own prompting guide has recommended XML-style tags for ages, noting that Claude was specifically trained to respond to wrappers like <example>, <instructions>, and <context>.

The gap is that most developers apply this advice to one-off prompts, then go write their CLAUDE.md — the file the model reads on every single turn — in plain Markdown. A second video from May 10, AI Evening News’ “Stop Asking Claude Code for Markdown — HTML Makes AI Work Feel 10X Faster,” zeroes in on the same disconnect: the most load-bearing context in your repo is often written in the format the model handles worst.

Why tags actually work better

Three reasons keep coming up.

Boundaries are explicit. Anything inside <rules>...</rules> is unambiguously “the rules.” Headings can’t promise that.

Nesting is native. Want to mark a code sample as a sub-item of a specific rule? In Markdown you fake it with indentation and heading levels. In HTML you just nest tags. Done.

Tag names carry meaning. <must_do>, <never_do>, <good_example>, <bad_example> are signals on their own. With Markdown, you write “never do this” in prose and rely on the model to re-parse the intent every time it reads the file. Tags compress instruction into structure.

But is it really 10x?

Worth pumping the brakes here. “10X faster” is marketing. Even the first video softens its own title with the subhead “Or doesn’t it?” — an admission that HTML isn’t a universal upgrade.

A counterweight, also from May 10, is GilliLab IT’s “The LLM Agent Loop Trap Most Developers Fall Into,” which argues the bigger failure mode for coding agents isn’t formatting at all — it’s structural. Agents getting stuck in loops, re-reading the same files, re-running the same tools. Switching to HTML won’t save you from that.

A more honest framing: for short, single-step tasks, Markdown is fine. For long system prompts, multi-rule agent instructions, or anything mixing rules with examples and counter-examples, tags pay for themselves quickly.

The smallest experiment worth running

The cheapest version of this is to open your CLAUDE.md and wrap just the critical sections. Put your hard rules in <critical_rules>...</critical_rules>. Split your examples into <good_example> and <bad_example>. Leave the rest as prose. That’s it.

What’s striking is how much this looks like a regression in prompt engineering. We spent a couple of years convincing ourselves that talking to LLMs in human-friendly Markdown was the natural endpoint. The agent era is quietly reversing that. The smarter the models get, the more they seem to reward us for being mechanically precise — tagged, bounded, semantically labeled.

Open your CLAUDE.md right now. Look at the format. The biggest performance gain on your machine this month might not come from a new model release — it might come from twenty minutes with find-and-replace.