Saber cómo redactar requisitos de calidad supone la diferencia ente crear documentos que ayudan a construir bien un producto y crear documentos que solo generan conversaciones interminables, interpretaciones distintas y trabajo rehecho.
La diferencia muchas veces no está en la buena voluntad del equipo ni en la cantidad de páginas. Está en algo bastante más básico: si el documento distingue con claridad qué está definiendo, qué está especificando y qué está restringiendo.
En software esto aparece constantemente. Ocurre en requisitos, en propuestas de producto, en documentación funcional, en decisiones de arquitectura e incluso en instrucciones para agentes de IA. Mezclamos conceptos de dominio con comportamiento esperado, reglas de negocio con decisiones de implementación, restricciones legales con simples aclaraciones terminológicas. Y cuando todo va junto, el texto deja de ser una guía fiable y se convierte en un bloque ambiguo donde cada lector entiende una cosa distinta.
La ingeniería de requisitos lleva décadas intentando resolver justo este problema. Aunque no exista una “ley universal” formulada exactamente como “definición, especificación y restricción”, sí existe una base muy sólida en autores y estándares que convergen en esa idea. Zave y Jackson separan requisitos, especificación y conocimiento del dominio como partes diferentes del problema. El estándar ISO/IEC/IEEE 29148 insiste en la claridad, la no ambigüedad, la verificabilidad y la separación entre tipos de enunciados. Karl Wiegers, desde un enfoque muy práctico, lleva años explicando que un documento útil no debe mezclar en una sola frase requisitos funcionales, reglas, restricciones y atributos de calidad.
La idea de fondo es simple y poderosa: no todo lo que escribimos cumple la misma función. Y cuando no distinguimos esas funciones, el coste acaba apareciendo más tarde en forma de errores, discusiones o implementaciones equivocadas.
El problema real: escribir como si todo fuera lo mismo
Uno de los errores más habituales en documentación técnica y funcional es tratar cada frase como si fuera un requisito. No importa si estamos definiendo un concepto, pidiendo una capacidad, imponiendo un límite regulatorio o describiendo una decisión ya tomada: todo se redacta igual, en el mismo tono normativo y dentro del mismo bloque.
Eso rompe algo esencial: la capacidad de leer un documento y entender de inmediato qué tipo de información contiene cada enunciado.
No es lo mismo decir:
Un cliente premium es un cliente con suscripción activa y método de pago válido.
que decir:
El sistema deberá permitir renovar la suscripción de un cliente premium.
o decir:
La renovación deberá cumplir PSD2 y registrarse con trazabilidad auditable.
Las tres frases pueden aparecer en el mismo proyecto. Las tres son importantes. Pero no hacen el mismo trabajo.
La primera define.
La segunda especifica.
La tercera restringe.
Cuando un documento no separa estas capas, lo que debería ser claro empieza a difuminarse. Entonces aparecen preguntas que no deberían existir: si eso era una simple definición o una obligación real, si aquella limitación era legal o técnica, si una frase describe el comportamiento esperado o una decisión de solución ya cerrada. A partir de ahí, el documento deja de ordenar el trabajo y empieza a desordenarlo.
Qué significa definir
Definir es fijar el significado de las cosas. Es delimitar el lenguaje con el que vamos a pensar y hablar sobre el problema.
Esto parece menor, pero no lo es. En muchos proyectos, una parte enorme de los malentendidos nace porque dos personas usan la misma palabra para referirse a cosas distintas, o usan palabras distintas para referirse a la misma cosa. Ahí es donde entran las definiciones: glosarios, modelos de dominio, catálogos de conceptos, términos normativos, estados del negocio.
Cuando definimos, no estamos exigiendo comportamiento. No estamos diciendo lo que el sistema debe hacer. Estamos aclarando el terreno semántico sobre el que luego construiremos especificaciones y restricciones.
Por ejemplo:
“Pedido confirmado” es aquel cuyo pago ha sido autorizado y cuya dirección de entrega ha sido validada.
Esta frase no pide nada al sistema. No describe una funcionalidad. No impone una limitación. Lo que hace es dar un significado preciso a un término clave del dominio.
Y eso tiene mucho valor. Porque si esa definición no existe, luego cada uno interpretará “pedido confirmado” a su manera: para unos será cuando el usuario pulse un botón, para otros cuando se cobre, para otros cuando se valide stock, y para otros cuando salga del almacén. El sistema puede acabar implementado correctamente según una de esas interpretaciones y, aun así, estar mal respecto a la necesidad real.
Definir bien no es rellenar un glosario por formalismo. Es reducir ambigüedad antes de que se convierta en coste. Esto puede parecer algo trivial, pero hay dominios donde se convierte en algo que a la postre es crucial para definir alcance, hacer el modelo técnico, etc.
Stakeholders y lenguaje de dominio: por qué definir bien los conceptos
Conviene recordar que, en la mayoría de los proyectos, el equipo técnico no parte de un vacío, sino de necesidades que vienen expresadas desde el negocio. El problema es que negocio y técnica no siempre hablan el mismo idioma.
Los perfiles de negocio conocen su realidad, su operativa y sus reglas. Hablan desde ahí. Y eso significa que utilizan términos, matices y asociaciones que para ellos son evidentes, pero que no siempre lo son para quienes deben traducir esa necesidad a requisitos, modelos y soluciones implementables. A veces, incluso, distintas personas usan palabras diferentes para referirse al mismo concepto, o la misma palabra con matices distintos según el contexto. Si no se detecta pronto, esa ambigüedad se filtra en el documento y acaba contaminando todo lo demás.
Por eso la definición importa tanto. Antes de discutir qué debe hacer un sistema, conviene fijar con precisión qué significa cada concepto importante del dominio. Sin esa base, la especificación nace inestable.
Esto se aprecia especialmente bien en dominios complejos como finanzas, banca o contabilidad, donde pequeñas variaciones terminológicas pueden arrastrar diferencias de interpretación nada pequeñas. Y cuando el lenguaje no se aclara a tiempo, el problema deja de ser terminológico para convertirse en un problema de alcance, diseño e implementación.
Qué significa especificar
Especificar es describir qué debe hacer la solución.
Aquí ya entramos en el terreno del comportamiento esperado. La especificación traduce necesidades, objetivos o reglas del negocio en capacidades, respuestas, procesos o interacciones que el sistema debe ofrecer. Ya no estamos nombrando el problema, sino indicando cómo debe comportarse la solución para contribuir a resolverlo.
Siguiendo el ejemplo anterior:
El sistema deberá permitir confirmar un pedido cuando el pago esté autorizado y la dirección haya sido validada.
Aquí sí hay una exigencia verificable. Ya podemos discutir implementación, pruebas, trazabilidad y aceptación.
La especificación tiene una función muy concreta: hacer explícito el comportamiento esperado de forma que pueda construirse y validarse.
Por eso importa tanto su calidad. Una especificación vaga, ambigua o mezclada con otras capas acaba siendo muy difícil de implementar bien. Si además incluye decisiones de diseño innecesarias, restricciones escondidas o definiciones camufladas, el resultado se complica todavía más.
La ingeniería de requisitos ha insistido durante años en que una buena especificación debe ser clara, consistente, verificable y trazable. No porque suene bien en un estándar, sino porque esas propiedades son las que permiten que varias personas construyan una misma solución sin estar interpretando cada una una película distinta.
Qué significa restringir
Restringir es establecer límites.
Una restricción no suele introducir una funcionalidad nueva. Lo que hace es acotar el espacio de soluciones válidas. Puede venir de normativa, seguridad, rendimiento, tecnología heredada, contexto organizativo, plazos, presupuesto o decisiones externas ya fijadas.
Por ejemplo:
La confirmación del pedido deberá cumplir la normativa fiscal vigente y registrarse con trazabilidad auditable.
Esto no describe una nueva capacidad de negocio. Lo que hace es imponer condiciones obligatorias sobre la solución.
Las restricciones son fundamentales porque en el trabajo real nunca diseñamos en vacío. Siempre hay límites. El error está en esconderlos o mezclarlos como si fueran otra cosa.
Cuando una restricción está bien expresada, el equipo entiende desde el principio dentro de qué marco tiene que operar. Cuando no lo está, aparecen soluciones aparentemente correctas que más tarde se descartan porque incumplen una condición legal, técnica o corporativa que nadie había dejado clara en el documento.
Por qué esta separación cambia la calidad del trabajo
La razón más inmediata es la claridad. Si cada enunciado tiene una función reconocible, el documento se vuelve más fácil de leer, revisar, discutir y transformar en trabajo real.
La segunda razón es la trazabilidad. Cuando separas definición, especificación y restricción, puedes seguir mejor el origen de cada cosa. Sabes qué parte pertenece al dominio, cuál expresa comportamiento esperado y cuál viene impuesta por un límite externo. Eso facilita el análisis, la validación y también la gestión del cambio.
La tercera razón es la verificabilidad. No se valida igual una definición que una especificación. No se prueba igual una funcionalidad que una restricción regulatoria. Si lo mezclas todo, luego también mezclas cómo se revisa, cómo se implementa y cómo se acepta.
La cuarta razón es más práctica todavía: evitas discusiones inútiles. Muchas reuniones se alargan porque en realidad se está debatiendo sobre capas distintas sin que nadie lo haya explicitado. Unos hablan del significado de un concepto, otros del comportamiento que esperan del sistema y otros de una limitación externa. Todos usan las mismas palabras, pero no están hablando de lo mismo.
Separar estas piezas no resuelve por sí solo todos los problemas, pero sí elimina una parte muy importante del ruido.
El error más frecuente: meter decisiones de diseño dentro del requisito
Un documento empieza a estropearse de verdad cuando convierte decisiones de implementación en supuestos requisitos.
Pasa algo así:
El sistema deberá usar microservicios, Kafka, PostgreSQL y OAuth para permitir al cliente consultar su saldo.
Aquí se han mezclado varias capas de golpe. La necesidad real probablemente sea que el cliente pueda consultar su saldo. El resto puede ser una restricción tecnológica, una decisión arquitectónica o una condición heredada del entorno, pero no forma parte del núcleo funcional de la necesidad.
Una composición más limpia sería esta:
Definición
“Saldo disponible” es el importe que el cliente puede utilizar en el momento de la consulta.
Especificación
El sistema deberá permitir al cliente consultar su saldo disponible.
Restricción
La consulta deberá responder en menos de 2 segundos y cumplir las políticas corporativas de seguridad y auditoría.
Si además el proyecto obliga de verdad a usar una determinada infraestructura o un stack concreto, eso debe quedar expresado como contexto o restricción de solución, no incrustado dentro del requisito funcional como si fuera lo mismo.
Esto no significa que debamos redactar todos los documentos como una plantilla mecánica, separando siempre cada párrafo en bloques de definición, especificación y restricción. En muchos casos, especialmente en artículos, propuestas o documentos más narrativos, esa rigidez no es necesaria. Lo importante es otra cosa: aunque el texto fluya de forma natural, debe seguir dejando claro qué se está definiendo, qué se está pidiendo a la solución y qué límites condicionan esa solución. La forma puede ser narrativa; la disciplina de fondo no debería perderse. Lo anterior podríamos redactarlo como:
Cuando el cliente consulte su saldo disponible, entendido como el importe que realmente puede utilizar en ese momento, el sistema deberá mostrárselo de forma clara, respondiendo en menos de dos segundos y respetando las políticas corporativas de seguridad y auditoría.
Esta diferencia parece sutil, pero no lo es. Mezclar niveles provoca que los documentos envejezcan mal, sean más difíciles de discutir y conviertan cualquier cambio técnico en una aparente renegociación del requisito de negocio.
Lo que la ingeniería de requisitos lleva años enseñando
Aquí no estamos inventando una moda documental. La base teórica y práctica existe desde hace tiempo.
Zave y Jackson dejaron muy claro que el problema del software no se entiende bien si describimos demasiado pronto la máquina y mezclamos lo que queremos conseguir con lo que sabemos del dominio y con lo que la solución debe hacer. Su separación entre requisitos, especificación y conocimiento del mundo sigue siendo tremendamente útil porque obliga a pensar mejor antes de escribir.
Por su parte, ISO/IEC/IEEE 29148 insiste en que un requisito de calidad debe ser no ambiguo, singular, consistente, verificable y trazable. También deja clara una idea muy relevante: las definiciones deben tratarse como declaraciones declarativas, no como requisitos. Esto es importante porque evita que conceptos de dominio se redacten como si fueran obligaciones del sistema.
Karl Wiegers aterriza todo esto en el terreno práctico. Su trabajo sobre redacción de requisitos insiste en evitar lenguaje difuso, distinguir entre tipos de enunciado, limpiar términos ambiguos y construir un vocabulario compartido. No es teoría por la teoría. Es la constatación de que los equipos se entienden mejor cuando el lenguaje está bien ordenado.
Visto en conjunto, el mensaje es bastante claro: un buen documento no solo dice cosas correctas; también separa correctamente la naturaleza de esas cosas.
Esto no sirve solo para requisitos
Aquí está una de las partes más interesantes. Esta disciplina no se limita a un documento de requisitos formal. También sirve en otros contextos donde solemos trabajar con texto estructurado y decisiones importantes.
Propuestas de producto
Una propuesta floja mezcla visión, funcionalidades, condicionantes, supuestos y promesas comerciales en un mismo discurso. El resultado puede sonar convincente, pero rara vez deja una base sólida para alinear expectativas.
Si aplicamos esta composición, la propuesta gana fuerza.
- Primero definimos los conceptos clave del problema o del negocio.
- Luego especificamos las capacidades que ofrecerá la solución.
- Después expresamos las restricciones reales: presupuesto, plazos, regulación, integraciones, limitaciones técnicas o dependencias externas.
Eso obliga a pensar mejor y a vender con más honestidad. Una propuesta madura no solo expone lo que quiere hacer, sino también el marco conceptual y operativo dentro del que realmente puede hacerlo.
Instrucciones para agentes de IA
Este patrón es especialmente útil cuando trabajamos con agentes.
Muchísimas instrucciones a IA fallan porque mezclan en un mismo bloque contexto del proyecto, objetivo de la tarea, reglas obligatorias, estilo de salida, excepciones, límites, ejemplos y advertencias. El resultado es una sopa de texto donde el agente no siempre distingue qué es contexto, qué es mandato y qué es mera explicación.
Cuando lo separas, todo mejora.
- Definición: qué significan los conceptos del marco de trabajo.
- Especificación: qué debe producir el agente y bajo qué estructura.
- Restricción: qué no puede inventar, qué fuentes debe priorizar, qué formato debe respetar y qué límites no puede cruzar.
No convierte al agente en infalible, pero sí reduce improvisación, ambigüedad y resultados inconsistentes. Y eso, en un entorno donde el texto se convierte en acción, importa mucho.
Documentación operativa y arquitectura
También aplica a procedimientos, decisiones técnicas, manuales internos o marcos metodológicos.
Por ejemplo, en arquitectura es habitual que una decisión técnica esconda varias capas: una definición de concepto, una especificación de comportamiento esperado y una restricción corporativa o de plataforma. Si se documentan separadas, la revisión es mucho más limpia. Sabes qué parte responde al dominio, cuál responde a la solución y cuál a límites no negociables.
Un ejemplo simple para verlo claro
Imagina esta frase:
El sistema de reservas deberá gestionar clientes, servicios y horarios conforme a la normativa, usando la API corporativa, y los clientes premium tendrán prioridad.
Suena razonable, pero está mal compuesta. Ahí dentro hay conceptos de dominio, comportamiento funcional, una restricción de integración y una regla de negocio.
Una versión bien estructurada podría ser:
Definiciones
- “Cliente premium” es aquel con suscripción activa y pagos al día.
- “Reserva confirmada” es aquella aceptada por el sistema y con franja horaria asignada.
Especificaciones
- El sistema deberá permitir crear, modificar y cancelar reservas.
- El sistema deberá asignar franjas horarias disponibles a cada reserva.
- El sistema deberá aplicar prioridad en la asignación a clientes premium.
Restricciones
- La solución deberá integrarse con la API corporativa de agenda.
- La gestión de reservas deberá cumplir la normativa aplicable de protección de datos.
- La disponibilidad deberá mantenerse consistente ante accesos concurrentes.
Este formato tan rígido y explicito puede ser apropiado si nos encontramos redactando un DDR (Documento Detallado de Requisitos), pero vuelvo a insistir, si tenemos preferencia o necesidad por hacer esto en un texto con forma narrativa, podemos saltarnos el formato explicito, pero podemos narrarlo y cubrirnos las espaldas a futuro, no solo para entender y transmitir el conocimiento obtenido, sino también para que cuando implementemos la solución, podamos defender por qué hemos hecho lo que hemos hecho. Para el ejemplo podríamos hacer lo siguiente:
- El sistema deberá permitir crear, modificar y cancelar reservas, asignando a cada una una franja horaria disponible y aplicando prioridad a los clientes premium, entendidos como aquellos que tienen una suscripción activa y sus pagos al día.
- Una reserva se considerará confirmada cuando haya sido aceptada por el sistema y tenga una franja horaria asignada.
- Todo ello deberá realizarse mediante integración con la API corporativa de agenda, cumpliendo la normativa aplicable en materia de protección de datos y garantizando la consistencia de la disponibilidad incluso cuando se produzcan accesos concurrentes.
Este ejemplo ya se corresponde con el típico formato de bullets ampliamente usado en documentos y/o presentaciones Power Point (o herramientas similares), habítualmente usado para la elaboración de propuestas. Puese incluirse en un slide sin mayor problema y sigue cumpliendo el principio.
La diferencia es evidente. Ahora el documento se puede leer de forma mucho más precisa. Cada pieza tiene su sitio, cada discusión tiene mejor foco. Cada parte puede trazarse, implementarse y validarse con menos fricción.
Una experiencia personal: el precio de no definir, especificar y restringir
Recuerdo un proyecto en el que existía una propuesta vinculante firmada mucho antes de que yo me incorporase al equipo. El documento describía, a alto nivel, las características que debía cumplir la solución final. Probablemente se redactó con información todavía incompleta sobre el negocio y sobre el producto definitivo. Eso, siendo mejorable, no era lo más grave.
Lo realmente problemático estaba en una frase aparentemente inofensiva:
“Se integrará con los sistemas existentes”.
Aquella línea no definía qué debía entenderse por “sistemas existentes”, no especificaba con qué sistemas concretos debía integrarse la solución ni restringía el alcance de esa integración mediante límites, exclusiones o condiciones. Era una frase contractual abierta.
El cliente, además, no era una organización pequeña, sino una empresa internacional con un ecosistema tecnológico amplio y complejo. Durante la definición funcional, el alcance comenzó a expandirse progresivamente. Cuando el equipo técnico analizó la propuesta firmada y la comparó con el alcance funcional que se estaba consolidando, apareció el problema: la ambigüedad de aquella frase permitía interpretar que prácticamente cualquier integración podía considerarse incluida.
La consecuencia fue inmediata. Lo que en la propuesta parecía una formulación genérica pasó a convertirse en un punto de fricción que por contrato casi daba licencia al cliente para desangrar al proveedor económicamente. Si todo lo que el cliente entendía como “integración con los sistemas existentes” debía ejecutarse dentro del precio ya firmado, el proyecto corría el riesgo de convertirse en una carta blanca al cliente para pedir casi cualquier cosa.
Ese caso me confirmó algo que en ingeniería de requisitos y en definición de producto debería tratarse casi como una regla básica: cuando no separas definición, especificación y restricción, dejas espacios que más tarde alguien rellenará según su conveniencia. Y, en un contexto contractual, esos espacios se traducen en costes y pérdidas económicas.
Cómo detectar que estás mezclando capas
Hay varias señales bastante claras.
- La primera aparece cuando una frase “parece importante”, pero no sabes si debe ir al glosario, al catálogo de reglas, al bloque de requisitos o al apartado de restricciones. Esa duda ya indica que probablemente estás mezclando cosas distintas.
- La segunda surge cuando usas lenguaje normativo para definir conceptos. Si una frase solo aclara qué significa algo, no debería disfrazarse de requisito.
- La tercera es la acumulación de conjunciones y condiciones en una sola línea: “y”, “o”, “además”, “siempre que”, “salvo”, “conforme a”, “usando”. Muchas veces eso delata que en una misma frase se están empaquetando varias exigencias de naturaleza distinta.
- La cuarta aparece cuando el lector necesita preguntar: “sí, pero aquí qué es exactamente obligatorio y qué es solo contexto”. En ese momento, el documento ya no está cumpliendo bien su función.
Una pauta sencilla para escribir mejor
Hay una forma muy práctica de aplicar esta disciplina sin convertirla en burocracia. Antes de dejar por buena una frase importante, conviene hacerse tres preguntas:
- Qué estoy nombrando o delimitando.
Si la frase fija el significado de algo, estás definiendo. - Qué comportamiento o capacidad estoy exigiendo.
Si la frase pide que la solución haga algo, estás especificando. - Qué límite externo o condición obligatoria estoy imponiendo.
Si la frase acota el espacio de soluciones válidas, estás restringiendo.
Este filtro tan simple mejora muchísimo la calidad de un documento. No porque lo vuelva más elegante, sino porque obliga a pensar con más precisión.
Lo importante no es la etiqueta, sino la disciplina mental
Puedes hablar de definición, especificación y restricción. O de vocabulario, comportamiento y límites. O de dominio, solución y condicionantes. El nombre exacto importa menos que la disciplina que hay detrás.
Lo decisivo es entender que no todo enunciado cumple la misma función. Algunos aclaran el significado del problema. Otros expresan el comportamiento esperado de la solución. Otros imponen límites que no pueden ignorarse.
Cuando un documento distingue esas funciones, se vuelve más útil. Cuando no las distingue, se vuelve más peligroso, porque da una falsa sensación de claridad mientras deja demasiadas cosas abiertas a interpretación.
Escribir mejor para construir mejor
Definir, especificar y restringir no es un formalismo documental. Es una forma de pensar y de escribir que reduce ambigüedad, mejora la trazabilidad y hace que los documentos sirvan de verdad para trabajar.
Sirve en requisitos, desde luego. Pero también en propuestas de producto, documentación operativa, arquitectura e instrucciones para agentes de IA. En todos esos contextos el problema es el mismo: si no distinguimos qué significa cada cosa y qué función cumple cada enunciado, acabamos pidiendo mal, entendiendo mal y construyendo mal.
Y eso siempre termina costando más de lo que parecía al principio.