Markdown in /src

Carson Gross has a simple claim in his latest essay: if agentic coding is doing the real work, the Markdown behind it should stop hiding in docs and start living beside the code. Not because Markdown is glamorous. Because it’s becoming the thing that holds the intent together while the generated code changes under it.

His starting point is the mess created by prompt-driven development. In many teams, code appears from a chain of ephemeral prompts, while the real explanation for a feature gets scattered across Slack, Linear, wikis and whatever else somebody remembers to open. That makes the generated code the closest thing to ground truth, even when everyone knows the prompt trail matters too.

Gross’s answer is to treat Markdown as source and put it in the source tree, under something like /src/md. That Markdown would carry architectural decisions, source-level decisions and low-level data design decisions. It would sit closer to a specification than a normal project document, but still remain plain text: diffable, searchable, reviewable and readable by both humans and agents.

He also wants a cleaner split with tests. Tests can verify behavior, but they are awkward as the main place where humans and agents negotiate meaning. They come with ceremony, often hide the point, and don’t naturally hold higher-level explanations like Mermaid diagrams. So the division he sketches is simple: Markdown in /src as the specification-ish layer, tests in /test or wherever as the automatic check.

Gross is careful not to oversell the idea. He says this /src/md setup is still tentative, and that the Markdown should mostly be human authored and curated rather than churned out by agents. But his broader point is hard to miss: as code gets cheaper to generate, the intent behind it gets more valuable, and that intent needs a home that isn’t a forgotten prompt thread.