Configuración avanzada

La variable SPECIFY_FEATURE

El flujo SDD estándar utiliza las ramas de Git como mecanismo principal para identificar la feature activa. Cuando el agente IA ejecuta un slash command, lee el nombre de la rama actual (por ejemplo, feature/003-gestion-notificaciones) y lo utiliza para localizar el directorio correspondiente en specs/ (en este caso, specs/003-gestion-notificaciones/).

La variable de entorno SPECIFY_FEATURE proporciona una alternativa a este mecanismo. Cuando está definida, el agente utiliza su valor en lugar de inferir la feature desde la rama Git:

export SPECIFY_FEATURE="003-gestion-notificaciones"

Con esta variable definida, todos los slash commands operan sobre specs/003-gestion-notificaciones/ independientemente de la rama Git en la que se encuentre el desarrollador. El agente lee y escribe los artefactos (spec.md, plan.md, tasks.md) en ese directorio.

SPECIFY_FEATURE no crea directorios ni archivos. Solo indica al agente qué directorio de feature utilizar. El directorio y los artefactos deben existir previamente o ser creados por el slash command correspondiente.

Cuándo usar SPECIFY_FEATURE

La variable SPECIFY_FEATURE resuelve escenarios donde la asociación automática entre rama Git y feature no funciona:

Trabajo en la rama principal: en ciertos flujos de trabajo, el equipo no crea ramas por feature. Todo el desarrollo se realiza en main o en una rama de desarrollo compartida. Sin SPECIFY_FEATURE, el agente no puede determinar qué feature está activa y los slash commands fallan o operan sobre un directorio incorrecto.

Múltiples features en la misma rama: en equipos que manejan varias features en paralelo dentro de una misma rama (por ejemplo, durante un sprint), SPECIFY_FEATURE permite conmutar entre features sin cambiar de rama:

export SPECIFY_FEATURE="005-autenticacion"
# Trabajar en la feature 005...

export SPECIFY_FEATURE="007-dashboard"
# Trabajar en la feature 007...

Entornos de CI/CD: los pipelines de integración continua pueden ejecutar comandos de Spec Kit para validar artefactos o generar informes. En estos entornos, el checkout puede no estar en una rama de feature, y SPECIFY_FEATURE permite indicar explícitamente la feature sobre la que operar.

Ramas con nombres no estándar: si la convención de nombres de las ramas del equipo no coincide con el formato que Spec Kit espera (por ejemplo, ramas con prefijo hotfix/ o release/), SPECIFY_FEATURE permite mantener la asociación correcta.

Configuración de SPECIFY_FEATURE

La variable se puede definir de varias formas según el entorno de trabajo:

Exportación directa en la terminal:

export SPECIFY_FEATURE="003-gestion-notificaciones"

En un archivo .env del proyecto (si el agente soporta la carga de archivos .env):

SPECIFY_FEATURE=003-gestion-notificaciones

Inline en la invocación del agente:

SPECIFY_FEATURE="003-gestion-notificaciones" claude

La variable se desactiva eliminándola del entorno:

unset SPECIFY_FEATURE

Cuando SPECIFY_FEATURE no está definida, el agente vuelve al comportamiento por defecto de inferir la feature desde la rama Git.

Trabajo sin Git

Spec Kit está diseñado para trabajar con repositorios Git, pero no lo requiere de forma estricta. Es posible utilizar el flujo SDD en directorios que no son repositorios Git, aunque con ciertas limitaciones.

Inicializar sin Git

El comando specify init funciona en directorios sin repositorio Git. Genera la estructura de .specify/, el directorio del agente y specs/ de la misma forma que en un repositorio Git:

mkdir mi-prototipo
cd mi-prototipo
specify init --here --ai claude

La diferencia principal es que las funcionalidades que dependen de Git no están disponibles:

• Feature branching automático: /speckit.specify no puede crear ramas de feature, por lo que es necesario usar SPECIFY_FEATURE para indicar la feature activa.
• Commits atómicos: /speckit.implement no puede realizar commits después de cada tarea. El código se genera pero queda sin commitear.
• Hooks de Git: los hooks post-checkout no se ejecutan porque no hay cambios de rama.

Flujo SDD sin Git

Para trabajar sin Git, la secuencia recomendada es:

• 1. Definir la variable SPECIFY_FEATURE con el nombre de la feature:

export SPECIFY_FEATURE="001-primera-feature"

• 2. Crear manualmente el directorio de la feature:

