Desarrollo guiado por especificaciones con Claude Code: tutorial paso a paso

¿Qué es el desarrollo guiado por especificaciones?

Es un flujo de trabajo basado en tres documentos, en este orden: uno que explica qué debe hacer el cambio, un plan que detalla los pasos y el código escrito siguiendo ese plan, con una revisión humana entre cada pareja de documentos.

Los tres puntos de revisión por los que pasa una funcionalidad en el desarrollo guiado por especificaciones.

Una especificación es un documento breve, en lenguaje natural y previo a cualquier código, que define qué debe hacer el cambio. Imagina una función como «permitir a los usuarios exportar sus datos». Una especificación para ello fija las respuestas que, de otro modo, el agente tendría que adivinar. Enumera:

• Los formatos de archivo compatibles
• El modo de entrega
• El comportamiento durante una exportación a medio hacer
• Las partes de la función que se dejan fuera a propósito

Este es el inicio real de una especificación que Claude Code escribió para un cambio llamado workout-shape-verification en una app de accountability basada en Telegram. El cambio sustituye un umbral frágil de frecuencia cardiaca por una comprobación de la forma de la curva de frecuencia a lo largo del tiempo:

# Workout Shape-Based Verification — Design Spec
 
**Created:** 2026-05-05
**Status:** Draft
**Supersedes (partially):** [2026-03-17-calisthenics-verification-design.md]
  — replaces the absolute-HR thresholds for the Workout activity type.
  Run / Ride / Walk verification is unchanged.
 
## Problem
 
The current Workout verifier accepts an activity only if absolute heart-rate
levels clear fixed cutoffs: avg ≥ 120, max ≥ 140, range ≥ 30, suffer_score ≥ 3.
Two failures in production:
 
1. **False-negative risk.** As cardiovascular fitness improved
   (resting HR ~80), real calisthenics sessions with disciplined rest now
   average 115–125 bpm. Recent sessions have come within 4 bpm of the 120 floor.
 
<!-- ... continues for hundreds of lines through Solution, Risks,
 	Out of scope, and What is removed / added / changed / unchanged -->

El plan es el siguiente documento. Descompone la especificación en tareas numeradas con las que el agente puede trabajar una a una, y cada tarea indica archivo, cambio, orden y prueba. Donde la especificación responde al «qué», el plan responde al «en qué pasos».

El código llega al final, escrito siguiendo el plan, una tarea cada vez.

Tres documentos. Una revisión humana entre cada pareja. Revisas la especificación antes de convertirla en plan. Revisas el plan antes de escribir el código. Revisas el código antes de fusionarlo.

En qué se diferencia del modo plan

Puede que hayas usado el modo plan integrado de Claude Code (pulsa Mayús+Tab dos veces) y te preguntes qué cambia aquí. El modo plan genera un plan en un único turno de chat. Ese plan vive en la memoria, sin especificación persistida ni revisión entre fases.

El desarrollo guiado por especificaciones guarda la especificación y el plan como archivos en disco. Cada uno pasa por una revisión humana antes de que empiece la siguiente fase, y los artefactos sobreviven entre sesiones. El modo plan comprime dos fases del desarrollo en un solo turno. Eso funciona en tareas pequeñas y falla en cuanto el código crece y sirve a usuarios reales.

Por qué el vibe-coding se queda corto

El vibe-coding sirve para prototipos, archivos sueltos y scripts desechables. Empeora en aplicaciones reales con usuarios y en bases de código grandes. La línea roja está en torno a 4 archivos. Cualquier cambio que toque tantos archivos necesita una especificación, igual que cualquier refactor con un estado final claro, o cualquier tarea donde la parte difícil es «¿qué debe hacer esto exactamente?».

El fallo tiene una causa clara. Un prompt vago como «añade compartir fotos a mi app» hace que el modelo adivine miles de requisitos no declarados.

Piensa en uno solo de esos requisitos: las preferencias de notificación. La product manager asume interruptores por canal. El backend construye un on/off global. El frontend da por hecha la integración a nivel de SO. Cuatro lecturas razonables de tres palabras, cuatro productos diferentes.

