ADR-030: SpecKit como sistema de gobernanza documental¶
Estado: aceptado
Contexto¶
SmallCountry acumuló 131 documentos históricos, 23 ADRs, 12 principios, y decisiones implícitas dispersas entre archivos sin estructura. Se necesitaba un sistema que unificara la gobernanza documental, proporcionara memoria entre sesiones, y aplicara reglas de control de deriva de forma verificable.
Decisión¶
SpecKit como sistema de gobernanza documental de SmallCountry. Tres subsistemas:
mk-spec-memory — Memoria indexada con búsqueda semántica. Almacena principios, ADRs, y reglas de gobernanza como memorias constitucionales que persisten entre sesiones.
mk-code-index — Grafo estructural del repositorio system/. Permite consultas de impacto, dependencias y blast radius sobre los specs.
mk-skill-advisor — Metadata de skills para enrutamiento de tareas a las herramientas correctas.
El spec folder 000-governance-constitution es el primer spec del sistema y define las reglas de uso de SpecKit para SmallCountry.
Alternativas consideradas¶
| Opción | Por qué se descartó |
|---|---|
| Solo documentación en Markdown | Sin búsqueda semántica. Sin memoria entre sesiones. Sin validación estructural. |
| Base de datos SQL dedicada | Requiere schema maintenance. Sin integración con herramientas de AI. |
| Wiki interno | Sin indexación semántica. Sin control de deriva automatizado. |
Consecuencias¶
- ✅ Memoria constitucional indexada con búsqueda semántica (62 documentos)
- ✅ CI de gobernanza verifica coherencia system/ ↔ web/
- ✅ Reglas anti-deriva con 3 capas de enforcement (SpecKit + CI + humano)
- ✅ Cada cambio no trivial requiere spec folder validado
- ❌ Complejidad adicional: 3 subsistemas MCP que mantener
- ❌ Curva de aprendizaje para el operador
- ❌ Dependencia de Ollama para embeddings (mitigado: modelo local, sin API externa)