Skip to content
ArceApps Logo ArceApps
EN
#AI #Workflow #SDD #IA Agéntica #Documentación #Productividad #GitHub Copilot #BMAD #OpenSpec

Desarrollo Impulsado por Especificaciones con IA Agéntica: Metodologías, Frameworks y Aplicación Real

17 min de lectura
Desarrollo Impulsado por Especificaciones con IA Agéntica: Metodologías, Frameworks y Aplicación Real
Índice de contenidos

Lecturas relacionadas: Construyendo AI Skills para Desarrollo · Configurando Agentes de IA · Code Reviews con IA: Puertas de Calidad Automáticas

🧠 La Crisis del Vibe Coding

Durante los últimos dos años, el “vibe coding” se ha convertido en el nombre no oficial para un patrón muy extendido: abrir una ventana de chat, describir una funcionalidad en lenguaje natural impreciso, esperar que la IA lo entienda, pegar la salida, y repetir hasta que algo más o menos funcione. Es rápido, entretenido, y completamente insostenible a escala.

El problema fundamental no es la capacidad de la IA — los modelos de lenguaje modernos son genuinamente impresionantes generando código. El problema es la degradación de contexto: sin una fuente de verdad estable y estructurada, cada mensaje a un agente de IA es una negociación nueva con un sistema que no tiene memoria duradera de tu arquitectura, restricciones, decisiones pasadas ni estándares de calidad.

El resultado es código que acumula deuda técnica a la misma velocidad con que fue generado. El Desarrollo Impulsado por Especificaciones (SDD) es la disciplina de ingeniería que cambia esta ecuación.

📐 ¿Qué es Spec-Driven Development (SDD)?

Spec-Driven Development es una metodología que eleva el documento de especificación formal al artefacto central y autoritativo del ciclo de vida de desarrollo de software. La spec — no el código, no el ticket, no la conversación — es la única fuente de verdad.

En TDD tradicional, escribes tests antes que el código. En SDD, escribes especificaciones antes que los tests y el código. La especificación captura:

  • Intención: Por qué existe esta funcionalidad, qué problema de negocio resuelve.
  • Contratos: Definiciones precisas de modelos de datos, superficies de API y estados de UI.
  • Restricciones: Requisitos no funcionales — rendimiento, seguridad, accesibilidad, elecciones de librerías.
  • Casos borde: Cada escenario que el camino feliz ignora.
  • Criterios de aceptación: Condiciones verificables por máquina para la completitud.

La idea clave para la era de la IA agéntica es que una spec bien escrita no es documentación que los humanos escriben y olvidan. Es contexto estructurado que los agentes de IA consumen, verifican y usan para impulsar la implementación. Una spec es un programa que programa al programador — humano o artificial.

┌──────────────────────────────────────────────────────────┐
│               CICLO DE VIDA SDD                          │
│                                                          │
│  ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐ │
│  │ESPECIF. │──▶│  PLAN   │──▶│ TAREAS  │──▶│  CÓDIGO │ │
│  │ spec.md │   │ plan.md │   │tasks.md │   │  impl/  │ │
│  └─────────┘   └─────────┘   └─────────┘   └─────────┘ │
│       ▲                                          │       │
│       └───────────── retroalimentación ──────────┘       │
│                                                          │
│   Checkpoints humanos: Especificación → Aprobación plan  │
│   Autonomía IA: Tareas → Implementación                  │
└──────────────────────────────────────────────────────────┘

🌐 El Panorama: Los Principales Frameworks SDD en 2025

El ecosistema SDD ha madurado significativamente. A continuación, una visión experta de los frameworks más influyentes.

1. GitHub Spec Kit (github/spec-kit)

Lanzado en septiembre de 2025 como toolkit open-source con licencia MIT, GitHub Spec Kit codifica el flujo de trabajo de cuatro fases que el equipo de ingeniería de GitHub desarrolló internamente al construir funcionalidades de Copilot.

Las Cuatro Fases:

