Los artículos de la constitución

Qué son los artículos de la constitución

La constitución de un proyecto SDD se organiza en artículos (también llamados principios). Cada artículo define un aspecto fundamental de cómo debe construirse el software: desde la estructura del código hasta la estrategia de testing, pasando por la filosofía de diseño y las convenciones de integración.

La plantilla por defecto de Spec Kit incluye placeholders para que el equipo defina sus propios principios. Sin embargo, la comunidad y la documentación oficial han convergido en un conjunto de artículos que aparecen con frecuencia en proyectos SDD bien estructurados. Estos artículos no son obligatorios en su forma exacta, pero representan patrones probados que resuelven problemas recurrentes en el desarrollo con agentes IA.

Los artículos de la constitución no son sugerencias ni buenas prácticas opcionales. Son reglas de obligado cumplimiento que el agente IA debe respetar en cada línea de código que genere.

Los artículos que se describen a continuación cubren los aspectos más relevantes de un proyecto de software y pueden combinarse, ampliarse o reducirse según las necesidades del equipo. Lo importante es que cada artículo sea específico, declarativo y verificable.

Library-First

El principio Library-First establece que cada funcionalidad del proyecto se implementa primero como una librería independiente con una interfaz clara, tests propios y documentación. El código de aplicación (controladores, rutas, handlers) actúa como una capa fina que conecta librerías entre sí.

Las reglas concretas de este artículo son:

• Cada feature nueva se estructura como un módulo autocontenido con su propia API pública, sin depender de la infraestructura de la aplicación (frameworks, bases de datos, servicios externos).
• Las librerías deben ser independientemente testables. Si un módulo no puede probarse sin levantar un servidor web o conectarse a una base de datos, viola este principio.
• No se permiten módulos que existan solo por razones organizativas. Cada librería debe tener un propósito funcional concreto que justifique su existencia.
• Se priorizan las librerías estándar y de terceros bien mantenidas sobre las implementaciones propias. Si ya existe una librería que resuelve el problema, se usa en lugar de reinventar la solución.

Estructura Library-First de un proyecto Python:

mi-proyecto/
  libs/
    auth/           # Librería de autenticación
      __init__.py
      tokens.py
      validators.py
      tests/
    notifications/  # Librería de notificaciones
      __init__.py
      channels.py
      templates.py
      tests/
  app/
    main.py         # Capa fina que conecta librerías
    routes.py

Library-First reduce el acoplamiento entre componentes y facilita que el agente IA trabaje en una funcionalidad sin necesitar contexto de todo el proyecto.

Este principio tiene una implicación práctica directa para el trabajo con agentes IA: cuanto más autocontenido es un módulo, menos contexto necesita el agente para implementarlo correctamente. Un agente que trabaja con una librería de autenticación independiente no necesita conocer los detalles del sistema de notificaciones ni de la capa de persistencia.

CLI Interface

El principio CLI Interface define las convenciones para herramientas de línea de comandos, pero su filosofía se extiende a cualquier tipo de interfaz del sistema: APIs REST, SDKs, mensajes entre servicios. El principio establece que las interfaces del proyecto deben ser predecibles, consistentes y bien documentadas.

Las reglas típicas incluyen:

• Los datos de salida van a stdout y los errores a stderr. Esta separación permite componer comandos con pipes y redirecciones sin mezclar la salida útil con los mensajes de error.
• Se soportan al menos dos formatos de salida: JSON para procesamiento automatizado y un formato legible por humanos para uso interactivo.
• Los códigos de salida siguen convenciones estándar: 0 para éxito, valores distintos de cero para errores, con códigos específicos para tipos de error distintos.
• Los parámetros de entrada siguen convenciones POSIX: flags cortos (-v), flags largos (--verbose), argumentos posicionales para datos obligatorios.

Este artículo es especialmente relevante en proyectos que construyen herramientas de desarrollo, CLIs o APIs. Para aplicaciones web o servicios backend, puede adaptarse para definir convenciones de API: formato de respuestas, códigos HTTP, estructura de errores y versionado de endpoints.

