Carson Gross proposes checking Markdown into /src as source code
Carson Gross, a professor at Montana State University who also consults on agentic coding, published an essay arguing that Markdown is becoming source code rather than documentation. His starting point: when developers use LLM agents to generate code from a string of prompts, the generated code ends up as the only "ground truth" for a feature, because the reasoning behind it lives in ephemeral prompt sessions or in documentation scattered across tools such as Linear, Slack and wikis that never get checked in with the code. He contrasts this with compiler workflows, where the original source code is retained even though a compiler's output is what actually runs; LLM-generated code, in his account, typically leaves no equivalent record of the input that produced it.
His proposal is to capture that intent in Markdown and check it into a new directory, /src/md, alongside the code it describes. He points out that Markdown already functions as source in files such as AGENTS.md, specs and TASK.md; what is missing, in his view, is a standard place and structure for it. He sketches one: a README.md that indexes the module's Markdown for agents, a TODO.md, an OVERVIEW.md, and optional subfolders, features/, data/, api/ and infrastructure/, for feature-, data-model-, API- and infrastructure-specific documents. Code and tests, he argues, should be derived from this Markdown rather than generated straight from prompts alongside it. He is skeptical of treating tests themselves as the specification, saying they carry too much ceremony and sit at a lower level than most people want to read when they are trying to understand a system.
Gross frames the benefit as locality: keeping the "why" next to the code removes what he calls "specification at a distance," where the logic behind a decision sits in a separate wiki or ticket system, and lets both humans and agents pull context from one place. He is explicit that agents should not write most of /src/md themselves; he wants it mainly human-authored and curated, with developers responsible for syncing constraining or subtractive edits made to generated code back into the Markdown. He quotes an earlier essay by Hartley Brody, "Markdown is the new source code," which observed that application logic is increasingly defined and edited as Markdown while the code an agent generates becomes "a low-level implementation detail."
Gross calls the specific /src/md directory layout the weakest part of his essay, describing it as an idea he is thinking out loud about rather than one he has used extensively. He names no company, client or tool that has adopted the convention, and gives no timeline for adoption; the essay is presented as an observation from his own consulting work, at organizations he says are moving toward agentic coding "often at terrific speed," rather than as an established practice.
Key facts
- Carson Gross, a Montana State University professor who also consults on agentic coding, argues Markdown is becoming source code rather than documentation.
- His core complaint: code generated by LLM agents from ephemeral prompt sessions has no retained "source" the way compiled code keeps its original source, so the intent behind it gets lost.
- He proposes a /src/md directory, checked in beside the code, containing files such as README.md, TODO.md and OVERVIEW.md plus optional features/, data/, api/ and infrastructure/ subfolders.
- Code and tests would be derived from that Markdown, and he wants the directory to be mainly human-authored, not agent-generated.
- He calls the proposed directory structure the essay's weakest, untested part and names no organization currently using it.
Why it matters
Agentic coding has made generating code cheap, but Gross's point is that the reasoning behind the code, what it should do and why, is what now gets lost: it lives in a prompt session that closes or in docs kept elsewhere, never checked in with the result. His proposal treats Markdown as the missing source artifact, the thing a team should actually maintain and review, with the generated code as a derived, lower-level output.
Who it affects
Teams and companies already running agentic coding workflows, where most new code comes from LLM agents rather than being hand-written. It speaks to developers who write specs, plans or AGENTS.md files that agents consume, and to anyone trying to keep a codebase's intent legible once the code itself is machine-generated and frequently regenerated.
How to use it
Gross's sketch: a /src/md folder next to the code, with a README.md acting as an index for agents, a TODO.md, an OVERVIEW.md, and optional subfolders for features, data models, APIs and infrastructure. Markdown there should be mainly written and curated by humans, not generated by agents; code and tests are derived from it, and when a developer makes subtractive or constraining changes directly to generated code, those changes should be carried back into the Markdown to keep the two in sync.
How solid is it
This is Gross's own opinion, drawn from his consulting work rather than from a study or a shipped tool. He states plainly that the specific /src/md structure is the weakest part of the essay, an idea he is "thinking out loud" about and has not used extensively. No company, client or product is named as having adopted it.
Risks and caveats
No timeline, client or tool backs the proposal, so it should be read as a personal position rather than an emerging standard. Gross also flags a maintenance cost baked into the idea itself: keeping Markdown and generated code in sync requires developers to deliberately port changes back, which is discipline that can lapse. He notes elsewhere in the essay that he remains ambivalent about AI-generated code in general, even as he argues organizations are moving this direction quickly.
“Markdown is now source code, not documentation.”
— Carson Gross