FaseArtefactoResponsablePuerta de Control
Especificarspecs/feature.mdHumano + IAAprobación humana
Planificarplan/architecture.mdIA + revisión humanaAprobación humana
Tareastasks.md (autogenerado)IAValidación CI
Implementarsrc/ (código)Agente IATests aprobados

Ejemplo de flujo usando CLI:

# Inicializar proyecto spec-driven
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify init mi-funcionalidad

# La IA genera una spec detallada desde tu descripción
# → specs/mi-funcionalidad.md

# Validar completitud de la spec
specify check

# La IA genera el plan, tareas e implementación secuencialmente
# Con el agente Copilot: @copilot /specify plan
# @copilot /specify tasks
# @copilot /specify implement

La clave de Spec Kit es su control por fases: un agente de IA no puede saltar a la implementación sin un plan aprobado por un humano. Esto crea una pista de auditoría natural y previene la generación descontrolada de código que el vibe coding permite.

Ideal para: Equipos pequeños y medianos, proyectos open-source, flujos de trabajo nativos de GitHub.

2. Método BMAD (bmad-code-org/BMAD-METHOD)

BMAD (Build More, Architect Dreams) es el framework SDD más ambicioso arquitectónicamente. Donde Spec Kit es una lista de comprobación de cuatro pasos, BMAD es un organigrama agéntico completo.

Incluye más de 20 agentes de IA especializados, cada uno desempeñando un rol en un pipeline multi-agente:

┌─────────────────────────────────────────────────────────┐
│               PIPELINE DE AGENTES BMAD                  │
│                                                         │
│  Analista ──▶ Product Manager ──▶ Arquitecto            │
│                                      │                  │
│            Scrum Master ◀────────────┘                  │
│                   │                                     │
│         ┌─────────┼─────────┐                           │
│         ▼         ▼         ▼                           │
│    Desarrollador Dev.   Desarrollador                   │
│         │         │         │                           │
│         └─────────┼─────────┘                           │
│                   ▼                                     │
│          Ing. QA ──▶ Revisor                            │
└─────────────────────────────────────────────────────────┘

BMAD impone una estructura de spec tripartita:

specs/
├── api/           # Contratos OpenAPI / Swagger
│   └── users.yaml
├── data/          # Definiciones de entidades JSON Schema
│   └── user.schema.json
└── behavior/      # Archivos Gherkin de funcionalidades
    └── user-auth.feature

Esta separación es arquitectónicamente elegante: la spec de API define el contrato entre servicios, la spec de datos define la estructura y validación de entidades, y la spec de comportamiento define lo que el sistema debe hacer desde la perspectiva del usuario — las tres son legibles por máquina y testeables.

# specs/behavior/user-auth.feature
Feature: Autenticación de Usuario
  Como usuario
  Quiero iniciar sesión con mi email y contraseña
  Para poder acceder a mi contenido personalizado

  Scenario: Login exitoso
    Given que estoy en la pantalla de login
    When introduzco credenciales válidas
    Then debería ser redirigido a la pantalla principal
    And mi token de sesión debería persistirse en EncryptedSharedPreferences

  Scenario: Credenciales inválidas
    Given que estoy en la pantalla de login
    When introduzco una contraseña incorrecta
    Then debería ver el error "Credenciales incorrectas"
    And el campo de contraseña debería mostrar una animación de shake

Ideal para: Proyectos empresariales, coordinación multi-agente, equipos que necesitan pistas de auditoría y claridad de onboarding.

3. OpenSpec (Fission-AI/OpenSpec)

OpenSpec adopta una filosofía deliberadamente ligera. Ve las especificaciones como carpetas vivas que viajan junto a tu código, no silos de documentación separados.

Cada cambio propuesto genera una nueva carpeta:

.openspec/
└── proposals/
    └── 2025-rediseno-login/
        ├── proposal.md       # Por qué: motivación y alcance
        ├── spec.md           # Qué: spec técnica detallada
        ├── design.md         # Cómo: arquitectura y modelo de datos
        └── tasks.md          # Tareas atómicas de implementación

La idea clave de OpenSpec es la ergonomía del revisor: cualquier desarrollador (o agente) que revise un PR puede leer la carpeta de propuesta para entender por qué cambió el código, no solo qué cambió. Esto reduce drásticamente el tiempo de onboarding y la fricción en code reviews.

OpenSpec funciona nativamente con más de 20 herramientas de IA incluyendo Claude, GitHub Copilot, Cursor, Amazon Q Developer y Gemini. Su configuración es un único comando:

npx openspec init

Ideal para: Desarrolladores individuales, equipos pequeños, proyectos donde la velocidad de adopción importa más que la profundidad de orquestación.

4. Framework SPARC (ruvnet/sparc)

SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) es un andamiaje cognitivo para estructurar las interacciones con agentes de IA en problemas complejos. Es anterior a la oleada moderna de SDD pero su modelo de fases estructuradas influyó en muchos sucesores.

S - Specification (Especificación): Define el problema y restricciones con precisión
P - Pseudocode (Pseudocódigo):      Expresa la solución en lógica agnóstica al lenguaje
A - Architecture (Arquitectura):    Diseña el componente y la estructura de datos
R - Refinement (Refinamiento):      Ciclos de revisión iterativa con la IA
C - Completion (Completitud):       Integración final, testing y documentación

SPARC es menos un framework a nivel de proyecto y más una disciplina de prompt engineering. Su valor está en enseñar a los desarrolladores a dejar de tratar la IA como un genio y empezar a tratarla como un pair programmer que necesita contexto estructurado en cada etapa.

5. GSD-2 (gsd-build/gsd-2) y Forge Framework (scottfeltham/forge-framework)

GSD-2 (Get Stuff Done) se centra en el lado operacional de SDD: proporciona plantillas y herramientas CLI para generar definiciones de tareas estandarizadas que los agentes pueden recoger y ejecutar de forma fiable. Su filosofía es que la spec solo tiene valor si se traduce en tareas concretas, atómicas e independientemente verificables.

Forge Framework aborda SDD desde una perspectiva de contrato primero: antes de escribir una sola línea de código, cada interfaz pública, endpoint de API y contrato de datos debe estar formalmente especificado. Los agentes de Forge se negarán a implementar un componente cuyo contrato de interfaz esté incompleto.

6. CC-SDD (rhuss/cc-sdd) y Traycer

CC-SDD (Claude Code SDD) es un toolkit de practicante construido específicamente para Claude Code. Incluye un conjunto de comandos personalizados y plantillas de especificación optimizadas para la gestión de la ventana de contexto de Claude, haciéndolo particularmente efectivo para proyectos con grandes bases de código.

Traycer (docs.traycer.ai) adopta un ángulo diferente: hace ingeniería inversa de specs a partir de bases de código existentes, dando a los equipos una manera de aplicar retroactivamente los principios SDD a proyectos legacy. Esto es cada vez más importante ya que muchos equipos tienen meses de output “vibe-codeado” que necesita ser estructurado y documentado.

🔬 Análisis Profundo: Anatomía de una Spec de Producción

Una spec vaga produce código vago. Aquí es como se ve una spec de producción real para una funcionalidad — un sistema de “Favoritos del Usuario” en una aplicación Android:

# Especificación de Funcionalidad: Favoritos del Usuario

**Versión**: 1.2
**Estado**: Aprobada
**Autor**: Equipo de Ingeniería
**Última Actualización**: 2026-03-24

---

## 1. Visión General

### 1.1 Problema a Resolver
Los usuarios no pueden guardar ítems de interés para más tarde. Esto crea fricción
en el journey del usuario y aumenta la tasa de rebote en pantallas de detalle.

### 1.2 Métricas de Éxito
- Reducción del 30% en tasa de rebote (ventana de 90 días)
- Tiempo de respuesta al toggle < 200ms (P95)
- Cero pérdida de datos en caso de fallo de red

---

## 2. User Stories

| ID  | Como...        | Quiero...                        | Para...                              |
|-----|---------------|----------------------------------|--------------------------------------|
| US1 | usuario auth  | marcar/desmarcar un ítem como fav| guardarlo para después               |
| US2 | usuario auth  | ver mis favoritos sin conexión   | navegar sin conectividad             |
| US3 | usuario auth  | sincronizar favoritos entre disp.| que mi lista sea siempre consistente |

---

## 3. Modelo de Datos

```kotlin
// Capa de Dominio
data class FavoriteItem(
    val itemId: String,
    val addedAt: Instant,
    val syncStatus: SyncStatus  // SYNCED | PENDING | FAILED
)

enum class SyncStatus { SYNCED, PENDING, FAILED }
-- Base de datos (Room)
CREATE TABLE favorites (
    item_id TEXT PRIMARY KEY NOT NULL,
    added_at INTEGER NOT NULL,  -- Unix epoch millis
    sync_status TEXT NOT NULL DEFAULT 'PENDING',
    FOREIGN KEY (item_id) REFERENCES items(id) ON DELETE CASCADE
);
CREATE INDEX idx_favorites_sync_status ON favorites(sync_status);

4. Contrato de API

# API Remota
POST /api/v2/favorites/{itemId}:
  responses:
    201: { description: "Favorito añadido" }
    409: { description: "Ya es favorito" }
    404: { description: "Ítem no encontrado" }

DELETE /api/v2/favorites/{itemId}:
  responses:
    204: { description: "Favorito eliminado" }
    404: { description: "Favorito no encontrado" }

GET /api/v2/favorites:
  parameters:
    - page: integer
    - pageSize: integer (default: 20, max: 100)
  responses:
    200: { schema: { items: FavoriteItem[], total: integer } }

5. Arquitectura

Capa UI (Compose)
  └── FavoritesScreen.kt        # Composable sin estado
  └── FavoritesViewModel.kt     # Mantiene FavoritesUiState

Capa de Dominio
  └── ToggleFavoriteUseCase.kt  # UI optimista + sincronización
  └── GetFavoritesUseCase.kt    # Retorna Flow<List<FavoriteItem>>

Capa de Datos
  └── FavoritesRepository.kt   # Coordina local + remoto
  └── FavoritesLocalSource.kt  # Operaciones DAO de Room
  └── FavoritesRemoteSource.kt # Llamadas API de Retrofit

6. Casos Borde y Manejo de Errores

EscenarioComportamiento Esperado
Toggle sin conexiónActualizar BD local inmediatamente; encolar trabajo de sync
API retorna 409Tratar como éxito (idempotente)
API retorna 5xxReintentar 3 veces con backoff exponencial (1s, 2s, 4s)
Ítem eliminado en servidorEliminar de BD local en próxima sincronización
Usuario cierra sesiónLimpiar todos los favoritos de BD local
Toggle concurrente (doble toque)Debounce 300ms, último estado gana

7. Requisitos No Funcionales

  • Rendimiento: Toggle debe completar actualización local en < 50ms
  • Offline First: Todas las lecturas deben funcionar sin red
  • Seguridad: Los favoritos son de ámbito de usuario; nunca exponer datos cruzados
  • Testing: Mínimo 80% de cobertura de tests unitarios en capas UseCase y Repository

Con este nivel de especificación, un agente de IA — ya sea GitHub Copilot, Claude Code o Gemini — puede implementar la funcionalidad completa con ambigüedad cercana a cero. Más importante, la implementación es *verificable*: cada línea de código puede comprobarse contra la spec.

---

## 🤖 SDD y el Futuro Multi-Agente

El verdadero poder de SDD emerge en arquitecturas multi-agente. Cuando múltiples agentes de IA colaboran — un analista, un arquitecto, un desarrollador, un ingeniero QA — la spec se convierte en la **memoria compartida** que evita que trabajen con propósitos cruzados.

Considera este flujo de trabajo usando el pipeline de agentes de BMAD:

  1. Agente Analista lee requisitos del producto → Produce: user_stories.md, acceptance_criteria.md

  2. Agente Arquitecto lee user_stories.md → Produce: system_design.md, api_spec.yaml, data_schema.json

  3. Agente Desarrollador lee system_design.md + api_spec.yaml → Produce: código de implementación, tipado estrictamente según spec

  4. Agente QA lee acceptance_criteria.md + implementación → Produce: suite de tests, informe de cumplimiento de spec

  5. Agente Revisor lee spec + código + resultados de tests → Aprueba o solicita revisión de spec


En ningún momento ningún agente "improvisa". Cada agente opera dentro de los límites establecidos por la spec. Esto es fundamentalmente diferente a dar a un único agente de IA un prompt vago y confiar en que lo resolverá.

La spec también resuelve el **problema de la ventana de contexto**: ningún agente individual necesita mantener en memoria todo el historial del proyecto. Cada agente lee los artefactos de spec relevantes para su rol y procede. La spec es un sistema de memoria externo y persistente para todo el equipo agéntico.

---

## ⚙️ Eligiendo el Framework Adecuado

| Framework | Filosofía | Tamaño de Equipo | Complejidad | Soporte Herramientas IA |
|-----------|-----------|-----------------|-------------|------------------------|
| **GitHub Spec Kit** | Flujo controlado por fases | 1–20 | Baja | Copilot, Claude, Gemini |
| **Método BMAD** | Organización agéntica completa | 5–50+ | Alta | Cursor, Claude, Copilot |
| **OpenSpec** | Ligero, iterativo | 1–10 | Muy Baja | Más de 20 herramientas |
| **SPARC** | Disciplina de prompting | 1–5 | Ninguna | Cualquier LLM |
| **GSD-2** | Atomicidad operacional | 1–15 | Baja-Media | Varios |
| **Forge Framework** | Contrato primero | 3–20 | Media | Varios |
| **CC-SDD** | Optimizado para Claude | 1–10 | Baja | Claude Code |

**Guía de decisión para desarrolladores indie/en solitario:**

- Empezando con SDD → **OpenSpec** o **SPARC**
- Flujo de trabajo nativo de GitHub → **GitHub Spec Kit**
- Proyecto complejo multi-funcionalidad → **Método BMAD**
- Trabajando principalmente con Claude Code → **CC-SDD**

---

## 🛡️ Integrando SDD con CI/CD

El valor de SDD se multiplica cuando se integra con la integración continua. Considera este flujo de trabajo de GitHub Actions que impone el cumplimiento de specs:

```yaml
# .github/workflows/spec-check.yml
name: Comprobación de Cumplimiento de Spec

