Enmiendas y versionado de la constitución

La constitución como documento vivo

A diferencia de lo que su nombre pueda sugerir, la constitución de un proyecto SDD no es un documento inmutable que se define una vez y permanece intacto para siempre. Es un documento vivo que evoluciona junto con el proyecto, pero de forma controlada y trazable.

La distinción clave es entre inmutabilidad durante la ejecución y evolución entre iteraciones. Mientras el agente IA trabaja en una feature (especificación, planificación, implementación), la constitución actúa como un conjunto de reglas fijas que no cambian. Entre features, el equipo puede actualizar la constitución para reflejar aprendizajes, cambios de contexto o nuevas necesidades.

La constitución se mantiene estable durante cada ciclo de desarrollo, pero evoluciona entre ciclos. Los cambios se realizan de forma deliberada, nunca como efecto secundario de otra operación.

Esta mecánica responde a un problema práctico: si la constitución cambiara durante la implementación de una feature, el código generado al principio de esa feature podría contradecir los principios vigentes al final. Mantener la constitución estable durante cada ciclo garantiza la coherencia del código generado.

Cuándo enmendar la constitución

Las enmiendas a la constitución se disparan por situaciones concretas que el equipo identifica durante el desarrollo:

Principios demasiado restrictivos: un principio que parecía razonable resulta inviable en la práctica. Por ejemplo, "no usar ORMs" puede ser un buen principio para un equipo con experiencia en SQL, pero si el equipo descubre que el agente IA genera queries SQL incorrectas con frecuencia, puede ser más productivo adoptar un ORM y modificar la constitución.

Principios demasiado vagos: un principio genérico como "mantener el código simple" no proporciona guía suficiente y el agente IA lo interpreta de formas inconsistentes entre ejecuciones. La enmienda concretaría el principio con reglas medibles.

Cambios en el stack tecnológico: si el equipo migra de PostgreSQL a MongoDB, o de REST a GraphQL, la constitución debe reflejar las nuevas convenciones y restricciones del stack actualizado.

Nuevos requisitos organizacionales: cambios regulatorios, nuevas políticas de seguridad o requisitos de compliance que afectan a todo el código generado.

Lecciones aprendidas: tras varias iteraciones de desarrollo, el equipo detecta patrones problemáticos recurrentes que un nuevo principio podría prevenir. Si el agente IA genera consistentemente funciones con demasiados parámetros, un principio que limite el número de parámetros a un máximo razonable resolvería el problema de raíz.

Versionado semántico de la constitución

Spec Kit aplica versionado semántico a la constitución, siguiendo el esquema MAJOR.MINOR.PATCH. Cada tipo de cambio tiene un impacto diferente en el proyecto y requiere un nivel de atención distinto por parte del equipo.

Cambios PATCH (x.y.Z)

Los cambios PATCH son refinamientos que no alteran el significado de los principios existentes:

• Correcciones de erratas y mejoras de redacción
• Clarificaciones que eliminan ambigüedad sin cambiar la regla
• Reorganización del documento sin añadir ni eliminar principios
• Actualización de ejemplos para reflejar mejor la intención del principio

Un cambio PATCH no requiere revisar el código existente ni los artefactos generados previamente. La intención del principio se mantiene intacta.

Antes (v1.0.0):
  Test-First: escribir tests antes del código.

Después (v1.0.1):
  Test-First: escribir tests que fallen antes de
  implementar la funcionalidad. Seguir el ciclo
  Red-Green-Refactor. Los tests de integración
  son obligatorios para cada endpoint.

En este ejemplo, la regla "Test-First" no cambia, pero se concreta con detalles que reducen la ambigüedad. El principio ya implicaba el ciclo Red-Green-Refactor, pero ahora lo explicita.

Cambios MINOR (x.Y.0)

Los cambios MINOR son adiciones o expansiones materiales que no modifican ni eliminan principios existentes:

• Añadir un nuevo artículo a la constitución
• Expandir un artículo existente con reglas adicionales que amplían su alcance
• Incorporar secciones nuevas (por ejemplo, una sección de restricciones organizacionales)

Un cambio MINOR es compatible hacia atrás: el código generado bajo la versión anterior sigue siendo válido bajo la nueva versión. Sin embargo, el código futuro deberá cumplir reglas adicionales.

Antes (v1.0.1):
  Core Principles: Library-First, Test-First,
  Simplicity, Anti-Abstraction

Después (v1.1.0):
  Core Principles: Library-First, Test-First,
  Simplicity, Anti-Abstraction, Observability

  (Nuevo) Observability: cada servicio emite logs
  estructurados en JSON con campos timestamp,
  level, service, trace_id y message. Las métricas
  de latencia se exponen en formato Prometheus.

Cambios MAJOR (X.0.0)

Los cambios MAJOR son incompatibles hacia atrás: modifican, redefinen o eliminan principios existentes de forma que el código generado bajo la versión anterior podría no cumplir con la nueva constitución.

• Eliminar un artículo de la constitución
• Cambiar fundamentalmente las reglas de un artículo existente
• Redefinir un principio de forma que contradiga su versión anterior

Antes (v1.1.0):
  Anti-Abstraction: no crear interfaces con una
  sola implementación. No usar patrones de diseño
  sin necesidad demostrable.

Después (v2.0.0):
  Modular Architecture: cada módulo expone una
  interfaz abstracta. Los consumidores dependen
  de la interfaz, no de la implementación concreta.

