Introducción a Spec-Driven Development

Autor/a

Diego Saavedra

Fecha de publicación

24 de febrero de 2026

🎓 Spec-Driven Development: La Metodología

👨‍🏫 Del Investigador: Como investigador en desarrollo de software, he analizado múltiples metodologías de desarrollo. La evidencia empírica sugiere que SDD no es burocracia, sino ingeniería sistemática aplicada a la generación de código con IA.

💭 Mentalidad de Investigador: “Según los principios de ingeniería de software establecidos, la especificación precede a la implementación. La literatura académica respalda este enfoque.”

🤔 El Problema con la IA

El Patrón Típico (Incorrecto)

Usuario: "Agrega autenticación a mi app"
IA: [genera 500 líneas de código]
Usuario: "Eso no es lo que quería..."
IA: [genera otras 500 líneas]
Usuario: "Ahora está mejor pero falta..."

Problemas:

  1. ❌ Sin contexto claro → interpretaciones múltiples
  2. ❌ Sin trazabilidad → ¿por qué esta decisión?
  3. ❌ Sin verificación → ¿cumple los requisitos?
  4. ❌ Sin rollback → ¿cómo deshacer?

El Patrón SDD (Correcto)

Usuario: /sdd:new add-user-authentication
IA: [crea propuesta.md con intent, scope, approach]
Usuario: [revisa y aprueba propuesta]
IA: [crea spec.delta.md con requisitos]
Usuario: [revisa y aprueba specs]
IA: [crea design.md con arquitectura]
Usuario: [revisa y aprueba diseño]
IA: [crea tasks.md desglosado]
Usuario: [aprueba tareas]
IA: [implementa tarea por tarea, verificando]

🧠 ¿Qué es SDD?

Spec-Driven Development es una metodología donde:

  1. Las especificaciones son primero-clase: Tan importantes como el código
  2. El workflow es estructurado: Fases definidas con artefactos
  3. La trazabilidad es automática: Cada cambio tiene historial
  4. La IA es guiada: Contexto claro en cada interacción

Analogía: Arquitectura de Edificios