Test-First

El principio Test-First establece que los tests se escriben antes que la implementación, siguiendo el ciclo Red-Green-Refactor de TDD (Test-Driven Development):

• Red: se escribe un test que describe el comportamiento esperado. El test falla porque la funcionalidad aún no existe.
• Green: se implementa la cantidad mínima de código necesaria para que el test pase.
• Refactor: se mejora el código manteniendo los tests en verde.

Las reglas concretas de este artículo definen:

• Cada user story aprobada en la especificación debe tener tests que fallen antes de empezar la implementación.
• Los tests de integración son obligatorios para cada feature completa. Los tests unitarios son complementarios.
• No se considera una tarea como completada hasta que todos sus tests pasen.
• La cobertura de tests tiene un umbral mínimo definido por el equipo (por ejemplo, 80%).

flowchart LR
    RED["Red<br>Test que falla"] --> GREEN["Green<br>Implementación mínima"]
    GREEN --> REFACTOR["Refactor<br>Mejora del código"]
    REFACTOR --> RED

Test-First no es solo una práctica de testing. Es una herramienta de diseño: escribir el test primero obliga a pensar en la interfaz del módulo antes de su implementación.

Cuando el agente IA trabaja con el principio Test-First, genera los tests como primera tarea de cada feature. Esto proporciona una red de seguridad automática que detecta regresiones y valida que el código generado cumple los criterios de aceptación de la especificación.

Simplicity

El principio de Simplicity (simplicidad) es una declaración contra la complejidad innecesaria. Define que el código generado debe ser lo más simple que resuelva el problema, sin añadir capas de abstracción, patrones de diseño ni infraestructura que no aporten valor inmediato.

Las reglas habituales son:

• No anticipar necesidades futuras: el código resuelve los requisitos actuales. Las extensiones se añaden cuando se necesitan, no por si acaso.
• Preferir código explícito sobre código "inteligente". Un bloque de código que se entiende a primera lectura es preferible a una solución elegante que requiere documentación para comprenderla.
• Minimizar dependencias: cada dependencia externa es un vector de riesgo (mantenimiento, compatibilidad, seguridad). Solo se añaden dependencias que resuelvan problemas que no justifican una implementación propia.
• Funciones y módulos pequeños: si una función supera un umbral razonable de complejidad (por ejemplo, 30 líneas), es candidata a dividirse.

Un ejemplo concreto: si la especificación pide un endpoint que devuelve una lista de usuarios, el principio de simplicidad dicta implementar una consulta directa a la base de datos con los filtros necesarios. No añadir un sistema de caché, ni paginación basada en cursores, ni compresión de respuestas, a menos que la especificación lo requiera explícitamente.

La simplicidad no es hacer menos. Es hacer exactamente lo necesario, sin deuda técnica por exceso de ingeniería ni por falta de ella.

Anti-Abstraction

El principio Anti-Abstraction complementa al de Simplicity, pero se centra específicamente en las capas de indirección. Establece que no se deben crear abstracciones a menos que exista una necesidad demostrable y actual.

Este artículo combate un patrón frecuente en el desarrollo de software: crear interfaces, factorías, wrappers y capas de abstracción "por si acaso" se necesitan en el futuro. En el contexto de SDD, donde el agente IA genera código, las abstracciones prematuras son especialmente problemáticas porque:

• Aumentan el contexto necesario: el agente necesita entender más archivos y relaciones para implementar una funcionalidad simple.
• Dificultan la regeneración: si se regenera código a partir de una especificación actualizada, las abstracciones innecesarias añaden complejidad que el agente debe reproducir o gestionar.
• Oscurecen la intención: un wrapper sobre un cliente HTTP no añade valor si simplemente delega todas las llamadas al cliente original.

Las reglas de Anti-Abstraction incluyen:

