Feature branching automático

Gestión automática de ramas y directorios

Cuando se ejecuta el comando /speckit.specify, Spec Kit no solo genera el archivo de especificación. También ejecuta un script automático que gestiona la infraestructura Git y de archivos necesaria para mantener cada feature organizada de forma independiente.

Este script realiza dos acciones fundamentales: crea una rama Git con un nombre estandarizado y genera una estructura de directorios donde se alojarán todos los artefactos de la feature (especificación, plan, tareas, checklists).

Cada feature de Spec Kit vive en su propia rama y en su propio directorio. Esta separación garantiza que el trabajo en una feature no contamina ni interfiere con el de otras features en desarrollo paralelo.

La gestión automática de ramas y directorios es una de las funciones del script de creación de feature que Spec Kit instala durante la inicialización del proyecto. Este script se encuentra en .specify/scripts/ y tiene versiones para Bash (Linux/macOS) y PowerShell (Windows).

Numeración de features

Spec Kit asigna un número secuencial a cada feature que se especifica en el proyecto. La primera feature recibe el número 001, la segunda 002, y así sucesivamente. El número se formatea con tres dígitos y relleno de ceros para mantener una ordenación alfabética consistente.

El script determina el siguiente número disponible inspeccionando las ramas existentes del repositorio. Si ya existen ramas 001-, 002- y 003-, la siguiente feature recibirá el número 004. Este mecanismo garantiza que no se produzcan colisiones de numeración, incluso cuando varios miembros del equipo trabajan en paralelo.

Ramas existentes en el repositorio:
  main
  001-crear-eventos-calendario
  002-sistema-notificaciones-profesores
  003-panel-administracion-usuarios

Siguiente feature:
  004-exportacion-informes-pdf

La numeración secuencial cumple varias funciones:

• Ordenación cronológica: las features se listan en el orden en que fueron creadas, lo que facilita entender la evolución del proyecto.
• Referencia rápida: en conversaciones y documentos, decir "la feature 003" es más conciso que "el panel de administración de usuarios".
• Unicidad: el número previene colisiones de nombres cuando dos features tienen descripciones similares.

Personalizar la numeración con hooks

Para equipos que necesitan un esquema de numeración diferente (por ejemplo, que el número de feature corresponda al número de issue de GitHub o de ticket de Jira), Spec Kit ofrece un mecanismo de hooks que permite sobreescribir la lógica de numeración por defecto.

El hook prepare-feature-num se ejecuta antes de que el script asigne el número de feature. Si el hook devuelve un número, ese número se usa en lugar del secuencial automático:

#!/bin/bash
# .specify/hooks/prepare-feature-num.sh
# Obtener el número del último issue de GitHub
gh issue list --limit 1 --json number --jq '.[0].number + 1'

La versión PowerShell equivalente sería:

# .specify/hooks/prepare-feature-num.ps1
$lastIssue = gh issue list --limit 1 --json number --jq '.[0].number + 1'
Write-Output $lastIssue

Con este hook configurado, los números de feature se sincronizarían con los números de issue de GitHub, lo que mejora la trazabilidad entre el gestor de issues y las ramas de especificación.

Convención de nombres de rama

El nombre de la rama se compone de dos partes: el número de feature y un resumen descriptivo derivado de las primeras palabras del prompt proporcionado al comando /speckit.specify.

El formato estándar es:

{numero}-{primeras-tres-palabras-en-kebab-case}

Ejemplos de nombres de rama generados automáticamente:

| Prompt de especificación | Rama generada | |---|---| | "Los usuarios pueden crear eventos de calendario..." | 001-crear-eventos-calendario | | "Sistema de notificaciones para profesores y alumnos..." | 002-sistema-de-notificaciones | | "Panel de administración con gestión de roles..." | 003-panel-de-administracion |

El script extrae las primeras tres palabras del prompt, las convierte a minúsculas, elimina caracteres especiales y las conecta con guiones. Este mecanismo produce nombres de rama que son suficientemente descriptivos para identificar la feature sin ser excesivamente largos.

Limitaciones y consideraciones

La convención de nombres por defecto tiene algunas limitaciones que conviene conocer:

• El patrón de tres palabras puede producir nombres poco descriptivos si las primeras palabras del prompt son genéricas. Un prompt que empieza por "Implementar un sistema..." genera la rama 001-implementar-un-sistema, que es poco informativa. Empezar el prompt con palabras específicas mejora los nombres: "Notificaciones push para usuarios..." genera 001-notificaciones-push-para.

• Los caracteres especiales se eliminan del nombre de la rama. Acentos, signos de puntuación y otros caracteres no compatibles con nombres de rama Git se descartan.

• El patrón ^[0-9]{3}- (tres dígitos seguidos de un guion) es la expresión regular que Spec Kit usa para identificar ramas de feature. Si se crean ramas manualmente que cumplan este patrón, Spec Kit las contabilizará al calcular el siguiente número disponible.

