Dentro de Superpowers: El Framework que Obliga a la IA a Hacer Ingeniería

Lectura previa recomendada: Metodologías de Ingeniería Agéntica: Superpowers vs OpenSpec · Subagentes en OpenCode · TDD e IA en el Desarrollo Android

Si has pasado una cantidad significativa de tiempo construyendo software con agentes de IA, conoces el ciclo. Empiezas con una idea brillante, escribes un prompt detallado y presionas Enter. El agente escribe 500 líneas de código. Lo ejecutas. Falla. Pegas el error de vuelta. Escribe otras 200 líneas, arreglando el error pero rompiendo silenciosamente una funcionalidad no relacionada. Dos horas después, te estás ahogando en un mar de historial de chat contaminado por el contexto, revirtiendo archivos manualmente y preguntándote por qué no escribiste el código tú mismo desde el principio.

Esta es la realidad de la generación con IA sin restricciones. Los Grandes Modelos de Lenguaje (LLMs) son motores probabilísticos de texto; sin barandillas estrictas, se desvían. Alucinan APIs, olvidan casos límite y abandonan patrones arquitectónicos en el instante en que aparece un error.

Entra Superpowers.

Desarrollado por Jesse Vincent, Superpowers no es solo un wrapper o un conjunto de prompts ingeniosos. Se describe a sí mismo como una “metodología de desarrollo de software completa para tus agentes de programación”. Después de pasar semanas diseccionando su código fuente y poniéndolo a prueba en el portafolio de ArceApps, puedo decir con confianza que es el enfoque más obstinado, riguroso y fascinante para la programación con IA disponible actualmente.

En mi artículo anterior, comparé Superpowers con OpenSpec, destacando las diferencias filosóficas entre los frameworks orientados a procesos y los orientados a artefactos. Hoy, vamos a llegar hasta el fondo de la madriguera del conejo. Veremos exactamente cómo funciona Superpowers, cómo están estructuradas sus “habilidades” (skills), por qué su uso de subagentes paralelos es una genialidad y en qué puntos flaquea el framework.

Los Cimientos: Habilidades Componibles

Para entender Superpowers, tienes que entender cómo interactúa con la IA. Superpowers está diseñado para ejecutarse dentro de un entorno o harness de agente existente, como Claude Code, Codex CLI o Cursor.

En lugar de un único y monolítico prompt del sistema, Superpowers se construye como una biblioteca de “Habilidades” (Skills). Cada habilidad se define en un archivo markdown que contiene un nombre, una descripción de cuándo usarla y un conjunto de instrucciones altamente detalladas.

Cuando instalas el plugin, estas habilidades se cargan en el contexto del agente. Se instruye al prompt del sistema nativo del agente para que evalúe la solicitud del usuario y active de forma autónoma la habilidad pertinente.

Aquí están algunas de las habilidades centrales en la biblioteca de Superpowers:

• test-driven-development (Desarrollo Guiado por Pruebas)
• systematic-debugging (Depuración Sistemática)
• brainstorming (Lluvia de ideas)
• writing-plans (Redacción de planes)
• using-git-worktrees (Uso de Git Worktrees)
• subagent-driven-development (Desarrollo Guiado por Subagentes)

La Anatomía de una Habilidad

Veamos cómo se escribe realmente una habilidad. No es texto conversacional educado; es un algoritmo estricto que el LLM debe seguir. Tomemos como ejemplo la habilidad test-driven-development. La documentación declara explícitamente:

La Ley de Hierro: NINGÚN CÓDIGO DE PRODUCCIÓN SIN UNA PRUEBA QUE FALLE PRIMERO. ¿Escribiste código antes que la prueba? Bórralo. Empieza de nuevo. Sin excepciones.

Esto es ingeniería de prompts llevada a su extremo lógico. No deja margen para que el LLM se salte pasos “para ayudar”. Si el agente activa la habilidad TDD, está obligado por estas instrucciones. Esta arquitectura componible significa que puedes añadir nuevas habilidades o modificar las existentes sin tener que reescribir toda la lógica del framework.

El Flujo de Trabajo de Superpowers: De la Idea a la Ejecución

El verdadero poder de Superpowers se hace evidente cuando ves encadenarse estas habilidades. Cuando pides al agente que implemente una nueva funcionalidad, no empieza a escribir código sin más. Inicia un flujo de trabajo complejo de múltiples etapas.

Fase 1: Lluvia de Ideas (brainstorming)

En el momento en que el agente detecta que quieres construir algo nuevo, se detiene. Se niega a escribir código. En su lugar, activa la habilidad de brainstorming.

