Lo que no les conté cuando les hablé del «Medio millón de specs» que SpecMine recopiló en más de 70 mil repositorios es lo que dice el resumen del mismo trabajo: la spec la escribe el desarrollador o, con más frecuencia, la redacta una herramienta de IA y el desarrollador la «cura».

Curar. Según mi Gazafatonario, palabra de médico, de museo, de párroco de pueblo que absuelve sin haber oído la confesión. Cuarenta años en este oficio me han enseñado a desconfiar de los verbos que suenan bien y no dicen quién hizo qué. En el experimento que hice con el Sintonizador de Tono, el agente tomó doce decisiones que yo no había tomado y solo dos tomaron el tinte de preguntas. Si eso es curar, el paciente se cura solo.

También les dije en mi artículo anterior que la anatomía de una spec la podían encontrar muy fácil en la Web o preguntándole a cualquiera de los chatbots que circulan por allí. Pero pudieron más mis ganas de escribir sobre el asunto. De publicar realmente, porque ya lo había escrito desde el mismo febrero, solo que actualicé el artículo con algunas otras cositas que aprendí desde entonces. Además recordé la recomendación que siempre doy a escritores noveles: si es tu visión, si es tu experiencia, siempre hay algo que aprender de allí.

Las specs pueden contener historias de usuario o casos de uso. No se alarmen, en realidad eso no tiene nada de especial, siempre ha sido así. Son formas apenas. Lo importante sigue siendo la conversación entre humanos. Llegaré a eso en un momento, entremos en materia.

Mi primera recomendación es que abran el spec-template.md de Spec Kit (el del repositorio, al 30 de octubre, última fecha en que lo revisé) y miren lo que le piden al agente: escenarios de usuario con prioridad, cada uno comprobable por separado y escrito en Gherkin (GIVEN/WHEN/THEN – Dado/Cuando/Entonces); requisitos numerados (FR-001) con su «MUST»; criterios de éxito medibles; y una sección de supuestos, que la plantilla describe como valores predeterminados escogidos cuando la descripción no decía algo. Está bien configurada.

Sin embargo, lo que no van a encontrar es una sección para lo que no se va a hacer (aparece una sola vez, como ejemplo dentro de los supuestos) y mucho menos una para indicar quién decidió qué. Y aquí viene mi primera recomendación propia: puedes modificar la plantilla a tu antojo, aunque no te emociones mucho con ello, no vaya a ser que termines creando un monstruo de esos que ni la misma IA sea capaz de manejar. Escribe esas «no-metas» y las preguntas abiertas al final y acompáñalas de reglas muy simples y directas. Por ejemplo, Kiro escribe historias de usuario con criterios de aceptación y comportamientos en notación EARS (CUANDO «ocurra esto», EL SISTEMA DEBERÁ «hacer esto otro»), y no genera el diseño hasta que uno confirma los requisitos.

Es que esto no es nada novedoso. He escrito sobre ello desde hace más de dos décadas. En el Gazafatonario escribí que un requisito tiene que ser verificable, atómico y no ambiguo, y dediqué unos diez consejos a las palabras que, en su momento, había que sacar de un caso de uso (que después se podían aplicar a las historias de usuario y hoy, por supuesto, a las Specs): «automáticamente», «procesar», «administrar», «gestionar». Las sigo viendo en muchas especificaciones de las que ya se ha producido software en 2026, con IA o sin IA y siempre me pregunto qué interpretó el programador, sea humano o máquina.

La Spec de mi Sintonizador de tono podría tener una línea como esta:

El sistema debe procesar automáticamente el mensaje y entregar las versiones con el tono adecuado.

Dos de mis cuatro palabras vetadas. Así la escribiría hoy:

Cuando el usuario pulse «Sintonizar» con un mensaje de hasta 1.000 caracteres, el sistema muestra tres versiones: Directa, Empática y Mínima. La Mínima no pasa de quince palabras.

Es apenas un ejemplo, las quince palabras se cuentan; no obstante, el atributo «Empática» no es verificable, al menos no de manera automática. Aun así, un criterio verificable puede requerir personas: tres lectores reciben las versiones sin etiqueta y señalan cuál es la Empática. Si aciertan en ocho de diez, pasa (otra vez, ese umbral es un ejemplo). Falla de verdad y no obliga a convertir «cálido» en una lista de palabras.

Las historias de usuario ya estaban ahí

Los «escenarios de usuario» de Spec Kit, las historias de Kiro o los «requisitos» de OpenSpec son historias de usuario con otro disfraz, y de eso he escrito en cantidades industriales. Con mi gran amigo Jorge Abad les dedicamos dos tomos, Historias de usuario: una visión pragmática. Vistas con ojos de SDD, me dejan cuatro ideas.

