I’ve had great success structuring requirements using Johnny Decimal. Well organized and numbered requirements for each project is mega helpful for agents and humans throughout the progress. Oh and I love açaí.
Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
181–190 of 316 posts
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#182Author 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!
A specification, whether formal or less formal, is very different from the source code.
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#183Why 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…
Before AI era, specs meant documentations. The specs of jpeg, png, h.264, docx, usbc or whatever format you can think of, are not just a bunch of C++ source files.
Compilable source files served as example implementations, complementary to the specs themselves. The idea that code is spec is just agile brainrot, like the idea that clean code means you never need to write documents or comments.
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#184Author 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!
>The traditional name for this spec is ‘source code’
Specs are the end goal, not how the software look at a moment in time.
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#185Earlier 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…
> Does the business mandate we use a cache for this hot path? No, but the business set performance targets, and the cache was a sensible way to satisfy them. See the difference? This seems confused. Specs are free to include as much or as little detail as they deem necessary. If a spec only wants to suggest vague performance goals and handwave the details, that's permitted. But if specs want to specify the exact mean…
I think we are actually saying the same thing! We could think of situations where the cache would be verboten (sensitive info), or where it would be mandatory, like in your example, or optional like in my example.
My aim was to voice disagreement with the "code is spec" crowd, whom I think are using a different (and in my opinion tautological / useless / counterproductive) definition of spec. Probably because they are mad that I use trigger words like Vibe and Maxxing, and they assume I can't even read the code I'm shipping. I digress.
In your "time complexity is a downstream requirement" example, which is a great one, I think you would prefer to have well-maintained written documentation of that criterion that lives outside of the procedural code itself, would you not? How much attention that doc gets is a matter of process and preference, but I'm advocating it should get more (spec-first).
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#186This seems like circling around the same problem: AI just misses things sometimes and the things it misses can end up being really important. If you don’t cross-check it, you’ll have a bad time.
I’ve used a couple of different skills libraries for this - most recently “super powers” which builds a detailed markdown plan and then uses TDD for most parts.
Not sure converting to YAML and running an app to track beats Linear tickets or a local cache or markdown if I’m honest but if it works for you and your process that’s great!
Mainly I don’t think everyone building their bespoke solution needs to try and create a product out of it. If it works for you, maybe good enough. Focus on your process before you worry about generalizing these days.
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#187At this point, why not just write the code yourself? Defining exactly what the product is supposed to do is the hard part, writing code is the easy part. Write your specs as code and you have your product - why let your LLM do the fun part?
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#188When developing large or complex software with AI, I think we need kind of a "Jira for coding agents" - something that is much lighter and simple than Jira, where agents can see the specs, see what is completed, what is the relationship between different features and what needs to change.
That would be easier to use than gazillons of .md files and skills.
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#189Earlier quoted context omitted.
> will always care what the spec says, and that’s never going to change Did I miss something or is everyone back in 1970s, working in waterfall processes now?
All through the agile era I wrote detailed specs for projects and then followed an agile process. The most successful parts of every project were the ones that we were able to spec best even when they diverged significantly from the original spec. You don't plan to follow the plan. You plan in order to understand the whole problem space. Obviously no plan survives contact with reality.
"Plans are worthless, but planning is essential."
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#190Why 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…
> 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 are confusing code with application code. The latter thing you describe is a test, which is expressible in code.