Spec-Driven Development con Superpowers: Como evoluciono mi vibecoding

El problema con el vibecoding común

Todos hemos estado ahí. Abres Claude Code, escribes "hazme una app de tareas con autenticación y base de datos", y la IA se lanza a escribir código durante 10 minutos. El resultado: una mezcla de archivos que a veces funciona, a veces no, y que nadie, ni tú ni la IA, entiende del todo bien.

Eso es vibecoding, darle un prompt vago a la IA y esperar que interprete correctamente lo que tienes en la cabeza. Funciona para prototipos de 20 minutos. No funciona para software real.

El problema no es la IA. El problema es que le estás pidiendo que haga arquitectura, diseño, implementación y revisión al mismo tiempo, sin ningún proceso.

Qué es Superpowers

https://github.com/obra/superpowers es un plugin para Claude Code (y otros agentes de IA como Cursor, Gemini CLI, OpenAI Codex) que le inyecta skills (habilidades especializadas o comportamientos) al modelo. En lugar de que Claude improvise cómo abordar una tarea compleja, sigue un proceso probado.

Se instala en segundos:

Claude Code

/plugin install superpowers@claude-plugins-official

Una vez instalado, Claude tiene acceso a skills como brainstorming, writing-plans, subagent-driven-development, requesting-code-review, y muchas más. Cada skill es una guía de comportamiento que el modelo sigue disciplinadamente.

Mi flujo. Spec-Driven Development en 8 pasos

Lo que aprendí trabajando con IA es que la calidad del software que produce es directamente proporcional a la claridad del proceso que le das.

Este flujo de 8 pasos convierte el caos del vibecoding en algo reproducible y predecible.

Paso 1: Brainstorming

Antes de escribir una sola línea de código, exploro el problema con la skill superpowers:brainstorming.

/skill superpowers:brainstorming
"Quiero construir un sistema de notificaciones para la app"

La diferencia con simplemente preguntarle a Claude es que esta skill hace preguntas que yo no pensé hacer: ¿quién consume las notificaciones?, ¿qué pasa si el usuario está offline?, ¿necesitamos tiempo real o eventual consistency basta?, ¿cómo
afecta esto a la arquitectura existente?

El brainstorming no es generar ideas al azar —es descubrir los requisitos ocultos antes de que se conviertan en bugs.

Paso 2: Verificar el diseño

El brainstorming produce ideas. La verificación las filtra. Aquí reviso con la IA si el diseño propuesto tiene sentido técnico:

• ¿Hay decisiones de arquitectura que se contradicen?
• ¿Hay over-engineering? (YAGNI)
• ¿Hay suposiciones no validadas?

Este paso me ha salvado de construir cosas que no necesitaba. La IA es muy buena proponiendo soluciones elaboradas. Ser disciplinado aquí evita semanas de trabajo innecesario.

Paso 3: Escribir el spec

Con el diseño validado, la skill superpowers:writing-plans genera un documento de especificación estructurado. Un spec no es código —es la descripción precisa de lo que el software debe hacer.

Un buen spec tiene:

• Comportamiento esperado por caso de uso
• Casos borde explícitos
• Lo que está fuera de scope (tan importante como lo que está dentro)
• Criterios de aceptación verificables

Sin spec, cada desarrollador (o agente de IA) interpreta los requisitos a su manera. Con spec, todos trabajan hacia el mismo objetivo.

Paso 4: Revisar el spec

Aquí la IA actúa como revisor crítico del spec que acaba de escribir. La skill lanza un subagente específico para revisar documentos con esta lógica:

| Categoría | Qué buscar |
|---------------|--------------------------------------------------|
| Completitud | TODOs, secciones incompletas, "por definir" |
| Consistencia | Requisitos que se contradicen |
| Cobertura | Casos de error no manejados, edge cases |
| YAGNI | Features no solicitadas, over-engineering |

Si el revisor encuentra problemas, volvemos al paso 3. Si aprueba, seguimos.

Este ciclo de spec → revisión parece lento. En realidad es lo más rápido: un problema detectado en el spec tarda 5 minutos en corregirse. El mismo problema detectado en producción tarda días.

Paso 5: Escribir el plan de implementación

El spec dice qué. El plan dice cómo y en qué orden.

La skill genera un plan con tareas atómicas e independientes. Cada tarea tiene esta estructura:

### Tarea N: [Nombre del componente]

Archivos:

• Crear: ruta/exacta/al/archivo.ts
• Modificar: ruta/existente/archivo.ts:123-145

• Test: tests/ruta/test.ts

• [ ] Paso 1: Escribir el test que falla

• [ ] Paso 2: Verificar que falla

• [ ] Paso 3: Implementar el mínimo código

• [ ] Paso 4: Verificar que pasa

• [ ] Paso 5: Commit

