Your agent wrote 300 lines of code last night, and it works. It passes the tests you wrote, yet it does something completely different from what you wanted. 

The model is not the problem here, because your prompt was a vague thought, so a vague thought is what got built.

Spec-driven development closes that gap. You write the spec first and the agent executes against it, reading the spec as the source of truth before it touches a single file.

Before We Begin

Three things break when you skip specs:

Intent drift.

"Add login" means one thing to you and something else to your agent, then a third thing again to the version of you who reopens the project next week. The agent fills the gaps with reasonable defaults, and those defaults are almost never what you meant.

By the time you notice, the implementation is already three layers deep.

Context decay.

As your codebase grows past the agent's effective working memory, it starts forgetting earlier decisions and silently contradicts them. You end up with two auth patterns and three different ways to handle errors, none of it consistent.

No verification gate.

Without explicit acceptance criteria, "does this work?" comes down to vibes, and code review turns into you reverse-engineering what the agent was trying to do in the first place. At scale, that is a tax that compounds.

A spec removes all three at once, sitting as the missing layer between human intent and machine execution.

A good spec has six elements.

1. Outcome (not features)

Start with what success looks like for the user, not what the system does.

This is the anchor that everything else in the spec works toward.

If an agent builds something that technically passes but never reaches this outcome, the failure sits in the spec.

2. Scope boundary (what's in, what's out)

This is the most underrated section, because agents love adding things you never asked for.

The "out of scope" list matters as much as the "in scope" list, so write both.

An agent without explicit boundaries will hallucinate features into existence, while the v1 label signals future intent without reopening current scope.

3. Constraints (your stack, your rules)

This is where you tell the agent what it cannot touch or assume.

Constraints stop the agent from "improving" your architecture while it solves your problem, and this section alone cuts roughly 80% of the rework on agent-generated code.

4. Prior decisions (what was already decided and why)

Agents have no memory between sessions, so this section is how you hand them institutional memory.

When an agent asks "why are you doing it this way?" this is the answer it should already have.

5. Requirements (in EARS format)

EARS, the Easy Approach to Requirements Syntax, came out of Rolls-Royce's aerospace work, and it is the best format I have found for writing requirements an AI agent can verify.

The basic pattern: WHEN [trigger], the system SHALL [response]

Five patterns to know:

The load-bearing word is SHALL rather than should or might, and that one word turns a preference into a verifiable contract.

A full requirements section for the password reset example:

Notice what this buys you: the agent can read "WHEN a user submits the form with an unregistered email, the system SHALL display..." and write a test for it before writing a single line of implementation.

6. Acceptance criteria (your verification gate)

These are the specific pass/fail checks the agent runs after implementation.

These checkboxes double as instructions: after implementing, the agent verifies each criterion by running the app and checking every item, and it does not mark the task complete until they all pass.

Here is a copy-paste template.

The spec is only as good as the prompt that delivers it, so here is the pattern I use:

The step 2 instruction, "list ambiguities before starting", is the highest-leverage line here, because it forces the agent to surface gaps before it fills them with guesses. 

Every gap it surfaces is one you get to close before the wrong implementation buries itself three layers deep.

A spec will not fix everything, and you need to know where it fails.

I spent 2 years watching agents go off the rails on features I thought I had described clearly, and the model was never the thing letting me down.

The EARS format is the single biggest upgrade I have made to my workflow. 

The "WHEN... SHALL..." pattern sounds formal, but it does one specific thing: it turns every requirement into a test the agent can read, fail against, and then write code to pass. 

The section people always skip is "out of scope," and that one section alone saves hours. 

An agent with no explicit exclusions will build the most complete version of what it understands you to want, which is the last thing you want on a deadline.

The prior decisions section changed how I work across sessions. 

Every time I catch myself explaining context to an agent that it should already have, that context belongs in the spec, which is your project's institutional memory.

The spec is really for you. 

Writing it forces you to answer the questions you were planning to defer until the code already existed, and those deferred questions are exactly where the expensive rework lives.

Write the spec, then let the agent work. 

The gap between a vague prompt and an executed spec is the gap between reviewing code and rewriting it.

Until next time,
Vaibhav 🤝🏻

If you read till here, you might find this interesting

#Partner 1

A US startup just hit a $1 billion private valuation, joining billion-dollar private companies like SpaceX, OpenAI, and ByteDance. Unlike those other unicorns, you can invest in EnergyX.

Over 50,000 people already have. So have industry giants like General Motors and POSCO.

Why all the interest? EnergyX’s patented tech can recover up to 3X more lithium than traditional methods. That's a big deal, as demand for lithium is expected to 5X current production levels by 2040. Today, they’re moving toward commercial production, tapping into 100,000+ acres of lithium deposits in Chile, a potential $1.1B annual revenue opportunity at projected market prices.

Right now, you can invest at this pivotal growth stage for $13/share. But only through July 16. Become an early-stage EnergyX shareholder before the deadline.

Invest in EnergyX

^{Energy Exploration Technologies, Inc. (“EnergyX”) has engaged Beehiiv to publish this communication in connection with EnergyX’s ongoing Regulation A offering. Beehiiv has been paid in cash and may receive additional compensation. Beehiiv and/or its affiliates do not currently hold securities of EnergyX.}

^{This compensation and any current or future ownership interest could create a conflict of interest. Please consider this disclosure alongside EnergyX’s offering materials. EnergyX’s Regulation A offering has been qualified by the SEC. Offers and sales may be made only by means of the qualified offering circular. Before investing, carefully review the offering circular, including the risk factors. The offering circular is available at invest.energyx.com/.}

^{Comparisons to other companies are for informational purposes only and should not imply similar results. Past performance is not indicative of future results. Market shortfall are forward‑looking estimates and are subject to substantial uncertainty.}

#Partner 2

Speak your prompts into ChatGPT or Claude and get detailed, paste-ready input that actually gives you useful output. Wispr Flow captures what you'd cut when typing. Free on Mac, Windows, and iPhone.

Try Wispr Flow free