Especificación antes que código: un documento vivo con límites de tres niveles

Por qué escribir una especificación antes de construir: objetivo, comandos, estructura, pruebas, límites de tres niveles y un flujo por fases con un control en cada una.

Metodologíametodologiaspecificherequisitiingegneria del software19 de noviembre de 2026 · 3 min de lectura

«Es obvio lo que hay que construir» es la frase que precede a muchas revisiones al final del proyecto. Escribir una especificación antes de empezar no es burocracia: es el momento en que descubres que dos personas, convencidas de haber entendido, habían entendido cosas distintas.

Un flujo por fases con un punto de control cada una

Fase 1, especificar. Se escribe qué se construye y por qué. Fase 2, planificar. Se decide cómo, con qué elecciones arquitectónicas. Fase 3, descomponer. Se divide el trabajo en tareas verificables. Fase 4, realizar. Se construye una tarea cada vez. No se pasa a la fase siguiente hasta que la anterior haya sido revisada por quien decide.

Qué contiene una especificación

Seis elementos, en pocas páginas:

  1. Objetivo. Qué se construye y por qué, para quién y qué significa que ha salido bien.
  2. Comandos. Los comandos completos con opciones para construir, probar, arrancar: no solo los nombres de las herramientas.
  3. Estructura del proyecto. Dónde vive el código, dónde las pruebas, dónde la documentación.
  4. Estilo del código. Un ejemplo real vale más que tres párrafos de descripción: nombres, formato, convenciones.
  5. Estrategia de pruebas. Qué framework, dónde están las pruebas, qué cobertura se espera, qué niveles de prueba para qué riesgos.
  6. Límites de tres niveles. Qué se hace siempre, qué se pregunta antes, qué no se hace nunca.

Se añaden los criterios de éxito (condiciones verificables) y las preguntas abiertas, hasta que alguien las cierre.

Los límites de tres niveles

Son la parte que más a menudo falta y que más a menudo salva. «Siempre» son las acciones seguras que se hacen sin preguntar (ejecutar las pruebas antes de entregar). «Pregunta antes» son las que tienen consecuencias (modificar el esquema de datos, añadir una dependencia). «Nunca» son las prohibidas (escribir secretos en el repositorio, tocar producción). Un colaborador, humano o agente, sabe así por dónde puede moverse solo.

Una especificación viva

La especificación no se escribe una vez y se archiva. Cuando una decisión cambia, se actualiza el documento; cuando el código diverge, se decide cuál de los dos tiene razón. Una especificación parada en el primer día se convierte en otra fuente de errores.

Las excusas más comunes

ExcusaRealidad
«Es un cambio pequeño»Los cambios pequeños con requisitos ambiguos son los que vuelven. Basta una especificación corta.
«Es obvio lo que hace falta»Si es obvio, escribirlo cuesta diez minutos. Si no lo es, acabas de encontrar el problema.
«Empiezo y ya veré»Vale para explorar, no para entregar: el código de exploración se tira.

Señales de alarma

  • Se escribe código sin ningún requisito escrito.
  • Se pregunta «¿puedo empezar?» antes de aclarar qué significa «terminado».
  • Se realizan funcionalidades que no aparecen en ninguna especificación ni lista de tareas.
  • Decisiones arquitectónicas tomadas y no documentadas.
  • Especificación omitida porque «es obvio».

Un ejemplo

Una petición: «añade la exportación de informes». Una especificación de media página pregunta: en qué formato, para quién, con qué datos, en cuánto tiempo debe llegar el archivo, quién puede exportar. Dos líneas sobre los límites: siempre filtrar por los permisos del usuario, preguntar antes de incluir datos personales, no exportar nunca el archivo completo. Las respuestas cambian la solución antes de que exista una línea de código.

Cuándo usarla

Al inicio de un proyecto, de una funcionalidad o de un cambio significativo cuando no existe especificación, los requisitos son ambiguos o existen solo como idea.

Este método deriva de la familia de skills de código abierto agent-skills de Addy Osmani (licencia MIT), reescrita y adaptada.

Este artículo es una skill de OIAR

Lo que acabas de leer es el contenido de una skill del catálogo de OIAR, escrito para las personas. Un conocimiento como este pero más rico y profundo, escrito para los agentes, guía las entrevistas, el análisis y el informe dentro de la plataforma. Las skills se usan en OIAR: para probarla en un proyecto tuyo necesitas una cuenta.

spec-driven-developmentMétodo para escribir una especificación breve y viva antes de construir: objetivo, comandos, estructura, estilo, estrategia de pruebas, límites de tres niveles (siempre, pregunta antes, nunca), criterios de éxito, preguntas abiertas; flujo por fases: especificar, planificar, descomponer, realizar. Úsese al inicio de un proyecto o de una funcionalidad sin especificación, o con requisitos ambiguos.