Cada revisión en el desarrollo guiado por especificaciones detecta una clase distinta de errores antes de que salgan caros. La revisión de la especificación frena desvíos de alcance y diagnósticos mal planteados. La del plan detecta implementaciones a medias y patrones en conflicto. La de código pilla planes que parecen correctos pero se rompen en la primera prueba fallida.

La recompensa es real y crece poco a poco. La fase de especificación cuesta horas de escritura antes de ejecutar código, y las primeras funciones parecen ir más lentas que con vibe-coding. En mi caso, el punto de equilibrio llegó en la cuarta o quinta funcionalidad. Para entonces, las especificaciones ya estaban cazando errores de diseño que, de otro modo, habría enviado a producción y reescrito una semana después.

Las tres secciones siguientes recorren tres enfoques open source para ejecutar este flujo dentro de Claude Code. Están ordenados de menor a mayor estructura.

Superpowers

Superpowers es el más ligero de los tres. Es el que uso a diario y el que veremos con más detalle.

¿Qué es Superpowers?

Superpowers es un plugin de Claude Code creado por Jesse Vincent (obra/superpowers, licencia MIT), con unas 194k estrellas en GitHub.

Incluye un conjunto de skills. Una skill de Claude, en Claude Code, es un archivo de instrucciones con nombre que el agente carga bajo demanda para seguir un flujo concreto. Superpowers añade skills que mantienen a Claude Code dentro del bucle guiado por especificaciones en lugar de saltar directo al código.

La página del proyecto Superpowers en GitHub.

Cómo instalar Superpowers

Instálalo desde el marketplace oficial de plugins de Claude Code:

/plugin install superpowers@claude-plugins-official

Un hook de SessionStart carga automáticamente la skill using-superpowers, así que el flujo está activo en cuanto empiezas a escribir. (Los hooks de Claude Code son scripts que el agente ejecuta en eventos concretos del ciclo de vida). No hay nada que configurar por proyecto.

El flujo de trabajo de Superpowers

A partir de ahí, cuatro skills organizan tu trabajo diario:

Un subagente es una instancia separada de Claude Code que el padre lanza para un trabajo focalizado en su propia ventana de contexto. Los subagentes revisores de la tabla anterior se ejecutan así, de modo que leen el código en frío, sin el sesgo del contexto del agente principal.

Cómo usar Superpowers

Invocas las cuatro skills describiendo en lenguaje natural lo que quieres. La skill de brainstorming detecta «hablemos de esta nueva función» y arranca sola la conversación de especificación. Las otras se activan igual.

Las cuatro skills de Superpowers en orden, con los dos puntos de revisión humana entre brainstorming y writing-plans.

El paso a paso de abajo usa la misma función workout-shape-verification de la que vimos un extracto de la especificación.

Fase 1: del brainstorming a la especificación

Abro Claude Code y escribo:

Let's discuss a new feature. The Workout verifier in make-me-work uses absolute heart-rate cutoffs and is now misfiring as my resting HR drops. I want to replace the absolute cutoffs with a check on the shape of the HR curve over the session.

La skill brainstorming toma el control y lanza una decena de preguntas, entre ellas:

• Qué forma cuenta como «correcta»
• Qué flujos de datos combinar
• Qué hacer con sesiones que encajan por forma pero fallan un umbral antiguo
• Si el cambio debe aplicarse también a Run y Ride

Aquí caen dos revisiones humanas. La primera es la revisión de diseño, donde confirmo que las respuestas encajan con lo que quiero. La segunda es la revisión de la especificación: leo el archivo que ha escrito Claude y lo apruebo antes de que empiece el trabajo de plan.

Fase 2: de la especificación al plan

Ejecuto la skill writing-plans. Lee la especificación aprobada y escribe un plan con cuatro partes:

• Una definición de «Hecho»
• Un mapa de archivos tocados
• Un viaje de usuario por la ruta de demo
• Una lista numerada de tareas con subpasos marcables