Esta fase es socrática. El agente hace preguntas incisivas sobre casos límite, estructuras de datos y restricciones arquitectónicas. Una vez que tiene suficiente información, genera un documento de diseño preliminar y te lo presenta en fragmentos. Te obliga a validar el diseño antes de continuar.

Como desarrollador independiente, esto tiene un valor incalculable. A menudo abordo una funcionalidad con una idea a medio cocinar. Tener a un agente cuestionando implacablemente mis suposiciones (“¿Cómo manejará este componente de UI los idiomas RTL?”, “¿Cuál es el plan de contingencia si la API supera el límite de peticiones?”) detecta fallos fundamentales antes de que queden fijados en el código.

Fase 2: Aislamiento (using-git-worktrees)

Una vez aprobado el diseño, Superpowers impone un espacio de trabajo limpio. Activa la habilidad using-git-worktrees.

En lugar de contaminar tu rama actual con código experimental generado por IA, crea un git worktree dedicado en un directorio temporal en una nueva rama. Luego ejecuta los scripts de configuración de tu proyecto y verifica que la suite de pruebas pase limpiamente en este entorno aislado. Si las pruebas fallan antes de siquiera empezar, el proceso se detiene.

Esto garantiza que cualquier fallo posterior sea culpa del nuevo código, no de la contaminación del entorno.

Fase 3: El Plan (writing-plans)

Con un worktree limpio y listo, el agente activa writing-plans. Toma el diseño aprobado y lo desglosa en un plan de implementación en formato markdown altamente granular.

Superpowers dicta que las tareas deben ser “pequeñas” (bocados de 2 a 5 minutos de trabajo). Cada tarea en el plan debe incluir:

1. Rutas de archivo exactas.
2. El código completo que se debe escribir (nada de placeholders como “etc.” o “implementa la lógica aquí”).
3. Pasos de verificación específicos (la prueba que debe escribirse).

Este plan actúa como el plano para el resto de la ejecución. Es el artefacto crucial que evita que el agente pierda el rumbo.

Fase 4: Orquestación de Subagentes (subagent-driven-development)

Esta es la joya de la corona de la metodología Superpowers. Si tu entorno base lo soporta (como Claude Code), el agente principal activará ahora el subagent-driven-development (Desarrollo Guiado por Subagentes).

En lugar de que el agente principal lea el plan e intente ejecutar los 15 pasos en una sesión masiva y cargada de contexto, se convierte en un orquestador. Para la Tarea 1, genera un subagente completamente nuevo.

El orquestador le entrega al subagente solo lo que necesita:

• El contexto general (para que sepa dónde encaja).
• Las instrucciones específicas para la Tarea 1.
• La orden estricta de seguir la habilidad test-driven-development.

El subagente se despierta, escribe la prueba que falla, escribe la implementación, hace que la prueba pase y reporta su estado. Luego, es terminado.

El orquestador inicia entonces una revisión en dos etapas:

1. Revisión de Cumplimiento de Especificaciones: ¿Construyó el subagente exactamente lo que la Tarea 1 exigía?
2. Revisión de Calidad del Código: ¿Cumple el código con los estándares del proyecto?

Si la revisión falla, el orquestador genera un nuevo subagente “reparador” con comentarios específicos. Si pasa, pasa a la Tarea 2 y genera otro subagente completamente fresco.

Por Qué los Subagentes lo Cambian Todo

Si alguna vez has visto a un LLM intentar implementar un plan de 10 pasos en un solo chat, has visto el colapso del contexto. Para el Paso 6, el LLM ha olvidado las restricciones arquitectónicas establecidas en el Paso 1. Empieza a repetirse, confunde nombres de variables de pasos anteriores y, en general, se degrada en su capacidad de razonamiento a medida que el conteo de tokens explota.

Los subagentes resuelven esto de forma elegante. Un subagente nuevo tiene cero recuerdos de las dificultades del paso anterior. Su ventana de contexto está vacía, su mecanismo de atención está enfocado como un láser y su generación de tokens es barata. Solo sabe sobre la Tarea N.

Este aislamiento es cómo Superpowers puede funcionar autónomamente durante dos horas, implementando funcionalidades complejas en docenas de archivos, sin desviarse del plan original. Imita cómo un líder técnico (el orquestador) delega pequeños tickets a desarrolladores junior (los subagentes) y revisa sus Pull Requests antes de seguir adelante.

La Ley de Hierro de TDD en la Práctica

