Why Do AI Agents Keep Building the Wrong Thing? How Spec-Driven Development Fixes Ambiguous Requirements

The Problem: Your AI Agent Built Something, But It's Not What You Meant

You describe a feature to your AI coding agent. Something like, "Add a dashboard that shows user activity." The agent nods, generates code, and delivers a working dashboard. But it's not what you wanted.

Maybe it shows the wrong metrics. Maybe the layout ignores your design system. Maybe it pulls data from the wrong source. You spend the next hour explaining what you actually meant, undoing work, and re-prompting. The agent built something technically correct but functionally wrong.

This happens constantly, and it's not the agent's fault. It's a requirements problem.

Why Ambiguity Breaks AI Agent Workflows

AI agents are powerful code generators, but they operate on the information they receive. When you say "user activity dashboard," the agent fills in dozens of assumptions silently:

• Which users? All users, or just the current user's team?
• What counts as "activity"? Logins, clicks, API calls, content creation?
• What time range? Last 24 hours, last 30 days, all time?
• Where does the data come from? An existing analytics service, raw database queries, a third-party API?
• What does "show" mean? A table, a chart, a summary card?

Each silent assumption is a potential mismatch between what you imagined and what the agent builds. The more complex the feature, the more assumptions multiply.

The Real Cost of Skipping Specifications

Without a written specification, you pay for ambiguity in several ways:

• Rework cycles. The agent builds, you correct, it rebuilds. Each cycle costs time and tokens.
• Scope creep. Without boundaries, the agent may add features you didn't ask for or skip ones you assumed were obvious.
• Inconsistent architecture. Different sessions or agents make different implicit decisions, leading to code that doesn't fit together.
• Testing gaps. If you don't define what "done" looks like, you can't verify the agent actually finished the task.

The pattern is familiar: vague prompt → plausible output → mismatch discovered → rework. The fix isn't better prompting alone. It's a structured process that forces clarity before code.

What a Good Solution Should Change

An effective approach to this problem would:

1. Surface assumptions early. Before any code is written, identify what the agent is assuming and let you correct it.
2. Create a shared reference. Both you and the agent need a document that defines what's being built, why, and how success is measured.
3. Gate progress on validation. Don't let the agent move from planning to implementation until the plan is reviewed.
4. Stay alive. Requirements change. The specification should update with them, not become a stale artifact.

This is the core idea behind spec-driven development, a structured workflow for AI agents that prioritizes written specifications before any code is generated.

Introducing Spec-Driven Development

Spec-driven development is an AI agent skill that enforces a four-phase gated workflow: Specify, Plan, Tasks, Implement. The agent cannot advance to the next phase until the current one is validated by a human.

The skill comes from the agent-skills repository by Addy Osmani, a collection of reusable patterns for AI coding agents. It's designed for situations where requirements are unclear, ambiguous, or only exist as a vague idea.

How the Four-Phase Workflow Works

Phase 1: Specify

The agent starts by listing its assumptions explicitly. For example:

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.

This is the most valuable part of the process. Instead of silently guessing, the agent forces you to confirm or correct its understanding. Then it writes a specification document covering six areas: objective, commands, project structure, code style, testing strategy, and boundaries.

The spec also reframes vague requirements as concrete success criteria. "Make the dashboard faster" becomes:

- Dashboard LCP < 2.5s on 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
→ Are these the right targets?

Phase 2: Plan

With a validated spec, the agent generates a technical implementation plan. It identifies major components, implementation order, risks, and what can be built in parallel. The plan is saved to tasks/plan.md for review.

Phase 3: Tasks

The plan is broken into discrete tasks, each with explicit acceptance criteria and verification steps. Each task should be completable in a single session and touch no more than about five files.

Phase 4: Implement

The agent executes tasks one at a time, referencing the spec sections relevant to each task rather than loading the entire document.

When This Skill Applies

Use spec-driven development when:

• Starting a new project or feature from scratch
• Requirements are ambiguous or only exist as a vague idea
• The change touches multiple files or modules
• You're about to make an architectural decision
• The task would take more than 30 minutes to implement

When Not to Use It

This skill is overkill for:

• Single-line fixes or typo corrections
• Changes where requirements are unambiguous and self-contained
• Simple bug fixes with a clear reproduction path

For those cases, a direct prompt is faster and more appropriate.

Evaluating Whether This Skill Fits Your Workflow

Before adopting spec-driven development, consider these factors:

Strengths

• Reduces rework. By catching misunderstandings before code is written, you avoid the build-correct-rebuild cycle.
• Creates documentation as a byproduct. The spec becomes a living reference for future changes.
• Works with any AI coding agent. The skill is a process pattern, not tied to a specific tool.
• Handles vague requirements well. The assumption-surfacing mechanism is specifically designed for unclear inputs.

Limitations and Trade-offs

• Adds upfront time. Writing a spec takes 15-30 minutes. For small tasks, this overhead isn't justified.
• Requires human review at each gate. If you're not available to review assumptions and plans, the agent stalls.
• Not a magic fix for communication. If you can't articulate what you want even in response to clarifying questions, the spec will still be wrong.
• Depends on agent discipline. The agent must follow the gated workflow. If it skips phases, the benefit disappears.

Setup Context

This skill is a process pattern documented in a SKILL.md file. It doesn't require installing packages or configuring tools. You load it into your AI agent's context (how you do this depends on your agent platform) and instruct the agent to follow the spec-driven workflow.

The skill references other skills from the same repository for the implementation phase, including incremental implementation, test-driven development, and context engineering. These are optional companions, not hard dependencies.

Safety and Repository Signals

• Repository: addyosmani/agent-skills with over 76,000 stars, indicating broad community adoption.
• License: The repository includes a LICENSE file. Review it for your use case.
• Security level: Low risk. The skill is a process document, not executable code. It doesn't access external services or modify system state.
• Topics: The repository covers skills for Cursor, Codex, Claude Code, and other agent platforms.

What to Inspect Before Using

1. Read the full SKILL.md. The excerpt above covers the core workflow, but the full document includes additional guidance on keeping the spec alive and handling common rationalizations.
2. Check compatibility with your agent. The skill assumes the agent can create files, follow multi-phase instructions, and wait for human review. Test with a small task first.
3. Review the referenced skills. The implementation phase references incremental-implementation, test-driven-development, and context-engineering. Decide whether you want to use those as well.
4. Adapt the spec template. The six-section template is a starting point. Your projects may need different sections (e.g., API contracts, data models, deployment requirements).

Practical Example: Building a Notification System

Imagine you tell your agent: "Add notifications to the app."

Without spec-driven development, the agent might build push notifications with Firebase, a bell icon in the header, and a notification preferences page. All reasonable guesses, but possibly wrong.

With spec-driven development, the agent first lists assumptions:

ASSUMPTIONS:
1. Notifications are in-app only (no email, no push)
2. Notifications are stored in the database (not a third-party service)
3. Users can mark notifications as read
4. No notification preferences page in this phase
→ Correct me now.

You correct: "Actually, we need email notifications too, and there's already a SendGrid integration."

The agent updates the spec, writes a plan, breaks it into tasks, and implements. The result matches what you actually wanted, because the mismatch was caught in the first five minutes instead of after two hours of coding.

The Bottom Line

Spec-driven development is not about slowing down. It's about shifting the time spent on clarification from the end of the process (rework) to the beginning (specification). For complex features, ambiguous requirements, or new projects, the 15 minutes spent on a spec can save hours of misdirected implementation.

If your AI agent frequently builds the wrong thing, the problem is likely not the agent's capability but the clarity of the input. Spec-driven development provides a structured way to fix that.