on: [pull_request]

jobs:
  spec-validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validar completitud de spec
        run: specify check --strict
        # Falla si spec.md no tiene las secciones requeridas

      - name: Comprobar cobertura de implementación
        run: |
          # Verificar que todos los requisitos de spec tienen tests correspondientes
          python scripts/spec_coverage.py --spec specs/ --tests tests/
          # Falla si cobertura < 80%

      - name: Revisión de spec por IA
        uses: actions/ai-review@v1
        with:
          prompt: |
            Revisa este PR contra la especificación en specs/.
            Marca cualquier implementación que contradiga la spec.
            Falla si se encuentran desviaciones críticas.

Este pipeline asegura que ningún código se fusiona sin ser trazable a una spec — un nivel de disciplina de ingeniería que es casi imposible de mantener con el coding ad-hoc con IA.

📚 Buenas Prácticas desde el Campo

Tras trabajar con SDD en varios proyectos personales, estas son las prácticas que aportan más valor:

1. Spec Antes que Prompt, Siempre. Incluso para una funcionalidad “rápida”, dedica 10 minutos a escribir una spec. La IA genera código dramáticamente mejor, y piensas en los casos borde que habrías descubierto como bugs más tarde.

2. Versiona tus Specs. Las specs deben vivir en tu repositorio y pasar por code review, igual que el código. Una spec que cambia sin revisión es una spec que miente.