Veamos más de cerca cómo Superpowers impone el TDD. Para muchos desarrolladores humanos, TDD es una aspiración, no una realidad diaria. Superpowers obliga a que sea una realidad.

Cuando se asigna a un subagente la tarea de implementar una funcionalidad, la habilidad test-driven-development prohíbe explícitamente escribir código de producción primero.

Si estás construyendo una aplicación de Android y le pides que implemente un nuevo ViewModel, no escribirá el código Kotlin para el ViewModel. Primero escribirá MyViewModelTest.kt, instanciando el view model y afirmando que el estado inicial es correcto. Ejecutará la prueba. La prueba fallará (porque la clase no existe). Solo entonces escribirá el esqueleto de la clase ViewModel.

Este proceso es lento. Se siente agónicamente metódico cuando estás viendo la salida del terminal. El agente ejecuta pnpm test, lee los logs de fallos, escribe tres líneas de código, ejecuta pnpm test de nuevo, lee los logs de éxito y hace un commit.

Pero el resultado es innegable. Cuando termina la ejecución de Superpowers, no tienes solo una funcionalidad; tienes una funcionalidad completamente probada. Tienes absoluta confianza en que el código funciona exactamente como se especificó en el plan. Para un desarrollador indie que gestiona solo una base de código compleja, esta red de seguridad automatizada no tiene precio.

Análisis Crítico: Lo Bueno, Lo Malo y Lo Brutal

Superpowers es una pieza increíble de ingeniería, pero no es una bala de plata. Tras un uso extensivo, aquí están mis opiniones sin barniz sobre sus fortalezas y debilidades.

Lo Bueno: Calidad y Enfoque Sin Precedentes

1. Preservación del Contexto a través del Aislamiento: La arquitectura de subagentes es la característica estrella. Al hacer borrón y cuenta nueva para cada tarea discreta, Superpowers elimina por completo la deriva del contexto que plaga las sesiones largas de IA. La calidad del código generado en la Tarea 15 es tan nítida como el código generado en la Tarea 1.

2. El Fin de “En mi máquina funciona”: La insistencia en los git worktrees es brillante. ¿Cuántas veces has dejado a una IA suelta en tu repositorio, solo para darte cuenta de que modificó un archivo de configuración con el que estabas experimentando, rompiendo tu entorno local? Los worktrees garantizan que la IA opera en un laboratorio estéril, probando que su código funciona contra una línea base limpia.

3. TDD como Barandilla de Seguridad: Mientras que los desarrolladores humanos a menudo discuten sobre el retorno de inversión del TDD estricto, para un agente de IA, es la barandilla de seguridad definitiva. La prueba actúa como una validación objetiva y legible por máquina de que el agente entendió el prompt. Si el agente alucina, la prueba falla. Obliga al LLM a fundamentar su razonamiento en una realidad ejecutable.

Lo Malo: Fricción y Velocidad

1. Es Agónicamente Lento: Superpowers sacrifica la velocidad por la exactitud. Una tarea que podrías hackear manualmente en 10 minutos podría tomarle a Superpowers 45 minutos entre hacer la lluvia de ideas, planificar, crear el worktree, probar, implementar y revisar. Si estás haciendo prototipado rápido o ajustes visuales de UI, la metodología se siente como caminar sobre melaza. Está diseñado para hacer ingeniería, no para hackear.

2. Gula de Tokens: El flujo de trabajo es increíblemente intensivo en tokens. El constante cambio de contexto, la lluvia de ideas socrática, la redacción y lectura de extensos documentos de planes y el ir y venir del ciclo TDD consumen cantidades masivas de créditos de API. Si estás pagando por token, Superpowers quemará un agujero en tu cartera rápidamente.

3. La Carga del Boilerplate: A veces, solo quieres añadir una sola clase CSS o corregir un error tipográfico en un archivo markdown. Activar el flujo de trabajo de Superpowers para estas microtareas es absurdo. Tienes que luchar activamente contra el framework o salir de él para hacer cosas sencillas.

Lo Feo: Dependencia del Entorno y Fragilidad

El mayor defecto fundamental de Superpowers es su arquitectura como un plugin que reside dentro del prompt de un LLM.

Debido a que depende del LLM anfitrión (como Claude 3.5 Sonnet dentro de la CLI de Claude Code) para leer las instrucciones de la habilidad y ejecutarlas sin problemas, es inherentemente frágil. Los LLMs no son máquinas de estado deterministas. A veces, a pesar de las instrucciones estrictas en subagent-driven-development, el orquestador se vuelve perezoso e intenta ejecutar una tarea él mismo en lugar de despachar a un subagente. A veces decide escribir la implementación antes que la prueba, violando flagrantemente “La Ley de Hierro”.

