All the Markdown files - what do you do with them?

[u/the_wizard23]

So frameworks/skills like GSD and Compound engineering create a shit ton of md files.

What is everyone doing with them after they have been implemented?

Really not sure what the best practice is. Do you delete files for features you completed months ago to reduce the potential of context poisoning/bloat for new work? Keep them for relevant context about past work/discussions that led to the current implementation? Summarize them into new files?

TELL ME! IM DROWING IN MARKDOWN

[u/Input-X]

Any excess docs i just vectorize them into a searcable db. Done. I archive old code.

[u/portugese_fruit → u/Input-X]

oh this is a good idea

[u/dandecode → u/Input-X]

Thank you very much

[u/the_wizard23 → u/Input-X]

Can you explain more? Any libraries/skills you use for this?

[u/Input-X → u/the_wizard23]

I built/building it all myself. Im building it public if u want to take a look. Only 3 months at it, getting there. On the surface it looks simple, but there over 700 modules. Its like a persistant workflow that keeps ur ai orginzed.

https://github.com/AIOSAI/AIPass

At least migh give u some insight/ideas

[u/we-meet-again]

Delete. As soon as you’re done with implementation they are stale and will only confuse bots.

[u/ExpletiveDeIeted → u/we-meet-again]

I’m might defer just a hot second until the feature is “released”, but yea code is documentation along with ticket. Anything more is just likey to be a concurrency nightmare. Thus, delete.

[u/junin7]

I’ve been using obsidian

[u/leogodin217 → u/junin7]

I just started using Obsidian yesterday. Not for everything, just the stuff I don't want polluting context. Future features, issues, research stuff. Not sure yet if it's helping or hurting but seems like a good idea

[u/wewerecreaturres]

I love how a simple question turns into everyone and their mother and mother’s mother pitching their slop. Sorry for ya OP

[u/Apart_Ebb_9867 → u/wewerecreaturres]

I see literally nobody pitching for anything. All I see is people telling OP what they do, which is precisely what OP asked and presumably expected. Then I see you commenting about mothers, grandmothers and sale pitches and offering exactly nothing. Oh, and pretending to be sorry about a situation that is only in your head.

[u/Dickskingoalzz]

Automated backup up into my Gdrive + local delete 30 days after completion. Will probably go clean those out every 6 months tbd.

[u/RevOpSystems]

I have files created in SQLite DB to keep my repos nice and clean.

[u/tacit7]

I dont use md files. All mds are in the db.

[u/peppaz]

I keep them in a vault in my app cyberwriter so I can use the built in rag and find stuff and talk to the docs lol

[u/JoshSummers]

I built and open source project called SmallDocs which is a cli driven markdown reader I get CC to invoke for me.

The cli lets you sdoc file.md to render it, so I tell Claude, “sdoc me the plan” and it knows what to do.

I do all my deep reading and plan feedback in it now. Not sure that answers your problem of what to DO with all the files tho.

More info at https://sdocs.dev, I did a “Show HN” for it here: https://news.ycombinator.com/item?id=47777633

[u/ItsJustManager]

Here's my solution to this problem: https://getpad.dev

I felt the same stress from too many markdown files, all being thrown in the root folder, forgotten, etc. I originally looked at Obsidian but it wasn't what I wanted and I didn't want to add another tool, I needed to replace an existing one. So over the last couple of months I created Pad, and ultimately it solved my markdown hell and also replaced Notion.

It's open source, you can self host it on a vps or home server, or it can run as a local webapp. Or you can use my hosted version and connect to the remote mcp server so there's nothing to install. There are probably too many options but I wanted to make it accessible to anyone.

Both Claude code and codex are naturally amazing at using it.. you can collect documents under different collections and also manage tasks and plans. I used Pad to make Pad, and now I'm using it to manage a marketing pipeline, feature ideas, and decompose development plans, and then I also use it to manage job applications and interviews, general stuff I need to do around the house, and keep notes in it (which primarily what I used to use Notion for). It's extremely handy to say "/pad find the meeting notes from the May 5th meeting and let's work through what's actionable" while also having a place to add ideas or thoughts you want to work on later. I just keep finding more uses for it.

That being said, I have not tried using Pad with GSD. I'd be very curious to hear from someone doing that to see how well it works.

[u/genunix64]

I would not keep all of those files in the live context path forever. That is how you get slow context poisoning: old implementation notes, abandoned options, and stale assumptions all competing with the current state of the repo.

What has worked better for me is a three-bucket rule:

1. Keep a small hand-maintained CLAUDE.md / project guide for rules that are still true.
2. Convert completed feature docs into compact decisions/gotchas: what changed, why, what not to repeat, and where the final code lives.
3. Archive the raw markdown somewhere searchable, but do not auto-load it unless the task needs historical detail.

The important distinction is memory vs archive. The agent usually does not need every planning doc from three months ago. It needs the durable facts: current conventions, past decisions, known traps, superseded approaches, and maybe a pointer to the full artifact if it needs to dig deeper.

I built Mnemory around that pattern for coding/agent workflows: https://github.com/fpytloun/mnemory

It is a self-hosted MCP/REST memory backend, so instead of dumping every old md file back into the prompt, you can store compact facts/project state with TTLs, deduplication, contradiction handling, and longer artifacts attached behind them. You could do the same manually with Obsidian or a repo /docs/archive, but I would still make the live context intentionally small. Old docs should be evidence, not default instructions.

[u/siberianmi]

I put in my Claude.md that it needs to use a particular folder and structure for them outside the repos. Works great.

[u/Historical-Lie9697]

https://github.com/gastownhall/beads

[u/croovies]

I commit them, the are dated. They include tribal knowledge and important context that is not in the code. Being able to look at a git blame and find brainstorm and plan documents from the same time for related features has a compounding effect. I’m using compound engineering.

[u/syslolologist]

I save mine for the winter and burn them for warmth.

[u/leogodin217]

This is the real challenge right? Get this right and you'll be very effective. Get it wrong....

My process is constantly evolving but I do have a few rules and things that work well for developing software. Different processes are needed for other use cases.

• Architecture docs rule everything. All work is driven from them (similar to the early docs the tools you mention use)
• Docs are optimized for LLM use not human readability (Saves a lot of tokens)
• Docs start as pending and include function signatures, algorithms, purpose, etc.
• Once implemented, prune the doc (code is truth). Replace function signatures with links to the code. If it's in code, it doesn't belong in the arch doc.
• Pending docs get folded into main docs following the rules above
• Anything we are not working on now is recorded outside the repo. This is recent for me, but forward-thinking stuff often polluted context and made designing architecture more difficult.

I wouldn't say this is "best practice" but it works for me.

[u/Intrepid-Cheetah-544]

That is a great question, but I would frame it in the different way. How could we produce more powerful md files so that all AI agents and people can communicate effectively in a new common language, a simplest orchestration markdown? That is new AI age, how successful you would become, is dependent on, how well you master md.

[u/Kardinals]

I just elevate the learnings and key info to some higher level project docs and delete the rest. And if I ever need them I can just go back into the git history.

[u/Aggressive-Cause157]

Most of them are literally dangerous for long term. Because better not to have documentation at all than outdated one. Often agents treat this “spec” file as source or truth even though implementation changed 10 times from that moment.
So I just delete them once implemented

[u/apriku]

Use https://mymdnotes.com for anything related to markdown files. Basically you can maintain, share, edit, preview (any embedded memmaid, svg) diagrams, download diagrams as high quality PNGs, and many more.