AI-assisted, Spec-Driven Software Development with markdown-den · markdown-den<br>AI-assisted, Spec-Driven Software Development with markdown-den

By Diego Guridi

Problems with prompting your way to a feature

TL;DR: A chat window is a good way to get code and a bad way to keep purpose and decisions.

Problem one: the reasoning disappears. Getting a feature built takes a lot of<br>explaining, and almost none of it ends up in the code: why an awkward case is<br>handled the way it is, which approach you tried first and abandoned, what the<br>alternative would have cost. All of it lived in the conversation, and the<br>conversation is gone by the next session. What survives is the code, and code is<br>a poor record of intent: it tells you what happens, never what was meant to<br>happen.

Problem two: the ideas you have while waiting get lost. This one is quieter,<br>and day to day it costs more. You send a prompt, and then you wait. That minute<br>is exactly when a good but unrelated thought arrives: the sign-up flow is<br>confusing, that error message is wrong, this page is slow on a phone. None of it<br>is about what the agent is doing right now, and a chat has one queue. So you<br>either derail the work in progress, or you hold the thought until it evaporates.<br>Most evaporate. The waiting costs focus as well: an empty minute pulls you<br>somewhere else, and coming back is slower than leaving was.

Neither problem is new. In The New Code, Sean Grove estimates that the<br>code itself is only 10-20% of what a programmer contributes; the rest is<br>understanding the problem, deciding what to build, and checking that the result<br>solves it. Call that "the writing around the code", and it is the part a chat<br>window throws away, because a spec keeps it and a prompt does not. The tooling<br>is following this trend: GitHub's Spec Kit and AWS's Kiro both make a spec the unit of<br>work. Vibe coding without killing focus<br>takes up the second problem, and answers it by batching: plan a handful of small<br>tasks in one sitting, launch them in parallel, then review the results together.<br>That only works if the thought arriving mid-wait has somewhere to land, so it can<br>join the next batch instead of derailing this one.

Markdown is what makes that workable. It is the one format both parties read<br>natively (a person needs no viewer, a model needs no conversion), and it is<br>still precise enough to carry a table of scenarios and to diff cleanly when one<br>line changes. Neither side is translating for the other, which is why the<br>document can be where the work happens rather than a record of it.

What markdown-den adds is a where . The spec lives in the workspace the agent<br>works in, the collaborator that writes the code also maintains the document, and<br>reviewing it happens on the document itself rather than on a copy of it.

Idea formality is a ladder

Formality usually gets treated as a switch: either you just prompt, or you write<br>the whole specification. Most ideas need neither. They arrive half-formed, and<br>they are worth writing down long before they are worth designing, so writing one<br>down should cost nothing, and only deciding to build it should cost something.

That gives one idea four shapes it can have, in order of how much work it has<br>earned:

Idea ShapeWho writes itWhat it costsIt moves on whenA line in a to-do listyou, mid-thought, in secondsnothingan agent or human picks it upA paragraph in your own words, informal and unstructuredyoua minuteit's worth a designA draft spec : the problem, the options, a recommendation, and how you'd know it workedthe agent writes it; you read and commentrounds of reviewyou agree to build itA spec, with code : versioned beside the code, tests named after its scenariosthe agent implements; you mergea branch and a reviewit ships<br>Three things are worth saying about these:

None of the first three go into version control. The line, the paragraph and<br>the draft all live outside it: they are documents you argue with in the margins.<br>No branch, no pull request, no merge. Version control makes disagreement expensive<br>at exactly the moment it should be cheap. A line you thought better of should cost<br>a deletion rather than a revert, a paragraph should be rewritten without ceremony,<br>and the whole value of writing a proposal down is that rejecting it costs a<br>comment. The repository begins at the last step, where a decision has been made<br>and the code has to match it, or at a branch that skipped the documents entirely,<br>because the work never needed designing.

A line can go straight to the end. Plenty of work needs no design at all: a<br>bug someone can reproduce from the sentence describing it, a rename, a wrong<br>label, a missing guard. That goes from one line to a branch and a pull request<br>without passing through anything in between. The reasoning fits in the commit<br>message, and inventing a document for it would be ceremony rather than thought.<br>These are shapes an idea can take, not steps that have to be walked through.

A paragraph is a fine place to stop. Most...