Hay un patrón que aparece una y otra vez cuando los devs se frustran con Claude Code (o con cualquier agente de código, en realidad): le dan una idea vaga, el agente interpreta algo distinto a lo que tenían en mente, genera código que funciona pero no resuelve el problema real, y el ciclo de correcciones se convierte en un loop interminable.
El problema casi nunca está en el modelo. Está en el input.
spec-based-claude-code es una implementación concreta de una solución a ese problema: un workflow de Spec-Driven Development construido directamente en Claude Code usando slash commands personalizados.
¿Qué es Spec-Driven Development?
La idea central es simple: antes de escribir una sola línea de código, escribís una especificación. No un comentario vago en el chat. Una spec real — con contexto del problema, comportamiento esperado, casos edge, criterios de aceptación, y decisiones de diseño explícitas.
Solo cuando la spec está clara, el agente empieza a implementar.
El enfoque no es nuevo. Tiene raíces en BDD (Behavior-Driven Development) y en las metodologías de diseño por contrato. Lo que cambió es que ahora tenemos agentes de código lo suficientemente capaces como para que una buena spec se convierta directamente en implementación funcional, sin tener que escribir cada línea manualmente.
Cómo funciona spec-based-claude-code
El repositorio implementa el workflow a través de slash commands que guían tanto al desarrollador como al agente a través de un proceso estructurado:
/spec — Definir antes de implementar
El primer comando fuerza la creación de una especificación completa antes de tocar código. El agente no pregunta “¿qué querés que haga?” — te lleva a través de un proceso estructurado para definir:
- El problema real que estás resolviendo (no la solución que tenés en mente)
- El comportamiento esperado en términos de inputs y outputs observables
- Los casos edge que importan para tu contexto específico
- Las restricciones técnicas — qué puede usar, qué tiene que respetar, qué está fuera de scope
El resultado es un documento de spec que vive en tu repositorio. No en el chat. En el repo.
/plan — Arquitectura antes de código
Con la spec como base, el siguiente comando genera un plan de implementación técnico. Qué archivos se van a crear o modificar, qué dependencias entran, qué decisiones de arquitectura se toman y por qué.
Este paso es especialmente valioso porque fuerza a Claude Code a razonar sobre la solución completa antes de comprometerse con una implementación particular. Los errores de arquitectura son exponencialmente más baratos de corregir en un plan de texto que en código ya escrito.
/implement — Ejecución disciplinada
Recién en este punto el agente empieza a generar código — pero no desde cero, sino siguiendo el plan aprobado y la spec definida. El contexto está cargado, las decisiones están tomadas, y el margen para interpretaciones divergentes está minimizado.
Por qué funciona
El problema de fondo con el prompting conversacional para coding es que la ambigüedad se acumula. Cada instrucción vaga agrega incertidumbre, y el agente llena esa incertidumbre con sus propias asunciones — que a veces son razonables, y a veces no.
Una spec bien escrita elimina esa ambigüedad antes de que el problema exista.
También cambia la dinámica de la revisión. En lugar de revisar código línea por línea y tratar de entender si hace lo que querías, revisás la spec primero. Si la spec está bien, el código casi siempre también lo está. Si el código está mal, volvés a la spec y encontrás la desconexión.
Quién debería usar esto
Spec-based-claude-code tiene más valor en contextos donde:
- Los features son complejos — más de un par de archivos, más de un caso de uso, dependencias cruzadas
- El costo de rehacer es alto — features que impactan partes críticas del sistema, APIs públicas, o lógica de negocio central
- Trabajás en equipo — las specs son documentación viva que otros pueden revisar y cuestionar antes de que exista una sola línea de código
- Usás agentes de larga duración — workflows como Ralph Loop se benefician enormemente de tener specs que el agente pueda releer entre tareas
Para scripts pequeños y tareas de CRUD simple, el overhead probablemente no vale la pena. Pero para cualquier cosa que requiera más de 30 minutos de implementación, el tiempo que invertís en la spec te lo ahorrás en correcciones.
Cómo empezar
El repositorio tiene 103 estrellas y está creciendo activamente. La instalación es directa — los slash commands se agregan a tu configuración de Claude Code y están disponibles en cualquier proyecto desde ese momento.
Lo más valioso no es solo ejecutar los comandos, sino internalizar el cambio de mentalidad que proponen: primero entender completamente el problema, después resolver.
Con agentes de código cada vez más capaces, la habilidad diferencial no va a ser saber programar — va a ser saber especificar. Los devs que aprendan a escribir specs claras van a multiplicar lo que pueden construir solos.
spec-based-claude-code está disponible en GitHub. Claude Code, los slash commands personalizados, y el ecosistema de plugins que los rodea son temas que cubrimos regularmente en yoDEV.