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 the cache was a sensible way to satisfy them. See the difference?
I believe that the 'musts' and 'must nots' deserve special attention, and need to be recorded well before I decide on the 'how'. Every team does this differently. I find that writing itemized, functional acceptance criteria is practical way to marry the two domains. I also think the process matters a lot more now, because the temptation to let an agent ship it is increasing and the tedium of maintaining these specs is decreasing.
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 means by which performance will be guaranteed, that's also permitted. And this isn't an anti-pattern, this is often very useful. For example, plenty of APIs in the real world specify algorithmic upper bounds for time and space consumption, which is useful in that they allow downstream consumers to have a greater understanding of what sort of performance their own systems will exhibit despite the API itself being a black box in other respects.
So the answer to the original question definitely isn't "no", it's "maybe, depending on the sort of guarantees we want to provide to our users".
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).
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.
Therefore, you must not use humans for any important work.
> 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".
You are confusing code with application code. The latter thing you describe is a test, which is expressible in code.
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.
When you want to build a bridge you finalize all the blueprints and then someone goes and actually pours concrete, in software the blueprint is the code, and the code is also the bridge.
However there are different levels of abstraction for writing specs and code is just the most explicit form. With LLMs more of our time can be spent in those higher levels of abstraction and free us from work that is often repetitive and mundane.
I think the (distant) future of software engineering is not code writing but mostly requirements writing, and so it makes sense to build frameworks, “IDEs”, etc. around this new form of “programming”.
I don’t know if ACAI is the right one but the direction is interesting.
Construction has plans "as designed" and "as built".
What is different now is that maintainability and debugging design decisions were made w.r.t. human coders or teams in the past which is not necessarily the case anymore. Should we just specify the API and let agents figure the rest or do we still want to control the rest to ensure maintenance and security? A year ago I definitely thought so. Now it is more murky as the agents are faster browsers of codebases and can explore runtime effects faster than I can type and parse output. Strongest empirical observations depend on the runtime behavior so they have an edge there.
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.
The core of the misunderstanding is between new builds and making changes to existing builds (where most software dev work actually happens). Yes, you'll get a great headstart with a detailed spec for a new build. The issue is in the hundreds of changes that'll follow that.
Do people think that the desire to make shortcuts and do minimum effort changes is going to stop just because you've got a bit-more-natural-language-looking spec? And then with an AI underneath making probabilistic changes to code that's now basically a compile target - they really think the dev pace isn't going to collapse, but just faster and with a big ongoing inference bill?
The LLM's do not form mental models. You are not going to get a better results from an LLM vibe coding against spec diffs vs a dev prompting it from a position of understanding the codebase and the requested change.
Having functional behavior and implementation details separate can be really useful, even though it is typically a pain to keep them in sync.
> "we never said this would work for everyone, it depends on the effort you put into it!"
it's perfect for extending the lifespan of a scam on someone because yes, obviously it's true that in general you can improve results by working harder, being more disciplined, whatever...
same here, functionally. of course there are better and worse ways of writing a spec, a prompt, etc. but i honestly think a lot of the focus on this is a way to divert attention from the overall ceiling of these tools in general.
in other words yes, it's not all bullshit, but there's a huge aspect of this "prompt/spec engineering" that in my view is a way to unconsciously buttress the "LLMs are going to 10x our GDP" mindset -- if those high expectations aren't panning out, there's always:
> "we never said this would work for everyone, it depends on the effort you put into the spec!"
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.
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.
So yeah, sorry but your imagination is running wild
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.