Markdown in /src – Treating Markdown as Source Code

TL;DR

• Markdown is shifting from documentation to source code.
• Store Markdown alongside code in a /src/md folder.
• Derive code and tests from that Markdown instead of relying on transient prompt sessions.

Why Markdown Should Be Treated as Source Code

Markdown satisfies the core properties of traditional source files: it is plain‑text, diffable, searchable, and easily reviewed in pull requests. Large language models (LLMs) can read and write Markdown natively, and humans can edit it without specialized tools. Consequently, Markdown can act as the intent layer that drives code generation, much like a compiler’s high‑level specification drives machine code.

The Problem with Ephemeral Prompting

Current agentic workflows often generate code through a series of ad‑hoc prompts. The resulting code becomes the de‑facto ground truth, while the prompts themselves remain scattered across Slack, Linear, or private notes. This “prompt rot” leads to:

• Lost context for future developers and agents.
• Inability to version‑control the original specifications.
• Increased token usage when agents must reconstruct missing intent.

Benefits of a /src/md Directory

Locality of Intent

Placing Markdown next to the code it describes eliminates the “specification at a distance” problem. Developers can view the rationale for a module without leaving the source tree, and agents can retrieve the same context without extra lookups.

Human‑Agent Symmetry

Both humans and LLMs can consume the same Markdown files, ensuring a single source of truth for intent, architecture decisions, and data models.

Version Control and Review

Markdown files participate in the same Git workflow as code: they can be diffed, linted, and discussed in pull‑request comments. This makes intent changes auditable and reviewable.

How Markdown Complements Tests

Tests remain essential for automated correctness verification, but they are low‑level and often obscure why a feature exists. By storing intent in /src/md and generating tests from that intent, teams achieve a clear division of labor:

• Markdown – specification‑ish description of behavior, architecture, and data.
• Tests – concrete validation that the generated code matches the specification.

Proposed /src/md Layout

A concrete folder structure helps keep Markdown organized and discoverable:

src/
  md/
    README.md          # Entry point for agents and humans
    TODO.md            # Open tasks for the module
    OVERVIEW.md        # Technical overview of the module
    features/
      FEATURE_1.md     # Feature‑specific description
    data/
      DATAMODEL_1.md   # Data model definitions
    api/
      API_1.md         # API contracts and usage
    infrastructure/
      INFRA_1.md       # Infrastructure dependencies

Sub‑folders are optional; they allow teams to separate concerns along logical axes (features, data, APIs, infrastructure).

Community Feedback Highlights

• Prompt rot concerns – @aDyslecticCrow warned that storing outdated prompts could clutter the repo and increase token usage. The consensus is to keep Markdown minimal, up‑to‑date, and treat it as intent rather than a full transcript of every prompt.
• Clutter vs. Value – @benrutter argued that excessive Markdown could bloat the repository and be hard to maintain. He suggested using Markdown mainly during review or regression analysis, not as a permanent dump of every prompt.
• Tooling support – @xg15 asked about syntax highlighting and navigation for Markdown. Existing IDE extensions already provide rich Markdown support, and tools like Varar or Cucumber‑style linters can enforce consistency.
• Alternative placement – @ktpsns and @maxk42 prefer keeping documentation in /docs or separate README files. The key distinction is locality: placing intent next to the code (in /src/md) reduces the mental distance between implementation and rationale.
• Literate programming inspiration – @sroerick likened the approach to a loosely compiled DSL or literate programming, emphasizing the need for a “spec‑matches‑code” workflow.
• Standardization suggestions – @divbzero proposed using a README.md in each subdirectory rather than a central index, aligning with common repository conventions.

Practical Workflow

1. Create or update a Markdown file in /src/md describing the new feature, data model, or API.
2. Run the LLM with the Markdown as the prompt to generate or update code.
3. Generate tests automatically from the same Markdown (e.g., using a custom generator or a tool like mdtest).
4. Review both the Markdown and generated code in a single pull request.
5. Synchronize any manual edits back to the Markdown to keep intent and implementation aligned.

Potential Pitfalls and Mitigations

• Stale Markdown – Establish a linting step that flags Markdown files not referenced by recent commits.
• Token cost – Keep Markdown concise; treat it as a high‑level spec, not a verbatim transcript of every prompt.
• Non‑deterministic generation – Accept that LLM output may vary; rely on tests to catch regressions rather than the exact generated code.

Conclusion

As AI makes code generation cheap, the most valuable artifact becomes the intent behind that code. Storing that intent as Markdown in a /src/md directory provides locality, version control, and a shared medium for both humans and agents. While the exact layout will evolve, the core idea—treating Markdown as source code rather than peripheral documentation—offers a pragmatic path forward for agentic development workflows.