VIBE Anything. Specs > Code
The end goal of a programmer has never been the code; it has always been to solve a human problem through practical technology. The code is only the enabler.
With AI, code is no longer a capability barrier—AI can translate human language into machine language. Claude Code is a beast, Cursor is impressive... and they are all getting better super fast.
Specifications (Specs) are the documents where technical specialists determine how the output should be. They are the artifact that bridges intent and values, with the final result. And they're everywhere! Take the Constitution as an example of a national spec. The same applies in business: HR teams write Policies & Values, Marketing defines Brand Guidelines...
If you're already a spec contributor, then you're a programmer in someway. As a product manager, I've had to vibecode my entire website and build a side product for Clous. But I was already vibing in product—giving clear specs of features to the dev team.
This democratization of capabilities is changing how work is done and how organizations operate. In marketing, for example: the barrier to making graphic designs has been reduced enormously with Sora, Veo, and others. Can social media specialists go further? Or can designers move into strategy? So many questions to be solved. Entertaining times to live in!!
Specs Align Humans
Intentions and values change over time, so specs need to change too. They should be living document where every participant contributes. They are the democratic element that everyone can refer to.
Specs are nothing more than the result of that ongoing debate. And that hides their real power: to align stakeholders. Take code review as an example—it's less about solving bugs and more about mental alignment on the intended solution.
Markdown is the universal language because it's a structured way of communication that is both human- and machine-friendly. It's simple enough for anyone to write, yet precise enough for machines to parse and execute. This dual readability makes it the perfect format for specs—your PM, designer, and AI can all read the same document and understand exactly what needs to be built.
# Product Specification: User Dashboard
## Overview
A real-time dashboard showing user metrics and activity
## Requirements
- **Performance**: Load time < 2s
- **Data**: Update every 30s
- **Responsive**: Mobile-first design
## Features
1. Activity feed
2. Analytics charts
3. Quick actions panelStructured communication is the bottleneck
Since specs are the way to capture intent and values in detail so they can be executed. It means that to vibe anything, the process is always: communication first, execution second.
When development becomes faster, communication emerges as the new bottleneck. This was certainly our biggest problem when building Clous. We could ship faster than we actually did; validating, defining, and testing ideas was significantly slower.
How Structured Communication Looks:
- You talk with users to understand their problems.
- You distill these discussions and ideate concrete goals to solve those challenges.
- You plan ways to build those goals.
- You share those plans with colleagues.
- You translate those plans into code.
- You test and verify that the result matches your plans and achieves your original goals.
The teams or companies that master communication will have the biggest defensibility in the AI era.
Specs as a Judge
Just like the example of the constitution, the spec should serve to evaluate how the final product performs. That is why specs must be clear and executable. They are useful for:
- Evaluation: Determining how the output differs from the expectation. In AI engineering, this is often done using Evals to grade a model's response quality.
- Precedence: Specs or well-written system prompts can serve as behavior guidelines or examples, helping models understand edge cases and desired outcomes.
Why Specs Beat Code
Code is just a representation of the intent. Misalignment can cause serious damage—think of corporate 'broken telephone' or the butterfly effect. A single deviation can lead to a tremendous overall failure.
Specs are powerful because they are reusable across different scenarios. Executors are the ones who interpret those high-level intents and 'bring them down to earth.' This is the main reason why software engineers aren't going anywhere, even though everyone can program.
Dex Horthy illustrates this perfectly in this code example, showing how each layer of abstraction represents a layer of leverage. And it also explain where human should be focus. Not only because of the leverage effect, because of also for mental and team alignment.
Bad AI Responses Expose Our Flaws
As we have seen, obsolete or inaccurate documentation is the easiest way to slow your team down. With unclear specifications, you only have a vague idea. The way to improve is by observing the model's deviation. I love this tweet from Vishal Kapur:
One thing coding with agents does is it exposes how underbaked your thinking on the details of a product really are
— Vishal Kapur (@figelwump) June 5, 2025
They'll do some stuff that isn't what you wanted, and then you realize you never told it what you wanted, and maybe never fully understood it yourself
The model's responses expose precisely what desperately needs to be specified. It's common to believe that the model isn't capable or is 'dumb,' but the truth is that 90% of the time, you are giving it the wrong context, meaning that the bad response is due to the model has as input, inaccurate data, there is missing info or too much noise.
The bad response is the signal that you have not been clear enough, pointing what is not defined. The fact of not been able to explain ideas without ambiguite, show that we didn't have clear idea of what we want. That why the expose our flaws.