mkdir -p specs/001-primera-feature

• 3. Ejecutar los slash commands normalmente. El agente utiliza SPECIFY_FEATURE para localizar el directorio y genera los artefactos en él:

/speckit.specify
Crear un sistema de gestión de tareas...

• 4. Avanzar por las fases del flujo SDD ejecutando /speckit.plan, /speckit.tasks y /speckit.implement.

El principal inconveniente de trabajar sin Git es la pérdida de trazabilidad. No hay historial de commits, no hay rollback granular de tareas y no hay puntos de verificación automáticos. Para prototipos rápidos o exploraciones iniciales puede ser aceptable, pero para proyectos de producción se recomienda utilizar Git.

La opción --ai-skills

La opción --ai-skills de specify init permite inyectar habilidades adicionales al agente IA durante la inicialización del proyecto. Estas habilidades son instrucciones o capacidades que se incorporan a los archivos de slash command y que el agente utiliza durante la ejecución del flujo SDD.

specify init mi-proyecto --ai claude --ai-skills

Las habilidades adicionales pueden incluir:

• Conocimiento de frameworks específicos: instrucciones para que el agente genere artefactos teniendo en cuenta un framework concreto (Django, Spring, Next.js).
• Patrones arquitectónicos: directrices para que los planes y tareas sigan un patrón arquitectónico determinado (hexagonal, clean architecture, microservicios).
• Convenciones de código: reglas de estilo y nombrado que el agente debe aplicar durante la implementación.

Las habilidades se definen en archivos de configuración que specify init lee e inyecta en los archivos de slash command del agente. El efecto es que los slash commands incluyen directrices adicionales que no están presentes en la versión estándar.

Configuración por entorno

En equipos con múltiples entornos de trabajo (desarrollo, staging, CI/CD), la configuración de Spec Kit puede variar entre entornos. Las variables de entorno permiten adaptar el comportamiento de la CLI y de los slash commands sin modificar los archivos del proyecto.

Las variables de entorno más relevantes son:

| Variable | Propósito | |---|---| | SPECIFY_FEATURE | Identificar la feature activa sin depender de Git | | SPECKIT_CATALOG_URL | URL del catálogo de extensiones privado | | CODEX_HOME | Directorio home de Codex CLI |

Estas variables se pueden definir en diferentes niveles de alcance:

• Nivel de sesión: exportándolas en la terminal actual. Solo afectan a la sesión activa.
• Nivel de usuario: añadiéndolas al archivo de perfil del shell (.bashrc, .zshrc, $PROFILE en PowerShell).
• Nivel de proyecto: definiéndolas en un archivo .env si el agente soporta su carga.
• Nivel de CI/CD: configurándolas como secrets o variables de entorno del pipeline.

flowchart TB
    subgraph Alcances["Niveles de configuración"]
        CI["CI/CD<br>Variables del pipeline"]
        USER["Usuario<br>.bashrc / .zshrc"]
        SESSION["Sesion<br>export en terminal"]
        PROJECT["Proyecto<br>.env"]
    end
    CI --> USER
    USER --> SESSION
    PROJECT --> SESSION

Proyectos multi-agente avanzados

En proyectos donde diferentes fases del flujo SDD las ejecutan diferentes agentes, la configuración avanzada permite optimizar cada fase:

Un escenario frecuente es utilizar Claude Code para las fases de especificación y planificación (donde el descubrimiento completo de slash commands es necesario) y Cursor para la fase de implementación (donde la integración con el IDE proporciona una experiencia de edición más fluida).

Para este escenario, el proyecto se inicializa con ambos agentes:

specify init --here --ai claude
specify init --here --force --ai cursor

El desarrollador utiliza Claude Code para ejecutar /speckit.specify, /speckit.clarify y /speckit.plan. Después, cambia a Cursor para ejecutar /speckit.tasks y /speckit.implement, aprovechando las capacidades de navegación y edición del IDE.

Los artefactos generados en specs/ son los mismos independientemente del agente. Un spec.md generado por Claude Code es legible y utilizable por Cursor, y viceversa. La compatibilidad se garantiza porque ambos agentes utilizan los mismos templates de .specify/templates/.

La configuración avanzada de Spec Kit se basa en un principio simple: los artefactos SDD son el contrato entre fases. No importa qué agente genera un artefacto ni qué agente lo consume. Lo que importa es que la estructura del artefacto se ajusta al template y cumple con la constitución del proyecto.