Thomas Buss blog

Markdown? Seriously?

Table of Contents

Oh, how I love Markdown! I guess every developer does. For years we’ve been writing readmes and other forms of documentation in it. Most Markdown renderers also understand special syntax for Mermaid diagrams, automatically apply syntax highlighting for code blocks or even bring some basic forms of interactivity like collapsible sections. And tools like Obsidian build upon markdown and extend it with YAML front-matter, so you can pair structured data with unstructured text. It is incredibly approachable and strikes a great balance between WYSIWYG and WYSIWYM that is not tied to a specific tool or vendor.

However, I’m a dev…

I write code for a living (or rather, I used to before AI did most of it), so I am accustomed to dealing with the non-intuitive syntax. Moreover, I’m used to write markdown without seeing the result immediately, diff’ing divergent versions of a file and sharing files with coworkers using Git. And while I don’t want to claim that this true for everyone, I do want to point out that not every manager can or wants to do that.

So, I’m surprised to see that a lot of new tooling around agentic AI tools in the realm of Spec Driven Development uses markdown to write the specification. To make clear what tools I’m referring to, here are some of them:

For the unfamiliar, these tools let you basically generate specification documents as markdown files inside the repository where the code changes are going to happen. The user starts describing what he/she wants to the coding agent which yields an initial spec, then iterates on the spec until satisfied, and then executes a command to start a coding agent that implements the spec.

Why tool vendors chose markdown

I mean, I get why they did it that way. Markdown is not only easy for developers, it’s also very easy for AI agents to read and write to. It is the format that we have been using and will continue to be using for coding tasks that have a human in the loop. Therefore, it’s not surprising that this format was used for these newer types of coding efforts where the developer becomes more of a requirements engineer than a coding monkey. But if the claims of tech bros are true, that soon the business people can simply describe what they want and some AI army is going to generate exactly what they meant, they’re probably not gonna be doing this with markdown files.

Why markdown files in a Git repo don’t cut it

So even while I love markdown, here are some reasons why I don’t think these tools are the end of the line when it comes to spec driven development tooling.

  1. WYSIWYM is not what business people are used to or want. There are, of course, exceptions to this and I congratulate you if your product manager is tech-savvy enough to write requirements in markdown. I have worked with this type of product managers. I wish there were more of them.
  2. Unfinished task descriptions don’t belong in the same Git repository. Even in teams that do not follow a waterfall-methodology, some ideas come up and remain in an incomplete state for weeks. If requirements are left incomplete, how can you tell what has already been implemented? What is just a goofy idea someone had a while back and what is genuinely actionable?
  3. No support for management features. No assignments, no statuses, no filtering. Just plain text files on disk somewhere.
  4. No collaboration from other people. I can request comments to a Jira or GitHub issue from anyone who has access, even end users if they happen to work for the same company. But I cannot easily get non-technical people to weigh in on issue descriptions in a markdown file in a Git repo.
  5. No cross-repository changes.
  6. Kinda nit-picky, but: It makes the CI/CD pipeline more complicated because we now have to check if code was changed and if we need to run tests, linters etc. (to be fair, we already have this problem with readme files, but I suspect that SDD would require much more changes to non-code files than before).

The overarching assumption here is that serious product work, contrary to vibe-coding experiments of individuals, will require more than what markdown files can provide right now.

What to do instead

Now, you could build some tooling around markdown files to mitigate some of these shortcomings. But why bother?

What you need is a tool that not only assists the writer with the act of writing the specification, but also let’s you collaborate with peers (including specialized agents). Maggie Appleton had an interesting idea a while back on how AI “daemons” with different personalities could be used in creative writing. A similar type of editor could be used for writing specifications, with different agents paying attention to different topics (security specialist, accessibility specialist etc.) Imagine this being integrated in a GitLab issue creation form and we’re almost there.

When everything is sorted out, it passes the instructions to a coding agent to begin working on the issue. This part could very well be done with a simple markdown file as an exchange format. But for real, long-lived backlogs, in a real product setting, writing markdown files in a Git repo are not going to replace project management software. GitLab Duo Agent Platform comes close, but does not seem to offer anything that supports Spec Driven Development.

You would then need observability into the coding agent itself, which GitLab (correct me if I’m wrong here) does not currently have since the automated coding agents run on ordinary GitLab runners. Something like LangFuse perhaps?

Conclusion

To summarize, I don’t think that the current era of SDD tools will last for a long time. At least they will have to be augmented in significant ways. End-to-End Platforms (likely GitHub and GitLab) will emerge that will assist developers and product managers alike with the specification and coding parts of software.

Comments powered by Disqus