La primera, las siempre muy comentadas aunque pocas veces entendidas «tres C». Les contaba desde entonces que una historia tiene Carta, Conversación y Confirmación. El spec.md es la carta y los criterios de aceptación son la confirmación. ¿Y la conversación? Spec Kit le deja al agente tres preguntas. Hemos insistido en esto hasta el cansancio: lo más importante de una historia son las conversaciones a su alrededor, y que tenemos que pasar de un mindset «especificacional» a uno conversacional. Una spec generada por un agente es lo especificacional llevado al extremo: un documento completísimo del que casi nadie conversó.

La segunda, la hipótesis. Una historia es una hipótesis mientras el producto no esté en manos del usuario, y escribí sobre pasar de «requisito» a «necesidad o hipótesis». La spec también lo es. Sus criterios de éxito son la manera de saber si acertamos, y ahí vuelve la frase que ya conocen: reflexionar con datos, no con supuestos.

La tercera, objetivo y solución. Una buena historia dice qué quiere lograr la persona («elegir un método de envío») y le deja la solución al equipo; una mala historia dicta el botón. En mi Sintonizador hay de las dos: «eliminar la ansiedad en la comunicación digital» es objetivo, y «Azul Cobalto» es solución. Lo que escribo como solución lo decido yo. Lo que dejo abierto lo decide el agente, y me toca revisar el plan.

La cuarta, el tamaño. Escribí que ¡El tamaño sí importa!: una historia pequeña, de una décima a una sexta parte de la velocidad del equipo, se entiende rápido y se termina. Para una spec uso una regla igual de rudimentaria, aunque efectiva: si no se revisa en diez minutos, es grande, y se divide por capacidad.

Ahora bien, Spec Kit le ordena al agente que, ante lo que falta, «adivine» con criterio y lo anote como supuesto. Si tiene más de tres dudas, se queda con las tres más críticas y adivina el resto. Está escrito así en sus instrucciones.

En mi miniserie de 2012 sobre los casos de abuso (no, no de esos, me refiero a los malos usos de las especificaciones escritas con casos de uso, quizás un mal juego de palabras, pero que en esa época me sonó distintivo) hay un capítulo para decir que el analista no es psíquico. Y un año después añadí que los supuestos pasivos degradan la calidad de la especificación y que había que cambiarlos por hechos, preguntándole a más de una persona. La plantilla vuelve al agente el analista psíquico del que yo advertía. Con la velocidad que se gana, adivinar y dejarlo anotado es razonable. El problema aparece cuando nadie lee lo anotado, y sigo sin encontrar un dato que me diga cuántos lo leen. Mi hipótesis es que ese número tiende a cero.

Espero que a estas alturas se estén haciendo las mismas preguntas que yo. ¿La Spec se revisa? ¿Se modifica? Mi respuesta y mi recomendación es que sí, con tres miradas distintas, porque cada una ve lo que las otras no.

La primera es la mecánica, y se delega: contradicciones, ambigüedades, criterios sin forma de probarse. Spec Kit trae compuertas para eso (clarify, checklist y analyze en su ruta completa). Mi contradicción entre «Mínima (estilo Gen-Z)» y «Minimalista» cae aquí. A lo largo de este entramado, en general, he usado a Spec Kit como modelo, pero esto sucede con Kiro o con OpenSpec, o con cualquier otra de las herramientas que tenemos para jugar a SDD. Incluso con las propias.

La segunda es la de las decisiones, y es humana. Se lee lo que el agente asumió, lo que preguntó y cada «debe» que uno no recuerda haber pedido, y a cada decisión se le pone dueño y fecha. Si el agente supuso «límite de 2.700 caracteres» y me parece bien, lo cambio por una decisión mía, con mi nombre y mi razón.

La tercera es la de lo ausente, también humana, y va con lista: datos personales, costo, qué pasa cuando algo falla, límites, retención. En mi experimento con el sintonizador de tono, seis de las doce decisiones no aparecieron en ninguna sección, y leer lo escrito nunca las encuentra. Esto ya me había pasado preIA. El extraño caso del caso de uso faltante. Es un juego de palabras, apenas para mi Gazafatonario.

Y modificarla: la misma spec retocada a mano por mí me ha devuelto resultados distintos, así que toco decisiones y no el estilo. Cambio el supuesto, no reescribo el párrafo. En un prototipo me quedo con la primera mirada; con una factura electrónica o un dato de salud, las tres, y con una persona que firma.

Finalmente, la Spec

Para ver todo junto, les dejo aquí la spec del botón «Copiar» del Sintonizador de tono:

