El comando /speckit.specify

El núcleo del flujo SDD

Una vez que la constitución del proyecto está definida, el siguiente paso en el flujo SDD es especificar qué construir. Este es el momento donde se articula la intención del producto sin entrar en detalles técnicos de implementación.

El comando /speckit.specify es la pieza central de esta fase. Su función es tomar una descripción de alto nivel de una funcionalidad y transformarla en un documento de especificación estructurado (spec.md) que servirá como fuente de verdad para las fases posteriores de planificación, tareas e implementación.

El comando /speckit.specify responde a las preguntas "qué" y "por qué". Las preguntas sobre el "cómo" (stack tecnológico, arquitectura, patrones de diseño) se resuelven en la fase de planificación.

Esta separación deliberada entre requisitos y tecnología tiene una justificación práctica. Si la especificación menciona "usar PostgreSQL" o "implementar con React", el agente IA pierde la oportunidad de seleccionar la mejor solución técnica durante la fase de planificación. La especificación debe ser tecnológicamente neutra para que las decisiones de arquitectura se tomen con criterio en el momento adecuado.

Cómo ejecutar el comando

El comando se ejecuta dentro del chat del agente IA compatible con Spec Kit. Se escribe /speckit.specify seguido de una descripción que articule la funcionalidad deseada desde la perspectiva del usuario:

/speckit.specify

Los usuarios pueden crear eventos de calendario
personalizados e importarlos en aplicaciones como
Google Calendar o Apple Calendar. Cada evento tiene
título, fecha, hora de inicio y fin, ubicación
opcional y descripción. Los usuarios pueden previsualizar
el evento antes de descargarlo.

Al ejecutar el comando, el agente IA realiza varias acciones de forma coordinada:

• 1. Ejecuta un script de creación de feature que genera una nueva rama Git con un nombre basado en el número de feature y las primeras palabras del prompt (por ejemplo, 001-crear-eventos-calendario).

• 2. Lee la plantilla de especificación almacenada en .specify/templates/spec-template.md. Esta plantilla define la estructura que debe tener el documento de especificación resultante.

• 3. Lee la constitución del proyecto desde .specify/memory/constitution.md para asegurar que la especificación generada respeta los principios establecidos.

• 4. Genera el archivo spec.md en el directorio specs/{numero-feature}/. El agente estructura la descripción proporcionada en user stories, criterios de aceptación, requisitos no funcionales y una checklist de revisión.

• 5. Genera un archivo de checklist en specs/{numero-feature}/checklists/requirements.md con criterios de calidad, completitud y preparación de la feature.

flowchart LR
    PROMPT["Descripción<br>de la feature"] --> CMD["/speckit.specify"]
    CMD --> BRANCH["Rama Git<br>001-crear-eventos"]
    CMD --> SPEC["specs/001/<br>spec.md"]
    CMD --> CHECK["specs/001/checklists/<br>requirements.md"]

Qué incluir en el prompt

La calidad de la especificación generada depende directamente de la calidad del prompt proporcionado. Un prompt efectivo para /speckit.specify se centra en la experiencia del usuario y en el valor de negocio, sin mencionar tecnologías concretas.

Prompt efectivo (centrado en el usuario):

/speckit.specify

Sistema de notificaciones para una plataforma educativa.
Los profesores pueden enviar notificaciones a alumnos
individuales o a grupos completos. Los alumnos reciben
las notificaciones en tiempo real y pueden marcarlas como
leídas. Los profesores ven estadísticas de lectura
por notificación.

Prompt problemático (mezcla requisitos con tecnología):

/speckit.specify

Implementar notificaciones con WebSockets usando Socket.io
en Node.js. Guardar en MongoDB con una colección
notifications. Frontend en React con un componente
NotificationBell que use useEffect para suscribirse
al canal de WebSocket.

El segundo ejemplo viola el principio de neutralidad tecnológica. Al especificar Socket.io, MongoDB y React, la fase de planificación pierde la capacidad de evaluar alternativas. Si el proyecto usa Python con FastAPI, toda la especificación queda invalidada.

La especificación describe el problema y el valor que aporta la solución. El plan técnico describe la solución concreta. Mezclar ambos produce especificaciones frágiles que no sobreviven a un cambio de stack.

Alcance de la especificación

Una decisión importante al usar /speckit.specify es el tamaño del alcance que se especifica en cada ejecución. Spec Kit funciona mejor cuando se especifican funcionalidades contenidas que representan una unidad coherente de valor para el usuario.

Alcance adecuado: una funcionalidad completa que puede desarrollarse, probarse y entregarse de forma independiente. Ejemplos: "sistema de autenticación con login, registro y recuperación de contraseña", "módulo de exportación de informes en PDF", "panel de administración de usuarios con roles y permisos".

