Every AI coding tool lets you write natural language prompts. Very few let you build structured workflows on top of them. That’s the gap most developers miss, and the reason their AI-generated code keeps needing rewrites.

The concept isn’t new. Spec-driven development — defining what you want before writing how — has been a software engineering discipline for decades. What’s new is applying it to AI-assisted coding. As Birgitta Bockeler explores on martinfowler.com, SDD tools are bringing the discipline of early engineering — design before code — into the agentic era.

The idea is simple: instead of typing the same instructions every time (“explore my codebase first”, “follow existing patterns”, “don’t write tests yet”), you encode them into reusable slash commands. Markdown files. No SDK, no API, no plugin system. Just files that your AI tool reads as instructions.

I built 6 commands that form a spec-driven development pipeline. Here’s how and why you should build your own.

Why Raw Prompts Fail at Scale

When you type “add JWT auth to my API”, you’re asking the model to make dozens of implicit decisions:

  • Which JWT library?
  • Where do tokens get stored?
  • How does it integrate with your existing middleware?
  • What’s your error handling pattern?

The model will guess. Sometimes it guesses right. Often it doesn’t. And you spend more time debugging AI guesses than you would have spent writing the code yourself.

The Pipeline

Six commands, each a single markdown file, forming a linear pipeline where each step produces an artifact and every transition requires your approval:

Spec-Driven Pipeline

Command 1: Create. From Idea to Structured Spec

You give it a name and a rough description. The command outputs a structured spec with context, expected behavior, edge cases, constraints, acceptance criteria, and, critically, open questions it detected that you need to answer.

.commands/spec-create.md 
# Create Spec

Create a structured spec for: **$ARGUMENTS**

## Your task

1. Generate a structured specification document
2. Include: context, expected behavior, edge cases,
   constraints, acceptance criteria
3. List open questions you detected that need human decisions

**Do not explore the codebase. Only create the spec.**

Instead of guessing your JWT library preference, it asks you.

Command 2: Audit. The Spec Meets Your Codebase

This is where the model explores your actual project — file structure, naming conventions, error handling patterns, existing dependencies — and enriches the spec with a technical analysis section.

What the audit explores
  • Project structure (folders, modules, layers)
  • Architecture patterns (MVC, service layer, feature-based)
  • File and function naming conventions
  • Current error handling approach
  • Test organization and coverage
  • Dependencies in package.json / requirements.txt
  • Similar files to what you’re building (to follow the same pattern)

This step prevents the #1 failure mode of AI-generated code: ignoring existing patterns. After the audit, the model knows your project’s conventions. The code it writes later will fit.

Command 3: Review. The Readiness Traffic Light

Before investing time in implementation, this command evaluates the spec:

🟢 Ready: Well-defined. All decisions made. Proceed to planning.

🟡 Can proceed: Ambiguity exists, but reasonable assumptions can be made. Each assumption is listed explicitly for you to approve or override.

🔴 Blocking: Critical decisions remain. Examples: “Sessions or JWT?”, “Which database?”, “Does this need real-time?” Fix these before proceeding.

If something is red, you fix it now, not after 3 phases of implementation.

Command 4: Plan. Phased Implementation

The plan command generates a step-by-step implementation plan. Each phase is small (1-3 files), verifiable (clear “done” criteria), and independent (reviewable before continuing).

Example plan output 
### Phase 1: Database schema and migration
**Objective:** Users table exists with auth fields
**Files:** create migration, modify schema
**Verify:** migration runs without errors

### Phase 2: Auth middleware and utilities
**Objective:** Protected routes return 401 without auth
**Files:** create middleware, create utils, modify app entry
**Verify:** curl unprotected → 200, protected → 401

Command 5: Implement. One Phase at a Time

The implementation command only executes one phase at a time. After each phase, it summarizes what it did, what decisions it made, and asks for your review before continuing.

This is the key difference from “generate everything at once”. If Phase 1 reveals a problem, you adjust the plan before Phase 2 starts. The cost of change stays low throughout the project.

Bonus: Review Commands

Two additional commands for ongoing code quality:

CommandWhat it checksOutput
Performance reviewO(n²) loops, N+1 queries, memory leaks, caching, bundle sizesSeverity-ranked findings with fixes
Architecture reviewSOLID principles, coupling, separation of concerns, securityLayer diagram + refactoring roadmap

Set It Up

$ mkdir -p .commands

Drop your command files in:

.commands
spec-create.md
spec-audit.md
spec-review.md
spec-plan.md
spec-implement.md
performance.md
architecture.md

Each command is a standalone markdown file. Your AI coding tool picks them up automatically as slash commands. No configuration needed.

Build Time Saved

In my experience, the spec-driven approach cuts rework significantly:

Time Spent on Rework
Raw prompts
With spec

(Percentage of session time spent fixing AI-generated code that didn’t fit)

The Golden Rule

Never skip steps under pressure. The time you “save” by skipping the audit or the review, you pay triple in corrections later.

This isn’t about slowing down. It’s about investing 10 minutes in specification to save 2 hours in debugging. Your AI tool becomes dramatically more useful when you treat it as a collaborator that needs context, not a magic box that guesses what you want.

Structured workflows beat raw prompts. Every time.

Further reading: