Markdown in /src

by perrygeo on 9/21/2026, 10:47:54 PM

https://htmx.org/essays/markdown-in-src/

Comments

by: aDyslecticCrow

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.

9/22/2026, 9:29:16 PM

by: benrutter

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.

9/23/2026, 9:11:48 AM

by: xg15

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.

9/22/2026, 9:29:15 PM

by: ktpsns

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.

9/22/2026, 5:52:21 AM

by: sroerick

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.

9/22/2026, 10:22:18 PM

by: fifferfaffer

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. <a href="https://searchfox.org/firefox-main/source/js/public/RootingAPI.h#33" rel="nofollow">https://searchfox.org/firefox-main/source/js/public/RootingA...</a>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.

9/22/2026, 8:50:35 PM

by: baldvinmar

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.

9/23/2026, 12:00:29 AM

by: tombert

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] <a href="https://blog.tombert.com/Posts/Technical/2026/04-April/Stop-Pushing-AI-Generated-Code-to-Git" rel="nofollow">https://blog.tombert.com/Posts/Technical/2026/04-April/Stop-...</a>

9/22/2026, 8:55:12 PM

by: allknowingfrog

You have to track the thing that you expect humans to understand. I still prefer for the code to be that layer, and yet somehow I'm still employed and overseeing a profitable codebase. The software industry is vast and varied.Essays of this nature should generally be prefixed with "if you happen to work in exactly the same way that I do..."

9/22/2026, 10:34:56 PM

by: aslakhellesoy

This aligns 100% with the philospohy of Varar (<a href="https://varar.dev" rel="nofollow">https://varar.dev</a>).In-between all those ephemeral agent sessions, spec, plan and design files, there is something that survives. The src/*.md files.With Varar you can link small parts (cells) of those Markdown files to your code, so they stay in sync. So you (and agents) can find out what your system does without reading 300 million lines of code.Full disclaimer: I am the guy who wrote Cucumber - that most people here hate. I eventually lost my love for that tool myself, but I did miss the ability to keep docs and code in sync. Hence Varar - a tool like that with fewer (different?) warts, for the agentic area.

9/22/2026, 10:43:59 PM

by: jmathai

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 <a href="https://jaisenmathai.com/articles/sojourn-for-ios-was-45-one-shot-prompts/" rel="nofollow">https://jaisenmathai.com/articles/sojourn-for-ios-was-45-one...</a>

9/22/2026, 12:24:42 PM

by: divbzero

Instead of the proposed /src/md convention:<pre><code> src/ md/ README.md # index of all md, entry point for agents TODO.md # a list of general TODOs open for this module OVERVIEW.md # a technical overview of this module features/FEATURE_1.md # a set of feature-specific documents data/DATAMODEL_1.md # descriptions of data models in the module api/API_1.md # descriptions of APIs the module provides infrastructure/INFRASTRUCTURE_1.md # descriptions of infrastructure used by the module </code></pre> What if we standardized on README.md in each subdirectory alongside the code?<pre><code> src/ README.md # entry point for humans and agents TODO.md # list of general TODOs open for this module INFRA.md # descriptions of infrastructure used by the module api/ README.md # descriptions of APIs the module provides models/ README.md # descriptions of data models in this module </code></pre> README.md in each subdirectory seems to align better with OP’s objective “that Markdown should be checked in to /src, next to the code it produces”. It is also a convention already in use in many code repositories.

9/22/2026, 11:09:07 PM

by: philipodonnell

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 think next to the source but away from the others is a good combination.

9/23/2026, 12:02:11 PM

by: maxk42

Docs in VCS, yes. Docs in /src, no.

9/22/2026, 8:13:20 AM

by: thatguy89

So1. 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?

9/22/2026, 2:46:19 PM

by: euroderf

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.

9/22/2026, 10:17:04 AM

by: jdzikowski

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. <a href="https://softengbook.org/articles/deep-modules" rel="nofollow">https://softengbook.org/articles/deep-modules</a>

9/22/2026, 9:07:44 PM

by: je42

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 <a href="https://mdsmith.dev" rel="nofollow">https://mdsmith.dev</a> to specifically do that. Includes tooling for progressive disclosure, etc.

9/23/2026, 5:46:40 AM

by: esalman

Markdown in /src comes with some unwelcome assumptions.This is being done with an agent-first approach in mind. Agents cost a lot to run. Moving markdown to /src will only help AI subscription sellers.If you are a fan of local LLM, then you also know code is not cheap. It requires substantial amount of investment in infra acquisition and maintenance.Markdown should be where they always were, in /docs. It does not make a difference for an agent. But it allows to keep /src clean and adhere to zero-token architecture.

9/23/2026, 1:54:59 AM

by: cobychapple

Directionally similar discussion to the goals of Open Knowledge Format (OKF) markdown bundles, by the sound of it? See <a href="https://okf.md" rel="nofollow">https://okf.md</a> and <a href="https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md" rel="nofollow">https://github.com/GoogleCloudPlatform/knowledge-catalog/blo...</a>

9/23/2026, 3:26:07 AM

by: maarut

In many apps I've built, every decision is stored in Markdown files under docs/. But documentation can become obsolete, even comments inside source files can.I assume src/ is treated as the source of truth. If we start placing Markdown documentation inside src/, outdated documentation can live alongside the actual source of truth, blurring the boundary between what the system actually does and what the documentation says it does.

9/23/2026, 2:07:39 AM

by: mcrk

I wonder how would this work in an international dev teams. While code is always the common language (including the UML), markdown requires you to have really good english writing skills. This can get messy really fast.

9/23/2026, 7:25:07 AM

by: throwuxiytayq

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.

9/22/2026, 7:06:49 AM

by: arthurjj

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

9/22/2026, 9:36:03 PM

by: Naru41

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.

9/22/2026, 10:29:56 AM

by: recursivedoubts

Hi there. I wrote this as a bit of speculation since I'm seeing more and more agent based coding in my consulting.One thing to say given some of the comments here: in this approach the stuff in /src/md would be treated as well as stuff in /src/java or whatever: it would need to be maintained as precisely as possible, not just be a stream of development record of what has happened.I'm also happy to consider that Markdown might not be the right format for this, or that the whole thing is a terrible idea. But I see people saving content in other places (linear, etc.) that drive agents and it just seems like maybe we should keep that stuff close to the generated source.

9/23/2026, 12:19:49 AM

by: kderbyma

They should track SemVer....the bot should know what version applies to both the spec and the product scope....these are solved problems :/

9/22/2026, 10:39:10 PM

by: undershirt

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.

9/22/2026, 10:11:17 PM

by: tancop

This sounds a lot like a low tech version of Delta from Zed. All your agent transcripts live in the same place as code.

9/22/2026, 7:07:31 AM

by: Sha1rholder

That kinda like what delta.dev is trying to do.I don't like it though.

9/23/2026, 4:06:41 AM

by: skybrian

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.

9/22/2026, 11:20:23 AM

by: 2001zhaozhao

Isn't it better to do inline code comments, e.g. JavaDoc?

9/22/2026, 10:36:25 PM

by: bbor

Interesting article, and I generally agree! And I'm just thrilled it's being discussed at all, as a MyST superfan. That said, a few quibbles I'd be curious to hear thoughts on:First, none of this changes the need for a separate `/docs` dir, also checked into git. Wikis are fun, but docs are essential!Second, I personally think the new paradigm will be putting all of this into tons of new README.md files, which I'm kinda baffled aren't more common deep into dir hierarchies already. That intuitively tells the human authors and the artificial readers that;A) it toes a similar "for technical people but not necessarily just our dedicated engineering team" line as the root README --more formal than an ephemeral "prompt" and less formal than a user-facing doc,B) this isn't the AGENT.md file so should remain human-authored only,C) this is only an overview with a strong preference for brevity & clarity, andD) this is focused on this specific directory (along w/ the other benefits of locality, as the author extolls already).Have I cracked the code? Is there a Turing award for inventing the concept of using a tool we already use but just a bit more extensively -- or at least a YC slot?*P.S.* OP you dropped this: )