Fase Arquitectura SDD
Concepto Boceto inicial proposal.md
Planos Blueprints detallados spec.delta.md
Ingeniería Cálculos estructurales design.md
Construcción Lista de tareas tasks.md
Ejecución Obra Implementación
Inspección Certificación verification.md
Archivo Planos finales specs/*.spec.md

🔄 Las 8 Fases de SDD

1. INIT - Inicialización

Propósito: Preparar el proyecto para SDD

Artefacto: openspec/config.yaml

schema: spec-driven

context: |
  Tech stack: Node.js, Express
  Architecture: REST API
  Testing: Jest

rules:
  specs:
    - Use Given/When/Then format
    - Use RFC 2119 keywords (MUST, SHALL)

Comando: /sdd:init

2. EXPLORE - Exploración (Opcional)

Propósito: Investigar antes de comprometerse

Artefacto: Exploración inline o exploration.md

Cuándo usar:

  • Requisitos poco claros
  • Múltiples opciones de implementación
  • Necesitas entender código existente

Comando: /sdd:explore <topic>

3. PROPOSE - Propuesta

Propósito: Definir QUÉ y POR QUÉ

Artefacto: openspec/changes/NNN-name/proposal.md

# Proposal: Add Health Endpoint

## Intent
Add /health for Kubernetes health checks

## Scope
In scope: GET /health, JSON response
Out of scope: Database checks, auth

## Approach
Add route in app.js, minimal implementation

## Risks
Low - simple endpoint, no side effects

## Rollback
Remove route if issues arise

Comando: /sdd:new <name>

4. SPEC - Especificaciones

Propósito: Definir comportamientos esperados

Artefacto: openspec/changes/NNN-name/spec.delta.md

# Spec Delta: Add Health Endpoint

## Requirements

### REQ-1: Endpoint Availability
The system SHALL provide GET /health.
MUST respond within 100ms.

## Scenarios

### SCENARIO-1: Healthy Response
**Given** the API is running
**When** GET /health is requested
**Then** response is 200 OK
**And** body contains { "status": "ok" }

Comando: /sdd:spec

Keywords RFC 2119:

Keyword Significado
MUST Requisito obligatorio
SHALL Comportamiento requerido
SHOULD Recomendado
MAY Opcional

5. DESIGN - Diseño Técnico

Propósito: Definir CÓMO implementar

Artefacto: openspec/changes/NNN-name/design.md

# Design: Add Health Endpoint

## Architecture Decisions

### ADR-1: Inline Route
**Context**: Health check is simple
**Decision**: Add directly in app.js
**Consequences**: Minimal change, easy to test

## Technical Approach

### Components Affected
- src/app.js: Add health route

### Sequence Diagram
Client -> API: GET /health
API -> Client: 200 { status, timestamp }

Comando: /sdd:plan o /sdd:design

6. TASKS - Tareas

Propósito: Desglosar en unidades completables

Artefacto: openspec/changes/NNN-name/tasks.md

# Tasks: Add Health Endpoint

## Phase 1: Implementation
- [ ] 1.1 Add GET /health route
- [ ] 1.2 Return JSON with status

## Phase 2: Testing
- [ ] 2.1 Add Jest test
- [ ] 2.2 Test 200 response
- [ ] 2.3 Test JSON format

Reglas de tareas:

  • ✅ Completable en una sesión
  • ✅ Número jerárquico (1.1, 1.2)
  • ✅ Agrupadas por fase
  • ✅ Incluyen testing

Comando: /sdd:tasks

7. APPLY - Implementación

Propósito: Ejecutar las tareas

Comando: /sdd:implement [task-number]

Proceso:

  1. Lee specs y design
  2. Carga skills relevantes (react-19, typescript, etc.)
  3. Implementa siguiendo el diseño
  4. Marca tarea completada
  5. Continúa con siguiente tarea

8. VERIFY - Verificación

Propósito: Validar contra especificaciones

Artefacto: openspec/changes/NNN-name/verification.md

# Verification: Add Health Endpoint

## Requirements Coverage
| Requirement | Status | Notes |
|-------------|--------|-------|
| REQ-1 | ✅ PASS | Implemented |

## Scenario Results
| Scenario | Status | Evidence |
|----------|--------|----------|
| SCENARIO-1 | ✅ PASS | tests/health.test.js |

## Test Results
All 3 tests passing

Comando: /sdd:verify

9. ARCHIVE - Archivado

Propósito: Completar y merge specs

Comando: /sdd:archive

Proceso:

  1. Verifica tareas completas
  2. Merge spec.delta.md → specs/*.spec.md
  3. Mueve cambio a archive/
  4. Guarda aprendizajes en Engram

📁 Estructura de Directorios

project/
├── openspec/
│   ├── config.yaml              # Config del proyecto
│   ├── specs/                   # Source of truth
│   │   ├── core/
│   │   │   └── auth.spec.md
│   │   └── features/
│   │       └── health.spec.md
│   └── changes/                 # Cambios activos
│       ├── 001-add-health/
│       │   ├── proposal.md
│       │   ├── spec.delta.md
│       │   ├── design.md
│       │   ├── tasks.md
│       │   └── verification.md
│       └── archive/             # Completados
│           └── 001-add-health/
└── src/                         # Código

🎯 Beneficios de SDD

Para Desarrolladores

Beneficio Descripción
Claridad Sabes exactamente qué construir
Trazabilidad Historial de decisiones
Consistencia IA sigue patrones definidos
Revisibilidad Specs como contrato

Para Equipos

Beneficio Descripción
Onboarding Nuevos miembros leen specs
Code Review Verificar contra specs
Conocimiento Specs como documentación viva
Calidad Tests derivados de scenarios

Para Proyectos

Beneficio Descripción
Mantenibilidad Specs actualizan con código
Onboarding Contexto preservado
Rollback Cambios documentados
Compliance Auditoría disponible

🎭 Escenario Real: Sin SDD vs Con SDD

Sin SDD

Dev: "Agrega login"
Agente: [genera código]
Dev: "No, quería OAuth"
Agente: [regenera]
Dev: "Pero falta el logout"
Agente: [agrega más código]
Dev: "Ahora hay bugs..."
[Loop infinito de correcciones]

Con SDD

Dev: /sdd:new add-oauth-auth
Agente: [crea propuesta con opciones OAuth]
Dev: [revisa, ajusta scope]
Agente: [crea specs con escenarios]
Dev: [aprueba specs]
Agente: [crea diseño con bibliotecas]
Dev: [aprueba diseño]
Agente: [implementa paso a paso]
Dev: [verifica, archiva]
[Resultado: código correcto primera vez]

🎓 Síntesis de la Investigación

  1. SDD es una metodología donde las especificaciones son artefactos de primera clase
  2. 8 fases estructuran el trabajo con IA de manera sistemática
  3. Cada fase produce artefactos específicos documentados
  4. Trazabilidad automática en cada cambio del sistema
  5. IA guiada reduce alucinaciones y aumenta calidad según estudios [1]

🚀 Siguiente Paso

Continúa con Módulo 1B: Context Architecture para profundizar en la arquitectura de contexto.

Módulo 1.0 | Duración: 30 min | Dificultad: 🟢 Básico

📊 Los 3 Niveles de SDD

Birgitta Böckeler (Thoughtworks) identificó tres niveles de implementación [1]:

Nivel 1: Spec-First

Spec → Implementación → Spec descartada

Características: - Specs se escriben antes del código - Sirven como guía durante la implementación - Se descartan o archivan después

Cuándo usar: - Features nuevas - Proyectos greenfield - Cambios aislados

Nivel 2: Spec-Anchored

Spec → Implementación → Spec persiste → Actualizaciones

Características: - Specs viven junto al código - Se actualizan cuando cambia la funcionalidad - Son “source of truth” persistente

Cuándo usar: - Features críticas del sistema - APIs públicas - Componentes compartidos

Nivel 3: Spec-as-Source

Spec (editado por humanos) → Código generado

Características: - Humanos SOLO editan specs - Código es generado automáticamente - Código lleva comentario // GENERATED FROM SPEC - DO NOT EDIT

Cuándo usar: - Componentes bien definidos - APIs con contratos estables - Experimental (todavía madurando)

Comparación de Niveles

Nivel Edición Humana Trazabilidad Mantenibilidad Madurez
Spec-First Código + Spec Temporal Media Alta
Spec-Anchored Código + Spec Permanente Alta Media
Spec-as-Source Solo Spec Total Variable Baja

📝 Tipos de Specs

Patrick Debois (AI Native Dev) identifica 4 tipos:

1. Specs Funcionales/Técnicos

# Feature: Health Endpoint

## Requirements
- GET /health returns 200 OK
- Response includes status and timestamp

## Acceptance Criteria
GIVEN API is running
WHEN GET /health
THEN 200 OK with { status: "ok" }

Propósito: Describir QUÉ hace el sistema

2. Specs de Identidad de Agente

# Agent: Code Reviewer

## Role
You are a senior code reviewer...

## Capabilities
- Review code for patterns
- Suggest improvements
- Check security issues

## Boundaries
- DO NOT modify code directly
- ONLY suggest changes

Propósito: Definir personalidad y límites del agente

3. Specs de Workflow/Tareas

# Workflow: Feature Development

## Steps
1. Create proposal
2. Write specs
3. Design architecture
4. Break into tasks
5. Implement
6. Verify
7. Archive

Propósito: Describir procesos y secuencias

4. Specs de Conocimiento/Uso

# Knowledge: Authentication Patterns

## OAuth 2.0 Flow
- Authorization Code for web apps
- PKCE for SPAs
- Client Credentials for services

## Session Management
- JWT for stateless
- Redis for stateful

Propósito: Capturar conocimiento del dominio

⚠️ Desafíos de SDD

Context Window Constraints

Problema: Demasiados specs sobrecargan el contexto del LLM

Soluciones: - RAG/Context selection - Subagentes con contexto específico - AST parsing + LSP integration

Escribir Buenas Specs

Problema: Los desarrolladores no están acostumbrados a escribir requisitos precisos

Soluciones: - Templates estandarizados - Checklists de validación - Iteración basada en feedback del agente

Spec vs Memory Bank

Memory Bank Spec
Contexto global Contexto específico
Reglas del proyecto Requisitos de feature
Persistente Temporal o persistente
AGENTS.md spec.md

🔗 Specs vs Otros Conceptos

Spec vs Prompt

Prompt: "Add a health endpoint"
→ Instrucción única, sin estructura

Spec: Documento estructurado con requisitos
→ Fuente de verdad, persistente, versionable

Spec vs Test

Test: Verifica comportamiento después
→ "¿Funciona como esperado?"

Spec: Define comportamiento antes
→ "¿Qué se espera que haga?"

SDD + TDD = Mejor juntos: 1. Spec define QUÉ 2. Tests verifican QUÉ 3. Implementación es CÓMO

🚀 Siguiente Paso

Continúa con Módulo 1B: Context Architecture para profundizar en la arquitectura de contexto.

Módulo 01 | © Diego Saavedra

Referencias

[1]
B. Böckeler, «Understanding Spec-Driven Development». Accedido: 24 de febrero de 2026. [En línea]. Disponible en: https://martinfowler.com/articles/spec-driven-development.html