Cómo mejorar la calidad del código con Spec-Driven Development

Spec-Driven Development en la práctica: del prompt al código mantenible — Un walkthrough real mostrando cómo una buena spec cambia la calidad del output de Claude Code o Cursor. Caso antes/después

Tiempo estimado de lectura: 6 min

• Ideas clave:
• Una spec técnica reduce la ambigüedad en prompts y convierte salidas generativas en contratos verificables.
• Sin spec, los LLMs tienden a producir código rápido pero frágil y con deuda técnica.
• Una spec mínima (stack, artefactos, contratos, edge cases) es suficiente para outputs reproducibles y testeables.
• Integra specs en CI/PR para automatizar comprobaciones y mantener control humano sobre arquitectura.

Resumen rápido (lectores con prisa)

Qué es: Una spec técnica es un documento corto que define stack, artefactos, contratos de datos y criterios de aceptación.

Cuándo usarla: Antes de pedirle a un LLM que genere código o acciones automáticas; imprescindible para features que afectan arquitectura o seguridad.

Por qué importa: Reduce ambigüedad, limita el espacio de decisión del modelo y convierte output en un contrato auditables y testeable.

Cómo funciona: Provee stack y contratos (ej. Zod schemas, tipos TS, API contracts) que el agente implementa exactamente, produciendo artefactos modulares y testeables.

Por qué una spec cambia todo

Los LLMs son excelentes en patrones, no en contexto de producto. Cuando reciben un prompt abierto, generan la solución más probable según su entrenamiento: ejemplos de tutoriales y antipatrón comunes. Esa es la razón por la que el output suele ser rápido pero frágil.

Una especificación técnica (spec) reduce el “espacio de probabilidad” del modelo. Le das:

• el stack exacto,
• las restricciones arquitectónicas,
• los contratos de datos,
• y los criterios de aceptación/edge cases.

Con esa entrada, herramientas como Cursor o Claude dejan de improvisar y comienzan a implementar un contrato.

Walkthrough real: formulario de registro en Next.js

Escenario: crear un registro de usuario con validación Zod y Server Actions (Next.js App Router). Te muestro el antes y el después, sin adornos.

Antes — Prompt conversacional (vibe coding)

Prompt enviado al modelo:

“Crea un formulario de registro en Next.js con email, password y confirmación. Conéctalo a la API.”

Salida típica:

• Un solo archivo RegisterForm.tsx con JSX, estado useState y fetch mezclados.
• Validación DIY con regex.
• Manejo de errores = console.log.
• Tipos débiles (any o sin tipos).
• No hay tests ni contractos reutilizables.

Resultado: funciona en local. Falla en producción. Es deuda técnica con firma.

Después — Prompt con spec (Spec-Driven Development)

Antes de preguntar al modelo, escribes spec-auth-register.md y lo adjuntas.

Fragmento de spec:

# Spec: Registro de usuario
Stack: Next.js App Router, React Hook Form, Zod
Outputs: 3 archivos
  - src/lib/validations/auth.ts (registerSchema)
  - src/actions/auth.actions.ts (Server Action) -> devuelve { success: boolean; error?: string }
  - src/components/auth/RegisterForm.tsx
UI: usar useTransition para isPending; mostrar errores por campo; redirigir a /dashboard en éxito.
Edge cases: handling de timeouts, duplicados, validación server-side.

Prompt al modelo:

“Lee @spec-auth-register.md e implementa exactamente los archivos descritos, respetando tipos y contratos.”

Salida típica con spec:

• registerSchema en auth.ts (Zod) reutilizable en cliente y servidor.
• Server Action tipada que devuelve { success, error }.
• Componente de presentación que usa React Hook Form y solo hace binding.
• Estados de UI y manejo de errores explícito.
• Código modular, testeable y legible.

La diferencia es clara: la spec obliga al modelo a ceñirse a un contrato verificable. Lo que se genera se puede code-reviewar, testear e integrar.

Plantilla mínima de spec que funciona

No necesitas escribir una novela. Esta plantilla (portable en .specs/feature.md) es suficiente:

1. Contexto de negocio (1-2 líneas).
2. Stack y restricciones (libraries permitidas/prohibidas).
3. Artefactos esperados (files + path).
4. Contratos de datos (TS interfaces o Zod schemas).
5. Estados UI y criterios de aceptación.
6. Edge cases y métricas de éxito.

Incluye URLs útiles en la spec para librerías: Zod, OWASP para seguridad, documentación de Cursor si lo usas.

Integración práctica en el flujo de trabajo

• Guarda specs en .specs/ y referencia el archivo en el prompt (Cursor soporta @Files).
• Automatiza comprobaciones básicas con linters/CI: que exista un schema Zod, que acciones devuelvan un tipo estándar, que tests unitarios pasen.
• Añade una regla en code review: si el cambio viene de un agente, el PR debe acompañar la spec original y un ADR si la modificación afecta arquitectura.
• No olvides observabilidad y testing: cada tool o action generada debe tener tests unitarios independientes del LLM.

Conclusión: la IA ejecuta, el ingeniero decide

Spec-Driven Development no elimina la IA; la pone en su lugar. En lugar de confiar en la creatividad del modelo, confías en el criterio técnico del equipo para dirigirlo. Los equipos que adoptan specs claras convierten a Claude Code y Cursor en herramientas productivas en lugar de fuentes de deuda técnica. Implementar specs no es una carga extra: es la inversión que transforma prototipos de IA en software mantenible y auditable.

La siguiente pieza en esta serie mostrará ejemplos de specs reales y scripts de CI que validan la conformidad automática entre spec y código.

Para continuidad con iniciativas de automatización y prácticas de ingeniería aplicadas a IA, revisa recursos adicionales y experimentos en Dominicode Labs. Estos materiales complementan la adopción de specs y proporcionan plantillas y scripts para integrar comprobaciones automatizadas en CI/PR.

FAQ

• ¿Qué es una spec técnica y cuánto debe medir?
• ¿Qué diferencia hay entre una spec y una historia de usuario?
• ¿Qué herramientas debo pedir en la spec para validación de datos?
• ¿Cómo integro specs en CI?
• ¿Qué hacer si el LLM ignora la spec?