Why AI Coding Agents Need Specs (And What Happens Without Them)

There's a pattern that shows up again and again in developer communities. Someone discovers that Claude can write a whole feature in minutes, or that Cursor can refactor an entire service while they get coffee. The AI is genuinely impressive. Then, a few weeks in, the codebase starts feeling inconsistent. Decisions made in one session contradict decisions from another. Code that was supposed to be "done" keeps needing fixes. The developer can't quite explain why things are harder now than before they started using AI.

The root cause is almost always the same: the AI had no spec.

---

The Problem: AI Agents Have No Memory of Your Decisions

Every new conversation with an AI coding agent starts from scratch. The agent has access to your codebase — sometimes all of it, sometimes just the files you reference — but it has no memory of the reasoning behind your architecture, the trade-offs you evaluated last month, or the decision you made three sessions ago to use a specific pattern for error handling.

This creates predictable failure modes:

Contradictory implementations. You ask the agent to add a feature. It produces code that technically works but introduces a pattern that conflicts with something you built two weeks ago. Both are "valid" in isolation. Together, they're inconsistent.

Scope creep without visibility. The agent interprets "add a settings page" broadly. It creates new database tables, new API routes, a new component library approach. Each individual decision might seem reasonable. The aggregate is far more than you asked for.

No definition of done. When does the feature end? The agent will keep going — adding error handling, edge cases, fallbacks, tests — until you tell it to stop. Without acceptance criteria, "done" is arbitrary.

Parallel session conflicts. As multi-agent workflows become common, two agents working on related features can produce code that collides. Without a shared spec, there's no coordination.

---

Why Specs Solve This

A spec is a contract. It defines:

1. What the feature does — in plain language that both you and the agent can understand
2. Acceptance criteria — concrete, verifiable conditions that must be true for the feature to be complete
3. Scope boundaries — which files are touched, which are off-limits, what new types or schemas are introduced
4. Risks and constraints — known edge cases, performance concerns, rollback complexity

When an AI agent has a spec, it has context that survives the session boundary. More importantly, it has a definition of done that you agreed to in advance.

The agent's job shifts from "figure out what to build" to "satisfy these criteria." That's a much better use of its capabilities.

---

What a Good Spec Looks Like in Practice

Here's a minimal spec for a feature like "add email notification on signup":

## User Story
As a new user, when I complete signup, I receive a welcome email
so that I know my account was created successfully.

## Acceptance Criteria
- [ ] Welcome email is sent within 5 seconds of signup completion
- [ ] Email contains the user's name and a verification link
- [ ] If the email service is unavailable, signup still succeeds (fire-and-forget)
- [ ] No duplicate emails are sent on retry
- [ ] Email sending is logged with success/failure status

## Scope
Files modified: src/auth/signup.ts, src/services/email.ts (new)
New types: EmailPayload (in src/types/notifications.ts)
External: requires EMAIL_SERVICE_URL env var

## Out of scope
- Email templates beyond the welcome email
- Unsubscribe handling (separate spec)

This takes five minutes to write. It saves hours of back-and-forth and prevents at least two or three wrong implementations.

---

Real Workflow Examples

Without a spec

Developer: "Add rate limiting to the API"
Agent: [writes rate limiting in middleware]
Developer: "That's not quite right — it should be per-user, not per-IP"
Agent: [rewrites it]
Developer: "Also it needs to work with our existing auth token system"
Agent: [rewrites again, introduces new dependency]
Developer: "Now it conflicts with the cache layer"
[Three more iterations]

Each iteration costs tokens, time, and introduces new points of inconsistency.

With a spec

Developer: "Create a spec for per-user rate limiting"
Agent: [generates spec with acceptance criteria]
Developer: [reviews, adds one criterion about cache compatibility, approves]
Agent: [implements exactly to spec, marks criteria done as it goes]
Developer: [reviews output — all criteria satisfied, no surprises]

The spec made the requirements explicit before implementation. The agent had nothing to misinterpret.

---

The Approval Gate Matters

One part of SDD that developers initially resist is the explicit approval step. The workflow is:

1. Write the spec
2. Get approval before writing any code
3. Implement against the approved spec

This feels slow. It isn't.

The approval gate is where you catch scope problems, architectural conflicts, and missing requirements. Catching them at the spec stage takes minutes. Catching them after implementation takes hours. Catching them in production takes days.

More practically: the approval gate means you've actually read and agreed to what the agent is about to do. That's not bureaucracy — that's basic engineering discipline.

---

Getting Started with Planu

Planu is an MCP server that embeds the SDD workflow directly into your AI coding sessions. Instead of managing spec documents manually, your agent handles it through structured tools:

• create_spec — generates a structured User Story and Technical Sheet from a plain-language description
• list_specs — shows all specs and their implementation status
• validate — checks that implementation satisfies the acceptance criteria
• detect_drift — identifies when code has drifted from the spec

The workflow integrates with Claude, Cursor, Windsurf, Gemini CLI, and any MCP-compatible agent. Setup takes about five minutes.

Starting point

You don't need to adopt SDD for everything at once. Start with new features only. Once you feel the difference — fewer surprises, cleaner reviews, better handoffs — you'll naturally apply it more broadly.

Read the Getting Started guide

---

Specs don't slow you down. Ambiguity does.