Aprende a escribir especificaciones efectivas para LLMs
DominicodePor qué dejé de escribir código desde cero y empecé a hacer specs primero
Tiempo estimado de lectura: 3 min
- Menos correcciones manuales: las specs reducen el tiempo invertido en ajustar código generado por LLMs.
- Contratos ejecutables: una spec bien definida evita ambigüedades y deuda técnica.
- Escalabilidad y previsibilidad: la spec es la fuente de verdad para cambios y nuevos colaboradores.
¿Sabes qué consume más tiempo que escribir código? Corregir el código que generó la IA porque nadie le dejó claro qué hacer.
Hace un par de años disfrutaba abrir un editor en blanco. Era adrenalina pura: estructura, imports, resolver problemas “sobre la marcha”. Parecía productividad. Era ilusión.
La transición a escribir specs primero cambió eso por completo. No porque sea más elegante, sino porque es más efectivo. Aquí te cuento por qué dejé de escribir código desde cero y empecé a hacer specs primero, qué contiene una spec útil y cómo eso transforma la relación entre humanos, agentes y código.
Resumen rápido (lectores con prisa)
Spec‑Driven Development: definir specs precisas antes de implementar reduce ambigüedades, minimiza correcciones manuales y convierte la spec en la fuente de verdad. Útil cuando el producto se mantiene, la lógica es compleja o hay múltiples integradores. Implementación: especifica stack, datos, contratos de API, reglas de negocio y casos de aceptación.
Por qué dejé de escribir código desde cero y empecé a hacer specs primero
El catalizador fue simple: gastaba horas ajustando código generado por LLMs. No es culpa de la IA. Es culpa de la ambigüedad. Un modelo no conoce tus convenciones, tus límites ni las decisiones que tomaste el martes. Para un LLM, lo que no está escrito no existe.
Cuando trabajas sin spec, cada prompt es un microcontrato mal redactado. Resultado: fragmentos que funcionan aisladamente y rompen la coherencia global. El coste no es solo tiempo; es deuda técnica que aparece en sprint 3 y se siente en el cuello del repo.
Escribir specs primero no es volver a la documentación de los 90. Es escribir contratos ejecutables: lo suficiente para que un agente implemente sin inventar nada. Eso cambió mi productividad: menos correcciones, menos parches, más iteraciones reales.
¿Qué lleva una spec que funcione con IA?
No basta con una descripción bonita. Una spec útil es precisa, limitada y accionable. Esto es lo que siempre incluyo:
- Stack exacto con versiones. No “React moderno”. React 18.3, Next.js 14, etc.
- Modelo de datos. Tablas, campos, tipos y restricciones. Si usas UUID, dilo.
- Contratos de API. Endpoints, payloads de ejemplo, códigos de error y formatos.
- Reglas de negocio explícitas. Qué hacer y, más importante, qué no hacer.
- Casos de aceptación. Escenarios claros que definen el comportamiento visible.
- Límites del MVP. Qué se queda fuera en esta iteración y por qué.
El documento vive en el repo (spec.md), versionado. Si algo cambia, la spec cambia primero. No al revés.
Si quieres una guía práctica para redactar specs que funcionen con LLMs, uso y recomiendo el libro Spec‑Driven Development.
Cómo cambiaron mis sesiones con agentes
Antes: abría un chat, pedía componentes, pegaba código. Después de dos horas, el sistema era Frankenstein.
Ahora: escribo la spec, lanzo al agente en terminal con la instrucción clara—lee spec.md e implementa la Fase X—y reviso diffs. El agente crea archivos, instala dependencias y propone un conjunto coherente desde la raíz. Mi rol pasa de “peón que teclea” a “arquitecto que aprueba”.
Regla de oro
Nunca corrijo el código directamente para resolver una ambigüedad. Actualizo la spec y mando al agente a refactorizar. Si corriges el código sin tocar la spec, el día siguiente volverás a ver el mismo fallo cuando el agente regenera algo incompatible.
Beneficios reales (sin poesía)
- Menos tiempo en ajustes menudos. Más tiempo en decisiones estratégicas.
- Menos deuda técnica porque las reglas de diseño se establecen antes.
- Cambios más predecibles: si una feature cambia, la spec es la fuente de verdad.
- Escalabilidad del equipo: nuevos desarrolladores o agentes arrancan en horas, no en días.
Cuando esto no aplica
No todos los proyectos necesitan SDD. Si estás escribiendo un script de 50 líneas o prototipando algo desechable para validar una idea, un prompt rápido tiene sentido. SDD brilla cuando el producto crece, hay datos críticos o múltiples integradores.
Regla práctica: si la base de código será mantenida más de un mes o la lógica de negocio es compleja, escribe la spec.
El cambio de rol del developer
Adoptar specs no elimina el trabajo humano; lo eleva. Ahora se pide que tomes decisiones tempranas y explícitas: límites, trade-offs, casos borde. La ejecución se delega, la responsabilidad de diseño sigue siendo humana.
Ese es el valor real: profesionales que saben diseñar sistemas se vuelven más valiosos porque delegan la repetición y retienen la toma de decisiones estratégicas.
El libro Spec‑Driven Development recoge las plantillas, patrones y ejemplos que uso todos los días para que un LLM implemente sin inventos. Si estás cansado de arreglar lo que la IA rompe, empieza por escribir la spec. Es incómodo al principio, pero harás más en menos tiempo y sin excusas.
La próxima iteración de tu proyecto debería empezar con un archivo spec.md, no con un editor en blanco. Hazlo y verás que tu trabajo deja de parecer frenético: se vuelve deliberado.
Para equipos que adoptan automatización y agentes como parte del flujo de desarrollo, una práctica centralizada de especificaciones acelera la coordinación entre humanos y máquinas. Si estás explorando flujos donde agentes y workflows son críticos, mira iniciativas y recursos prácticos en Dominicode Labs para ejemplos aplicables y plantillas.
FAQ
Respuesta: Spec‑Driven Development es la práctica de definir especificaciones precisas y accionables antes de implementar. Las specs actúan como contratos ejecutables para equipos humanos y agentes.
Respuesta: Escribe una spec cuando la base de código será mantenida más de un mes, la lógica de negocio es compleja o hay múltiples integradores. Para scripts pequeños o prototipos muy tempranos, un prompt rápido puede bastar.
Respuesta: Una spec mínima incluye: stack y versiones, modelo de datos, contratos de API con ejemplos, reglas de negocio claras y casos de aceptación. También define los límites del MVP.
Respuesta: Mantén la spec en el repo, lanza al agente con instrucciones que apunten al archivo (por ejemplo, “lee spec.md e implementa la Fase X”) y revisa diffs en lugar de editar código directamente.
Respuesta: Si alguien modifica código sin actualizar la spec, la siguiente regeneración por parte del agente puede reintroducir el fallo. La regla de oro es: actualiza la spec y vuelve a ejecutar al agente.
Respuesta: Guarda las specs en el repositorio como archivos versionados (ej.: spec.md). Cualquier cambio debe pasar por control de versiones para que la spec sea la fuente de verdad.