> Why is the vibecoding crowd still holding onto the idea that markdown (or here yml) is a better spec then code?

From your comments it sounds like you are oblivious to the whole problem domain.

The whole point of these tools and frameworks is to provide a high level description of not only what features are already implemented in a project but also and more importantly what features you want to implement.

To put it in simpler terms, the point is to write down high level specs in a way that coding assistants can parse them and implement them.

I recommend you research spec-driven development, a whole set of frameworks designed to put together specs in a way coding agents can roll out plans to implement features in one-shot or few-shot prompts.

You know, what specs are used for.

> To put it in simpler terms, the point is to write down high level specs in a way that coding assistants can parse them and implement them.

I have never seen a non-trivial product that didn't have the spec modified during development due to finding rare business edge cases when actual implementation happened.

It's a fantasy to think that all you need to do is give an agent a spec; every team I have been on over the last 30 years have needed to refine the spec while developing.

That's the whole reason for Agile in the first place.

Oh I've researched it and did two projects entirely like that, both scaled to 150k loc and I believe 90k loc last summer to fall.

That approach just doesn't scale unless you don't care about your product whatsoever, hence my comment

I've successfully been working on various personal projects with highly stable functionality since I stopped that approach and instead focused more into leveraging my codebase to become the spec.

Very low maintenance and great to add features after the initial hurdle of structuring your codebase that it's less about implementation detail and more about spec. So a lot less "smart" code and less highly advanced abstraction, and a lot more declaratively structured - boring and potentially repetitive, but easier to place good AGENTS.md and doctexts on areas which have requirements which may be unclear just from looking at the code for example. Then running multiple "QA" agents over the diff before you look at it yourself for the final review

So yeah, sorry but your imagination is running wild