Montana State prof proposes /src/md directory for AI-generated code workflows
Brady Olano argues that as LLMs generate code, markdown specifications should become tracked source artifacts alongside the generated output.
What to know
- Olano proposes a /src/md directory convention to version-control human-authored markdown specifications that guide LLM code generation, treating them as source artifacts rather than ephemeral logs.
- Developers question whether LLMs justify the practice, arguing that colocating source artifacts with code should have been standard before the AI era.
- Critics raise practical concerns: the proposal captures only initial prompts, not the iterative refinement rounds that shape final output; and a flat markdown directory mirrors poor code organization patterns.
- The core debate centers on whether markdown specifications can serve as formal, reproducible source artifacts—or whether typed systems and DSLs are better suited to encoding software intent.
The dispute Whether markdown in a /src/md directory addresses reproducibility in agentic coding or merely rebrands a pre-LLM best practice while failing to capture the iterative refinement that actually drives output generation. · positions read across 33 posts and comments
The proposal conflates a good practice (colocating artifacts) with a new problem (LLM traceability) when artifact locality should precede LLMs.
-
“It's strange to me that LLMs seem to motivate this, instead of 'your source artifacts should live with your code...'”
cceckman · Lobsters ↗
The proposal doesn't capture the iterative refinement cycles that actually shape LLM-generated code, only initial prompts.
-
“I don't know how this is actually supposed to work…for anything nontrivial there follows several back and forth rounds where I'm telling it 'actually, rip out the Foo and try just augmenting Bar'…”
bakkot · Lobsters ↗
Markdown is too informal and unstructured to serve as a specification vehicle; typed documentation or DSLs would be more rigorous.
-
“Type systems are deterministic & are trying to encode invariants in a predictable manner—2 features LLM outputs don't have. …& this is already frustrating enough that such a bad format for documentation/technical writing, Markdown, is…”
toastal · Lobsters ↗
The core idea has merit but the proposed flat /src/md directory repeats mistakes of language-based source organization.
-
“Documentation should live close to what it documents.”
dlisboa · Lobsters ↗
Brady Olano Montana State University professor, AI consultant
How it unfolded 5 developments, newest first · click a bar or a number to jump postscomments
-
5
Commenters debate directory organization and markdown viability
dlisboa argues the proposed /src/md flat directory structure mirrors the mistake of grouping code by language rather than by module. zetashift and toastal express skepticism about markdown as a formal specification vehicle, noting that typed documentation systems and DSLs offer more predictable guarantees.
“Documentation should live close to what it documents.”
— dlisboa -
> Markdown is becoming source code, not documentation :c
2 more of the top 3 · 29 posts in this stretch
-
Personally, I build a loosely compiled / linted DSL to handle spec.It's a SEXP language but could just as easily be markdown. It'd probably be better if it was - I spend a lot of tokens matching parentheses.Compared to markdown - I lose some human readability but gain a lot in workflow.For me - it turns the sort of "free form jazz code odyssey"…
-
H
Markdown in /src L: https:// htmx.org/essays/markdown-in-sr c/ C: https:// news.ycombinator.com/item?id=4 9794478 posted on 2026.09.21 at 18:47:54 (c=0, p=6)
-
-
4
Developer argues colocated artifacts should precede LLM era
cceckman notes that the practice of keeping source artifacts (decision records, lab notebooks, experiment logs) alongside code is not new and should not require LLMs as justification to implement it.
“It's strange to me that LLMs seem to motivate this, instead of 'your source artifacts should live with your code...' Yeah, someone trying to understand the code needs access to all those; make it accessible to them.”
— cceckman -
It's strange to me that LLMs seem to motivate this, instead of "your source artifacts should live with your code..." ...and source artifacts include [decision records](https://adr.github.io/) of [various sorts](https://rfd.shared.oxide.computer/), lab notebooks used to run experiments, etc. Yeah, someone trying to understand the code needs access…
-
-
3
Developers question whether proposal addresses the real problem
Commenters on Lobsters push back on the core premise. cceckman argues the essay frames LLMs as motivation for something that should have been standard practice already (colocating source artifacts with code). bakkot raises practical questions about how to capture the iterative back-and-forth refinement that happens between developer and LLM, which the initial prompts do not capture.
“I don't know how this is actually supposed to work…for anything nontrivial there follows several back and forth rounds where I'm telling it 'actually, rip out the Foo and try just augmenting Bar'…Even if I was capturing these later prompts, they aren't very…”
— bakkot -
This essay claims: > Markdown is becoming source code, not documentation
-
-
2
Essay gains traction on developer communities
The essay is posted and discussed on Lobsters and Hacker News. Olano clarifies in comments that the key to the proposal is that agents should not generate the /src/md content—it should be human-authored and curated.
“I believe that agents should not be used to generate much content in /src/md. This directory should be mainly human authored and curated.”
— Brady Olano -
> I believe that agents should not be used to generate much content in /src/md. This directory should be mainly human authored and curated. I think that’s the key to this proposal but it’s buried deep down in the article. Otherwise people would assume plan mode slop which I find is excruciating to review.
1 more of the top 2 · 2 posts in this stretch
-
> A Proposed /src/md Convention > > This is necessarily the weakest part of this essay because this is a new idea and I haven’t used it extensively yet. It is me thinking out loud and inviting discussion. I'm glad this was acknowledged because it really makes no sense to have a "markdown" directory with everything in it, just as it doesn't make…
-
-
1
Brady Olano publishes essay on markdown as source in agentic coding
Olano, a Montana State University professor who does consulting work on agentic coding systems, publishes an essay on htmx.org proposing that markdown specifications used to guide LLM code generation should be version-controlled in a /src/md directory alongside the generated code.
“It is starting to feel as if the application logic of the software is being defined and edited as markdown, and the actual code that is generated by the agent is sort of becoming a low-level implementation detail.”
— Brady Olano
What people are saying 17 voices from 2 sites · best of 33 · verbatim
- How would the /src/md directory capture the iterative prompting loops that refine code, not just the initial specification?
- Should artifacts be colocated near the modules they document, rather than grouped in a flat /src/md directory?
- Is markdown sufficiently formal to serve as source-of-truth specification for code generation, or do typed systems better encode intent?
- Sep 25
-
In my projects /docs is human authored and for humans /ai-docs/ is LLM-generated and specifically formatted to be LLM-readable. The two shall not cross.
- Sep 23
-
I think these are different things. The source code, it’s tests, it’s documentation, it’s data. They are different perspectives to approach a given body of work while together building an overall understanding. It doesn’t matter at all where the files live but when you approach the work from that perspective you know how to find it, and I don’t…
-
I think I'm with the majority of commenters here in thinking this would just wind up being clutter. Markdown might now generate code, but it isn't user facing and doesn't get shipped (I don't want to install a library and have a tonne of prompt text unnecessarily downloaded). I also don't really want to be on the hook for maintaining my co-workers…
-
Agree with markdown being important. I still see it as intent, processing it results in a new commit not part, hence I would not put it in src.My conclusion is, that i want neat markdown. Hence it needs to be linted/formatted.Developed a linter/formatter https://mdsmith.dev to specifically do that. Includes tooling for progressive disclosure, etc.
- Sep 22
-
I wonder if instead of checking the prompts into the repo as files, a better idea would be to store them inside the commit messages.If prompts are specifications for a change of the system's behavior, then it seems natural to manage them as changes and not as resources.This would also keep them in the right "historical context" of the repo and…
-
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…
-
If we go that route, can we have rich syntax highlighting, "go to definition"/"show usage sites", debuggers etc for the markdown docs as well? :)But I don't really like the "LLMs as compiler" metaphor. If you followed that logic to the end, you'd have to "rebuild" your entire project from the spec every time the spec changes. Not just would the…
-
I wrote something similar a few months ago [1], though admittedly I haven't been following my own advice terribly well.The interesting part of any program source is what it took to make that program. I view AI-generated code in the same category that I see a binary.[1]
-
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…
-
Let’s keep the Codex session JSONL there too, why the hell not. And the debug build logs, since they’re easily greppable text useful for diagnosing recurring problems. And logs/reports from every test run - a ton of useful info there, lets you track regressions over time; would be a shame to throw it away. We could also store screenshots of every…
-
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…
- Sep 21
-
I’m not getting it either. Type systems are deterministic & are trying to encode invariants in a predictable manner—2 features LLM outputs don’t have. …& this is already frustrating enough that such a bad format for documentation/technical writing, Markdown, is being plopped all over the place; it’s as ergonomic & feature rich as JavaScript’s type…
-
Really hard pass on this here, but I can definitely see why people want this, it sits right around the "tickets/discussion should be colocated with code" discussions. Elixir has `exdoc`, Rust has `rustdoc` and Unison has `{{ fancy doc comments}}`, there are also a quite a lot of notebook-style programming environments. I feel like all of those…
-
I think a possible consequence of the proposed model would be that every time (or every few times) you uncover new things like this, you would have to (manually) incorporate them back into the initial document and restart the session. I would complement with LLM CI reviews that judge whether the final implementation honors what is captured in the…
-
I don't know how this is actually supposed to work. I do write detailed initial prompts, and I often try to capture those (usually in the commit message), but for anything nontrivial there follows several back and forth rounds where I'm telling it "actually, rip out the Foo and try just augmenting Bar" or "add some tests for condition X (and fix…
-
In some projects, I will create a root folder `docs/`. I will then number files `YYYY-MM-DD-title.md`, or `NNN-title.md` starting at `000` and counting up. I strictly keep only human-authored documents in this folder. I will do things like spec out interfaces and tests and invariants by hand, and then write automated checks to ensure that the…
-
I disagree with that. Either way, we don't categorize source code by file type.