Spec-Driven Development: How to Give Your AI Coding Assistant a Blueprint

You open Claude Code, type "build me a notification system," and get back 400 lines of code. It works, sort of. But the data model is wrong for your use case, it's polling instead of using websockets, and it created three database tables you didn't need.

So you try again with more detail. Better, but now it's inconsistent with what it built yesterday. Different naming conventions. Different error handling patterns. A completely different approach to the same problem.

This is what happens when you use AI coding assistants without a blueprint. The AI is doing exactly what you asked — it's just that you didn't ask for enough.

The real problem isn't the AI

Developers blame the model when AI output is inconsistent. But the model is responding to what it's given. When the input is vague, the output is a guess. A sophisticated, well-structured guess, but a guess nonetheless.

Every time you start a new session and prompt "build me X," the AI makes dozens of implicit decisions: data model shape, error handling strategy, API design, file structure, naming conventions, dependency choices. Without constraints, it picks whatever seems reasonable in the moment.

The next session, it picks differently. Not because it's broken — because you gave it no reason to pick the same way twice.

Spec driven development: the fix

Spec driven development means writing a structured specification before you write a single line of code — or before you ask your AI to write one. The spec defines what you're building, why you're building it, what the constraints are, and critically, what you're not building.

This isn't waterfall. It's not a 40-page PRD. A good spec is 20-50 lines of markdown that removes the ambiguity your AI would otherwise fill with assumptions.

A minimal spec looks like this:

# Specification: Notification System

## Goal
Real-time notification delivery for user-facing events
with read/unread tracking and batch dismissal.

## Requirements
- WebSocket-based delivery, no polling
- PostgreSQL-backed persistence with 90-day retention
- Notification types: system, mention, assignment, deadline
- Batch mark-as-read API endpoint
- Rate limit: max 50 notifications per user per hour
- Mobile push via FCM for offline users

## Technical Approach
- Use existing WebSocket infrastructure from chat feature
- Add notifications table, not a separate service
- Fan-out on write, not read

## Out of Scope
- Email digest (separate spec)
- Notification preferences UI (blocked on settings redesign)
- SMS notifications
- Analytics on notification engagement

That's 25 lines. It took maybe 10 minutes to write. And it eliminates about 80% of the bad decisions an AI would make without it.

What changes when you spec first

Hand that spec to Claude Code instead of "build me a notification system" and the results are dramatically different.

Architecture aligns with your system. The AI sees you have existing WebSocket infrastructure and extends it instead of inventing a new transport layer. It adds a table to your existing database instead of spinning up Redis pub/sub.

Scope stays controlled. Without the out-of-scope section, the AI might build email digests, a preferences page, and an analytics pipeline. With it, the AI focuses on exactly what you need right now.

Decisions are consistent across sessions. When you come back tomorrow and ask the AI to add a new notification type, the spec is still there. The AI reads it and follows the same patterns — same data model, same delivery mechanism, same conventions.

Code review gets easier. You can review the output against the spec. Does it use WebSockets? Check. Does it persist to PostgreSQL? Check. Did it build email digests? That was out of scope — reject.

How Monday Morning structures specs

You can write specs in any format, but structure matters when you want your AI assistant to consume them automatically. Monday Morning organizes specs in a .mm/specs/ directory with a consistent folder structure:

.mm/specs/2026-05-15-notification-system/
├── spec.md              # Goals, requirements, out-of-scope
├── implementation.md    # Task tracking with checkboxes
├── requirements.md      # Detailed technical requirements
└── visuals/             # Mockups, diagrams (optional)

The spec.md is the blueprint. But the real power is in implementation.md, which breaks the spec into trackable tasks:

# Notification System - Implementation

## Completed
- [x] T1: Create notifications table migration
- [x] T2: WebSocket channel subscription handler

## In Progress
- [ ] T3: Fan-out write service with rate limiting

## Backlog
- [ ] T4: Batch mark-as-read API endpoint
- [ ] T5: FCM push integration for offline delivery
- [ ] T6: 90-day retention cleanup job

This creates a feedback loop that plain specs don't have. Your AI doesn't just know what to build — it knows what's already built, what's in progress, and what's left. When you start a new session, it reads the implementation file and picks up exactly where you left off.

The feedback loop

Spec driven development with AI isn't a one-shot process. It's a loop:

