Join the discussion
Write your take first — we'll ask for email only when you're ready to publish.
- Hacker News
- 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.
by baldvinmar - 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.
by sroerick - 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.
by fifferfaffer - 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.
- 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 past prompts etc.
For people who like this idea, or do something similar, how do you make use of prompts used to create code checked into your codebase?
I can see it valuable at the review stage, but if I was trying to trace-back a regression to a previous commit, I feel like I already have enough noise without this attached.
by benrutter - 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.
by ktpsns - 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.
by xg15 - 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.