Stop Using Markdown with Claude Code

Posted on In Views:

Stop Using Markdown with Claude Code

Why Confluence beats HTML and Markdown for human-AI collaboration

A recent article on the Anthropic blog sparked a massive debate.

The main idea is that using HTML is actually better than Markdown when collaborating with Claude Code.

And then the arguments started.

Supporters say Markdown looks terrible. By terrible, they mean it is both ugly to look at and hard to read, plus it lacks interactivity. On the flip side, critics argue that HTML burns through a ton of tokens and is just plain inefficient.

As for me, I do not really lean toward the Markdown camp, but I do not buy into the HTML argument either.

So let me break down the issues I ran into and how I solved them.

The Friction in Human-in-the-Loop Workflow

If you follow my work, you probably know I am not the type to just let agents run wild and do whatever they want. I constantly talk with them and guide their direction to get the exact output I need. To me, an agent is an accelerator and an amplifier, not a clone or a proxy.

Because of this, I need to communicate and iterate with my agents all the time.

At first, I used Markdown just like everyone else. My reasons were pretty standard: it uses fewer tokens, it is efficient, and it is easy for humans to edit.

But I quickly realized that when an agent generates a massive Markdown file, I lose interest in reading it. There are two main reasons for this. First, it is just too raw, which causes serious reading fatigue. Second, and this is my biggest pain point, it is incredibly hard to interact with. If I want to ask a question about a specific line, I either have to write it directly into the Markdown, which makes a mess, or copy and paste it back into the chat window to keep the conversation going.

Neither approach is sustainable. This is especially true for copying and pasting. I believe most people use agents specifically because they hate copying and pasting. Yet, here we are, going right back to our old ways just to keep the discussion alive, only in reverse: copying the agent’s output back into the chat window.

So, using Markdown for these discussions genuinely caused a lot of friction for me.

Another major issue is that all the back-and-forth edits on a Markdown file never get recorded.

  • What problem did we solve?
  • How did we solve it?
  • Why did we do it that way?

This context quickly vanishes as the Markdown gets edited over and over, especially when the agent updates it autonomously. The whole discussion process is completely lost.

These two massive roadblocks made me give up on Markdown as a collaboration tool.

The Problems with HTML

I actually gave HTML a shot.

I tried this tactic way before that blog post came out, and honestly, the results were mediocre at best.

There is no doubt that agents are great at writing HTML. However, adding interactive elements, like a text box for feedback, makes communication way too complicated. You have to give the agent explicit prompt instructions on how to build that highly interactive HTML, and you also have to tell it how to handle the communication loop.

After all, HTML itself is stateless. Usually, you just end up writing a file to some directory. You then have to establish a strict contract with the agent regarding where that file lives and what it looks like.

Plus, HTML still does not solve the missing context problem. To keep that context, you have to design precise contracts for those interactions. That is just as hard as architecting a whole system from scratch.

My Solution

So, we need to solve the following problems:

  1. High interactivity
  2. Context retention
  3. A simple, highly reusable design

Ultimately, I went with a very simple approach.

Since Markdown is hard to interact with, we just need to make it interactive.

All we have to do is send the Markdown into Confluence, and it instantly becomes an interactive page.

Confluence natively has every single feature we need:

  1. It looks clean and polished.
  2. It allows for interaction, using both inline and footer comments.
  3. It retains context because you can resolve comments without losing them.
  4. It includes version control, and Confluence can even show diffs between versions.

I already had a script that the agent could call to upload Markdown and turn it into a page anyway. In our organization, Confluence is the only place we publish RCAs and design docs.

I did not need to design anything new. I just called my predefined Confluence skill, and I solved all the pain points I mentioned earlier in one shot.

This was so much easier than trying to reinvent the wheel with HTML.

The One Thing I Didn’t Get

HTML does have one feature that Confluence cannot naturally replicate.

It can handle interactions that go way beyond text. By that, I mean doing more than just leaving comments. For example, if I were a data analyst, I could embed sliders directly into the HTML to build a live report. Or, I could generate fancy trend charts that let users dynamically switch timeframes and parameters.

Confluence simply does not offer that level of interactivity.

But frankly, I do not need it, so I do not care. I just wanted a medium to collaborate with my agent. I was not looking for a presentation layer to show off to other people.

Using Confluence was more than enough to solve all my pain points.

Originally published on Medium