Markdown in /src

Markdown in /src htmx.org

In this essay, Carson Gross argues that Markdown is now an important source artifact for software systems built with LLMs, and that, following the principle of locality, it should live in /src, alongside the code it…

155 points•perrygeo•9 days ago•99 comments•

#markdown #src #important #essay #gross #carson #argues #source

99 comments

aDyslecticCrow8 days ago

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.

xg158 days ago

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.

aDyslecticCrow8 days ago

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.

boomlinde7 days ago

I am skeptical of adding anything but a brief description of the change, the reason for the change and possibly some explanation of non-obvious implementation choices to the commit message.

The reason is that the commit message log serves as an overview of the changes commited. That's what humans use it for, anyway: to get an idea of what happened since they last pulled, to help give an idea of where a regression might have been introduced and so on, at a glance. To that end, brevity is very useful.

My understanding is that chatbots used to perform such tasks will also benefit from brevity.

nothrows8 days ago

Couldn't agree more. Rot is rot. People hate reading giant verbose AI generated PRs. Imagine mandating your codebase requires people now also read AI generated markdown files to compare the AI intent with the AI outcome. What a laugh and this is the guy giving out CS degrees and opposing React.

viccis8 days ago

Already happens in my experience. I'll try to figure out why it keeps doing this one thing and it turns out it's from some poorly advised info it put in a markdown file 20 commits ago that CLAUDE.md or AGENTS.md tell it to treat as gospel.

aDyslecticCrow8 days ago

Weekly reminder to delete your memories folder that claude code loves creating over the most silly of information.

"yes claude i prefered the blue graph two months ago, how does thar help us with this json parsing bug?"

jsw977 days ago

You could in theory require consistency of the spec with the product, but this is only valuable as a “source” if you ensure some kind of reproducibility. E.g., 9/10 times this spec + opus produces code that is equivalent, measured appropriately.

Ok I already talked myself out of this idea.

xg158 days ago

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.

MayeulC8 days ago

I think that "machine translator" is a much better metaphor: there is a lot more to translating a text than there is to compiling code: contextual cues, cultural settings. Various translations can be equally valid. All translations are imperfect.

Now, if you excuse my ramblings, here are a few ideas: I think we probably need new "programming" languages that are actually specification languages: reproducible default states, deterministic spec-to-code transformation.

I am not sure we actually need the determinism, but that would be a good property to have. At least with the same model/spec/temperature.

Now, prompts mutate the spec, which can also be edited by hand. You can already do this with the final code of course, but it is tedious as it contains many trivial implementation details.

But then, how do you handle bugfixes that need to persist during re-generation? Such as "Both Foo and foo can be present in the same directory if the file system is case-sensitive". If you add them to the spec, you are micro-managing implementation details again. So I think such "bug fixes" should be part of a prompt/spec that is automatically loaded when generating similar snippets (here, file I/O). It feels like I've just reinvented the concept of software libraries, though.

benrutter8 days ago

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.

akazantsev8 days ago

> I think I'm with the majority of commenters here in thinking this would just wind up being clutter.

Any prompt-storing/sharing ideas floating around hit the same wall - they assume the text will be in English. It won't.

intrasight8 days ago

Prompts and LLM conversations have now become an important software artifact. I don't think the question should be whether or not to save them. They should be saved. The question is how to structure them in your folders and whether or not they should be part of the context for the LLM.

Our approach is to save LLM conversations but to not have them be part of the context.

boomlinde7 days ago

Do you think it is equally important to save complete transcripts of your deliberations with coworkers? If not, why not?

aDyslecticCrow7 days ago

> have now become an important software artifact

have they though? I feel like 50% of the chat history is gettin in the way of the model that just created it half the time, let alone any future LLM.

Humans wont re-read an old chat history either unless very desperate for clues.

The few valuable nuggets of information in the chat history can probably be summarize into 3 bullet points and put in the docs or in code comments.

I really dont see the value.

xg158 days ago

I think the question is still valid what you actually do with them once they are saved.

ktpsns9 days ago

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.

Rendello8 days ago

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.

throwuxiytayq9 days ago

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.

jasbury8 days ago

The author is really just advocating for design docs, which do make sense in a repo. LLMs are excellent at creating .md docs tracking design decisions, code architecture, trade-offs, etc. And these actually can be of great use to future contributors.

Read the full thread on Hacker News →

99 comments

Related stories