Stop Rework: Spec-Driven Development Framework for AI Agents

Leonardo Sampaio — Sat, 03 Jan 2026 14:34:26 +0000

This is a submission for the DEV's Worldwide Show and Tell Challenge Presented by Mux

From Chat-Based Chaos to Spec-Driven Development

AI agents generate code fast—but without structure, you get vague requirements, repeated mistakes, and costly rework. ai-sdd brings engineering discipline to AI development.

What I Built

ai-sdd transforms AI coding agents into spec-driven developers with one command.

Install slash commands (/sdd:spec-init, /sdd:spec-requirements, /sdd:spec-design, /sdd:spec-impl) that enforce a proven four-phase workflow: Requirements → Design → Tasks → Implementation.

Works across 7 major AI platforms: Claude Code, Cursor, Gemini CLI, Codex CLI, GitHub Copilot, Qwen Code, and Windsurf.

The problems it solves:

❌ Vague requirements → AI generates wrong features
❌ No approval gates → Costly rework after implementation
❌ Lost context → Re-explaining architecture every session
❌ Sequential execution → Slow development cycles
❌ Scattered specs → No version control or traceability

The solution: Structured specifications in .sdd/ directories. AI agents follow approval checkpoints, generate EARS-format requirements, and execute tasks in parallel—all with Git-friendly version control.

🔗 Links

NPM: https://www.npmjs.com/package/ai-sdd
Book: AI-Assisted SDD on Amazon

🚀 Quick Start

npx ai-sdd  # Choose your platform

# Then in your AI agent:
/sdd:spec-init "user authentication with OAuth2"
/sdd:spec-requirements user-auth
/sdd:spec-design user-auth
/sdd:spec-tasks user-auth
/sdd:spec-impl user-auth

Zero configuration. No credentials required.

The Story Behind It

As a Principal Architect/Developer, I watched teams waste weeks on features that should take hours—not from lack of AI capability, but from lack of structure.

AI agents would generate code without understanding requirements. Teams would discover misalignments after implementation. Architecture decisions got lost between sessions. No approval gates meant costly rework.

I realized AI agents needed what engineering teams use every day: spec-first development with approval checkpoints.

So I built two things:

The methodology: Published "AI-Assisted SDD"—adapting traditional software engineering practices for AI agents.
The framework: Built ai-sdd to implement this across all major platforms, giving teams immediate adoption.

Now features that took weeks take hours—with higher quality and full traceability.

Technical Highlights

Stack: Node.js/TypeScript CLI with custom template engine (7 platforms × 12 languages = 84 configurations).

Key Innovations:

1. EARS-Format Requirements

Unambiguous specifications AI agents understand perfectly:

WHEN [trigger]
THEN the system SHALL [action]
WHERE [constraints]

No vague requirements. No misaligned implementations.

2. Approval Checkpoints

Three-phase gates: Requirements → Design → Tasks. AI cannot implement until you approve. Prevents costly rework.

3. Project Memory

Architecture, patterns, and decisions persist in .sdd/steering/ files. AI loads context automatically—no re-explaining needed.

4. Parallel Execution

Tasks marked (P) with automatic dependency tracking. Maximum efficiency.

5. Git-Friendly Specs

Markdown files in .sdd/specs/. Version control, code review, collaboration—just like your code.

Why It's Unique:

First unified SDD tool across 7 AI platforms
Methodology-backed by published book
Zero configuration, local-first

Use of Mux

Mux Features Used:

Video Hosting: Uploaded 1920x1080 video with automatic adaptive bitrate streaming + CDN
AI Captioning: One-click generation (~95% accuracy), manual corrections for technical terms
AI Transcript: SEO-friendly content reused in this post and social media
Seamless Embed: HTML iframe worked perfectly on DEV.to

Developer Experience: Sign up (free) → Upload → Enable AI features (one click) → Copy playback ID. Done in 5 minutes.

Key Benefits

Traditional AI Dev	With ai-sdd
❌ Vague requirements	✅ EARS-format precision
❌ No approval gates	✅ Validate before implementation
❌ Lost context	✅ Persistent project memory
❌ Scattered specs	✅ Git-friendly version control
❌ Sequential execution	✅ Parallel task execution

Try ai-sdd Today

Stop wasting weeks on rework. Start with specs, end with quality code.

cd your-project-directory
npx ai-sdd
/sdd:spec-init "your feature description"

What's your biggest AI development challenge? Share below! 👇

Forem: Leonardo Sampaio