10 de mayo de 2026
Spec-Driven Development con OpenSpec: cómo cambió mi forma de codear
Por qué empecé a definir especificaciones antes de implementar, y cómo esto encaja con herramientas de IA en mi flujo diario.
Durante años trabajé con el flujo clásico: “leer el ticket, abrir el editor, empezar a codear”. El problema con ese flujo no es que sea lento — es que invierto tiempo en código que después tengo que tirar porque entendí mal el requerimiento, o porque el contrato de la API cambió a la mitad del sprint.
Hace unos meses empecé a probar Spec-Driven Development con OpenSpec en un proyecto serio (una plataforma para una ONG del sector salud) y la diferencia fue mayor de lo que esperaba.
La idea es simple
Antes de escribir una línea de código, escribo la especificación. No un documento gigante de Word — un archivo .md con:
- El cambio que voy a hacer (en lenguaje humano).
- El contrato afectado (qué endpoints, qué shapes de datos).
- Los criterios de aceptación.
- Las preguntas pendientes (si las hay).
Esa spec se versiona en el repo junto con el código. Cuando la implementación está terminada, la spec se actualiza para reflejar el estado final.
Por qué funciona mejor con IA
Aquí está la parte interesante. Cuando le doy a Claude Code una tarea sin contexto, el output es mediocre — porque le falta entender el “por qué”. Cuando le doy una tarea con la spec adelante, el output salta de calidad: respeta el contrato, propone edge cases que yo no había considerado, y deja el código alineado con la intención.
La spec es el lenguaje compartido entre humano e IA.
Y entre humanos: cuando un compañero entra al proyecto, no le digo “lee estos 12 PRs” — le digo “lee las 4 specs en /specs/”. En 30 minutos entiende el sistema.
Lo que aprendí
- No es para todo. Para bugs triviales o tareas exploratorias, sigue siendo overkill.
- La spec es viva. Si la implementación se desvía del contrato original, actualizo la spec primero, no después.
- El equipo necesita disciplina. Si alguien commitea código sin actualizar la spec, todo el sistema se desincroniza rápido.
¿Quieres ver mi setup? En el /lab voy a publicar pronto un template de OpenSpec con la estructura que uso.