# Spec: copiar una versión del mensaje

## Historia
Como persona que acaba de sintonizar un mensaje, quiero copiar la
versión que me gustó con un clic, para pegarla en WhatsApp o en el
correo sin seleccionar texto a mano.

## Decisiones aprobadas
– [Producto, 20261108] Copiar entrega solo el texto de esa versión,
  sin título ni formato.
– [Producto, 20261108] Una versión por clic. No hay «copiar todas».

## Comportamiento
R1. CUANDO la persona pulse «Copiar» en una tarjeta, EL SISTEMA
    DEBERÁ dejar en el portapapeles el texto de esa tarjeta y
    cambiar el botón a «Copiado» durante dos segundos.
R2. CUANDO el navegador no permita usar el portapapeles, EL SISTEMA
    DEBERÁ seleccionar el texto y mostrar «Presiona Ctrl+C».

## Restricciones
– No enviar ni guardar el mensaje en ningún servidor al copiar.
– No agregar dependencias nuevas.
– No tocar el panel de entrada ni el prompt de sistema.

## Fuera de alcance
– Compartir directo a WhatsApp o al correo.
– Historial de lo copiado.

## Criterios de aceptación
– [ ] R1: pegar en un editor entrega exactamente el texto de la
      tarjeta (automática).
– [ ] R1: a los dos segundos el botón vuelve a decir «Copiar»
      (automática).
– [ ] R2: con el permiso denegado aparece el mensaje de respaldo
      (automática).
– [ ] Tres personas que no conocen la app copian una versión sin
      ayuda en menos de diez segundos (humana).

## Supuestos del agente (por revisar)
– Los saltos de línea se conservan.

## Preguntas abiertas
– [ ] ¿Contamos cuántas veces se copia cada versión, sin guardar
      el texto? Decide: Producto.

Cada pieza evita algo concreto. La historia proporciona el porqué y abre la conversación. Las decisiones tienen dueño. Las restricciones impiden que el agente «mejore» lo que nadie pidió, como guardar el mensaje en un servidor. Cada criterio nombra su prueba, y uno la hace una persona. La pregunta abierta es la hipótesis: si la gente copia más una versión que otra, algo nos dice sobre el tono, pero antes hay que decidir qué se mide y qué no se guarda.

Ahora bien, hace 20 años publiqué una lista de trece condiciones para decir que un caso de uso estaba terminado, y bastaba con cumplir diez. Para una spec mi lista corta es esta:

  1. Cada requisito tiene una manera de fallar.
  2. Cada decisión tiene dueño y fecha.
  3. Lo que no se va a hacer está escrito.
  4. Las preguntas abiertas siguen abiertas, y el agente no las cerró por su cuenta.
  5. Dos lectores distintos entienden lo mismo.

Si le faltan dos, no está terminada. La quinta es de mi cosecha de 2012: la especificación tiene que producir la misma interpretación en el diseño y en las pruebas.

No ha sido gratuito esto de mencionarles muchas de mis publicaciones anteriores. Créanme, no es un simple «yo ya lo había dicho». Lo que hice aquí (o al menos traté de hacer) fue reunir y resumir, en dos mil palabras lo que he escrito en cientos de miles a lo largo de más de 30 años. Las cosas no han cambiado en materia de especificación de requisitos de software, después de todo.

2026, 2027 y lo que viene después

Me gustan los tres niveles de Spec que Piskala identifica: spec-first (sirve para arrancar y luego se bota), spec-anchored (vive y evoluciona con el código) y spec-as-source. Cuánto hay que saber de la spec depende del nivel en el que uno juegue. Para el segundo hay que saber leer una spec como la leería un analista, aunque nunca se escriba desde cero. Pero eso fue para este 2026: saber ver lo que falta. Aquí no era mejor pájaro en mano que un ciento volando. Léanlo así: una spec que existe y no gobierna nada es peor que no tener spec, porque da falsa confianza.

Las cosas cambian muy rápidamente, así que para 2027 apuesto, y subrayo que es apuesta y no dato, a que lo que se pueda volver prueba será prueba: las quince palabras, los esquemas de las interfaces. La spec que quede para humanos será más corta: historia, decisiones con dueño, lo que no se hará. Más corta, pero también más importante.

Lo bueno de estas apuestas es que se pueden ganar si te lo propones. Si nadie está trabajando en ello, qué esperas para empezar a hacerlo.

Lucho Salazar

Envigado, 10 de noviembre de 2026.

Referencias

Algunos estudios y papers

Herramientas y guías de práctica

De mi Gazafatonario IT (luchosalazar.me)

Artículos propios recientes

Deja una respuesta