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
•
Agarwal, S. y Vasilescu, B. SpecMine: A
Large-Scale Corpus of Spec-Driven Development Artifacts (25 de agosto de
2026). https://arxiv.org/pdf/2608.25202
•
Hill, B. Specification Artifacts in
Open-Source Pull Request Workflows Do Not Reduce Defects. ESEM
2026. https://drops.dagstuhl.de/entities/document/10.4230/LIPIcs.ESEM.2026.84
•
Piskala, D. B. Spec-Driven Development:
From Code to Contract in the Age of AI Coding Assistants.
https://arxiv.org/html/2602.00180v1
•
Spec-Driven Development for Agentic Software
Engineering: Harnessing Human-Agent Teamwork.
https://arxiv.org/pdf/2609.00252
•
SDAD: Spec-Driven Agentic Development for the
AI-Native SDLC. https://arxiv.org/pdf/2608.20341
Herramientas y guías de práctica
•
GitHub Spec Kit: templates/spec-template.md, templates/commands/specify.md y docs/quickstart.md (repositorio al 30 de octubre de 2026).
https://github.com/github/spec-kit
•
Kiro, Feature Specs y Requirements-First
Workflow (actualizada el 25 de septiembre de 2026).
https://kiro.dev/docs/specs/feature-specs/ y
https://kiro.dev/docs/specs/feature-specs/requirements-first/
•
Glukhov, R. Spec-Driven Development
Workflow: From Requirements to Code.
https://glukhov.org/app-architecture/documentation/spec-driven-development-workflow/
De mi Gazafatonario IT (luchosalazar.me)
•
Specification-Driven Development: un nuevo
orden en el desarrollo de nuevo software con IA (10 de febrero de 2026).
https://www.luchosalazar.me/2026/02/specification-driven-development-un.html
•
El poder de las historias de usuario:
sembrando narrativas para cosechar productos disruptivos (4 de agosto de 2023).
https://www.luchosalazar.me/2023/08/el-poder-de-las-historias-de-usuario.html
•
Historias de usuario: un nuevo orden en
los requisitos del software (2013).
https://www.luchosalazar.me/2013/07/historias-de-usuario-un-nuevo-orden-en.html
•
Diferencias en el tratamiento de los
requisitos entre Cascada y Ágil (2018).
https://www.luchosalazar.me/2018/02/diferencias-en-el-tratamiento-de-los.html
•
¡El tamaño sí importa! (2016).
https://www.luchosalazar.me/2016/06/el-tamano-si-importa.html
•
Historias de usuario: una visión
pragmática (libros con Jorge Abad).
https://www.luchosalazar.me/search/label/Historias%20de%20usuario%3A%20una%20visi%C3%B3n%20pragm%C3%A1tica
•
Casos de abuso, partes 1 a 12 (2012).
https://www.luchosalazar.me/2012/09/casos-de-abuso-parte-1.html
•
Diez consejos útiles y simples para
escribir casos de uso (2012).
https://www.luchosalazar.me/2012/10/diez-consejos-utiles-y-simples-para.html
•
El extraño caso del caso de uso faltante
(2012).
https://www.luchosalazar.me/2012/12/el-extrano-caso-del-caso-de-uso-faltante.html
•
Sobre «interpretación» vs. «realización»
de casos de uso (2012).
https://www.luchosalazar.me/2012/04/sobre-interpretacion-vs-realizacion-de.html
•
¿Es usted la persona correcta para
responder mis preguntas? (2013).
https://www.luchosalazar.me/2013/04/es-usted-la-persona-correcta-para.html
•
Lecturas fundamentales 4 y 5, la Ley de la
Terminación de un Caso de Uso (2006).
https://www.luchosalazar.me/2006/12/lecturas-fundamentales-4-1-de-2.html
Artículos propios recientes
•
Medio millón de specs y ningún dueño: lo
que 2026 le hizo al Spec-Driven Development. https://www.luchosalazar.me/2026/11/medio-millon-de-specs-y-ningun-dueno-lo.html
•
El espejismo del control: cuando lo
determinista se topa de frente con lo probabilístico (agosto de 2026). https://www.luchosalazar.me/2026/08/el-espejismo-del-control-cuando-lo.html