Alcance demasiado amplio: "construir toda la aplicación de gestión de proyectos". Un alcance tan grande produce especificaciones extensas que saturan la ventana de contexto del modelo de lenguaje. Cuando el modelo pierde contexto, empieza a generar contenido genérico o contradictorio.

Alcance demasiado estrecho: "añadir un botón de logout". Una funcionalidad tan pequeña no justifica el flujo completo de SDD (specify, plan, tasks, implement). Para cambios menores, el vibe coding directo puede ser más eficiente.

La regla práctica es que una buena especificación debería producir entre 3 y 8 user stories. Menos de 3 indica un alcance demasiado limitado. Más de 8 sugiere que la funcionalidad debería dividirse en múltiples especificaciones independientes.

El archivo spec.md generado

El resultado principal del comando es un archivo spec.md que sigue la estructura definida en la plantilla del proyecto. El agente IA rellena cada sección con contenido derivado del prompt del usuario y de su conocimiento del dominio.

Un archivo spec.md típico contiene estas secciones principales:

specs/001-crear-eventos-calendario/
  spec.md
  checklists/
    requirements.md

El contenido del spec.md se organiza en bloques que cubren el "qué" y el "por qué" de la funcionalidad:

• Resumen de la feature: descripción concisa del propósito y valor de la funcionalidad.
• User stories: historias de usuario que describen las interacciones desde la perspectiva de los actores del sistema.
• Criterios de aceptación: condiciones medibles que deben cumplirse para considerar cada user story como completada.
• Requisitos no funcionales: restricciones de rendimiento, seguridad, accesibilidad y otros atributos de calidad.
• Edge cases: situaciones límite que requieren un tratamiento explícito.
• Checklist de revisión y aceptación: lista de verificación para validar la completitud de la especificación.

Cada una de estas secciones se analiza en profundidad en la lección dedicada a la anatomía de una especificación.

Iterar sobre la especificación

La primera versión del spec.md generada por el agente rara vez es definitiva. El flujo SDD contempla la iteración como parte natural del proceso. Tras revisar la especificación, el equipo puede:

Ejecutar /speckit.specify de nuevo con más contexto: si la primera especificación omite aspectos importantes, se puede volver a ejecutar el comando proporcionando información adicional. El agente actualizará el spec.md existente en lugar de crear uno nuevo.

/speckit.specify

Añadir a la especificación actual:
- Los eventos deben soportar zonas horarias
- Un evento puede tener varios participantes
- Los participantes reciben una invitación por email

Usar /speckit.clarify para resolver ambigüedades: este comando analiza la especificación existente, identifica puntos vagos o incompletos y genera preguntas concretas para el usuario. Es la forma más estructurada de refinar la especificación antes de pasar a la planificación.

Editar spec.md manualmente: como el archivo es Markdown estándar, se puede editar directamente en cualquier editor. Esta opción es útil cuando el equipo tiene requisitos muy específicos que prefiere redactar sin intermediación del agente IA.

flowchart TB
    V1["spec.md v1<br>Primera generación"] --> REVIEW["Revisión<br>del equipo"]
    REVIEW -->|Incompleta| CLARIFY["/speckit.clarify<br>Resolver ambigüedades"]
    REVIEW -->|Faltan requisitos| SPECIFY2["/speckit.specify<br>Añadir contexto"]
    REVIEW -->|Ajustes menores| EDIT["Edición manual<br>del spec.md"]
    CLARIFY --> V2["spec.md v2<br>Refinada"]
    SPECIFY2 --> V2
    EDIT --> V2
    V2 --> PLAN["/speckit.plan<br>Planificación técnica"]

La iteración no debe confundirse con la parálisis por análisis. El objetivo no es producir una especificación perfecta, sino una especificación lo suficientemente precisa para que la fase de planificación pueda tomar decisiones técnicas fundamentadas. Si quedan puntos ambiguos menores, el propio proceso de planificación los revelará y se podrá volver a la fase de especificación para resolverlos.

Contexto de archivos y assets

Al igual que con el comando /speckit.constitution, se puede enriquecer el prompt de especificación proporcionando archivos de contexto del proyecto. Esto es especialmente útil en proyectos brownfield donde ya existe código y la nueva funcionalidad debe integrarse con componentes existentes.

/speckit.specify

@src/models/user.py @src/api/routes.py

Añadir sistema de roles y permisos al sistema de
usuarios existente. Los administradores pueden asignar
roles. Los roles determinan qué secciones de la
aplicación son accesibles. Un usuario puede tener
múltiples roles.

Al incluir los archivos existentes como contexto, el agente IA genera una especificación que tiene en cuenta la estructura actual del proyecto. Las user stories mencionarán entidades y flujos que ya existen, y los criterios de aceptación reflejarán la integración con el código existente.

En proyectos greenfield donde no existe código previo, el contexto puede incluir documentos de producto, wireframes o cualquier otro artefacto que ayude al agente a entender la visión del producto.