Writing a spec for a developer is a skill most founders learn the hard way, usually after getting back something that technically matched what they wrote but was not what they wanted. A good spec threads a needle: it describes what you want built and why it matters clearly enough that the developer builds the right thing, while leaving the how, the technical implementation, to them, because that is their expertise. The two ways specs fail are opposite: a vague spec that is so unclear it guarantees you get the wrong thing, and an over-specified one that dictates technical decisions you are not equipped to make and wastes the developer's judgment. Aim for clear on the what and why, open on the how.
Key Takeaways
- A good spec describes what you want and why, clearly.
- Leave the how, the technical implementation, to the developer.
- A vague spec guarantees you get the wrong thing.
- An over-specified spec wastes the developer's judgment and expertise.
Be Clear on the What and the Why
The core of a good spec is a clear description of what you want and the reason behind it. What is the feature or product supposed to do, from the user's perspective? What problem does it solve, and what does success look like? The why matters as much as the what, because a developer who understands the goal can make good decisions in the gaps your spec inevitably leaves, and can flag when what you asked for would not actually serve the goal. Vagueness here is fatal: if the spec does not clearly convey what you want and why, the developer will fill the ambiguity with guesses, and you will get something that matches the words but misses the intent.
Leave the How to Them
The complementary discipline is restraint about implementation. The how, which technologies, how the code is structured, the technical approach, is the developer's domain, and a non-technical founder specifying it is both overstepping their expertise and wasting the developer's. A spec that dictates technical decisions ties the hands of the person you hired for exactly that judgment, and often specifies the wrong thing because the founder lacks the technical context. Describe the what and the why thoroughly, and trust the developer with the how, which is what you are paying them for (how to manage a developer remotely covers the ongoing version of this balance).
| Good spec | Bad spec |
|---|---|
| Clear on what you want | Vague, ambiguous goals |
| Explains why it matters | Leaves out the purpose |
| Leaves the how to the developer | Dictates technical implementation |
| Enables good judgment | Wastes the developer's expertise |
A Concrete Version
You need a feature built and sit down to write a spec. The vague version says something like build a way for users to save their work, so open-ended that the developer has to guess at almost everything and likely builds something that misses what you actually pictured. The over-specified version dictates the database structure and technical approach, decisions you are not equipped to make and that tie the developer's hands. The good version describes clearly what the saving feature should do from the user's side and why it matters to them, while leaving how to build it to the developer. They understand the goal, make sound technical choices in the gaps, and build the right thing, because you were clear on the what and why and trusted them with the how.
The Honest Counterpoint
Leaving the how to the developer assumes you have a trustworthy, capable developer, and the balance shifts if you do not. With an unproven or junior developer, more detailed guidance may be warranted, and some constraints, an existing tech stack you must integrate with, real requirements around security or compliance, genuinely belong in the spec even if they touch implementation. The principle is not that founders should never mention anything technical, but that they should not dictate technical decisions they are not equipped to make, and should convey real constraints as constraints rather than prescriptions. Clear on the what and why, open on the how, with genuine requirements stated, and more guidance where the developer is unproven.
The Bottom Line
Writing a spec for a developer means being clear on the what and the why while leaving the how to them. Vagueness guarantees you get the wrong thing, because the developer fills ambiguity with guesses, and over-specification wastes their judgment by dictating technical decisions you are not equipped to make. Describe thoroughly what you want and why it matters, state genuine constraints as constraints, and trust the developer with the implementation you hired them for. Clear on intent, open on execution, and the developer builds the right thing instead of merely matching your words.
Roberto Espinoza is CEO of Ruzora, which helps US startups hire pre-vetted senior LATAM engineers, with a vetted shortlist in 72 hours. See available engineers.
