Todas las herramientas de IA para programar te dejan escribir prompts en lenguaje natural. Muy pocas te dejan construir flujos de trabajo estructurados sobre ellas. Ese es el gap que la mayoría de desarrolladores no ven, y la razón por la que su código generado por IA necesita reescrituras constantes.
El concepto no es nuevo. El desarrollo spec-driven — definir qué quieres antes de escribir cómo — ha sido una disciplina de ingeniería de software por décadas. Lo nuevo es aplicarlo a la programación asistida por IA. Como explora Birgitta Bockeler en martinfowler.com, las herramientas de SDD están trayendo la disciplina de la ingeniería temprana — diseñar antes de codear — a la era agéntica.
La idea es simple: en lugar de escribir las mismas instrucciones cada vez (“explora mi codebase primero”, “sigue los patrones existentes”, “no escribas tests todavía”), las codificas en slash commands reutilizables. Archivos markdown. Sin SDK, sin API, sin sistema de plugins. Solo archivos que tu herramienta de IA lee como instrucciones.
Construí 6 comandos que forman un pipeline de desarrollo spec-driven. Te cuento cómo, y por qué deberías armar los tuyos.
Por Qué los Prompts Crudos Fallan a Escala
Cuando escribes “agrega autenticación JWT a mi API”, le estás pidiendo al modelo que tome docenas de decisiones implícitas:
- ¿Qué librería de JWT?
- ¿Dónde se almacenan los tokens?
- ¿Cómo se integra con tu middleware existente?
- ¿Cuál es tu patrón de manejo de errores?
El modelo va a adivinar. A veces acierta. A menudo no. Y terminas gastando más tiempo corrigiendo las suposiciones de la IA que lo que hubieras tardado escribiendo el código tú mismo.
El Pipeline
Seis comandos, cada uno un archivo markdown, formando un pipeline lineal donde cada paso produce un artefacto y cada transición requiere tu aprobación:
Comando 1: Crear. De Idea a Spec Estructurado
Le das un nombre y una descripción general. El comando genera un spec estructurado con contexto, comportamiento esperado, edge cases, restricciones, criterios de aceptación, y, crucialmente, preguntas abiertas que detectó que tú necesitas responder.
# Crear Spec
Crea un spec estructurado para: **$ARGUMENTS**
## Tu tarea
1. Genera un documento de especificación estructurado
2. Incluye: contexto, comportamiento esperado, edge cases,
restricciones, criterios de aceptación
3. Lista preguntas abiertas que necesitan decisiones humanas
**No explores el código. Solo crea el spec.**En lugar de adivinar tu preferencia de librería JWT, te pregunta.
Comando 2: Auditar. El Spec Se Encuentra con Tu Codebase
Aquí el modelo explora tu proyecto real: estructura de archivos, convenciones de nombrado, patrones de manejo de errores, dependencias existentes, y enriquece el spec con una sección de análisis técnico.
Lo que explora el audit
- Estructura del proyecto (carpetas, módulos, capas)
- Patrones de arquitectura (MVC, service layer, feature-based)
- Convenciones de nombrado de archivos y funciones
- Enfoque actual de manejo de errores
- Organización de tests y cobertura
- Dependencias en package.json / requirements.txt
- Archivos similares a lo que se quiere construir (para seguir el mismo patrón)
Este paso previene la falla #1 del código generado por IA: ignorar patrones existentes. Después del audit, el modelo conoce las convenciones de tu proyecto. El código que escriba después va a encajar.
Comando 3: Revisar. El Semáforo de Preparación
Antes de invertir tiempo en implementación, este comando evalúa el spec:
🟢 Listo: Bien definido. Todas las decisiones tomadas. Avanzar al plan.
🟡 Puede avanzar: Existe ambigüedad, pero se pueden hacer suposiciones razonables. Cada supuesto se lista explícitamente para que lo apruebes.
🔴 Bloqueante: Decisiones críticas pendientes. Ejemplos: “¿Sessions o JWT?”, “¿Qué base de datos?”, “¿Necesita real-time?” Resuelve antes de continuar.
Si algo está en rojo, lo arreglas ahora, no después de 3 fases de implementación.
Comando 4: Planear. Implementación por Fases
El plan genera una implementación paso a paso. Cada fase es pequeña (1-3 archivos), verificable (criterio claro de “está listo”) e independiente (revisable antes de continuar).
### Fase 1: Schema y migración
**Objetivo:** La tabla Users existe con campos de auth
**Archivos:** crear migración, modificar schema
**Verificar:** la migración corre sin errores
### Fase 2: Middleware de auth y utilidades
**Objetivo:** Rutas protegidas retornan 401 sin auth
**Archivos:** crear middleware, crear utils, modificar entry
**Verificar:** curl ruta libre → 200, protegida → 401Comando 5: Implementar. Una Fase a la Vez
El comando de implementación solo ejecuta una fase a la vez. Después de cada fase, resume qué hizo, qué decisiones tomó, y pide tu revisión antes de continuar.
Esta es la diferencia clave con “generar todo de un golpe”. Si la Fase 1 revela un problema, ajustas el plan antes de que arranque la Fase 2. El costo del cambio se mantiene bajo durante todo el proyecto.
Bonus: Comandos de Review
| Comando | Qué revisa | Output |
|---|---|---|
| Performance | Loops O(n²), queries N+1, memory leaks, caché, bundles | Hallazgos por severidad con fixes |
| Arquitectura | SOLID, acoplamiento, separación de concerns, seguridad | Diagrama de capas + roadmap |
Configúralo
mkdir -p .commands Pon tus archivos de comandos:
Tiempo Ahorrado en Retrabajo
(Porcentaje del tiempo de sesión arreglando código que no encajó)
La Regla de Oro
Nunca saltes pasos bajo presión. El tiempo que “ahorras” saltando el audit o el review lo pagas triple en correcciones después.
No se trata de ir más lento. Se trata de invertir 10 minutos en especificación para ahorrar 2 horas en debugging. Tu herramienta de IA se vuelve dramáticamente más útil cuando la tratas como un colaborador que necesita contexto, no como una caja mágica que adivina lo que quieres.
Los flujos estructurados le ganan a los prompts crudos. Siempre.
Lectura adicional:
- Spec-Driven Development: Designing Before You Code, Dave Patten, Medium
- Exploring SDD Tools, Martin Fowler
- Spec-Driven Development: When Architecture Becomes Executable, InfoQ
- Beyond Vibe-Coding: A Practical Guide to Spec-Driven Development, Scalable Path
- GitHub Spec Kit, Tooling open-source de GitHub para SDD
Conversación
Los comentarios viven en GitHub Discussions — inicia sesión con GitHub para responder.