git add tests/ruta/test.ts src/ruta/archivo.ts
git commit -m "feat: agregar feature específica"

La granularidad importa: tareas demasiado grandes generan conflictos entre subagentes. Tareas demasiado pequeñas generan overhead. El punto justo es una tarea por componente o responsabilidad clara.

Paso 6: Revisar el plan

Igual que con el spec, el plan pasa por un revisor antes de ejecutarse. El revisor verifica:

• ¿El plan refleja fielmente el spec?
• ¿Las tareas son verdaderamente independientes entre sí?
• ¿Las rutas de archivos son correctas?
• ¿El orden de implementación tiene sentido?

Si una tarea depende de otra, no pueden ejecutarse en paralelo. El revisor detecta estas dependencias ocultas antes de que rompan la ejecución.

Paso 7: Lanzar el plan con subagentes

Aquí está la magia del sistema. Con superpowers:subagent-driven-development, cada tarea del plan se ejecuta en un subagente independiente en paralelo o secuencialmente según las dependencias.

El flujo real se ve así:

[Extraer las 5 tareas del plan]
[Crear TodoWrite con todas las tareas]

Tarea 1: Sistema de colas
[Despachar subagente implementador con contexto completo de la tarea]

Implementador: "¿La cola debe ser persistente o en memoria?"
Tú: "Persistente con Redis"

Implementador: "Implementando..."
- Cola implementada con BullMQ
- 8/8 tests pasando
- Self-review: agregué manejo de reintentos, estaba en el spec
- Commit realizado

[Despachar revisor de spec]
Revisor: ✅ Cumple spec — todos los requisitos implementados

[Despachar revisor de código]
Revisor: Fortalezas: buena cobertura, arquitectura limpia
Issues: ninguno
Resultado: ✅ Aprobado

[Marcar Tarea 1 como completada]
[Continuar con Tarea 2...]

Cada tarea pasa por tres capas de validación:

1. El implementador hace self-review antes de entregar
2. El revisor de spec verifica que se implementó lo que se especificó (ni más, ni menos)
3. El revisor de código verifica calidad técnica

Si el revisor de spec encuentra que se implementó algo no pedido o faltó algo del spec, el implementador lo corrige antes de seguir con la siguiente tarea.

Paso 8: Commit de los cambios

Cada tarea hace su propio commit atómico siguiendo el formato convencional:

git add tests/ruta/test.ts src/ruta/archivo.ts
git commit -m "feat: agregar sistema de colas con reintentos"

Al final del plan, cada feature está en su propio commit trazable, con tests pasando, alineado con el spec original.

Por qué esto es una evolución y no solo "más pasos"

El vibecoding común trata a la IA como un oráculo: le haces una pregunta y recibes código. El problema es que un oráculo no tiene memoria del proceso, no tiene criterio de corrección, y no puede verificar su propio trabajo.

Spec-Driven Development trata a la IA como un equipo de ingeniería.

  ┌──────────────────────────────────────┬───────────────────────────────────────────┐
  │              Vibecoding              │          Spec-Driven Development          │
  ├──────────────────────────────────────┼───────────────────────────────────────────┤
  │ Un prompt → todo el código           │ Proceso estructurado en fases             │
  ├──────────────────────────────────────┼───────────────────────────────────────────┤
  │ Errores descubiertos en ejecución    │ Errores detectados en spec/plan           │
  ├──────────────────────────────────────┼───────────────────────────────────────────┤
  │ La IA interpreta los requisitos      │ Los requisitos están escritos y validados │
  ├──────────────────────────────────────┼───────────────────────────────────────────┤
  │ Código monolítico difícil de revisar │ Commits atómicos por responsabilidad      │
  ├──────────────────────────────────────┼───────────────────────────────────────────┤
  │ Resultado impredecible               │ Resultado alineado con el diseño original │
  ├──────────────────────────────────────┼───────────────────────────────────────────┤
  │ No escala con complejidad            │ Escala con subagentes paralelos           │
  └──────────────────────────────────────┴───────────────────────────────────────────┘

La clave no es que la IA sea más inteligente con este flujo. Es que el proceso elimina la ambigüedad que hace que la IA tome decisiones equivocadas.

Cuando la IA tiene un spec claro, un plan preciso y un revisor que verifica cada paso, produce software de la misma calidad que un equipo de ingenieros disciplinado. Sin ese proceso, produce el mismo vibecoding que todos hemos sufrido.

El resultado

Con este flujo, dejé de pasar horas corrigiendo código que la IA generó mal porque yo no fui claro. Ahora los problemas se detectan en el paso 3 o el paso 6 —cuando corregirlos cuesta minutos, no días.

El vibecoding es divertido para explorar ideas. El Spec-Driven Development es lo que uso cuando el código importa. Se puede decir que es ingeniería pura y dura.