Saltar al contenido principal
Intermedio

Desarrollo guiado por especificaciones con Spec Kit

Programar a ojo — "constrúyeme un panel", acepta lo que sea que devuelva — funciona de maravilla hasta que la función se vuelve grande. Entonces el agente se desvía: olvida una decisión anterior, reinventa una función o entrega algo que técnicamente se ejecuta pero no es lo que querías decir. El desarrollo guiado por especificaciones (SDD, por sus siglas en inglés) es la solución que ha calado entre la gente que programa con agentes en 2026: en lugar de tratar el prompt como algo desechable, conviertes una especificación escrita y revisable en la fuente de verdad y haces que el agente genere código a partir de ella.

El Spec Kit de código abierto de GitHub convierte esa idea en un flujo de trabajo concreto que puedes ejecutar dentro de Claude Code hoy mismo.

What you'll learn
  • Entender qué es el desarrollo guiado por especificaciones y qué problema resuelve
  • Recorrer las fases de Spec Kit: constitution → specify → plan → tasks → implement
  • Instalar la CLI de Specify y conectarla con Claude Code
  • Conocer las puertas de calidad opcionales (clarify, analyze, checklist)
  • Decidir cuándo el SDD merece la sobrecarga y cuándo omitirlo

Por qué especificaciones, no solo prompts​

Un prompt desaparece en el momento en que termina el turno. Una especificación es un artefacto: puede leerse, revisarse en un PR, corregirse y volver a ejecutarse. Ese único cambio corrige las tres formas en que se tuercen las construcciones agénticas grandes:

  • Desvío — el agente contradice una decisión anterior porque nada la dejó por escrito. La especificación es la memoria.
  • Ambigüedad — "hazlo bonito" significa diez cosas distintas. Forzar los requisitos a prosa saca a la luz las lagunas antes de que exista el código, donde son baratas de corregir.
  • Diffs no revisables — un PR generado de 2.000 líneas es difícil de juzgar. Una especificación y un plan revisados hacen que el diff sea esperado en lugar de sorprendente.

El modelo mental: la intención es lo valioso y duradero; el código es un artefacto derivado y regenerable. El SDD es el primo disciplinado del propio Modo Plan de Claude Code — planificar primero, construir después — llevado a escala de una función completa y persistido en archivos de tu repositorio.

El flujo de trabajo de Spec Kit​

Spec Kit estructura una función como una breve secuencia de comandos de barra. Cada uno escribe artefactos Markdown en tu repositorio (bajo .specify/), de modo que cada fase es inspeccionable y está bajo control de versiones.

Guided walkthrough1 of 5
  1. Ejecuta /speckit.constitution una vez por proyecto. Escribe principios rectores — estilo de código, listón de pruebas, innegociables de arquitectura — en .specify/memory/constitution.md. Todas las fases posteriores se comprueban contra él, así que esta es tu barrera de protección duradera (piénsalo como un CLAUDE.md centrado en principios).

Puertas de calidad opcionales​

Tres comandos más aprietan el bucle cuando una función es de alto riesgo:

  • /speckit.clarify — interroga la especificación en busca de áreas poco especificadas y te hace preguntas concretas antes de planificar. Lo mejor es ejecutarlo justo después de specify.
  • /speckit.analyze — coteja la especificación, el plan y las tareas en busca de consistencia y lagunas de cobertura.
  • /speckit.checklist — genera una lista de verificación de validación para que "terminado" quede definido y sea comprobable.
Pro tip
  • Ejecuta /speckit.clarify antes de /speckit.plan — corregir la ambigüedad es más barato antes de comprometer la arquitectura.
  • Trata cada artefacto generado como un PR: léelo, corrígelo y solo entonces avanza a la siguiente fase.
  • Haz commit de los artefactos de .specify/ — son el registro revisable de la intención detrás del código.

Ponlo en marcha con Claude Code​

Spec Kit incluye una CLI, Specify, que genera el andamiaje de los comandos de barra en tu proyecto. Es compatible con más de 30 agentes de programación, Claude Code entre ellos.

Guided walkthrough1 of 3
  1. Usa uv para instalarla desde el repositorio. (Se requieren Python + uv.)

Instala la CLI de Specify (uv)

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

Genera el andamiaje del flujo guiado por especificaciones en un proyecto

# new project
specify init my-feature

# or in the current repo
specify init --here

Luego, dentro de Claude Code, ejecuta la secuencia

/speckit.constitution Establish principles: TypeScript strict, tests for every public function, no secrets in code.
/speckit.specify Build a CSV export for the reports page: users pick a date range and download a CSV of matching rows.
/speckit.clarify
/speckit.plan Next.js App Router, server action for the query, stream the CSV; no new dependencies.
/speckit.tasks
/speckit.implement
Watch out
  • El flag exacto de selección de agente para specify init cambia entre versiones — consulta la guía de inicio rápido del README en lugar de copiar un flag a ciegas.
  • El SDD no elimina la necesidad de verificar: lee el código generado y ejecútalo. La especificación hace que el diff sea revisable, no automáticamente correcto.
  • Nunca pongas secretos ni credenciales en la especificación, el plan o la constitution — se versionan como cualquier otro archivo.

Cuándo usarlo (y cuándo no)​

El SDD cambia ceremonia inicial por control. Ese intercambio merece la pena cuando el trabajo es grande, ambiguo o debe ser revisado por otros — y es pura sobrecarga cuando no lo es.

What you'll learn
  • Recurre al SDD: funciones desde cero, construcciones multiarchivo, cualquier cosa que un compañero deba revisar, o trabajo que delegarás a una flota de subagentes.
  • Omite el SDD: scripts puntuales, arreglos diminutos, código exploratorio desechable — un simple prompt o el Modo Plan es más rápido.
  • El trabajo sobre código existente también funciona: apunta /speckit.specify a una mejora de una base de código existente, no solo a proyectos nuevos.
SDD at a glance
Pulsa Intro o Espacio para girar la tarjeta. Usa las flechas izquierda y derecha para moverte entre las tarjetas.Término mostrado.
1 / 5

Comprueba lo aprendido​

Comprueba lo aprendido

0/3
  1. ¿Cuál es la idea central del desarrollo guiado por especificaciones?
  2. ¿Qué fase de Spec Kit debería capturar el stack tecnológico y la arquitectura?
  3. ¿Cuándo NO merece la pena la sobrecarga del desarrollo guiado por especificaciones?
Key takeaways
  • El desarrollo guiado por especificaciones convierte una especificación revisable — no el prompt — en la fuente de verdad, eliminando el desvío, la ambigüedad y los diffs no revisables.
  • El Spec Kit de GitHub (la CLI de Specify) lleva el SDD a Claude Code como comandos de barra /speckit.*.
  • La secuencia es constitution → specify → (clarify) → plan → (analyze) → tasks → (checklist) → implement, y cada paso escribe artefactos inspeccionables.
  • Mantén el QUÉ/POR QUÉ en la especificación y el CÓMO en el plan; revisa cada artefacto como un PR antes de avanzar.
  • Úsalo para funciones grandes, ambiguas o revisadas; omítelo para trabajo desechable — y siempre verifica el código generado de todos modos.

Siguiente​

Fuentes y lecturas adicionales​