9/23/2026, 1:52:00 AM

by:

9/22/2026, 9:13:39 PM

by: insin

As the CEO of Terrible Ideas, I approve this take.

9/23/2026, 11:18:56 AM

by: wabstractions

[dead]

9/23/2026, 4:38:51 AM

by: jocelyner

[dead]

9/23/2026, 1:55:10 AM

by: TZubiri

> Markdown is becoming source code, not documentation> That Markdown should be checked in to /srcI've made a similar argument last June, although I made the point with a sample project rather than manifesto style<a href="https://github.com/TZubiri/keyboard-transpositions-checker" rel="nofollow">https://github.com/TZubiri/keyboard-transpositions-checker</a>> 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 codeAlthough 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.

9/22/2026, 9:43:11 PM

Top 20

Markdown in /src

Comments

by: aDyslecticCrow

by: benrutter

by: xg15

by: ktpsns

by: sroerick

by: fifferfaffer

by: baldvinmar

by: tombert

by: allknowingfrog

by: aslakhellesoy

by: jmathai

by: divbzero

by: philipodonnell

by: maxk42

by: thatguy89

by: euroderf

by: jdzikowski

by: je42

by: esalman

by: cobychapple

by: maarut

by: mcrk

by: throwuxiytayq

by: arthurjj

by: Naru41

by: recursivedoubts

by: kderbyma

by: undershirt

by: tancop

by: Sha1rholder

by: skybrian

by: 2001zhaozhao

by: bbor

by:

by: insin

by: wabstractions

by: jocelyner

by: TZubiri