Actualizar Spec Kit en proyectos existentes

Por qué actualizar Spec Kit

Spec Kit es un proyecto en desarrollo activo que publica mejoras con frecuencia. Las actualizaciones pueden incluir nuevos slash commands, correcciones en los templates existentes, mejoras en los scripts auxiliares y soporte para agentes IA adicionales. Mantener la instalación actualizada garantiza que el equipo trabaje con las últimas mejoras y correcciones.

La actualización de Spec Kit tiene dos componentes independientes:

• La CLI (specify): la herramienta global que se instala con uv tool install. Actualizar la CLI proporciona nuevas funcionalidades del comando specify (como specify check o mejoras en specify init).

• Los archivos del proyecto: los templates, scripts y slash commands que residen dentro del repositorio. Actualizar estos archivos proporciona las últimas versiones de los prompts, plantillas y scripts auxiliares.

Actualizar la CLI y actualizar los archivos del proyecto son operaciones independientes. Se puede actualizar solo la CLI, solo los archivos del proyecto, o ambos.

Actualizar la CLI

Para actualizar la CLI a la última versión publicada en el repositorio, se ejecuta el mismo comando de instalación con el flag --force:

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

El flag --force indica a uv que reemplace la versión instalada con la nueva, sin necesidad de desinstalar previamente. Si se utiliza uvx para ejecuciones puntuales, no es necesario actualizar nada: uvx descarga automáticamente la última versión disponible en cada ejecución.

Después de actualizar, se puede verificar que la nueva versión funciona correctamente:

specify check

Actualizar los archivos del proyecto

Actualizar la CLI no modifica los archivos que ya existen dentro del proyecto. Los templates, scripts y slash commands que specify init generó en su momento permanecen intactos. Para actualizarlos, se ejecuta specify init de nuevo dentro del directorio del proyecto:

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

Este comando sobrescribe los archivos de infraestructura de Spec Kit con las versiones más recientes.

Qué se actualiza

Los archivos que specify init --here --force reemplaza son:

• Memoria compartida (.specify/memory/): incluye constitution.md con la plantilla por defecto.
• Templates (.specify/templates/): plantillas de especificación, plan, tareas y checklist.
• Scripts (.specify/scripts/): scripts auxiliares de Bash o PowerShell.
• Slash commands: archivos del directorio del agente (.claude/commands/, .github/agents/, etc.).

Qué no se modifica

Los siguientes archivos están protegidos y nunca se ven afectados por la actualización:

• Código fuente: cualquier archivo de código del proyecto permanece intacto.
• Artefactos de features (specs/): las especificaciones, planes y tareas generadas para cada feature no se tocan. El directorio specs/ no forma parte de los paquetes de templates.
• Historial de Git: los commits, ramas y tags existentes se preservan.

El directorio specs/ está excluido de los paquetes de templates de Spec Kit. Las actualizaciones nunca modifican ni eliminan el trabajo realizado en especificaciones, planes o tareas.

Proteger la constitución personalizada

El aspecto más delicado de la actualización es que specify init --here --force sobrescribe el archivo constitution.md con la plantilla por defecto. Si el equipo ha personalizado la constitución (lo cual es lo habitual), esta personalización se pierde si no se toman precauciones.

Backup manual antes de actualizar

El flujo recomendado es hacer una copia de seguridad de la constitución antes de ejecutar la actualización:

cp .specify/memory/constitution.md .specify/memory/constitution-backup.md

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

mv .specify/memory/constitution-backup.md .specify/memory/constitution.md

Este patrón de tres pasos (backup, actualización, restauración) garantiza que la constitución personalizada sobreviva a la actualización.

Restaurar desde Git

Si la constitución está bajo control de versiones (lo cual es una buena práctica), se puede restaurar directamente desde el historial de Git después de la actualización:

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

git restore .specify/memory/constitution.md

El comando git restore recupera la última versión commiteada del archivo, deshaciendo la sobrescritura realizada por specify init. Este método es más limpio que el backup manual y no requiere archivos temporales.

flowchart TB
    subgraph Backup["Opción 1: Backup manual"]
        B1["cp constitution.md<br>constitution-backup.md"] --> B2["specify init<br>--here --force"]
        B2 --> B3["mv constitution-backup.md<br>constitution.md"]
    end
    subgraph GitRestore["Opción 2: Git restore"]
        G1["specify init<br>--here --force"] --> G2["git restore<br>constitution.md"]
    end

Gestión de templates personalizados

Si el equipo ha modificado templates en .specify/templates/ (por ejemplo, para añadir secciones específicas a las especificaciones o para cambiar la estructura del plan técnico), estas modificaciones también se sobrescriben durante la actualización.

El flujo de protección es similar al de la constitución:

cp -r .specify/templates .specify/templates-backup

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

Después de la actualización, se puede comparar la versión nueva con el backup para fusionar los cambios manualmente:

diff .specify/templates/spec-template.md .specify/templates-backup/spec-template.md

En PowerShell:

Compare-Object (Get-Content .specify\templates\spec-template.md) (Get-Content .specify\templates-backup\spec-template.md)

La comparación permite identificar qué ha cambiado en la versión nueva y decidir si se quiere mantener la personalización, adoptar los cambios nuevos o combinar ambos.

Antes de personalizar templates, considera si la modificación es necesaria a largo plazo. Las personalizaciones frecuentes aumentan el coste de cada actualización, ya que requieren revisión manual en cada ciclo.

Comandos duplicados en agentes de IDE

Un problema conocido tras actualizar Spec Kit en proyectos que usan agentes de IDE (Windsurf, Kilo Code, Roo Code) es la aparición de slash commands duplicados. Esto ocurre cuando la actualización genera archivos con nombres ligeramente distintos a los existentes, y el agente carga ambas versiones.

La solución consiste en navegar al directorio de comandos del agente y eliminar manualmente los archivos antiguos:

ls .windsurf/workflows/

Si se observan archivos duplicados (por ejemplo, speckit.specify.md y speckit-specify.md), se elimina el que corresponda a la versión antigua. Después, reiniciar el IDE para que el agente recargue los archivos de comandos.

Flujo completo de actualización

Un proceso de actualización completo que cubra todos los escenarios sigue estos pasos:

• 1. Backup de personalizaciones:

cp .specify/memory/constitution.md .specify/memory/constitution-backup.md
cp -r .specify/templates .specify/templates-backup

• 2. Actualizar la CLI:

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

• 3. Actualizar archivos del proyecto:

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

• 4. Restaurar personalizaciones:

mv .specify/memory/constitution-backup.md .specify/memory/constitution.md

• 5. Verificar:

specify check

Este flujo es conservador y protege todas las personalizaciones. Para proyectos que no han personalizado templates ni constitución, los pasos 1 y 4 se pueden omitir, simplificando la actualización a la CLI y los archivos del proyecto.

Cuándo actualizar

No es necesario actualizar Spec Kit con cada commit del repositorio. Las actualizaciones son más relevantes cuando:

• Se publican nuevos slash commands que el equipo quiere utilizar.
• Se corrigen bugs en templates que afectan a la calidad de los artefactos generados.
• Se añade soporte para nuevos agentes IA que el equipo quiere evaluar.
• El proyecto va a iniciar una nueva fase y se quiere partir de la base más actualizada.

El repositorio de Spec Kit en GitHub publica releases con notas de cambios que permiten evaluar si una actualización concreta aporta valor al proyecto.