El comando /speckit.constitution

El papel de la constitución en el flujo SDD

En Spec-Driven Development, la constitución es el primer artefacto que se crea en un proyecto. Antes de especificar qué construir, antes de planificar cómo hacerlo y antes de implementar una sola línea de código, el equipo define las reglas de gobernanza que guiarán todas las decisiones posteriores.

La constitución cumple una función análoga a la de una constitución en el ámbito legal: establece los principios fundamentales que no pueden violarse. Mientras que las especificaciones, los planes y las tareas cambian con cada feature, la constitución permanece estable y actúa como referencia constante para el agente IA y para el equipo humano.

La constitución no describe qué construir ni cómo hacerlo. Define las reglas del juego: los principios arquitectónicos, las convenciones de código y las restricciones técnicas que todo el código generado debe respetar.

Esta separación es importante. Sin una constitución explícita, cada vez que el agente IA genera código, toma decisiones que nadie ha validado: elige patrones de diseño, decide si escribir tests o no, selecciona librerías según su propio criterio. Con una constitución, esas decisiones están predefinidas y documentadas. El agente no improvisa los aspectos fundamentales del proyecto.

flowchart TB
    CONST["Constitución<br>Principios inmutables"] --> SPEC["Especificación<br>Qué construir"]
    CONST --> PLAN["Plan técnico<br>Cómo construirlo"]
    CONST --> TASKS["Tareas<br>Desglose ejecutable"]
    CONST --> IMPL["Implementación<br>Código generado"]
    style CONST fill:#f9f,stroke:#333,stroke-width:2px

La constitución influye en todos los pasos del flujo SDD. Cuando el agente genera un plan técnico, consulta la constitución para saber qué patrones están permitidos. Cuando descompone el plan en tareas, respeta las convenciones de testing definidas en la constitución. Cuando implementa código, aplica los principios de simplicidad, nomenclatura y estructura que la constitución establece.

Ejecutar el comando /speckit.constitution

El comando /speckit.constitution se ejecuta dentro del chat del agente IA compatible con Spec Kit. Su funcionamiento parte de un archivo de prompt que Spec Kit instala durante la inicialización del proyecto, ubicado en el directorio de agentes del proyecto (por ejemplo, .github/agents/speckit.constitution.agent.md para GitHub Copilot).

La forma más directa de usarlo es escribir el comando seguido de las directrices que se quieren establecer:

/speckit.constitution

Principios para el proyecto:
- Usar Python 3.12+ con FastAPI para la API REST
- Priorizar librerías estándar sobre dependencias externas
- Escribir tests de integración para cada endpoint
- No usar ORMs, trabajar con SQL directo usando asyncpg
- Formato de logs estructurado en JSON
- Documentar cada módulo público con docstrings

Al ejecutar el comando, el agente IA realiza varias acciones de forma secuencial:

• 1. Lee la plantilla de constitución almacenada en .specify/memory/constitution.md. Esta plantilla contiene tokens de posición (placeholders) con el formato [NOMBRE_EN_MAYUSCULAS] que el agente debe rellenar con valores concretos.

• 2. Procesa las directrices del usuario e interpreta los principios proporcionados, organizándolos en las secciones de la plantilla.

• 3. Genera la constitución completa reemplazando cada placeholder con contenido concreto: nombres de principios, descripciones detalladas, reglas de gobernanza y metadatos de versionado.

• 4. Propaga los cambios a los templates dependientes: spec-template.md, plan-template.md y tasks-template.md. Estos templates incorporan referencias a los principios de la constitución para que las especificaciones, planes y tareas generados en el futuro sean coherentes con los principios establecidos.

Proporcionar contexto al comando

Una práctica efectiva es incluir archivos de contexto junto con el comando. Por ejemplo, si el proyecto ya tiene un package.json o un pyproject.toml, proporcionarlo como contexto permite al agente entender las dependencias existentes y adaptar los principios al stack real del proyecto.

/speckit.constitution

@pyproject.toml

El proyecto usa FastAPI con SQLAlchemy async.
Mantener la arquitectura hexagonal existente.
Tests con pytest y cobertura mínima del 80%.

El agente utiliza el archivo de contexto para generar principios que no contradigan las decisiones técnicas ya tomadas. Si el pyproject.toml ya incluye SQLAlchemy como dependencia, el agente no generará un principio que prohíba su uso.

Estructura del archivo constitution.md

