Personalizar la constitución

Por qué personalizar la constitución

La plantilla por defecto de Spec Kit genera una constitución con principios genéricos que funcionan como punto de partida. Sin embargo, cada proyecto tiene un contexto único: un stack tecnológico concreto, convenciones de equipo heredadas, restricciones organizacionales y decisiones arquitectónicas que no pueden capturarse en una plantilla universal.

Una constitución genérica produce un efecto paradójico: principios tan amplios que el agente IA los interpreta de formas diferentes en cada ejecución. Un principio como "el código debe ser mantenible" no proporciona una guía accionable. El agente puede interpretar "mantenible" como añadir comentarios en cada línea, crear abstracciones para todo o simplificar hasta el punto de perder funcionalidad.

La personalización convierte principios genéricos en reglas específicas que el agente IA aplica de forma determinista, reduciendo la variabilidad entre ejecuciones.

El objetivo de la personalización no es reescribir la constitución desde cero, sino adaptar los principios a la realidad del proyecto. Esto implica tres operaciones: modificar artículos existentes para hacerlos más específicos, eliminar artículos que no aplican al contexto del proyecto y añadir artículos nuevos que cubran aspectos no contemplados en la plantilla por defecto.

Adaptar artículos al stack tecnológico

La personalización más directa consiste en concretar los principios genéricos con las tecnologías reales del proyecto. Un principio como "Library-First" tiene implicaciones diferentes en un proyecto Python que en uno TypeScript o Go.

Ejemplo: proyecto Python con FastAPI

Para un proyecto backend en Python con FastAPI, la constitución podría adaptar los principios de la siguiente forma:

/speckit.constitution

@pyproject.toml

Adaptar los principios al stack Python + FastAPI:

- Library-First: cada feature se implementa como un módulo
  Python independiente en el directorio libs/. Los módulos
  exponen funciones puras que no dependen de FastAPI.
  Los routers de FastAPI son una capa fina de adaptación.

- Test-First: usar pytest con pytest-asyncio para tests
  async. Fixtures compartidas en conftest.py. Tests de
  integración con httpx.AsyncClient contra la app real.

- Simplicity: usar Pydantic para validación de entrada,
  dataclasses estándar para modelos internos. No crear
  clases base abstractas para los schemas.

- Integration-First: usar testcontainers-python para
  PostgreSQL y Redis en tests de integración. No mockear
  la base de datos.

Al ejecutar este comando, el agente transforma los principios genéricos en reglas que mencionan herramientas, librerías y patrones concretos. Cada vez que el agente genere código para este proyecto, aplicará pytest (no unittest), usará Pydantic (no validación manual), y estructurará el código en libs/ (no en una estructura monolítica).

Ejemplo: proyecto TypeScript con Next.js

Para un proyecto frontend con Next.js, la adaptación sería diferente:

/speckit.constitution

@package.json @tsconfig.json

Principios para un proyecto Next.js con App Router:

- Library-First: la lógica de negocio va en lib/ como
  funciones puras TypeScript. Los componentes de React
  solo manejan UI y estado. No lógica de negocio en
  componentes.

- Test-First: vitest para tests unitarios de lib/.
  Playwright para tests e2e de flujos completos.
  Testing Library para tests de componentes.

- Simplicity: usar los patrones nativos de Next.js
  (Server Components, Server Actions) antes de añadir
  librerías externas de estado o data fetching.

- Anti-Abstraction: no crear HOCs ni wrappers sobre
  componentes de Next.js. Usar composición directa.
  No crear un "design system" propio si se usa una
  librería de componentes existente.

La diferencia entre ambos ejemplos ilustra por qué la personalización es necesaria. Los principios genéricos ("Library-First", "Test-First") se mantienen, pero sus reglas concretas cambian según el ecosistema tecnológico.

Eliminar artículos innecesarios

No todos los artículos de la plantilla por defecto son relevantes para todos los proyectos. Un artículo sobre CLI Interface tiene poco sentido en una aplicación web sin componentes de línea de comandos. Un artículo sobre Integration-First puede ser excesivo para un proyecto que no tiene dependencias externas.

Eliminar artículos innecesarios no es pereza, es higiene de la constitución. Cada artículo que no aplica añade ruido que el agente IA debe procesar e interpretar. En el peor de los casos, un artículo irrelevante puede provocar que el agente genere código innecesario para "cumplir" con un principio que no debería existir.

/speckit.constitution

Este es un proyecto de librería Python sin interfaz
de usuario ni servicios externos.

Eliminar los siguientes principios:
- CLI Interface: no es una herramienta de línea de
  comandos
- Integration-First: no hay bases de datos ni APIs
  externas

Mantener y reforzar:
- Library-First: es el principio central del proyecto
- Test-First: cobertura al 90% con pytest
- Simplicity: API pública mínima, sin clases cuando
  una función baste