Reviso el plan, cuestiono tareas desordenadas o demasiado gruesas y lo apruebo.

Fase 3: del plan al código

Ejecuto subagent-driven-development. Desde aquí, el bucle corre sin mí. Para cada tarea del plan, la skill:

1. Escribe una prueba que falle
2. Escribe el código para pasarla
3. Refactoriza
4. Lanza un subagente de revisión que lee el diff en frío

Si la persona revisora detecta un problema, el bucle lo corrige antes de pasar a la siguiente tarea. No hay revisión humana dentro de esta fase. Las revisiones que importan para esta fase son las dos anteriores.

Fase 4: revisión del diff completo

Cuando el plan termina, ejecuto requesting-code-review. Un subagente nuevo lee todo el diff contra la especificación y el plan y publica una revisión. Aplico sus sugerencias antes de fusionar.

Si una tarea del plan revela una contradicción con la especificación, el bucle se detiene y pregunta. Puedo editar la especificación (o dejar que Claude lo haga) y regenerar las tareas afectadas. La otra opción es corregir puntualmente en la propia tarea. Superpowers no se salta silenciosamente los errores de especificación.

Especificaciones y planes reales en disco

Aquí tienes la especificación de la función workout-shape-verification abierta en un editor:

El archivo de especificación tal y como queda en disco tras la skill de brainstorming.

La cabecera incluye los campos Created, Status y Supersedes que la skill de brainstorming escribe por defecto. Le sigue la sección Problem. No hay código. El archivo continúa más allá de la captura con secciones para la solución propuesta y las restricciones sobre qué debe y no debe tocar el cambio.

El plan correspondiente abre con su User Journey:

El plan que la skill writing-plans genera a partir de la especificación aprobada.

El viaje recorre la ruta de demo en bloques de cinco pasos, nombrando los comandos, archivos y argumentos exactos en cada paso. Las tareas numeradas convierten cada paso en subpasos con casillas que la skill subagent-driven-development puede ejecutar.

Los dos documentos se emparejan así:

Especificación y plan, lado a lado. La especificación responde qué y por qué. El plan responde en qué pasos.

Para especificaciones y planes grandes, añado un paso que el bucle oficial no incluye: una pasada de red team. Antes de dar el visto bueno, hago que uno o varios subagentes Opus lean la especificación en frío buscando lagunas desde distintos ángulos. Es una costumbre personal, no una función de Superpowers. Me ha descubierto suficientes suposiciones erróneas como para mantenerla.

Cuándo Superpowers no encaja

Superpowers encaja en trabajo en solitario sobre un único repo. Brilla cuando toda la base de código cabe en una sesión de Claude Code y vas a leer de verdad una especificación de 2 páginas. La comparación detallada está en Cómo elegir entre ellos más abajo. La versión corta: Superpowers sufre con funcionalidades multi-repo y con trabajo que exige separación clara de roles.

Un desarrollador detectó un cuarto modo de fallo en una queja pública sobre el plugin: «Hasta la tarea más pequeña se eterniza, con Claude lanzando subagentes y escribiendo planes totalmente desproporcionados. Cambiar un poco de CSS ahora lleva una vida».

La solución es saltarse Superpowers en cambios diminutos. Las skills solo se activan con el disparador de brainstorming. Un cambio de una línea de CSS puede pasar por Claude Code sin invocar el bucle de especificación. El verdadero error ahí es aplicar en exceso el flujo a trabajos que no necesitan especificación.

GitHub Spec Kit

Spec Kit es la elección cuando la especificación tiene que durar más que una sesión de Claude Code. También es la opción adecuada cuando hay personas que jamás abrirán Claude Code pero necesitan leer la especificación.

¿Qué es GitHub spec-kit?

Spec Kit es un proyecto de GitHub (github/spec-kit, licencia MIT), mantenido por la propia GitHub, con más de 100k estrellas. Incluye una CLI y un flujo que funciona igual en todos los agentes de IA para programación más usados. Claude Code, Cursor, Aider, Cline y Roo Code están soportados. Ese diseño neutral es lo que permite que la especificación viva fuera de Claude Code.