3. Separa el Comportamiento de la Implementación. La spec describe qué hace el sistema, no cómo lo hace. Resiste la tentación de prescribir detalles de implementación en la spec — ese es el trabajo del agente.

4. Usa Esquemas Agresivamente. JSON Schema, OpenAPI y Gherkin son multiplicadores de fuerza. Un esquema legible por máquina es tanto documentación como herramienta de validación. Cualquier agente de IA puede verificar su output contra un JSON Schema.

5. Trata la Spec como Artefacto de Retrospectiva. Después de cada sprint, revisa si la spec coincidía con la realidad de lo que se construyó. Si no, actualiza la spec — o investiga por qué la implementación se desvió.

6. Empieza Pequeño. No intentes especificar una aplicación completa el primer día. Elige un componente, especifícalo meticulosamente, impleméntalo con un agente de IA, y observa la mejora de calidad. Construye el hábito antes que el sistema.

🎯 Conclusión: Disciplina de Ingeniería para la Era Agéntica

La transición del vibe coding al desarrollo impulsado por especificaciones no es cuestión de añadir burocracia. Es reconocer que los agentes de IA son poderosos precisamente porque siguen instrucciones con precisión — y que las instrucciones vagas producen resultados vagos independientemente del modelo.

Frameworks como GitHub Spec Kit, el Método BMAD y OpenSpec proporcionan estructuras probadas en batalla para la nueva realidad del desarrollo de software: equipos de ingenieros humanos colaborando con agentes de IA, donde la especificación es el lenguaje común que todos hablan.

Para el desarrollador indie y creador en solitario, esta metodología es especialmente valiosa. Sin un equipo que capture la desviación arquitectónica, la spec se convierte en tu memoria arquitectónica — un documento que asegura que la versión de ti que trabaje en el proyecto dentro de tres meses sabe exactamente por qué la versión de ti de hoy tomó cada decisión.

La inversión en una spec bien escrita siempre se recupera — normalmente en la primera sesión de debugging que no tienes que hacer.

📖 Referencias y Recursos

Share this post:
Twitter (X) LinkedIn WhatsApp
Volver al Blog

También te puede interesar

Análisis Profundo de Frameworks SDD: GitHub Spec Kit, OpenSpec y BMAD-METHOD Comparados
SDD 28 de marzo de 2026

Análisis Profundo de Frameworks SDD: GitHub Spec Kit, OpenSpec y BMAD-METHOD Comparados

Un análisis exhaustivo de los tres principales frameworks de Desarrollo Guiado por Especificaciones: los contratos arquitectónicos de GitHub Spec Kit, la agilidad por propuestas de cambio de OpenSpec, y la orquestación multi-agente de BMAD-METHOD.

Leer más
Desarrollo Lean Task-First: Beads, LeanSpec y Taskmaster en la Práctica
AI 28 de marzo de 2026

Desarrollo Lean Task-First: Beads, LeanSpec y Taskmaster en la Práctica

Un análisis profundo de tres herramientas que combaten el context rot y mantienen a los agentes de IA enfocados: Beads (rastreador de issues DAG nativo de git), LeanSpec (workflow spec-driven minimalista) y Taskmaster (orquestación PRD-a-tareas). Comandos reales, workflows reales, perspectiva indie dev real.

Leer más
Documentación en Android: KDoc, Dokka y Flujo de Trabajo Profesional 📚
Android 10 de marzo de 2025

Documentación en Android: KDoc, Dokka y Flujo de Trabajo Profesional 📚

Domina las herramientas esenciales para documentar tu código Kotlin y Android como un profesional: desde KDoc hasta Dokka, con integración completa en tu workflow de desarrollo.

Leer más