Cuando esto sucede, toda la metodología se viene abajo. Te encuentras gritándole a la terminal: “¡No, lee la documentación de la habilidad de nuevo!”

Además, el framework depende en gran medida de las capacidades del entorno CLI. Si usas un entorno que carece de una API robusta para subagentes, Superpowers recurre a un modo de ejecución secuencial mucho menos efectivo (executing-plans), anulando su mayor ventaja. Se siente como intentar ejecutar un sistema operativo de alto rendimiento en una capa de abstracción de hardware que cambia las reglas constantemente.

El Veredicto: ¿Para Quién es Superpowers?

Superpowers no es para todos. Si tu principal caso de uso para la IA es escribir código repetitivo, generar scripts simples o ayudar con los diseños CSS, este framework te frustrará inmensamente. Te sentirás empantanado por el proceso y la ceremonia. Para esas tareas, un enfoque guiado por artefactos como OpenSpec es muy superior.

Sin embargo, si eres un desarrollador en solitario que construye sistemas de backend complejos, algoritmos intrincados o tuberías de datos de misión crítica —escenarios donde un error sutil puede causar un fallo catastrófico— Superpowers es una revelación.

Es lo más cercano que he experimentado a tener a un riguroso programador senior trabajando a mi lado. Me obliga a pensar bien mis diseños, exige que mis pruebas sean exhaustivas y ejecuta los planes de implementación con un enfoque implacable e incansable.

Para el portafolio de ArceApps, no uso Superpowers todos los días. Pero cuando necesito refactorizar la lógica central de indexación de búsqueda, o cuando estoy construyendo una compleja máquina de estados para una nueva mecánica de juego en PuzzleHub, Superpowers es la herramienta a la que recurro. Con gusto intercambio la velocidad y el costo de los tokens por la absoluta tranquilidad de saber que el código es robusto, está aislado y perfectamente probado.

A medida que la IA agéntica continúe evolucionando, es probable que veamos estos conceptos metodológicos integrados directamente en el IDE o en el propio entorno. Pero ahora mismo, Superpowers se erige como un ejemplo pionero de cómo obligar a los motores probabilísticos de texto a hacer ingeniería rigurosa y determinista. Es un vistazo al futuro de la colaboración humano-IA, donde el humano proporciona la arquitectura, y el agente, atado por la metodología, proporciona la ejecución.

Diseccionando la Habilidad de “Redacción de Planes”

Para apreciar verdaderamente la profundidad de la metodología Superpowers, debemos examinar la mecánica específica de su fase de planificación. La habilidad writing-plans no es meramente una sugerencia para “hacer una lista”; es un contrato arquitectónico rígido.

Cuando un agente activa esta habilidad, se le instruye para generar un documento Markdown que sigue un esquema altamente específico. Esto no es solo para la legibilidad humana; está diseñado para que los subagentes posteriores puedan analizar las tareas sin ambigüedades.

Una tarea típica generada por writing-plans se ve así:

### Tarea 1.2: Implementar la Validación del Token de Autenticación

**Contexto**: Necesitamos validar el token JWT en las solicitudes de API entrantes antes de permitir el acceso a las rutas protegidas.

**Archivo a modificar**: `src/middleware/auth.ts`

**Acción**: Crear una nueva función middleware `validateToken`.

**Código a escribir**:
- Importar la biblioteca `jsonwebtoken`.
- Extraer el token Bearer de la cabecera `Authorization`.
- Usar `jwt.verify` con la variable de entorno `JWT_SECRET`.
- Si es válido, adjuntar el payload del usuario decodificado al objeto `req` y llamar a `next()`.
- Si es inválido o falta, devolver una respuesta `401 Unauthorized` con un mensaje de error en JSON.

**Verificación (Requisito TDD)**:
- Crear `src/middleware/auth.test.ts`.
- Escribir pruebas para:
  - Token faltante (devuelve 401).
  - Firma inválida (devuelve 401).
  - Token expirado (devuelve 401).
  - Token válido (llama a next() y adjunta el usuario a req).

Por Qué Importa esta Granularidad

Observa el nivel de detalle aquí. El agente orquestador no dice “Añade un middleware de autenticación”. Especifica la ruta del archivo, el flujo lógico exacto y, críticamente, los casos límite exactos que deben ser probados.