Al ejecutar el comando /speckit.specify, el script crea la rama y la establece como rama activa en el repositorio local (git checkout), de forma que todo el trabajo posterior se realiza directamente en el contexto de la feature.

Estructura de directorios por feature

Junto con la creación de la rama, el script genera una estructura de directorios dentro de la carpeta specs/ del proyecto. Cada feature tiene su propio subdirectorio con un nombre que coincide con el nombre de la rama:

specs/
  001-crear-eventos-calendario/
    spec.md
    checklists/
      requirements.md
  002-sistema-de-notificaciones/
    spec.md
    checklists/
      requirements.md

Esta estructura se amplía a medida que se ejecutan los comandos posteriores del flujo SDD. Tras ejecutar /speckit.plan, se añade el archivo de plan. Tras /speckit.tasks, se añade el archivo de tareas:

specs/
  001-crear-eventos-calendario/
    spec.md
    plan.md
    tasks.md
    research.md
    checklists/
      requirements.md
    contracts/
      api-endpoints.md

La carpeta contracts/ almacena los contratos de API y el modelo de datos generados durante la planificación. El archivo research.md contiene la información de investigación técnica que el agente recopila al generar el plan.

Toda la información de una feature se concentra en un único directorio. Esto permite que el agente IA cargue todo el contexto necesario sin buscar archivos dispersos por el proyecto.

Aislamiento de contexto

La organización por directorios tiene un beneficio técnico directo: aislamiento de contexto para el agente IA. Los modelos de lenguaje trabajan con una ventana de contexto finita. Si toda la información de especificación de todas las features estuviera en un único archivo, la ventana de contexto se saturaría rápidamente en proyectos con muchas features.

Al separar cada feature en su propio directorio, el agente solo necesita cargar los archivos de la feature en la que está trabajando. Cuando se ejecuta /speckit.plan para la feature 001, el agente lee specs/001-crear-eventos-calendario/spec.md y la constitución, sin necesidad de procesar las especificaciones de las features 002, 003 o cualquier otra.

flowchart TB
    subgraph Feature001["Feature 001"]
        S1["spec.md"] --> P1["plan.md"]
        P1 --> T1["tasks.md"]
    end
    subgraph Feature002["Feature 002"]
        S2["spec.md"] --> P2["plan.md"]
        P2 --> T2["tasks.md"]
    end
    CONST["constitution.md"] --> Feature001
    CONST --> Feature002

El único archivo compartido entre features es la constitución (constitution.md), que actúa como referencia transversal para todas las especificaciones, planes y tareas del proyecto.

Trabajo paralelo con múltiples features

La combinación de ramas Git y directorios independientes facilita el trabajo paralelo en múltiples features. Dos desarrolladores (o dos agentes IA en sesiones separadas) pueden trabajar simultáneamente en features distintas sin conflictos.

Cada desarrollador trabaja en su propia rama y su propio directorio:

• Desarrollador A: rama 001-crear-eventos-calendario, directorio specs/001-crear-eventos-calendario/.
• Desarrollador B: rama 002-sistema-de-notificaciones, directorio specs/002-sistema-de-notificaciones/.

Los archivos de cada feature no se solapan, por lo que las ramas pueden mergearse a main de forma independiente sin generar conflictos en la carpeta specs/.

Este modelo de trabajo reproduce a nivel de SDD lo que los equipos ya hacen con feature branches en desarrollo convencional. La diferencia es que Spec Kit automatiza la creación y nomenclatura de las ramas, garantizando consistencia en todo el proyecto.

La variable SPECIFY_FEATURE

En algunos escenarios, el flujo automático de feature branching no es deseable. Por ejemplo, en entornos de CI/CD donde no se pueden crear ramas, en prototipos rápidos o en situaciones donde el equipo ya gestiona sus ramas con una convención propia.

Para estos casos, Spec Kit ofrece la variable de entorno SPECIFY_FEATURE. Al establecer esta variable antes de ejecutar un comando de Spec Kit, el sistema usa el valor de la variable como nombre de feature en lugar de crear una rama nueva.

export SPECIFY_FEATURE="auth-system"
# Los comandos de Spec Kit trabajarán en
# specs/auth-system/ sin crear una rama Git

En PowerShell:

$env:SPECIFY_FEATURE = "auth-system"
# Los comandos de Spec Kit trabajarán en
# specs/auth-system/ sin crear una rama Git

Cuando SPECIFY_FEATURE está definida, Spec Kit desactiva la creación automática de ramas y la numeración secuencial. Todos los artefactos se generan en el directorio correspondiente al valor de la variable, y el usuario es responsable de gestionar las ramas Git manualmente.

Esta variable es útil también para retomar el trabajo en una feature existente. Si se cerró la sesión del agente y se quiere continuar especificando, planificando o implementando una feature concreta, basta con establecer la variable con el nombre del directorio de esa feature.