Forem: Yi Huang

Ship Better Code with AI: Introducing SDD-MCP - A Spec-Driven Development Server for Claude Code & Cursor

Yi Huang — Sat, 13 Sep 2025 17:19:18 +0000

The Problem: AI Generates Code, But Where's the Architecture?

Ever notice how AI assistants can write impressive code snippets but struggle with the bigger picture? They'll happily generate a React component or Python function, but ask them to architect a complete system with proper requirements, design patterns, and task breakdown? That's where things get messy.

After watching countless developers (myself included) wrestle with AI-generated spaghetti code, I built something to fix this.

Enter SDD-MCP: Your AI's Architecture Coach

SDD-MCP is a Model Context Protocol server that enforces Spec-Driven Development workflows in AI coding assistants. Think of it as giving your AI a proper software engineering methodology.

Quick Start (Seriously, It's One Command)

# No installation needed - just run:
npx -y sdd-mcp-server@latest

# For Claude Code users:
claude mcp add sdd "sdd-mcp-server"

What Makes This Different?

Instead of letting AI jump straight into code, SDD-MCP enforces a structured workflow:

INIT → REQUIREMENTS → DESIGN → TASKS → IMPLEMENTATION

Each phase produces concrete artifacts that guide the next. No more "let me rewrite this entire codebase because I forgot what we discussed earlier."

Real-World Example: Building a React Dashboard

Here's what happens when you use SDD-MCP to build a feature:

1. Initialize Project with Context

"Use sdd-init to create a new dashboard project"

Creates .kiro directory with proper structure and AGENTS.md for AI context.

2. Generate Smart Requirements

"Use sdd-requirements to analyze the project"

SDD-MCP actually reads your package.json, analyzes dependencies, and generates EARS-formatted requirements that match your tech stack. No generic boilerplate.

3. Create Architecture That Makes Sense

"Use sdd-design to generate architecture docs"

Produces design documents based on your actual project structure and dependencies. If you're using React + Redux, it'll design around that. Using Spring Boot? Different architecture.

4. Break Down Into Manageable Tasks

"Use sdd-tasks to create implementation plan"

Generates granular tasks derived from your real project structure, not theoretical concepts.

5. Implement with Quality Gates

"Use sdd-spec-impl to execute task-001 with TDD"

Follows Kent Beck's Red-Green-Refactor methodology. Plus, sdd-quality-check provides Linus-style 5-layer code review.

The Secret Sauce: Context-Aware Generation

Most AI tools generate generic templates. SDD-MCP is different:

Reads Your Code: Analyzes package.json, project structure, existing patterns
Tech Stack Aware: React gets React patterns, Spring Boot gets Spring patterns
Learns Your Style: Steering documents capture your project's conventions
Memory Across Sessions: sdd-context-load restores project state

Language Agnostic, Framework Friendly

Fixed in v1.3.11 - no more hardcoded templates. Works with:

Frontend: React, Vue, Angular, Svelte
Backend: Node.js, Spring Boot, Django, FastAPI
Languages: JavaScript, TypeScript, Python, Java, Go, Rust
Mobile: React Native, Flutter, Swift, Kotlin

Production-Ready Features

Security First

Distroless Docker images (gcr.io/distroless/nodejs18-debian11)
Non-root execution (UID 1001)
Read-only filesystem
Dropped Linux capabilities

Enterprise Scale

# Docker deployment with security hardening
docker run -p 3000:3000 sdd-mcp-server

# Or with compose for orchestration
docker-compose up -d

Quality Enforcement

sdd-validate-design: Interactive GO/NO-GO design reviews
sdd-validate-gap: Requirements vs implementation gap analysis
sdd-quality-check: Automated 5-layer code review

Real Impact: What Developers Are Saying

Since launch, developers have used SDD-MCP to:

Reduce AI context confusion by 80%
Ship production features 3x faster
Maintain consistent architecture across AI sessions
Generate documentation that actually matches code

The Tools Arsenal

Tool	What It Does	When to Use
`sdd-steering`	Generates product.md, tech.md, structure.md	Project setup
`sdd-spec-impl`	TDD implementation with specs	Feature development
`sdd-validate-gap`	Finds missing implementations	Before deployment
`sdd-context-load`	Restores project memory	Resuming work

Common Gotchas & Fixes

"Templates Instead of Real Content"

If sdd-steering generates templates, prompt your AI:

"Please update product.md based on actual codebase analysis"

"Connection Issues with npx"

Use global installation for reliability:

npm install -g sdd-mcp-server@latest
claude mcp add sdd "sdd-mcp-server"

What's Next?

Currently working on:

Plugin marketplace for custom workflows
Team steering document sharing
Integration with more AI assistants
Visual workflow designer

Try It Now

Stop fighting with AI-generated chaos. Give your AI assistant proper engineering discipline:

# Install globally
npm install -g sdd-mcp-server@latest

# Add to Claude Code
claude mcp add sdd "sdd-mcp-server"

# Start building better

GitHub: github.com/yi-john-huang/sdd-mcp

Built for developers who ship, not just prototype.

Got questions? Found a bug? Let's discuss in the comments or open an issue.

AI #DeveloperTools #MCP #ClaudeCode #Cursor #SpecDrivenDevelopment

Spec-Driven Development: Stop "Vibe Coding" and Start Building Software That Actually Makes Sense

Yi Huang — Fri, 29 Aug 2025 16:50:27 +0000

Have you ever jumped straight into coding without a clear plan, only to realize halfway through that you're building the wrong thing? Or found yourself constantly refactoring because requirements keep "evolving"? Welcome to what I call "Vibe Coding" – and it's time we talked about a better way.

The Problem with Traditional Development

Let's be honest. Most of us have been guilty of this workflow:

💭 Get a vague idea of what needs to be built
💻 Start coding immediately
🔄 Realize requirements aren't clear
🤯 Context switch between different tools and docs
📝 Documentation becomes an afterthought (if it happens at all)
🐛 Reactive problem-solving becomes the norm

Sound familiar? This scattered approach leads to technical debt, frustrated teams, and products that miss the mark.

Enter Spec-Driven Development (SDD)

Spec-Driven Development flips the script. Instead of rushing to write code, it enforces a structured workflow that breaks development into three distinct phases:

1. 📋 Requirements Phase

Generate detailed user stories with clear acceptance criteria. No more guessing what "make it user-friendly" means.

2. 🏗️ Design Phase

Create technical designs with diagrams and schemas. Architecture decisions are made before implementation, not during.

3. ✅ Implementation Phase

Break work into trackable, sequential tasks. Each task has a clear definition of done.

Why This Matters

"Requirements are usually uncertain when you start building, which is why developers use specs for planning and clarity."

This isn't just about documentation for documentation's sake. It's about:

Clarity: Everyone knows exactly what's being built and why
Maintainability: Specs become living documentation that evolves with your codebase
Efficiency: Less time wasted on building the wrong thing
Collaboration: Teams can work from the same source of truth

Real-World Implementation with AWS Kiro

Recently, I've been exploring AWS Kiro IDE, an AI-powered development environment that enforces spec-driven workflows. It automatically generates three key documents:

project/
├── requirements.md  # What we're building
├── design.md       # How we're building it
└── tasks.md        # Steps to build it

But SDD isn't limited to specific tools. You can start implementing these principles today with your current workflow.

Beyond Just Planning

What makes SDD powerful is that it's not a one-time planning exercise. The specs evolve with your project:

Living Documentation: Specs stay synced with your evolving codebase
Team Alignment: Product managers can maintain requirement specs while developers own technical design
Clear Handoffs: No more confusion about what's ready for implementation

Getting Started with SDD

You don't need fancy tools to start. Here's how to begin:

Before coding anything, write down what you're building in plain language
Document the technical approach and key decisions
Break the work into specific, measurable tasks
Only then, start coding

For those interested in tooling, there are open-source CLI agents available:

claude-code-spec for Claude Code users
amazonq-spec for Amazon Q CLI

The Bottom Line

Spec-Driven Development transforms chaotic development into structured, secure, and maintainable software delivery.

It's not about adding bureaucracy – it's about being intentional with your development process. When you know exactly what you're building and how, you can move faster with confidence.

What's Next?

This is just the beginning of my exploration into Spec-Driven Development. Over the coming weeks, I'll be sharing a series of practical posts demonstrating how SDD can be applied to real-world coding challenges.

Follow me to get notified when the next post drops, and let's transform how we build software together!

Have you tried Spec-Driven Development? What's your biggest challenge with requirements gathering? Drop a comment below – I'd love to hear your experiences!