Skip to content

Agentic Software Development

Context & Specifications

Spec-Driven Development: How a 30-Line Blueprint Stops Agent Scope Creep

From Agentic Software Development · 10 articles · latest

Closed-loop diagram showing a 30-line EARS spec driving red tests, scoped code edits, and spec-diff verification
A 30-line written blueprint anchors Red-phase tests and stops the agent from rewriting half your codebase.

Ask a coding agent to "add retry logic to the Pressroom publisher" without writing anything down first, and watch what happens. Nine times out of ten, it won't just add bounded exponential backoff to one HTTP helper. It will invent a new configuration dataclass, introduce tenacity into requirements.txt, refactor logging across three unrelated scripts, add an environment variable nobody asked for, and rewrite five passing tests because their mock signatures changed.

Agents suffer from eager-helper syndrome: given an underspecified prompt, they extrapolate the cleanest textbook architecture they can imagine—and rewrite your surrounding codebase to match it. The fastest cure I have found is Spec-Driven Development (SDD) built around a brutally short, 30-line Markdown blueprint drafted before a single line of implementation code is generated.

The Myth of Heavy Waterfall Specs

Nobody wants to revive 40-page Word design documents for a two-hour bugfix. Good agent specifications borrow from Google's pragmatic design doc philosophy: write only enough structure to pin down trade-offs, invariants, and boundaries before touching code.

For 90% of day-to-day engineering work, four compact sections cover everything an agent needs:

  1. Goal & Trigger: One sentence stating what changes and why.
  2. EARS Requirements: Concrete behavioral rules using shall statements.
  3. Files in Scope & Explicit Non-Goals: Naming both what gets edited and what MUST remain untouched.
  4. Acceptance Check: The exact test or command proving done.

Why EARS Syntax Works Shockingly Well for LLMs

Unconstrained English requirements are famously sloppy ("handle timeouts gracefully"—gracefully how? Retry? Fail fast? Log a warning?). Back in 2009, Alistair Mavin and engineers at Rolls-Royce solved this for jet-engine control software with EARS (Easy Approach to Requirements Syntax).

EARS uses just five small grammatical patterns centered on the word shall:

  • Ubiquitous: The <system> shall <behavior>.
  • Event-driven: When <trigger>, the <system> shall <behavior>.
  • State-driven: While <state>, the <system> shall <behavior>.
  • Unwanted Behaviour: If <failure condition>, then the <system> shall <behavior>.

Why does a 2009 aerospace notation pair so well with 2026 coding models? Just like Specification by Example, every EARS clause maps one-to-one onto an automated unit test. When <trigger> is your Arrange/Act setup; the <system> shall <behavior> is your assert. There is almost zero ambiguity left for the model to "creatively interpret."

Tip

Always write the If <failure> clause first: Humans usually specify the happy path and forget failure states. Explicitly writing two If ... then the system shall ... lines catches silent swallowing of HTTP 429s, corrupt payloads, and stale optimistic locks before implementation begins.

Example: A Complete 30-Line Agent Blueprint

Here is a realistic spec I can write in four minutes before handing work to an agent—modeled on our optimistic locking and diff pipeline in Pressroom:

## Spec: Bounded Retry on Pressroom 502/503 Responses

### Goal
Add bounded retry handling for transient gateway errors in `PressroomClient.call_tool`.

### Requirements (EARS)
1. **Event-driven:** When `call_tool` receives HTTP 502, 503, or `TimeoutException`, the client shall retry up to 3 times using exponential backoff (1s, 2s, 4s).
2. **Unwanted Behaviour:** If `call_tool` receives HTTP 400, 401, 403, 404, or 409 (hash conflict), then the client shall raise `PressroomError` immediately without retrying.
3. **Ubiquitous:** While retrying `action="create"`, the client shall preserve idempotency or check existing `anchor` before duplicating entries.
4. **Unwanted Behaviour:** If all 3 retries fail, then `call_tool` shall raise the final `PressroomError` with the HTTP status and response body intact.

### Scope & Non-Goals
- IN SCOPE: `scripts/pressroom_client.py`, `tests/test_pressroom_client.py`
- OUT OF SCOPE (DO NOT TOUCH): `scripts/publish_post.py`, CLI flags, external packages (stdlib `time.sleep` + `urllib`/`httpx` only).

### Acceptance Gate
- Add mocked transport tests for 503->200 recovery, 409 no-retry, and max-retry exhaustion.
- `pytest -q tests/test_pressroom_client.py` passes with 0 skips.

Read that spec from an agent's point of view. It cannot sneak in tenacity because OUT OF SCOPE forbids new dependencies. It cannot accidentally retry a 409 Conflict from optimistic locking because Requirement 2 bans it explicitly. And it knows the exact two files it is allowed to touch.

The Four-Step Spec Loop

Once you have those 30 lines, execution turns mechanical—very similar to how requirements flow from knowledge pages into code in The Agentic Dogfood Loop:

  1. Freeze the Spec: Save it in the ticket, PR body, or a temporary spec file, and ask the agent to critique only ambiguity before touching code.
  2. Generate Red Tests First: Have the agent write failing tests directly from the EARS requirements—without editing implementation files yet (see Stopping Coding Agents from Gaming Your Tests).
  3. Implement Inside Scope: Let the agent edit only IN SCOPE files until the Red tests turn green.
  4. Diff Against Non-Goals: Before reviewing line-by-line logic, check git diff --stat. If an OUT OF SCOPE file appears in the diff, revert it immediately without even arguing.

When the Spec Needs to Change Mid-Flight

Specs are guardrails, not stone tablets. Roughly one in five times, implementing Requirement 2 exposes an existing caller in another module that actually needs updating. Instead of letting the agent silently expand its own blast radius, require it to stop and propose a one-line spec amendment first. Reviewing a proposed scope expansion takes ten seconds—untangling five unrequested cross-module edits after the fact takes an hour.

Notice how little time this takes: four minutes writing 30 lines of crisp EARS rules routinely saves forty minutes untangling unsolicited refactors. Combine this spec habit with a clean AGENTS.md and you are firmly operating at Stage 4 engineering.

Keep reading

Comments