Instalación y Configuración

Requisitos del Sistema

Antes de instalar Spec-Kit, asegúrate de tener:

Requisito	Versión Mínima	Verificar
Python	3.11+	python --version
Git	2.0+	git --version
uv	Última	uv --version

Instalación de uv

uv es un gestor de paquetes Python ultrarrápido escrito en Rust.

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell)

irm https://astral.sh/uv/install.ps1 | iex

Verificar Instalación

uv --version

Instalación de Spec-Kit

Instalación Persistente (Recomendada)

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

Esto instala specify como comando global disponible en tu terminal.

Instalación en Proyecto

# Crear entorno virtual
uv venv

# Activar entorno
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# Instalar dependencia
uv pip install \
  git+https://github.com/github/spec-kit.git

Verificar Instalación

specify --help

Inicializar Proyecto

Despues de instalar, inicializa Spec-Kit en tu proyecto especificando el agente AI:

# Crear proyecto nuevo con Claude Code
specify init mi-proyecto --ai claude

# Inicializar en directorio actual
specify init . --ai claude
# o con flag --here
specify init --here --ai claude

# Forzar en directorio no vacio
specify init . --force --ai claude

Agentes AI soportados

Flag --ai	Agente
claude	Claude Code
copilot	GitHub Copilot
cursor-agent	Cursor
gemini	Gemini
codex	OpenAI Codex
windsurf	Windsurf
amp	Amp

Flags adicionales de init

Flag	Funcion
--script ps	Genera scripts PowerShell (por defecto detecta OS)
--no-git	Omite inicializacion de Git
--ignore-agent-tools	Omite verificacion de herramientas del agente
--debug	Habilita output de depuracion

Verificar herramientas

specify check
specify version

Estructura de Carpetas

Spec-Kit crea la siguiente estructura:

proyecto/
├── .specify/
│   ├── constitution.md    # Principios del proyecto
│   ├── specs/             # Especificaciones funcionales
│   │   └── *.md
│   ├── plans/             # Planes técnicos
│   │   └── *.md
│   ├── tasks/             # Tareas desglosadas
│   │   └── *.md
│   └── extensions/        # Extensiones instaladas
└── src/                   # Código generado

Sistema de Extensiones

Spec-Kit soporta extensiones modulares para agregar comandos y funcionalidad:

# Listar extensiones disponibles
specify extension list --available

# Buscar extensiones
specify extension search jira

# Instalar una extension
specify extension add jira

# Habilitar/deshabilitar
specify extension enable jira
specify extension disable jira

# Actualizar extensiones
specify extension update

Las extensiones se instalan en .specify/extensions/ y agregan comandos slash adicionales (ej: /speckit.jira.specstoissues).

Configuración Opcional

.speckit.yaml

Puedes crear un archivo de configuración:

version: "1.0"

constitution:
  path: ".specify/constitution.md"

specs:
  directory: ".specify/specs"

plans:
  directory: ".specify/plans"

tasks:
  directory: ".specify/tasks"

output:
  directory: "src"

Solución de Problemas

Error: Python no encontrado

# Instalar Python con pyenv
curl https://pyenv.run | bash
pyenv install 3.12
pyenv global 3.12

Error: uv no reconocido

Añade uv al PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Error: specify no encontrado

Reinstala con:

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

Siguiente Paso

→ Capítulo 3: Flujo de Trabajo y Comandos