Spec-Driven Development

Spec-driven development is a methodology for AI-assisted software engineering where structured specifications drive the entire development lifecycle. Instead of describing features in chat and hoping for the best, you define specs with acceptance criteria, affected files, and implementation tasks. AI queries the spec, implements against it, and you verify the result.

This is the professional alternative to vibe coding. Models come and go. Prompts are ephemeral. Specs persist across sessions, tools, and team members.

Spec-driven development was previously explored as "context-driven development" (CDD), which focused on bringing deterministic context into the editor. Spec-driven development builds on that foundation with a concrete methodology: specs are the context.

The Problem: AI Without Structure#

AI coding tools are fast. They generate code in seconds. But speed without direction creates a different kind of technical debt.

The vibe coding loop:

1. Describe a feature in chat
2. AI generates code
3. It mostly works, but misses edge cases
4. Describe the fix in another chat message
5. AI patches it, breaks something else
6. Repeat until it seems right
7. Ship and hope

The result: code that works but nobody understands why. No traceability from requirements to implementation. No way to verify completeness. Context is lost between sessions. A different AI (or teammate) starts from zero.

The spec-driven loop:

1. Define a spec with acceptance criteria and tasks
2. AI queries the spec via MCP
3. AI implements against the spec, knowing exactly what to build and which files to touch
4. You commit, and the commit links back to the spec
5. Scan to verify the fix
6. Spec tracks what's done, what's left, and why decisions were made

Why Specs, Not Prompts#

Prompts are instructions for a single moment. Specs are durable artifacts that persist:

How It Works in Practice#

Manual specs: you define what to build#

You create a spec when you know what needs to happen. The spec includes a description, acceptance criteria, implementation tasks, affected files, and tech stack. Any AI coding tool can retrieve it via MCP and implement against it.

"Get the feature spec for auth token expiration"

AI: *calls get_feature_spec()*
    "Spec: Implement token expiration logic
     
     Acceptance criteria:
     1. Tokens expire after 15 minutes
     2. Refresh tokens last 7 days
     3. Expired tokens return 401
     
     Tasks:
     1. Add expiration check in lib/auth.ts
     2. Update verify endpoint
     3. Add refresh token flow
     
     Affected files: lib/auth.ts, app/api/auth/verify/route.ts
     
     Starting with task 1..."

Auto-generated specs: Rampify defines what to fix#

Run a scan, and Rampify analyzes your site for real issues. Each issue becomes a spec with affected URLs and fix instructions. No manual triage needed.

After scan:
  - "Missing Canonical Tag" (4 URLs affected)
  - "Pages Missing Structured Data" (3 URLs affected)  
  - "Meta Description Too Short" (2 URLs affected)

Each is a spec your AI can pick up and fix immediately.

The verification loop#

After AI implements a fix, you don't just trust it. You scan again. Rampify re-crawls the affected URLs and checks whether the issues are resolved. If they are, the spec is automatically marked as verified. If not, it stays open with updated affected URLs.

This closes the loop: define, implement, verify. No manual checking. No hoping it worked.

Specs Are the Single Source of Truth#

In spec-driven development, the spec is the authority. Not the chat log. Not the PR description. Not someone's memory of what was discussed.

A spec contains:

• What to build (title, description)
• Why it matters (context, business value)
• How to verify it's done (acceptance criteria)
• Where to implement it (affected files, tech stack)
• What's next (ordered tasks with dependencies)
• What happened (linked commits, progress tracking)

When a new developer joins the project, when you switch AI tools, when you resume work after a week, the spec has everything. No context reconstruction needed.

AI as Interface, Data as Truth#

Spec-driven development draws a clear line between what AI should do and what deterministic systems should do:

AI is a powerful interface. But it should operate on top of structured data, not instead of it.

Beyond SEO#

Spec-driven development is a general methodology. Rampify currently implements it for SEO, where the scan-to-spec pipeline creates specs from real site issues. But the same pattern applies to any domain:

• Accessibility - scan for WCAG violations, create specs with affected components
• Security - scan for vulnerabilities, create specs with remediation steps
• Performance - scan for Core Web Vitals issues, create specs with optimization targets

The architecture is the same: deterministic scan produces structured findings, findings become specs, AI implements against specs, scan verifies the fix.

Getting Started#

The fastest way to try spec-driven development:

1. Sign up at rampify.dev
2. Install the VS Code extension from the marketplace
3. Set up the MCP server so your AI tools can query specs directly
4. Run a scan to auto-generate your first specs from real site issues
5. Pick a spec and tell your AI to implement it

Or create a spec manually and watch your AI build to spec instead of building to vibes.