• No crear interfaces con una sola implementación. Las interfaces se justifican cuando existen al menos dos implementaciones concretas.
• No crear wrappers sobre librerías de terceros a menos que se necesite adaptar su API a las convenciones del proyecto.
• No usar patrones como Factory, Strategy o Observer a menos que el problema específico los requiera. Los patrones de diseño son soluciones a problemas concretos, no estructuras predeterminadas.
• Preferir composición de funciones sobre jerarquías de clases. Una función que recibe otra función como parámetro suele ser más simple que una jerarquía de clases con herencia y polimorfismo.

Integration-First

El principio Integration-First establece que las integraciones con sistemas externos (bases de datos, APIs de terceros, servicios de mensajería, sistemas de archivos) se implementan y prueban desde el principio, no al final del desarrollo.

Este artículo responde a un problema frecuente en proyectos de software: construir toda la lógica de negocio con mocks y stubs, dejando la integración real para el final. Cuando llega ese momento, las suposiciones sobre el comportamiento de los sistemas externos resultan incorrectas y hay que reescribir partes significativas del código.

Las reglas de Integration-First definen:

• Las conexiones a sistemas externos se configuran y verifican en las primeras tareas de implementación, antes de construir la lógica de negocio.
• Los tests de integración usan conexiones reales (o contenedores Docker que replican el servicio) en lugar de mocks que simulan el comportamiento esperado.
• Cada integración tiene un health check que verifica la conectividad y la compatibilidad de versiones.
• Las credenciales y configuraciones de servicios externos se gestionan desde el primer día, no se dejan como "TODO" para más adelante.

flowchart TB
    subgraph IntegrationFirst["Enfoque Integration-First"]
        direction TB
        I1["Configurar conexiones<br>reales"] --> I2["Verificar health checks"]
        I2 --> I3["Implementar lógica<br>de negocio"]
        I3 --> I4["Tests de integración<br>end-to-end"]
    end
    subgraph Traditional["Enfoque tradicional"]
        direction TB
        T1["Implementar lógica<br>con mocks"] --> T2["Integrar al final"]
        T2 --> T3["Descubrir<br>incompatibilidades"]
        T3 --> T4["Reescribir"]
    end

Integration-First reduce el riesgo de descubrir incompatibilidades en la fase final del proyecto, cuando el coste de corrección es máximo.

Otros artículos frecuentes

Además de los principios descritos, las constituciones de proyectos SDD suelen incluir artículos adicionales según el contexto del proyecto:

Documentation Separation of Concerns: establece que la especificación (spec.md) contiene exclusivamente el "qué" y el "por qué" (agnóstica de tecnología), mientras que el plan (plan.md) contiene el "cómo" (detalles técnicos). Esta separación evita que el agente IA mezcle requisitos de negocio con decisiones de implementación.

Observability: define que cada servicio debe emitir logs estructurados, métricas y trazas desde el primer día. No se deja la instrumentación como tarea final.

Security-by-Default: establece que las validaciones de entrada, la sanitización de datos y las comprobaciones de autorización se implementan como parte de la lógica principal, no como middleware opcional.

Dependency Management: define políticas sobre cómo gestionar las dependencias del proyecto: versiones pinneadas, auditorías periódicas, criterios para añadir o eliminar dependencias.

El número de artículos varía según el proyecto. Una constitución con tres principios bien definidos es preferible a una con quince principios vagos. Lo relevante es que cada artículo sea accionable: el agente IA debe poder leerlo y aplicarlo sin interpretación.

Relación entre artículos

Los artículos no son independientes entre sí. Forman un sistema de refuerzo mutuo donde cada principio complementa a los demás:

• Library-First + Test-First: si cada módulo es una librería independiente, testearla de forma aislada es directo.
• Simplicity + Anti-Abstraction: ambos artículos luchan contra la complejidad innecesaria, pero desde ángulos diferentes. Simplicity se enfoca en el código que se escribe, Anti-Abstraction en las capas que se crean.
• Integration-First + Test-First: los tests de integración se escriben desde el inicio, usando conexiones reales, lo que valida tanto la lógica como las integraciones.

Esta coherencia interna es lo que convierte a la constitución en un sistema de gobernanza efectivo, no solo una lista de principios aislados.