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.
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.
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.
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.
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 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.
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.
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.
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-...
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...
IME developers have low tolerance for interrupting flow to track down the docu that is aimed at them, so keep it near and obvious.