Esta granularidad es el antídoto contra la alucinación de los LLM. Cuando el subagente fresco recibe esta tarea, no tiene que adivinar cómo debería funcionar la autenticación. No tiene que inventar una nueva abstracción. Simplemente ejecuta la especificación técnica altamente restringida.

Si el plan fuera vago, el subagente podría decidir implementar un sistema de autenticación basado en sesiones personalizado en lugar de JWT, o podría olvidar manejar el caso límite del token caducado. Al obligar al agente planificador a pensar en estos detalles por adelantado durante la fase de writing-plans, Superpowers asegura que la fase de ejecución sea puramente mecánica.

El Proceso de Revisión en Dos Etapas

Otro aspecto fascinante de la habilidad subagent-driven-development es el proceso obligatorio de revisión en dos etapas. En un flujo de trabajo típico de codificación con IA, el agente escribe el código, dice “He terminado” y tú revisas el diff.

Superpowers automatiza las capas iniciales de esta revisión, imitando a un desarrollador senior revisando el Pull Request de un junior.

Una vez que un subagente completa una tarea (lo que significa que las pruebas pasan y el código está escrito), el agente orquestador no fusiona inmediatamente el trabajo ni pasa a la siguiente tarea. En cambio, se detiene y realiza dos revisiones distintas:

1. Revisión de Cumplimiento de Especificaciones

El orquestador mira la descripción original de la tarea en el plan y la compara con la implementación del subagente. ¿Construyó el subagente exactamente lo que se pidió?

Si la tarea pedía una función que devolviera un booleano, y el subagente escribió una función que devuelve un objeto, la revisión de cumplimiento falla. El orquestador generará un nuevo subagente “reparador”, pasándole el error: “La implementación devuelve un objeto, pero la especificación requiere un booleano. Corrige la implementación y actualiza las pruebas en consecuencia.”

Esto previene la corrupción de características (feature creep) y asegura que la arquitectura se mantenga alineada con el diseño original.

2. Revisión de Calidad del Código

Solo después de que el código pasa la comprobación de cumplimiento de especificaciones, el orquestador evalúa la calidad del código. Esta revisión busca las mejores prácticas estándar de ingeniería:

• DRY (Don’t Repeat Yourself): ¿Duplicó el subagente lógica que ya existe en otro lugar de la base de código?
• YAGNI (You Aren’t Gonna Need It): ¿Sobre-ingenierizó el subagente la solución añadiendo abstracciones innecesarias o interfaces genéricas?
• Complejidad: ¿Es el código excesivamente complejo o difícil de leer? ¿Son descriptivos los nombres de las variables?

Si el código es un desastre o está sobre-ingenierizado, el orquestador instruirá a un subagente reparador para que lo refactorice.

Este riguroso ciclo de revisión automatizado es agotador de ver en la terminal, pero el resultado es impecable. Obliga a la IA a producir código que no solo es funcional, sino mantenible.

El Futuro de los Flujos de Trabajo Agénticos

Trabajar con Superpowers se siente como asomarse al futuro del desarrollo de software. Nos estamos alejando de tratar a la IA como un motor de autocompletado altamente avanzado, y avanzando hacia tratarla como un participante activo en una organización de ingeniería.

La implementación actual de Superpowers tiene sus fallos —que en su mayoría provienen de las limitaciones de los LLMs subyacentes y la fragilidad de las arquitecturas de plugins basadas en prompts—. Los costos de los tokens son altos y el proceso es lento.

Sin embargo, los conceptos centrales —aislamiento forzado a través de subagentes, desarrollo guiado por pruebas obligatorio, planificación explícita y revisiones automatizadas en múltiples etapas— son principios de ingeniería fundamentalmente sólidos.

A medida que los LLMs se vuelvan más rápidos, más baratos y posean ventanas de contexto más grandes y confiables, la fricción de esta metodología disminuirá. Con el tiempo, es probable que los IDEs integren estos conceptos de forma nativa en sus interfaces. No necesitarás instalar un plugin de habilidades basado en Markdown; tu editor simplemente creará contenedores seguros y aislados para subagentes, impondrá visualmente las pruebas y orquestará el flujo de trabajo sin problemas.

Hasta entonces, para aquellos que construyen aplicaciones complejas donde la exactitud importa más que la velocidad, el framework Superpowers de Jesse Vincent ofrece la metodología más rigurosa, disciplinada y efectiva disponible para domar el caos de la IA agéntica. Requiere paciencia y la voluntad de adoptar el proceso, pero la recompensa es una base de código en la que realmente puedes confiar.