Stop Prompting Your Agents. Start Specifying.

Why Spec-Driven Development is becoming the real interface between humans and AI agents.

AI agents have quietly crossed a line. They no longer just answer questions they write code, generate content, run research, transform data, call tools, edit files, and decide what to do next. The interface stayed the same, but the stakes changed completely.

Prompting is powerful for generative AI. For agent instrumentation and invocation, prompting alone is often too weak.

Give an agent a vague prompt and you can get a surprisingly confident but inaccurate result.

The problem usually isn't the model. The problem is the specification.

Prompting was designed for a different job

A prompt is a request. It optimizes for one output, evaluated by a human, in a single turn. If the answer is off, you rephrase and try again. The cost of ambiguity is one bad paragraph.

An agent is different. It interprets context, makes decisions, chains actions, and produces side effects. Ambiguity doesn't get corrected it gets executed. A misread requirement in turn one becomes a refactor in turn four and a broken pipeline in turn nine.

At that point, the loop isn't "rephrase and retry." It's "audit what just happened."

From prompting to Spec-Driven Development

For agent-based work, the shift I believe we need is from:

"Tell the AI what you want." to:

"Specify precisely what the agent needs to accomplish, under which constraints, and how success should be evaluated."

That's the idea behind Spec-Driven Development (SDD): a simple but powerful way to structure instructions for an agent.

A good specification answers at least five questions.

1. WHY - Context & objective

Why are we doing this? What problem are we solving? What outcome actually matters?

This is what lets an agent arbitrate when it hits an unforeseen fork in the road and it always hits one.

2. WHAT - Expected outcome

What exactly should the agent produce or accomplish? Name the artifact, the format, the shape of "done."

3. CONSTRAINTS - Boundaries

What must the agent respect? What should it never do? Which tools, formats, technologies, policies, or limits apply?

Constraints are the highest-leverage part of any spec, and the part most often left implicit. "Don't touch the schema" is worth more than three paragraphs of encouragement.

4. CURRENT STATE - Starting point

What already exists? Which files, code, data, architecture, decisions, or assumptions should the agent understand before acting?

Most agent failures I've seen aren't reasoning failures. They're context failures the agent rebuilt something that already existed, or ignored a decision made three weeks ago that nobody wrote down.

5. TASKS - Execution

What are the concrete steps or deliverables? What comes first? What gets validated, and how?

The same request, twice

Here's what the difference looks like in practice.

As a prompt:

"Build me a churn report from the subscriber data."

The agent will produce something. It will pick a churn definition, choose a period, invent a segmentation, and probably add three charts nobody asked for. It might even rewrite a table along the way.

As a specification:

## WHY
The retention team needs to see which segments are driving the
month-over-month churn increase, to prioritize next month's campaigns.

## WHAT
One SQL query + a single summary table: churn rate by RFM segment,
last 6 months, month over month.

## CONSTRAINTS
- Read-only access. Never create, alter, or drop tables.
- Churn = no revenue-generating event for 30 consecutive days.
- Exclude B2B accounts and internal test lines.
- Output as Markdown. No charts.

## CURRENT STATE
- Segments already exist in `analytics.rfm_segments` (refreshed daily).
- Events in `core.subscriber_events`, partitioned by day.
- A previous churn query exists in `/queries/churn_v1.sql` it uses a
  90-day definition and should not be reused as-is.

## TASKS
1. Draft the query and show it to me before running it.
2. Run it on the last 6 months.
3. Return the summary table + a 3-line reading of what moved.

Same intent. Radically different execution surface. The second version doesn't make the agent smarter it removes the decisions it was never qualified to make.

Why this matters

Without a specification, agents tend to:

make assumptions over-engineer modify things that didn't need modification miss important requirements drift away from the original objective produce inconsistent outputs perform unnecessary actions

With a good specification, the agent has a much clearer decision boundary. It still decides but inside a fence you drew on purpose.

Longer is not clearer

The goal isn't to write longer prompts. The goal is to reduce ambiguity.

That's an important distinction.

A 500-word prompt can still be ambiguous. A concise, structured specification can be dramatically more effective. Volume creates the feeling of precision; structure creates the real thing.

Three common traps:

• Adding words instead of removing options. "Make it clean, modern, professional, and elegant" says less than "match the existing design tokens in theme.ts."
• Stating goals but not limits. An objective without constraints is an invitation to over-engineer.
• Assuming shared context. The agent hasn't been in your meetings. If a decision isn't written down, it doesn't exist.

SDD is not about controlling every step

We don't need to tell the agent how to do everything. That's precisely where agents become valuable: they can figure out execution.

So define the objective, the context, the constraints, and the expected result then let the agent determine the best path within those boundaries.

A spec that dictates every keystroke isn't a spec. It's a script with extra latency.

A template you can reuse today

# SPEC: <short name>

## WHY
<problem, business context, outcome that matters>

## WHAT
<deliverable, format, definition of done>

## CONSTRAINTS
- Must: <...>
- Must never: <...>
- Tools / stack: <...>
- Limits: <scope, budget, time, files that are off-limits>

## CURRENT STATE
<existing files, data, architecture, prior decisions, known gotchas>

## TASKS
1. <first step often "show me the plan before executing">
2. <...>
3. <validation step: how do we know it worked?>

Keep it in your repo. Version it. Reuse it across agents.

Where this is heading

As agents evolve from chat interfaces into autonomous execution systems, I expect specification to become the actual interface between humans and AI for coding agents, product agents, research agents, content agents, and workflow agents alike.

Prompting tells an AI what we'd like. Specification tells an agent what success looks like.

And that difference matters.

How are you structuring instructions for your agents today? I'd be curious to hear which part of the spec constraints or current state has made the biggest difference in your workflows.