Inicializar un proyecto con specify init

El comando specify init

specify init es el punto de entrada para incorporar Spec-Driven Development a cualquier proyecto. Este comando genera toda la estructura de archivos que Spec Kit necesita para funcionar: templates de especificación, scripts auxiliares, archivos de configuración del agente IA y el directorio de memoria compartida.

La forma más básica de uso crea un proyecto nuevo en un subdirectorio:

specify init mi-proyecto

Esto genera una carpeta mi-proyecto/ con toda la estructura SDD dentro. Si se quiere inicializar Spec Kit dentro del directorio actual (por ejemplo, en un repositorio que ya existe), se utiliza la opción --here:

specify init --here

Ambas formas producen el mismo resultado en cuanto a archivos generados. La diferencia es dónde se crean: en un nuevo subdirectorio o en la ubicación actual.

specify init solo necesita ejecutarse una vez por proyecto. Los archivos generados persisten en el repositorio y no requieren regenerarse en cada sesión de trabajo.

Seleccionar el agente IA con --ai

La opción --ai indica a Spec Kit para qué agente IA debe generar los archivos de configuración. Cada agente espera los slash commands en un directorio y formato específicos, y esta opción se encarga de adaptar la salida.

specify init mi-proyecto --ai claude

Los valores más habituales para --ai son:

| Valor | Agente | Directorio generado | |---|---|---| | claude | Claude Code | .claude/commands/ | | copilot | GitHub Copilot | .github/agents/ | | cursor | Cursor | .cursor/commands/ | | gemini | Gemini CLI | .gemini/commands/ | | codex | Codex CLI | .codex/commands/ | | windsurf | Windsurf | .windsurf/workflows/ |

Si no se especifica --ai, Spec Kit solicita al usuario que seleccione un agente de forma interactiva durante la inicialización.

Generar configuración para varios agentes

Un caso de uso frecuente es generar archivos de configuración para varios agentes en el mismo proyecto. Esto resulta útil en equipos donde cada miembro trabaja con un agente distinto, o cuando se quiere tener la flexibilidad de alternar entre agentes según la tarea.

Para conseguirlo, se ejecuta specify init varias veces con --here --force y diferentes valores de --ai:

specify init --here --ai claude
specify init --here --force --ai copilot

La primera ejecución genera la estructura base con los archivos de Claude Code. La segunda añade los archivos de Copilot sin eliminar los de Claude, ya que cada agente usa directorios distintos. El flag --force evita la confirmación de que el directorio no está vacío.

Elegir el tipo de script con --script

La opción --script controla el formato de los scripts auxiliares que Spec Kit genera. Estos scripts automatizan operaciones de soporte como la gestión de ramas y la preparación de directorios de features.

specify init mi-proyecto --ai claude --script sh

Los valores posibles son:

• sh: genera scripts en Bash, adecuados para macOS y Linux.
• ps: genera scripts en PowerShell, adecuados para Windows.

Si no se especifica, la CLI detecta el sistema operativo y selecciona el formato adecuado automáticamente, o bien se solicita al usuario durante la inicialización. La opción manual aún así es útil cuando el entorno no coincide con el shell deseado, como al usar WSL (Windows Subsystem for Linux) donde se prefiere Bash en lugar del PowerShell nativo de Windows.

Los flags --here y --force

Estos dos flags modifican el comportamiento de specify init para adaptarse a escenarios distintos.

--here: inicializar en el directorio actual

El flag --here indica que la estructura SDD debe crearse en el directorio de trabajo actual en lugar de crear un subdirectorio nuevo. Es la opción habitual cuando se añade Spec Kit a un repositorio existente:

cd mi-proyecto-existente
specify init --here --ai copilot

Si el directorio contiene archivos, Spec Kit muestra un aviso indicando que se fusionarán los archivos de template con el contenido existente:

Warning: Current directory is not empty (25 items)
Template files will be merged with existing content and may overwrite existing files
Proceed? [y/N]

Los archivos propios del proyecto (código fuente, configuraciones, documentación) no se modifican. Solo se añaden los directorios y archivos propios de Spec Kit.

--force: omitir confirmaciones

El flag --force suprime los mensajes de confirmación y ejecuta la inicialización directamente. Es útil en scripts de automatización o cuando ya se conoce el efecto del comando:

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

El flag --force solo afecta a los archivos de infraestructura de Spec Kit (templates, scripts, slash commands). El código fuente del proyecto y el directorio specs/ con las especificaciones existentes nunca se sobrescriben.

La combinación --here --force es especialmente frecuente en dos escenarios:

• Añadir soporte para un agente adicional sin repetir la confirmación interactiva.
• Actualizar los archivos de Spec Kit cuando se publica una nueva versión.

El flag --no-git

Por defecto, specify init ejecuta git init si el directorio no es ya un repositorio Git, y crea un commit inicial con los archivos generados. El flag --no-git desactiva este comportamiento:

specify init mi-proyecto --ai claude --no-git

Esto es útil en los siguientes casos:

• El proyecto forma parte de un monorepo donde el repositorio Git ya está gestionado a nivel superior.
• Se quiere experimentar con Spec Kit sin control de versiones temporal.
• Se utiliza un sistema de control de versiones distinto a Git.

Al usar --no-git, Spec Kit no puede detectar automáticamente la rama activa para determinar en qué feature se está trabajando. En ese caso, hay que indicar la feature de forma manual mediante la variable de entorno SPECIFY_FEATURE:

export SPECIFY_FEATURE="001-mi-feature"

En PowerShell:

$env:SPECIFY_FEATURE = "001-mi-feature"

Ejemplo completo de inicialización

Un flujo típico de inicialización para un proyecto nuevo con Claude Code en un entorno Linux/macOS combina las opciones presentadas:

specify init mi-api-rest --ai claude --script sh

Para un proyecto existente en Windows con Copilot:

cd mi-proyecto
specify init --here --ai copilot --script ps

Después de ejecutar specify init, la estructura del proyecto incluye los directorios y archivos necesarios para comenzar a trabajar con los slash commands de Spec Kit. El siguiente paso natural es explorar qué contiene cada directorio generado y cómo se relacionan entre sí.

flowchart TB
    subgraph Opciones["Opciones de specify init"]
        AI["--ai<br>Agente IA"]
        SC["--script<br>Tipo de shell"]
        HE["--here<br>Directorio actual"]
        FO["--force<br>Sin confirmación"]
        NG["--no-git<br>Sin Git"]
    end
    CMD["specify init"] --> AI
    CMD --> SC
    CMD --> HE
    CMD --> FO
    CMD --> NG
    AI --> OUT["Proyecto SDD<br>inicializado"]
    SC --> OUT
    HE --> OUT
    FO --> OUT
    NG --> OUT