En este ejemplo, el principio "Anti-Abstraction" se elimina y se reemplaza por "Modular Architecture", que contradice directamente al anterior. Este cambio requiere revisar todo el código existente para verificar su compatibilidad con los nuevos principios.

Los cambios MAJOR deben ser infrecuentes y deliberados. Una constitución que cambia fundamentalmente cada pocas semanas pierde su función de proporcionar estabilidad al proyecto.

Ejecutar una enmienda

El proceso de enmienda se realiza ejecutando /speckit.constitution con las directrices de cambio. El agente IA gestiona automáticamente el incremento de versión, la actualización de fechas y la propagación a los templates dependientes.

/speckit.constitution

Enmienda a la constitución actual:

- Añadir principio "Error Boundaries": cada módulo
  define sus propios tipos de error. Los errores se
  propagan hacia arriba sin transformación. El punto
  de entrada de la aplicación es el único lugar
  donde se convierten errores en respuestas HTTP.

- Modificar "Test-First": añadir que los tests de
  rendimiento son obligatorios para endpoints que
  manejan más de 100 peticiones por segundo.

- Eliminar "CLI Interface": el proyecto ya no tiene
  componentes de línea de comandos.

Al procesar esta enmienda, el agente ejecuta un flujo estructurado:

• 1. Lee la constitución actual e identifica la versión vigente.
• 2. Clasifica los cambios según su tipo: la adición de "Error Boundaries" es un cambio MINOR, la modificación de "Test-First" puede ser PATCH o MINOR según su alcance, y la eliminación de "CLI Interface" es un cambio MAJOR.
• 3. Determina la nueva versión: como hay al menos un cambio MAJOR (eliminación de un principio), la versión se incrementa a la siguiente MAJOR.
• 4. Actualiza la constitución con los cambios y las nuevas fechas.
• 5. Propaga los cambios a spec-template.md, plan-template.md y tasks-template.md.
• 6. Genera un informe de sincronización que lista los principios modificados, los templates actualizados y los posibles seguimientos necesarios.

flowchart TB
    ENM["Enmienda solicitada"] --> CLAS["Clasificar cambios<br>PATCH / MINOR / MAJOR"]
    CLAS --> VER["Determinar nueva<br>versión"]
    VER --> UPD["Actualizar<br>constitution.md"]
    UPD --> PROP["Propagar a<br>templates"]
    PROP --> INF["Generar informe<br>de sincronización"]

El informe de sincronización

Tras cada enmienda, el agente genera un Sync Impact Report que se incluye como comentario HTML al inicio de constitution.md. Este informe documenta:

• Cambio de versión: versión anterior y nueva, con la justificación del tipo de bump.
• Principios modificados: lista de principios con su estado (añadido, modificado, eliminado).
• Templates actualizados: cada template con su estado de sincronización (actualizado o pendiente de revisión manual).
• TODOs pendientes: si algún placeholder no se ha podido resolver o si algún template requiere intervención manual.

Este informe proporciona trazabilidad completa de cada cambio en la constitución. Cuando un miembro del equipo se pregunta por qué un principio ha cambiado, puede revisar el historial de informes para reconstruir la evolución de la constitución.

Gestión de conflictos

Cuando la enmienda introduce cambios que afectan a artefactos ya generados (especificaciones, planes o tareas en curso), pueden surgir conflictos de coherencia. Por ejemplo, si se elimina el principio "Test-First" cuando ya existen tareas generadas que incluyen la escritura de tests, las tareas existentes quedan desalineadas con la constitución vigente.

Spec Kit no resuelve estos conflictos automáticamente. El equipo debe decidir si:

• Regenerar los artefactos afectados: ejecutar de nuevo /speckit.plan y /speckit.tasks para que reflejen los nuevos principios. Esto garantiza coherencia pero implica revisión de los artefactos regenerados.

• Completar la iteración actual con la constitución anterior y aplicar los cambios a partir de la siguiente feature. Este enfoque minimiza la disrupción pero requiere gestionar temporalmente dos versiones de la constitución.

• Aplicar los cambios selectivamente: actualizar manualmente los artefactos afectados sin regenerarlos por completo. Esto es viable para cambios PATCH o MINOR pequeños.

La recomendación general es aplicar enmiendas MAJOR entre features, no durante la implementación de una feature. Los cambios PATCH y MINOR pueden aplicarse en cualquier momento sin riesgo significativo.

Frecuencia y disciplina de enmiendas

La constitución debe evolucionar al ritmo del proyecto, pero con disciplina. Dos antipatrones frecuentes son:

Constitución estática: el equipo define la constitución al inicio del proyecto y nunca la actualiza. Con el tiempo, los principios dejan de reflejar la realidad del proyecto y el agente IA genera código que cumple reglas obsoletas.

Constitución volátil: el equipo modifica la constitución con cada feature, añadiendo y eliminando principios según las necesidades inmediatas. Esto anula el propósito de la constitución como referencia estable y produce un historial caótico.

El equilibrio óptimo varía según el proyecto, pero una revisión trimestral de la constitución suele ser un buen punto de partida. En esa revisión, el equipo evalúa si los principios actuales siguen siendo relevantes, si hay patrones problemáticos que un nuevo principio podría prevenir y si algún principio existente está generando fricción innecesaria.