How Detailed Should Specs Be?

#357: Type a prompt, get code, fix the hallucinations, type another prompt. That is vibe coding, and it is a fine place to start. It is a terrible place to stay. So what comes next - and is spec-driven development actually it, or just waterfall wearing a new hat?

Here is the reframe that runs the whole conversation: everybody already works from a spec. Even the person who swears they are winging it has a spec in their head - which language, where it runs, what it does. The real question was never specs or no specs. It is whether you write them like waterfall, one giant document before anyone touches code, or like agile, just enough to start and the rest discovered as you go.

A design is only validated when you implement it - everything before that is an educated guess. So instead of spending a month on one detailed design, build five throwaway MVPs in a day. Fully operational. Frontend, backend, running in a cluster, connected to a database. Show them to customers. Pick the one that works. Then have the agent write the spec from the winning code, and throw the code away. The spec is the output, not the input. A PowerPoint took you a month and told the customer nothing. A working thing they can touch tells you everything.

Viktor and Darin push on where this breaks. Over-specifying gives you a false sense of security - you are lying to yourself that you know everything up front, and you do not. Legacy systems? The code is the only complete spec - any document written thirty years ago is fiction. Performance? Measure it in production and be lightning-fast to react. Greenfield, CRUD, clear API contracts - those genuinely want a spec first.

The part nobody on the org chart wants to hear: this does not delete the business analyst or the developer. It collapses the roles. The code monkey who pulls a Jira ticket, does the work, pushes it - that job is turning into tech lead, architect, product manager, all at once. Plan mode writes the spec with you, not for you. You write it to a file because you cannot review what you cannot see. And you review the tests harder than the code, because the tests are the spec made executable. Specs were always supposed to be living documents. Now there is finally no excuse.

YouTube channel:

https://youtube.com/devopsparadox

Review the podcast on Apple Podcasts:

https://www.devopsparadox.com/review-podcast/

Slack:

https://www.devopsparadox.com/slack/

Connect with us at:

https://www.devopsparadox.com/contact/