La página del proyecto Spec Kit en GitHub.

Cómo instalar GitHub spec-kit

Aún no hay paquete oficial en PyPI, así que instala la CLI desde la etiqueta de Git con uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Sustituye vX.Y.Z por la versión actual. El paquete es specify-cli, y el comando que registra es specify.

El flujo de trabajo de GitHub spec-kit

El flujo se ejecuta con nueve comandos slash que la CLI añade a la lista de tu agente. Seis son el núcleo del bucle y tres son opcionales para casos que el núcleo no cubre.

El separador entre grupo y verbo es un punto, no dos puntos: /speckit.specify, no /speckit:specify.

Los nueve comandos slash de Spec Kit: seis principales en la canalización, tres opcionales colgando de ella.

Los artefactos que producen estos comandos son la misma especificación y plan que viste en la sección de Superpowers, también escritos a disco y versionados con Git. La diferencia es la portabilidad: los artefactos de Spec Kit están diseñados para funcionar con cualquier agente de programación con IA, no solo con Claude Code, y el flujo favorece la revisión de stakeholders vía pull requests en GitHub, no como subproducto del bucle de una única herramienta.

Cuándo usar GitHub spec-kit

En un proyecto en solitario, probablemente no lo necesites. Recurre a él cuando:

• El proyecto supera a una sola persona
• Tu especificación necesita revisión por gente que nunca abre Claude Code
• Vas a usar un agente que no es Claude Code para parte del trabajo
• Quieres un formato de especificación que viva fuera de cualquier herramienta y siga siendo legible meses después

El método BMAD

Mientras que Spec Kit organiza los artefactos, BMAD organiza a las personas. Divide el flujo de especificación a código en cuatro fases, cada una gestionada por un agente con rol definido.

¿Qué es BMAD?

BMAD-METHOD (bmad-code-org/BMAD-METHOD, licencia MIT, unas 47k estrellas) va por su versión 6. El acrónimo, según la documentación del proyecto, significa «Breakthrough Method for Agile AI-Driven Development». Funciona sobre Claude Code y otros agentes, y se instala como un ecosistema de módulos. La instalación por defecto incluye un módulo core con seis agentes por rol, cuatro fases de trabajo y 34 o más flujos con nombre.

La página del proyecto BMAD-METHOD en GitHub.

Cómo instalar BMAD

Instala BMAD con Node:

npx bmad-method install

Los seis agentes por rol son personas de prompt que el usuario activa por nombre desde el host del agente. En Claude Code, se hace escribiendo el comando de activación que instala BMAD. Consulta el README para la sintaxis exacta, que cambia entre versiones.

Presentación de los agentes y artefactos de BMAD

Una vez activado, el agente adopta las instrucciones, la voz y las salidas de ese rol hasta que cambias de persona. Los seis son:

• Mary, la analista
• Paige, la técnica de documentación
• John, el product manager
• Sally, la diseñadora UX
• Winston, el arquitecto
• Amelia, la desarrolladora

Faltan dos roles que podrías esperar en la v6: no hay Scrum Master ni un agente de QA independiente. La planificación de sprint y la preparación de historias recaen en la desarrolladora, y la generación de pruebas de QA es un flujo que dispara la propia desarrolladora.

El conjunto de artefactos es más pesado que una sola especificación. Obtienes:

• un product brief
• un PRD (Product Requirements Document)
• una especificación de UX
• un documento de arquitectura
• épicas desglosadas en historias de usuario (lo que podrán hacer los usuarios cuando se publique)

El PRD y el documento de arquitectura juntos cumplen el mismo papel que la especificación de Superpowers. La división los reparte entre dos agentes con rol y en un formato más formal. El conjunto completo cubre todo el ciclo de desarrollo, con cada función heredando contexto de la capa superior.

El flujo de trabajo de BMAD