Una constitución con cinco artículos precisos es más efectiva que una con diez artículos genéricos. Cada artículo debe ganarse su lugar con una justificación concreta.

Añadir artículos propios

La parte más valiosa de la personalización es la capacidad de crear principios nuevos que reflejen las necesidades específicas del equipo o la organización. Estos principios no están en la plantilla por defecto porque son particulares de cada contexto.

Principios de equipo

Los equipos desarrollan convenciones propias a lo largo del tiempo que conviene codificar en la constitución:

/speckit.constitution

Añadir los siguientes principios específicos del equipo:

- Error Handling: todos los errores se gestionan con
  un tipo Result[T, Error] personalizado. No usar
  excepciones para flujo de control. Las excepciones
  solo capturan errores inesperados del runtime.

- API Versioning: todas las rutas de la API incluyen
  el prefijo /api/v1/. Los breaking changes requieren
  una nueva versión. Las versiones anteriores se
  mantienen durante 6 meses tras el deprecation.

- Naming Conventions: módulos en snake_case, clases
  en PascalCase, constantes en UPPER_SNAKE_CASE.
  Los nombres de funciones empiezan con verbo:
  get_, create_, update_, delete_, validate_, parse_.

Principios organizacionales

En entornos corporativos, la constitución puede incluir restricciones que vienen de la organización, no del equipo de desarrollo:

/speckit.constitution

Restricciones organizacionales:

- Cloud Provider: todo el despliegue se realiza en
  AWS. No usar servicios de otros cloud providers.
  Preferir servicios serverless (Lambda, DynamoDB,
  SQS) sobre instancias EC2.

- Compliance: los datos personales (PII) se cifran
  en reposo con AES-256 y en tránsito con TLS 1.3.
  Los logs no deben contener datos personales.

- Dependency Policy: solo se permiten dependencias
  con licencia MIT, Apache 2.0 o BSD. Las
  dependencias con licencia GPL requieren aprobación
  del equipo legal.

Principios de dominio

Para proyectos con lógica de dominio compleja, la constitución puede incluir reglas que reflejen las restricciones del negocio:

/speckit.constitution

Reglas de dominio financiero:

- Monetary Precision: todos los cálculos monetarios
  usan Decimal con 4 decimales de precisión. No
  usar float ni double para cantidades monetarias.

- Audit Trail: cada operación que modifica datos
  financieros genera un registro de auditoría
  inmutable con timestamp, usuario, operación y
  valores antes/después.

- Idempotency: todas las operaciones de pago son
  idempotentes. Cada petición incluye un
  idempotency_key que previene duplicados.

Buenas prácticas de personalización

La personalización efectiva de la constitución sigue un conjunto de criterios que maximizan la utilidad de cada artículo:

Ser específico y verificable: cada principio debe poder verificarse con un test o una revisión de código. "El código debe ser limpio" no es verificable. "Cada función pública tiene un docstring con al menos un ejemplo de uso" sí lo es.

Evitar contradicciones: los artículos no deben contradecirse entre sí. Si un artículo dice "preferir funciones puras" y otro dice "usar clases para todo", el agente IA no puede cumplir ambos simultáneamente.

Proporcionar contexto de archivos: al ejecutar /speckit.constitution, incluir archivos del proyecto como contexto (@pyproject.toml, @package.json, @tsconfig.json) permite al agente generar principios coherentes con las decisiones técnicas ya tomadas.

Iterar en lugar de definir de golpe: no es necesario definir todos los principios en la primera ejecución. Se puede empezar con los tres o cuatro principios más importantes y añadir el resto a medida que el equipo descubre qué reglas necesita codificar.

flowchart TB
    V1["Constitución v1<br>3-4 principios básicos"] --> USO["Uso en specs,<br>planes y tareas"]
    USO --> DESC["Descubrir que<br>falta o sobra"]
    DESC --> V2["Constitución v2<br>Principios ajustados"]
    V2 --> USO2["Uso continuado"]
    USO2 --> DESC2["Nuevos<br>descubrimientos"]
    DESC2 --> V3["Constitución v3<br>Principios maduros"]

No duplicar lo que dice la especificación: la constitución define principios transversales que aplican a todo el proyecto. Los requisitos específicos de una funcionalidad pertenecen a la especificación de esa feature, no a la constitución. Un principio como "la pantalla de login debe tener validación client-side" no pertenece a la constitución porque es un requisito de una feature concreta.

Documentar la razón de cada principio: cuando un artículo incluye una breve explicación del porqué (su rationale), el agente IA puede tomar mejores decisiones en situaciones no contempladas. Si el principio dice "no usar ORMs" pero no explica por qué, el agente no sabe si la razón es rendimiento, control sobre las queries o preferencia del equipo. Si el principio dice "no usar ORMs porque necesitamos control total sobre las queries SQL para optimizar tiempos de respuesta", el agente tiene contexto para tomar decisiones coherentes cuando surjan situaciones nuevas.