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" into something with structure. It changes the question to "does the spec match my idea? And does the code match my spec?"
Every so often, I do a "code astrology reset" and try to purge all the tricks I use to keep things functional. I absolutely notice an efficiency hit when I don't have a spec language. Even with the new models - I find this essential to keep things on track.
I think most people on large projects hit a scaling ceiling with markdown specs. They get massive and contradictory very quickly. I think a src/md folder is a good strategy. I try to organize with a "one spec per module" rule. It doesn't always happen that way but I find that helpful.
I think Literate Programming is a good inspiration here. I also think Yegge's beads and Gastown have some really smart things to say in this regard - even if he's a bit tokenmaxxy for my taste.
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 outdated 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.
Git history is a bit annoying to navigate, but that may just be a tooling issue. I've long been bothered by the loss of the review history when merging a PR. Would actually be pretty cool to click on a row of code and see the commit messages that formed that row of code in a little sidebar, and the technical discussions that were behind it.
Functional safety development processes often demand code-review, technical design decisions, changes of plans, or intentional compromises; to be linked together with reference IDs in the code they effect. But the workflow for this is usually extremely manual and absolute misery. But a codebase made like this is like magic to read later.
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.
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.
In terms of a documentation artifact, I love what `cargo doc` generates, but when I'm inside a source file, any plaintext solution seems so limiting.
I actually miss what I had when I was playing around in TempleOS. All text in the OS is rich (you can toggle between the markup and the standard WYSIWYG view), so comments could have formatting, colours, images (bitmap or vector, great for diagrams), hell, even (aggressively spinning) 3D models.
The thing I used most was the collapsible sections, think <details> and <summary> in HTML. Although I appreciate plain text and would hate WYSIWYG rich text in my serious source code (not to mention binary data appended to the end of the source file for images and models), I can't help but pine for those features. Being able to just draw a real diagram and being able to edit it later in seconds as opposed to making some horrid ASCII art was awesome.
so the holy grail of software engineering is a tool that allows us to commit minimally sufficient design documents as source code.
i'd be enthused to work this way if changes to `src/*.md` files could be "hot-reloaded" on save, like an iterative LLM watch compiler, and skipping the chat prompts altogether.
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 token cost be insane, but you'd also get a completely different implementation each time, maybe with different UI and design decisions where the spec left things open.
The alternative is to see the code as the source of truth and LLMs as (extremely sophisticated) editing or refactoring tools. Then by all means, still check in your prompts, but now they are documentation on how a feature was implemented, not the source of truth themselves.
We are close to inventing something like deep modules [1] for markdown and a whole methodology of managing docs abstraction and layers. And I'm somewhat serious. It's hard to manage one random, interconnected bag of (spaghetti) markdown. Abstract is the new interface.
Docs is already a notoriously under-prioritized and often rotting part of software projects. Making it more complex and larger to maintain and update doesn't feel like the right solution.
Nested markdown or restructured-text or asciidoc is pretty good workflow already to re-use blocks, link to different pages, or do some rich formatting like collapsible sections.
I realize I've been doing this as part of working with agents heavily the last few weeks. The issue is remembering to have it write and keep them up to date. One thing I've been considering is using a Claude Hook[1] when the session ends to basically "update readme and todo from this session. only change them if needed" or something similar
I have found a lot of value in the approach the post describes. I store my markdown as GitHub issues, regardless of how I come up with a detailed feature description (usually a chat session).
Before implementation, context is always cleared to ensure that the model is working only from known context (skills, AGENT.md, etc).
A major benefit of this is that agents can look up prior prompt instructions as needed or when mentioned in the current prompt it's working on.
I still like the idea of source code as documentation and unit tests as documentation. While revising code written by an LLM to make it easier for humans to understand is now a controversial practice, I believe it's worthwhile in a lot of case.
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 app run to have a LLM-compatible historical record of how each component changed visually. And the token provider billing documents, since we’re gonna have a lot of those once we’ll start maintaining all that.
1. he is saying md/english is the new source code..
2. yes - it is different that is geared towards english and very well supported by LLMs that is why it is being used in memory and instructions
3. llms are deterministic enough to translate adequately described specs into working system, the idea here is reason in md for core flow etc, and then verify with test cases
this not perfect but he is describing a real trend, so listen with open mind.
src/md doesn’t seem all that different from docs. Maybe it changes how people search the filesystem, though?
If you split code up into multiple packages, moving the docs closer to the code might make sense. The docs for package foo could be in packages/foo/docs.
> A Proof of Concept for LLM as source code. I am of the position that the "code" is now target code and not source code. My strongest source for this claim is Stallman's classical definition of Source Code which is the "preferred way to modify the program".
> Upload the conversation with ChatGPT as source code
Although this was pre-agents/markdown, the main way to generate code was just with user-interface conversations with the LLM.
And my position differs in which I argue against uploading the target code, just the source code. Which is an issue if the LLM is not deterministic, but it's workable.
That said I apparently did foreshadow solutions to these issues
> Since we are using a consumer interface, and not an api, (first we have no guarantees that the code will not be used for training, so there's no IP protection, but also), we don't have much reproducibility, robust publishing should use API access and publish exact model with revision as well as seed (and even then we are not guaranteed reproducibility.
I think in general we'll end up rewinding so much, the sloppers are recursing and building a ton of harnessing tools that will need to be trashed because they made a fundamental mistake at the very first steps. Those of us who are a bit more careful will probably only get back to agentic engineering once the slopper activity dies down, it's pretty much career suicide at this point to get into it. Anyone who is barely careful is just waiting it out.
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" into something with structure. It changes the question to "does the spec match my idea? And does the code match my spec?"
Every so often, I do a "code astrology reset" and try to purge all the tricks I use to keep things functional. I absolutely notice an efficiency hit when I don't have a spec language. Even with the new models - I find this essential to keep things on track.
I think most people on large projects hit a scaling ceiling with markdown specs. They get massive and contradictory very quickly. I think a src/md folder is a good strategy. I try to organize with a "one spec per module" rule. It doesn't always happen that way but I find that helpful.
I think Literate Programming is a good inspiration here. I also think Yegge's beads and Gastown have some really smart things to say in this regard - even if he's a bit tokenmaxxy for my taste.
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 outdated 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.
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 avoid the "prompt rot" you were talking about.
Git history is a bit annoying to navigate, but that may just be a tooling issue. I've long been bothered by the loss of the review history when merging a PR. Would actually be pretty cool to click on a row of code and see the commit messages that formed that row of code in a little sidebar, and the technical discussions that were behind it.
Functional safety development processes often demand code-review, technical design decisions, changes of plans, or intentional compromises; to be linked together with reference IDs in the code they effect. But the workflow for this is usually extremely manual and absolute misery. But a codebase made like this is like magic to read later.
Gits data structure already allows for that, as you can add additional data to a commit after it was made.
You'd consequently only need to implement your custom git gui and extension to visualize this information.
Maybe a good project for the next weekend? Just eg make a prototype tui in golang and see where you end up
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.
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.
In terms of a documentation artifact, I love what `cargo doc` generates, but when I'm inside a source file, any plaintext solution seems so limiting.
I actually miss what I had when I was playing around in TempleOS. All text in the OS is rich (you can toggle between the markup and the standard WYSIWYG view), so comments could have formatting, colours, images (bitmap or vector, great for diagrams), hell, even (aggressively spinning) 3D models.
The thing I used most was the collapsible sections, think <details> and <summary> in HTML. Although I appreciate plain text and would hate WYSIWYG rich text in my serious source code (not to mention binary data appended to the end of the source file for images and models), I can't help but pine for those features. Being able to just draw a real diagram and being able to edit it later in seconds as opposed to making some horrid ASCII art was awesome.
so the holy grail of software engineering is a tool that allows us to commit minimally sufficient design documents as source code.
i'd be enthused to work this way if changes to `src/*.md` files could be "hot-reloaded" on save, like an iterative LLM watch compiler, and skipping the chat prompts altogether.
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 token cost be insane, but you'd also get a completely different implementation each time, maybe with different UI and design decisions where the spec left things open.
The alternative is to see the code as the source of truth and LLMs as (extremely sophisticated) editing or refactoring tools. Then by all means, still check in your prompts, but now they are documentation on how a feature was implemented, not the source of truth themselves.
We are close to inventing something like deep modules [1] for markdown and a whole methodology of managing docs abstraction and layers. And I'm somewhat serious. It's hard to manage one random, interconnected bag of (spaghetti) markdown. Abstract is the new interface.
1. https://softengbook.org/articles/deep-modules
Docs is already a notoriously under-prioritized and often rotting part of software projects. Making it more complex and larger to maintain and update doesn't feel like the right solution.
Nested markdown or restructured-text or asciidoc is pretty good workflow already to re-use blocks, link to different pages, or do some rich formatting like collapsible sections.
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] https://blog.tombert.com/Posts/Technical/2026/04-April/Stop-...
I realize I've been doing this as part of working with agents heavily the last few weeks. The issue is remembering to have it write and keep them up to date. One thing I've been considering is using a Claude Hook[1] when the session ends to basically "update readme and todo from this session. only change them if needed" or something similar
I have found a lot of value in the approach the post describes. I store my markdown as GitHub issues, regardless of how I come up with a detailed feature description (usually a chat session).
Before implementation, context is always cleared to ensure that the model is working only from known context (skills, AGENT.md, etc).
A major benefit of this is that agents can look up prior prompt instructions as needed or when mentioned in the current prompt it's working on.
I recently described my workflow here https://jaisenmathai.com/articles/sojourn-for-ios-was-45-one...
Developer documentation in /src, yes. Anything else, no way.
IME developers have low tolerance for interrupting flow to track down the docu that is aimed at them, so keep it near and obvious.
Docs in VCS, yes. Docs in /src, no.
You missed the entire point of the post..the author is arguing docs in md are the src...
I still like the idea of source code as documentation and unit tests as documentation. While revising code written by an LLM to make it easier for humans to understand is now a controversial practice, I believe it's worthwhile in a lot of case.
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 app run to have a LLM-compatible historical record of how each component changed visually. And the token provider billing documents, since we’re gonna have a lot of those once we’ll start maintaining all that.
So
1. he's describing a manual version of Spec-Kit / OpenSpec / BMAD?
2. Thinks Markdown is... somehow different from normal text or other markup languages?
3. Doesn't seem to understand that LLMs are not deterministic?
1. he is saying md/english is the new source code.. 2. yes - it is different that is geared towards english and very well supported by LLMs that is why it is being used in memory and instructions 3. llms are deterministic enough to translate adequately described specs into working system, the idea here is reason in md for core flow etc, and then verify with test cases
this not perfect but he is describing a real trend, so listen with open mind.
This sounds a lot like a low tech version of Delta from Zed. All your agent transcripts live in the same place as code.
src/md doesn’t seem all that different from docs. Maybe it changes how people search the filesystem, though?
If you split code up into multiple packages, moving the docs closer to the code might make sense. The docs for package foo could be in packages/foo/docs.
> Markdown is becoming source code, not documentation
> That Markdown should be checked in to /src
I've made a similar argument last June, although I made the point with a sample project rather than manifesto style
https://github.com/TZubiri/keyboard-transpositions-checker
> A Proof of Concept for LLM as source code. I am of the position that the "code" is now target code and not source code. My strongest source for this claim is Stallman's classical definition of Source Code which is the "preferred way to modify the program".
> Upload the conversation with ChatGPT as source code
Although this was pre-agents/markdown, the main way to generate code was just with user-interface conversations with the LLM.
And my position differs in which I argue against uploading the target code, just the source code. Which is an issue if the LLM is not deterministic, but it's workable.
That said I apparently did foreshadow solutions to these issues
> Since we are using a consumer interface, and not an api, (first we have no guarantees that the code will not be used for training, so there's no IP protection, but also), we don't have much reproducibility, robust publishing should use API access and publish exact model with revision as well as seed (and even then we are not guaranteed reproducibility.
I think in general we'll end up rewinding so much, the sloppers are recursing and building a ton of harnessing tools that will need to be trashed because they made a fundamental mistake at the very first steps. Those of us who are a bit more careful will probably only get back to agentic engineering once the slopper activity dies down, it's pretty much career suicide at this point to get into it. Anyone who is barely careful is just waiting it out.