Markdown is becoming source code — check it into /src
Markdown in /src
Carson Gross argues that as LLM-generated code becomes the norm, the ephemeral prompts behind it are a missing source of truth. He proposes checking Markdown into /src/md alongside the code it produces, making intent diffable, greppable, and accessible to both humans and agents. Tests and wikis can remain, but the core specification should live with the code.
Markdown is now source code, not documentation.
- aDyslecticCrow
You've seen test-rot, specification rot, and documentation rot; we now introduce; prompt rot!
Cluttering the repo with out-dated, very wordy and quickly aging prompts will just confuse any agent tasked with looking at the repo in the future. Keeping context windows down is a real limitation to good LLM output, and this workflow may work completely against it.
- A plan.md describing the project, main abstraction idea, end costumer, and so on is great; but it should be kept minimal and up-to-date with the repo.
- Block comments on top of source-files and functions are great, and already very useful to coding agents. I don't see a value to anything more than what is already typical best practice.
- baldvinmar
Markdown is non deterministic when it comes to piping it through an LLM. Sure the prompt intent is the same, but it doesn't guarantee the same output.
I would much rather have significantly more detailed comments inline with code to describe the intention at any given step than just a high level markdown file. We already have PDRs and markdown seems like it would just be an extension of that.
- divbzero
Instead of the proposed /src/md convention:
src/
md/
README.md # index of all md, entry point for agents
TODO.md # a list of general TODOs open for this module
OVERVIEW.md # a technical overview of this module
features/FEATURE_1.md # a set of feature-specific documents
data/DATAMODEL_1.md # descriptions of data models in the module
api/API_1.md # descriptions of APIs the module provides
infrastructure/INFRASTRUCTURE_1.md # descriptions of infrastructure used by the module
What if we standardized on README.md in each subdirectory alongside the code?
src/
README.md # entry point for humans and agents
TODO.md # list of general TODOs open for this module
INFRA.md # descriptions of infrastructure used by the module
api/
README.md # descriptions of APIs the module provides
models/
README.md # descriptions of data models in this module
README.md in each subdirectory seems to align better with OP’s objective “that Markdown should be checked in to /src, next to the code it produces”. It is also a convention already in use in many code repositories.
- fifferfaffer
My favourite projects typically have documentation in comments.
One example is SpiderMonkey, which uses these beautiful, long expository comments explaining not only what, but why design choices have been made. https://searchfox.org/firefox-main/source/js/public/RootingA...
If the goal is "locality", you can't get much closer than as a comment.
As far as markdown becoming "source code for agents" under the agentic paradigm, per-directory `AGENTS.md` seems more consistent, at least visually. If agent managed markdown is going to be high-churn, I'd rather it be confined to a single file. Constraints, especially for agents, are good.
- ktpsns
I generally put markdown in /docs. I don't uppercase filenames. Instead I make a documentation generator consume the files so I get a decent navigation in HTML/PDF builds.
We did put non-code into /src for a very long time: It was heredocs, multiline docs, etc. Actually my preference is to put texts close to code and only fallback to /docs/something.md at a conceptual level. Which is probably what the author proposes, given that he sees markdown as primary interface to code.