Spec — Define what you're building. Goals, requirements, constraints, out-of-scope.

Tasks — Break the spec into discrete, ordered work items. Each task should be completable in a single session.

Implementation — Work through tasks with your AI assistant. The spec provides guardrails. The task list provides focus.

Progress tracking — Mark tasks complete. Your AI sees updated state next session. No re-explaining what's done.

This loop compounds. By the third session on a feature, your AI has the spec, knows what's complete, understands the patterns established in earlier tasks, and can make informed decisions about the remaining work. Compare that to session three without a spec, where you're still trying to get the AI to remember your database schema.

A concrete example

Let's compare two approaches to the same feature: adding a project activity feed.

Without a spec:

"Add an activity feed to the project dashboard that shows recent changes."

The AI builds something. Maybe it creates an activities table with id, type, message, created_at. Maybe it polls every 5 seconds. Maybe it shows 50 items with no pagination. Maybe it tracks every database write via triggers. It works, but none of these decisions were intentional.

Next session: "Add filtering to the activity feed." The AI doesn't remember the schema it created. It might suggest a completely different approach. You spend 15 minutes getting it back on track.

With a spec:

# Specification: Project Activity Feed

## Goal
Chronological feed of project events on the dashboard,
scoped to the current project, with type filtering.

## Requirements
- Event types: task_completed, issue_opened, spec_updated,
  note_added, member_joined
- Store events in project_events table with project_id FK
- Paginated API: 20 events per page, cursor-based
- Client-side filtering by event type (no additional API calls)
- Events created by application code, not database triggers
- Show relative timestamps ("3 hours ago")

## Out of Scope
- Real-time updates (acceptable to refresh on navigation)
- Cross-project activity feed
- Event deletion or editing
- Activity analytics or reporting

Session one: "Implement T1 and T2 from the activity feed spec." The AI reads the spec, creates the table with the right columns, builds cursor-based pagination.

Session two: "Implement T3: client-side filtering." The AI reads the implementation file, sees T1 and T2 are complete, knows the data model, and builds filtering that's consistent with the existing code. No re-explaining.

The second approach takes 10 minutes more upfront and saves hours over the life of the feature.

Why specs help AI make better architectural decisions

AI models are very good at pattern-matching and generation but poor at product judgment. They don't know whether your app needs WebSockets or polling. They don't know your team's conventions. They don't know what you tried last month and abandoned.

A spec encodes your judgment so the AI can apply its generation capability within your constraints. This division of labor is the whole point.

When you write "use existing WebSocket infrastructure from chat feature," you're giving the AI an architectural constraint that saves it from exploring 10 other approaches. When you write "no database triggers," you're ruling out an entire class of solutions before the AI wastes tokens on them.

The out-of-scope section is arguably the most valuable part. AI assistants are eager to help, which means they tend to over-build. Telling the AI what not to build is often more impactful than telling it what to build.

Specs are living documents

A spec isn't frozen after you write it. As you implement, you discover things: a requirement that's harder than expected, a constraint you didn't anticipate, a scope item that should be deferred.

Update the spec. Your AI reads the latest version every session. If you move "FCM push integration" from requirements to out-of-scope because the timeline shifted, the AI immediately adjusts. No conversation needed — the spec is the source of truth.

This is where the combination of specs and progress tracking in implementation.md pays off. You're not just planning — you're maintaining a live document that evolves with the work.

Getting started with spec driven development

You don't need Monday Morning to start writing specs, but it helps to have structure. Here's the minimum viable approach:

1. Before your next feature, create a markdown file with Goal, Requirements, and Out of Scope sections.
2. Break it into tasks with checkbox syntax (- [ ] / - [x]).
3. Feed the spec to your AI at the start of each session. Reference it explicitly: "Read the spec at .mm/specs/2026-05-15-feature/spec.md before implementing."
4. Update progress after each session. Mark completed tasks, adjust scope if needed.

If you want this automated — specs loaded into context automatically, progress tracked as you work, your AI picking up where you left off without manual file-pasting — that's what Monday Morning does. It turns spec driven development from a discipline into a workflow.

The investment is small: 10-15 minutes of writing before you start building. The return is code that matches your intentions, stays consistent across sessions, and doesn't require you to re-explain your project every time you open a terminal.