Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML • Hacker News Board

Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML

#171

Post by fragmede » Sun, May 03, 2026, 12:20 PM UTC

Twey wrote: post #130

brendanmc6 wrote: post #2

Author here, if you don't want to read all that, I'll post one excerpt that I think sums it up nicely: > My point is, the spec must live somewhere, even if you don’t write it down. The spec is what you want the software to be. It often exists only in your head or in conversations. You and your team and your business will always care what the spec says, and that’s never going to change. So you’re better off writing it…

The traditional name for this spec is ‘source code’ — a canonical source of truth for the behaviour of a system that is as human-readable as we know how to make it, that will be processed by automated tools into a less-readable derived artefact for a computer to execute. Checking the compiled artefact into the codebase without checking in its source code has always been a risky move!

Technology evolves and traditions change. What persists is the role, not the filename and its extension. Weddings are still weddings even after things went from painted portraits to film cameras to camcorders to smartphones to livestreams. Same with birthdays. Cards became phone calls, Facebook wall posts, group chats, shared albums, or generated videos (Sora, RIP).

The tradition of having a deck of punch cards evolved to having assembly, to Pascal, Fortran, C, basic. The important part is a human-auditable directive, not an opaque, generated artifact as the thing that matters.

have evolved and adapted. Photography, film cameras, polaroids, camcorders, digital cameras, smartphones, social media, Zoom/virtual attendees. Same with birthdays. Handwritten cards, to phone calls to e-cards, Facebook wall posts, video calls, shared photo albums and Sora (RIP) videos.

Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML

#172

Post by smokel » Sun, May 03, 2026, 12:26 PM UTC

Quite some people here dismiss requirements engineering as something non-agile and ancient.

If you are in this camp, consider educating yourself a bit on the V-model [1] and notice that this is not only used in the waterfall model, but that it is a way to decompose problems and verify that everything works properly.

This may not be required for a small hobby project, but if you start working at something with multiple companies in various technologies, it soon becomes extremely useful.

[1] https://en.wikipedia.org/wiki/V-model

Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML

#173

Post by soma8088 » Sun, May 03, 2026, 12:26 PM UTC

ffsm8 wrote: post #134

Why is the vibecoding crowd still holding onto the idea that markdown (or here yml) is a better spec then code ? Seriously, it's just not Write your code like it's your spec and your software will be more stable, maintainable clearer to read. Code is not transient, it is your friggin spec itself And if your code isn't structured like it's a spec, then your code is garbage from the perspective of LLM driven developmen…

This may hold true for greenfields, a little harder to do with a million line, 15 year old legacy code base. Good luck with your credits watching your agent churn those those files over and over and over for each request.

Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML

#174

Post by locknitpicker » Sun, May 03, 2026, 12:27 PM UTC

ffsm8 wrote: post #134

Why is the vibecoding crowd still holding onto the idea that markdown (or here yml) is a better spec then code ? Seriously, it's just not Write your code like it's your spec and your software will be more stable, maintainable clearer to read. Code is not transient, it is your friggin spec itself And if your code isn't structured like it's a spec, then your code is garbage from the perspective of LLM driven developmen…

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

Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML

#175

Post by ffsm8 » Sun, May 03, 2026, 12:29 PM UTC

soma8088 wrote: post #173

ffsm8 wrote: post #134

Why is the vibecoding crowd still holding onto the idea that markdown (or here yml) is a better spec then code ? Seriously, it's just not Write your code like it's your spec and your software will be more stable, maintainable clearer to read. Code is not transient, it is your friggin spec itself And if your code isn't structured like it's a spec, then your code is garbage from the perspective of LLM driven developmen…

This may hold true for greenfields, a little harder to do with a million line, 15 year old legacy code base. Good luck with your credits watching your agent churn those those files over and over and over for each request.

And are you seriously suggesting you'll be able to do spec driven development via markdown files in that? If not, then you're missing the point entirely.

I very explicitly stated that if your codebase isn't written like a spec you cannot effectively use it for LLM driven development.

You can still edit the code via LLM, it's just always going to be a highly involved process with very careful reviews unless you're happy with regressions.

Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML

#176