El resultado del comando es un archivo constitution.md actualizado en .specify/memory/. Este archivo tiene una estructura predefinida con secciones estandarizadas:

# Nombre del Proyecto - Constitution

## Core Principles

### Library-First
Cada funcionalidad se implementa primero como librería
independiente con interfaz clara, tests propios y
documentación. No se permiten librerías que existan solo
por organización sin un propósito funcional concreto.

### Test-First
Ciclo Red-Green-Refactor. Los tests se escriben antes
que la implementación. Cada feature requiere tests de
integración antes del merge.

### Simplicity
Salida estándar para datos, stderr para errores. Soporte
de formatos JSON y legible por humanos. Sin abstracciones
innecesarias.

## Governance

Procedimiento de enmienda, política de versionado
y expectativas de revisión de cumplimiento.

Version: 1.0.0 | Ratified: 2026-03-09 | Last Amended: 2026-03-09

Cada principio tiene un nombre conciso y una descripción que articula reglas concretas, no aspiraciones vagas. Un principio como "el código debe ser de calidad" no es útil porque es ambiguo. Un principio como "cada módulo público debe tener docstrings con ejemplos de uso" es específico y verificable.

Los principios de la constitución deben ser declarativos y verificables. El agente IA necesita reglas claras que pueda aplicar sin ambigüedad durante la generación de código.

Metadatos de versionado

La constitución incluye una línea de metadatos al final del documento que registra tres datos:

• Version: el número de versión semántica de la constitución (por ejemplo, 1.0.0).
• Ratified: la fecha en que se creó la constitución original.
• Last Amended: la fecha de la última modificación.

Estos metadatos permiten rastrear cuándo se establecieron los principios y cuándo se modificaron por última vez, lo cual es relevante cuando varios miembros del equipo trabajan con el mismo proyecto.

Efectos en los templates del proyecto

Uno de los aspectos menos evidentes del comando /speckit.constitution es que no solo actualiza constitution.md. También modifica los templates que Spec Kit usa para generar especificaciones, planes y tareas.

Cuando se ejecuta el comando, el agente revisa tres archivos en .specify/templates/:

• spec-template.md: la plantilla que se usa al ejecutar /speckit.specify. Tras actualizar la constitución, esta plantilla puede incluir secciones adicionales o restricciones que reflejen los principios establecidos.

• plan-template.md: la plantilla para /speckit.plan. Si la constitución define principios como "Test-First", el template de planificación incluirá secciones para la estrategia de testing. Si define "Library-First", el template puede incluir un checklist para verificar que cada componente se ha diseñado como librería independiente.

• tasks-template.md: la plantilla para /speckit.tasks. Los tipos de tareas disponibles se ajustan a los principios de la constitución. Por ejemplo, si la constitución requiere observabilidad, el template de tareas puede incluir categorías específicas para tareas de instrumentación y logging.

flowchart LR
    CMD["/speckit.constitution"] --> CONST["constitution.md<br>Principios actualizados"]
    CMD --> SPEC_T["spec-template.md<br>Secciones ajustadas"]
    CMD --> PLAN_T["plan-template.md<br>Checks alineados"]
    CMD --> TASK_T["tasks-template.md<br>Categorías actualizadas"]

Esta propagación automática garantiza que los principios de la constitución no se queden aislados en un documento que nadie consulta. Se integran directamente en el flujo de trabajo, de forma que cada especificación, plan y lista de tareas generados a partir de ese momento reflejan los principios del proyecto.

Cuándo ejecutar el comando

El comando /speckit.constitution se ejecuta principalmente en dos momentos del ciclo de vida del proyecto:

Al inicio del proyecto (greenfield): es el primer comando que se ejecuta tras specify init. El equipo define los principios fundamentales antes de crear la primera especificación. Este es el momento ideal porque los principios establecidos en la constitución influirán en todas las decisiones posteriores.

Al incorporar SDD a un proyecto existente (brownfield): cuando se adopta Spec Kit en un proyecto que ya tiene código, la constitución debe reflejar las decisiones técnicas ya tomadas. El stack tecnológico, los patrones arquitectónicos y las convenciones de testing que el equipo ya usa se codifican como principios para que el agente IA los respete al generar código nuevo.

En ambos casos, la constitución no necesita ser perfecta desde el primer día. El mecanismo de enmiendas permite actualizarla de forma controlada a medida que el equipo descubre nuevos principios o necesita ajustar los existentes.