Crea la Constitución de tu proyecto con Spec Kit

Antes de escribir una sola línea de código, necesitas la constitución de tu proyecto de software: el documento con las reglas inquebrantables que guían todo el desarrollo. Si construyes una casa sin el permiso de construcción, tienes un problema. Aquí ocurre lo mismo. Esta guía es para quien empieza con desarrollo asistido por IA usando Spec Kit y Claude Code, vengas o no del mundo técnico.

Por qué la constitución va antes que el código

Piensa en construir tu casa: ya eliges materiales, muebles y colores de los muros, pero todavía no tienes el permiso para construir en esa zona. Ese permiso faltante es exactamente lo que pasa cuando arrancas un proyecto sin constitución.

La regla es clara: debes tener la constitución mucho antes de definir cualquier especificación o desarrollar cualquier línea de código [00:22]. Sin ese permiso, todo lo demás se construye sobre terreno inestable.

¿Qué es la constitución de un proyecto de software? Es el documento que define las reglas inquebrantables de tu proyecto: propósito, tecnología, lógica de negocio y estilo de código. La IA la respeta en cada especificación y en cada línea que genera.

Qué componentes debe tener una constitución

La anatomía de una constitución se arma con seis bloques que ordenan tu proyecto de principio a fin. Vamos uno por uno con el ejemplo real de una app de reservas de canchas de pádel.

Cómo defines naturaleza, stack y reglas de dominio

Los primeros tres componentes fijan qué construyes y bajo qué límites.

• Naturaleza del proyecto: el propósito de la aplicación. En el ejemplo, permitir a los usuarios autenticarse y gestionar reservas de tiempo en espacios específicos [00:38].
• Stack de tecnología: frontend, backend y base de datos. Aquí se definió React para el frontend, Node.js con Express para el backend, SQLite en local y TypeScript como lenguaje [01:37].
• Reglas de dominio y lógica de negocio: los límites de los que el proyecto no se puede salir [01:52].

Si no vienes de tecnología, no te preocupes por el stack. En ese espacio puedes escribir reglas de negocio que sí conoces, como no usar herramientas de pago ni pedir tarjeta de crédito [01:13].

En las reglas de dominio del pádel se definieron cuatro puntos concretos:

1. Catálogo cerrado: el sistema solo maneja cinco canchas fijas.
2. Bloques de tiempo: las reservas operan en formato de 24 horas.
3. Prevención de colisiones: la regla crítica, nunca escribir una reserva sin validar primero que la cancha esté libre en ese horario [02:26].
4. Autenticación: todo flujo de reserva exige un usuario con sesión activa.

Si trabajaras con un bufete de abogados, ahí pondrías los horarios de atención reales en lugar de 24 horas. La constitución se adapta a tu negocio.

Cómo defines estructura, estilo y manejo de errores

Los siguientes componentes controlan cómo se escribe y cómo falla tu código.

Estructura y estilo de código define la organización del proyecto y las convenciones de escritura [02:50]. En el ejemplo se optó por una estructura plana, evitar la sobreingeniería y no implementar Clean Architecture ni patrones complejos. En estilo se priorizó la programación funcional, con componentes funcionales y hooks en React, evitando clases salvo obligación. La nomenclatura usa camelCase para funciones y variables, y PascalCase para interfaces y tipos [03:22].

Si no programas, aquí puedes pedir algo tan simple como generar comentarios en español para entender qué hace cada parte del código [03:40].

Manejo de errores y validaciones indica cómo responder ante fallas [03:50]. Desde la interfaz, nunca exponer errores crudos ni stack traces al usuario final: todo error técnico se traduce en un mensaje amigable como "la cancha ya fue reservada en este horario". Desde el backend, retornar siempre el código de estado HTTP correcto:

• 401 para errores de autenticación.
• 400 para petición inválida.
• 409 para conflicto de reserva [04:31].

¿Qué es la fuente de la verdad en una constitución? Es la instrucción que ordena a la IA detenerse si una orden del usuario contradice la constitución o detecta una falla lógica, avisar el problema y pedir actualizar el spec.md antes de tocar el código.

Ese último bloque, la fuente de la verdad, le dice a la IA cómo comportarse en cada especificación y cada vez que desarrolle código [04:35].

Cómo pasas la constitución a Spec Kit y Claude Code

Con la anatomía lista, el siguiente paso es convertir ese texto en un documento estructurado usando la herramienta.

El flujo es directo: copias tu constitución, vas a la terminal, entras a la raíz del proyecto que inicializaste antes y ejecutas el comando Claude para inicializar Claude en ese proyecto, confirmando que confías en el folder [05:11]. Ahí ya existen los templates de Constitution, Plan, Task y Spec con placeholders que se van llenando con tu información [05:24].

Luego ejecutas el comando de Spec Kit Constitution y pegas exactamente la constitución que definiste [05:43]. Al dar Enter, Claude Code usa los skills y plugins de Spec Kit para llenar el template.

¿Cómo genera Claude Code la constitución automáticamente? Cuando inicializas el proyecto con Spec Kit, se instalan una serie de skills que le dan a Claude Code la habilidad de tomar tu prompt y estructurarlo en un archivo constitution.md.

Después de unos minutos entrega el resultado: un archivo constitution.md con la constitución estructurada. En rojo ves lo que quitó y en verde lo que agregó, y te sugiere el siguiente comando a seguir [06:05].

Lo que hiciste fue personalizar las reglas de tu proyecto, convertirlas en un prompt y pasárselo a Claude para recibir de vuelta las reglas inquebrantables de tu proyecto [07:12]. Comparte en los comentarios el prompt que usaste y la constitución que Claude te devolvió.