Post by bdcravens » Sun, May 03, 2026, 12:30 PM UTC

ffsm8 wrote: post #134

Why is the vibecoding crowd still holding onto the idea that markdown (or here yml) is a better spec then code ? Seriously, it's just not Write your code like it's your spec and your software will be more stable, maintainable clearer to read. Code is not transient, it is your friggin spec itself And if your code isn't structured like it's a spec, then your code is garbage from the perspective of LLM driven developmen…

It needn't be an either/or. I find writing pseudocode in a structured, but flexible, manner highly effective.

Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML

#177

Post by locknitpicker » Sun, May 03, 2026, 12:32 PM UTC

brendanmc6 wrote: post #150

ffsm8 wrote: post #134

Why is the vibecoding crowd still holding onto the idea that markdown (or here yml) is a better spec then code ? Seriously, it's just not Write your code like it's your spec and your software will be more stable, maintainable clearer to read. Code is not transient, it is your friggin spec itself And if your code isn't structured like it's a spec, then your code is garbage from the perspective of LLM driven developmen…

I think you are confusing the spec as "this is how it must be built", as opposed to, "this is what the software must do and must not do to be acceptable". To me saying "the code is the spec" is like saying "the business wants it this way because that's how the code is written". Which is obviously backwards. Does the business mandate we use a cache for this hot path? No, but the business set performance targets, and t…

> To me saying "the code is the spec" is like saying "the business wants it this way because that's how the code is written". Which is obviously backwards.

Not only is it backwards, it is a belief that is completely wrong and detached from reality. More often than not, implementations contrast with business requirements both in terms of bugs and gotchas.

Also, it's laughable how code is depicted as the realization of any spec when the whole software development sector is organized around processes that amount to improvising solutions in short iterations.

Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML

#178

Post by brendanmc6 » Sun, May 03, 2026, 12:39 PM UTC

karmakaze wrote: post #146

colinmarc wrote: post #10

Wow - I love programming in YAML! You know what would make this really fun? Sprinkle in some Jinja. Then we'll be cooking with gas.

I started reading to find out why Yaml? In it's place I found a great post. One thing though, I loved the "AUTH-1" numbering and the Yaml breaks that into an Auth section, with "1." subsection which I don't like nearly as much, the codification AUTH-1 is more referenceable/searchable.

Ah, I should have said explicitly or provided an example of in the post;

The tooling expects that you refer to each requirement by full ID e.g.

  # admin.AUTH.1

Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML

#179

Post by jychang » Sun, May 03, 2026, 12:40 PM UTC

lelanthran wrote: post #170

brendanmc6 wrote: post #150

Earlier quoted context omitted.

I think you are confusing the spec as "this is how it must be built", as opposed to, "this is what the software must do and must not do to be acceptable". To me saying "the code is the spec" is like saying "the business wants it this way because that's how the code is written". Which is obviously backwards. Does the business mandate we use a cache for this hot path? No, but the business set performance targets, and t…

> I think you are confusing the spec as "this is how it must be built", as opposed to, "this is what the software must do and must not do to be acceptable". You can't enforce a "do not do this" to an LLM. Just putting it in the context by saying "don't do this" makes it more likely that it will eventually do that.

Yes, I agree. If you tell humans "do not think of pink elephants", they are more likely to think about pink elephants.

Therefore, you must not use humans for any important work.

Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML

#180

Post by lelanthran » Sun, May 03, 2026, 12:44 PM UTC

jychang wrote: post #179

lelanthran wrote: post #170

Earlier quoted context omitted.

> I think you are confusing the spec as "this is how it must be built", as opposed to, "this is what the software must do and must not do to be acceptable". You can't enforce a "do not do this" to an LLM. Just putting it in the context by saying "don't do this" makes it more likely that it will eventually do that.

Yes, I agree. If you tell humans "do not think of pink elephants", they are more likely to think about pink elephants. Therefore, you must not use humans for any important work.

> Yes, I agree. If you tell humans "do not think of pink elephants", they are more likely to think about pink elephants.

> Therefore, you must not use humans for any important work.

Counterpoint, all important work done in the history of humans were done by... humans, and yet I see no pink elephants created as a result of telling humans "do not think of pink elephants".