Markdown in /src
Short summary
As AI agents generate more code from prompts, the actual intent behind that code gets lost. The author argues teams should treat Markdown specifications as source code, checking them into `/src` alongside generated code so both humans and agents can reference the same source of truth.
- Today's AI-generated code emerges from ephemeral prompt sessions with no persisted specification, unlike traditional compilers that retain source code. Markdown in the codebase should become the canonical specification instead.
- Markdown belongs in `/src` next to code because it keeps intent and implementation together, eliminates scattered documentation across wikis and tickets, and works naturally for both human and agent consumption.
- Tests shouldn't be the specification—they're too ceremonial and low-level for humans to work with effectively. Markdown specs and derived tests should have separate roles.
Full summary
Carson Gross argues that as AI agents generate more code through prompting sessions, Markdown has become the real source of truth for software systems—not the generated code itself. Right now, developers feed strings of prompts to AI agents, and the resulting code is treated as gospel because there's nowhere else to look. But those prompts disappear, leaving future developers with only the code and scattered documentation across Linear, Slack, and wikis. Gross proposes treating Markdown as actual source code by checking it into `/src/md` alongside the generated implementation. This flips the workflow: developers write Markdown specifications first, then agents and humans derive code and tests from that Markdown, rather than the other way around.
The appeal is practical. Markdown is plain text, so it diffs cleanly in pull requests and works natively with LLMs. It keeps intent and architectural decisions right next to the code that implements them, eliminating the "specification at a distance" problem where logic lives buried in some wiki nobody reads. Tests can still exist in `/test`, but they become confirmation of behavior rather than the specification itself. Gross sketches a possible directory structure with README.md as an index, TODO.md for open work, OVERVIEW.md for technical context, and subdirectories for features, data models, APIs, and infrastructure. The key constraint: humans should author and curate `/src/md` directly, not agents.
Gross acknowledges this is new territory and he's thinking out loud. The real challenge is managing the Markdown's complexity budget and keeping it synchronized with code changes—developers will need to move subtractive work from generated code back into Markdown sometimes. But the underlying insight is straightforward: as code generation gets cheaper, what matters is capturing *why* the code exists, what it's supposed to do, and what it must never do. Right now that intent vanishes into ephemeral prompting sessions. Checking it into version control solves that.