El flujo de la v6 se ejecuta en cuatro fases.

Las cuatro fases de BMAD y el agente que gestiona cada una. La vía Quick Flow salta las tres primeras fases para trabajo pequeño.

Fase 1, análisis, es opcional. Mary (analista) y Paige (técnica) investigan y producen un product brief. Sáltala si ya sabes qué vas a construir.

Fase 2, planificación, es obligatoria. John (PM) escribe el PRD. Sally (UX) añade una especificación de UX si la función tiene interfaz.

Fase 3, solución, es la de Winston. El arquitecto redacta primero la arquitectura y luego John divide requisitos en épicas e historias. Poner las historias después de la arquitectura es una decisión de la v6 para dimensionarlas según límites reales de implementación. Winston ejecuta después una comprobación de preparación para implementar que termina con veredicto PASS, CONCERNS o FAIL.

Fase 4, implementación, es donde Amelia (desarrolladora) trabaja historia a historia: crea la historia, la construye y la revisa. Cuando termina una épica completa, lanza un flujo de generación de pruebas de QA sobre toda la épica. Aquí es donde Claude Code programa realmente, actuando como Amelia.

Para trabajo pequeño y bien acotado, BMAD incluye una vía «Quick Flow» que activa a Amelia directamente y salta las tres primeras fases. El comando de activación está en el README de BMAD (la sintaxis exacta cambia entre versiones). Quick Flow no produce PRD ni documento de arquitectura, solo una historia breve y el código que la satisface. Es la respuesta a «esto es excesivo para cambiar un botón».

Cuando la especificación resulta incorrecta a mitad de implementación, BMAD vuelve al veredicto de la fase 3 de Winston. Un FAIL te manda de vuelta a la fase 2 para reescribir el PRD. Con CONCERNS sigues adelante adjuntando los riesgos señalados por Winston a la historia. La división te permite avanzar con incoherencias pequeñas y parar en seco en las grandes.

Cuándo compensa la complejidad

BMAD compensa en proyectos de larga duración con usuarios reales. También encaja en equipos con varias personas, traspasando trabajo entre roles. La separación por fases y roles tiene que ahorrar más tiempo del que cuesta.

No es la opción adecuada para un proyecto personal. En solitario, las cuatro fases y seis agentes son, en su mayoría, sobrecarga. No hay una segunda persona para que la separación de roles importe.

Cómo elegir entre los frameworks

Tres reglas marcan la elección.

• Usa Spec Kit si la especificación tiene que leerla gente que no abre Claude Code o debe vivir en Git como artefacto a largo plazo.
• Si varias personas trabajan con roles distintos, o hay un stakeholder tipo PM en el bucle, usa BMAD.
• En caso contrario, usa Superpowers.

Tres preguntas sobre tu proyecto y cuatro opciones de framework al otro lado.

Hay una cuarta opción que nombra el árbol: combinar Spec Kit con Superpowers. Usa Spec Kit en la fase de especificación para que los artefactos vivan en Git y se revisen entre equipos. Luego apunta la skill subagent-driven-development de Superpowers al archivo de plan de Spec Kit con una línea de configuración. Obtienes la especificación duradera de Spec Kit junto al bucle de implementación ágil de Superpowers.

Conclusión

El desarrollo guiado por especificaciones son tres documentos en orden. La especificación dice qué construir, el plan dice en qué pasos y el código sigue el plan. Hay una revisión humana entre cada pareja.

Usa el árbol de decisión anterior para elegir un framework que, para la mayoría, será Superpowers. Instálalo y elige una función que de otro modo harías con vibe-coding, algo que toque de 3 a 5 archivos. Llévala de principio a fin: brainstorming, especificación, plan y ejecución. Una ejecución real enseña el flujo mejor que cualquier explicación.

Si quieres repasar antes los fundamentos de Claude Code, en DataCamp tienes un tutorial práctico de Claude Code, una guía de buenas prácticas que cubre el modo plan, CLAUDE.md y TDD, y un análisis a fondo del propio modo plan.