Dos meses con Spec-Kit de GitHub y Claude Code: Lo que funciona, lo que no

Después de dos meses usando spec-kit de GitHub para desarrollo basado en especificaciones (SDD) con Claude Code como agente principal, un desarrollador en r/LocalLLaMA informa sobre lo que funciona y lo que no. El kit, disponible en github.com/github/spec-kit, impone un flujo de trabajo de cinco fases: Constitución, Especificación, Plan, Tareas, Implementación. La idea central: la especificación, no el prompt, es la fuente de verdad.

Lo que realmente funciona

• Independiente del agente: La misma especificación funciona con Claude Code, Cursor, Codex, Gemini CLI, Copilot. El autor generó código con Claude Code, luego pasó la especificación a Cursor para refactorizar pruebas sin problemas.
• Puntos de control estrictos entre fases: La fase de Plan muestra la arquitectura propuesta completa antes de escribir cualquier código, detectando malas decisiones a un costo de arreglo de 5 minutos en lugar de 5 horas.
• Archivo de constitución como filtro de calidad: Defines reglas inviolables de antemano: cobertura mínima de pruebas, listas blancas de dependencias, presupuestos de rendimiento, rigurosidad de tipos. El agente falla su propia validación si intenta violarlas.
• Determinismo mejorado: Re-ejecutar la fase de implementación produce resultados más consistentes que el prompting puro, ya que el agente no está llenando 30 decisiones implícitas.

Lo que molesta

• La desviación es real: Ediciones manuales de código sin actualizar la especificación causan desincronización rápida. spec-kit tiene herramientas pero son tempranas.
• Sobrecarga para cambios pequeños: Correcciones de errores <50 LOC o características triviales se sienten ceremoniales. La regla del autor: solo SDD completo para nuevos módulos o características que toquen 200+ LOC.
• Migración heredada dolorosa: Adaptar SDD a una base de código de 30k LOC lleva meses.
• La calidad depende del agente: Claude Code (Sonnet/Opus 4.6+) lo maneja bien; los modelos más pequeños generan planes que compilan pero carecen de razonamiento arquitectónico.

Configuración práctica

• Instalación: uv tool install --from git+https://github.com/github/spec-kit.git specify-cli. Solo el repositorio oficial es seguro — PyPI tiene typosquatters.
• Agente principal: Claude Code, con validación cruzada en Cursor y Gemini CLI.
• Persistencia local: SQLite (fácil de especificar/validar, sin dependencia en la nube).
• Plantilla de constitución reutilizable: tipado estricto, cobertura de pytest >80%, lista blanca de dependencias explícita, sin servicios en la nube a menos que sea requerido.

Preguntas abiertas

• ¿Pueden los modelos locales (Qwen, DeepSeek-Coder, GLM, Llama) manejar Plan e Implementación de manera competente? El autor encontró que los modelos pequeños siguen el formato pero el razonamiento arquitectónico falla.
• ¿Funciona el SDD multi-agente? Especificación por un modelo, implementación por otro, auditoría por un tercero — teóricamente mejor, pero no mediblemente mejor que un solo agente en la práctica.