Spec-driven development es cómo shippear con menos guesswork

Hay un modo de fallo común en la ingeniería de producto que desde fuera parece productivo.

Alguien tiene una idea. Se crea un ticket. Un desarrollador empieza a programar rápido. Unos pull requests después, todos se dan cuenta de que estaban resolviendo versiones ligeramente distintas del problema.

Entonces empieza la parte cara:

• producto clarifica la intención a posteriori
• diseño parchea edge cases que nunca se describieron
• ingeniería reescribe flujos que técnicamente funcionan pero no dan en el punto
• QA reporta comportamiento "incorrecto" aunque nadie escribió qué era "correcto"

Ese es el coste de construir desde asunciones en vez de desde una spec.

Cuando digo spec-driven development, no me refiero a documentos pesados escritos por escribir. Me refiero a algo mucho más práctico: definir el comportamiento con la claridad suficiente para que implementar sea un paso de ejecución, no un proceso de descubrimiento.

Ese cambio suena pequeño. Cambia mucho.

Una spec es un registro de decisiones

El mayor malentendido sobre las specs es que son documentación.

No son principalmente documentación. Son una forma de forzar decisiones pronto.

Una buena spec responde preguntas como:

• ¿qué problema resolvemos?
• ¿para quién es?
• ¿qué debería pasar en el path normal?
• ¿qué debería pasar en el path de fallo?
• ¿qué está explícitamente fuera de scope?
• ¿cómo sabremos que está hecho?

Si esas respuestas son vagas, la implementación también será vaga.

La mayoría del desperdicio de ingeniería es desperdicio de ambigüedad

Los equipos suelen hablar de desperdicio en términos de mal código, malas abstracciones o infra lenta. Eso importa. Pero mucho tiempo perdido ocurre antes.

Aparece como:

• construir bien lo incorrecto
• descubrir requisitos tras el merge
• retrabajar UI porque las transiciones de estado nunca se definieron
• backend y frontend implementando asunciones distintas
• tests en verde mientras la feature sigue sintiéndose rota

Eso no es realmente un fallo de ejecución. Es un fallo de especificación.

Una spec fuerte no elimina la iteración. Elimina la iteración de baja calidad.

Cómo se ve "spec-driven" en la práctica

Una buena spec suele ser más pequeña de lo que la gente cree.

Para trabajo de producto y aplicación, quiero que una spec cubra al menos estas áreas:

1. Objetivo

¿Qué outcome de usuario o negocio debería cambiar?

Mal:

Añadir un mejor flujo de onboarding.

Mejor:

Reducir el drop-off del onboarding eliminando pasos innecesarios antes de crear la cuenta.

La segunda versión te dice qué importa. La primera solo suena ambiciosa.

2. Flujo de usuario

¿Cuál es el path exacto por la feature?

Por ejemplo:

1. el usuario hace clic en "Start trial"
2. el usuario introduce email y password
3. la cuenta se crea inmediatamente
4. los datos de empresa se recogen tras el login
5. si el email ya existe, mostrar error inline y preservar los campos

Ese nivel de claridad previene una cantidad sorprendente de churn.

3. Estados y edge cases

Aquí es donde muchas features se rompen.

No solo especeas el happy path. Especeas el comportamiento real:

• loading
• empty
• validation failure
• permission failure
• timeout
• partial success
• retry path

Si una feature toca dinero, auth, mensajería o acciones destructivas, los edge cases no son secundarios. Son la feature.

4. Restricciones

¿Qué debe seguir siendo verdad?

Ejemplos:

• esta acción debe ser idempotente
• el layout móvil debe soportar uso con una mano
• nada de información personal identificable en logs
• la respuesta de la API debe mantenerse bajo cierto presupuesto de latencia

Las restricciones evitan que la implementación derive hacia decisiones localmente convenientes pero globalmente incorrectas.

5. Criterios de aceptación

Esta es la parte que los equipos se saltan más a menudo, y luego lamentan.

Los criterios de aceptación deberían ser lo bastante específicos para que QA, producto e ingeniería evalúen lo mismo.

Por ejemplo:

• el usuario puede enviar el formulario solo con teclado
• los envíos duplicados no crean registros duplicados
• un pago fallido muestra un estado recuperable y preserva los datos de billing
• el email de confirmación se envía solo tras persistir con éxito

Eso es mucho mejor que "works as expected".

Las specs mejoran la velocidad, no solo la calidad

Algunos ingenieros oyen "spec-driven development" e inmediatamente temen el process drag.

Esa preocupación es comprensible si has visto specs hinchadas que nadie lee. Pero ese no es un problema de las specs. Es un problema de malas specs.

Una spec afilada acelera a los equipos porque:

• menos decisiones se difieren al code review
• la implementación es más fácil de repartir entre personas
• QA tiene un target concreto
• el feedback de diseño se vuelve objetivo más rápido
• las regresiones son más fáciles de detectar porque el comportamiento esperado está escrito

Los equipos más rápidos con los que he trabajado no eran los que empezaban a programar primero. Eran los que eliminaban la incertidumbre primero.

Las specs mejoran los code reviews

La calidad del code review sube mucho cuando hay una spec detrás del cambio.

Sin spec, las reviews suelen derivar a discusiones de estilo o preferencias locales de implementación:

• "Yo estructuraría este hook distinto."
• "¿Renombramos esta variable?"
• "Quizá usar otro patrón aquí."

Esos comentarios a veces sirven, pero no bastan.

Con spec, los reviewers pueden hacer preguntas de más valor:

• ¿la implementación coincide con el comportamiento esperado?
• ¿están cubiertos los estados de fallo?
• ¿falta algún criterio de aceptación?
• ¿el modelo de datos soporta el flujo descrito?

Esa es una review mucho más seria.

Las specs ayudan a discrepar antes, lo cual es bueno

Un beneficio infravalorado del spec-driven development es que crea un lugar para el desacuerdo antes de que exista código.

Eso importa porque discrepar se vuelve más caro una vez que la implementación empieza.

Si producto, diseño e ingeniería tienen modelos mentales distintos, quieres que esa colisión ocurra mientras el artefacto aún es barato de cambiar. Una spec le da al equipo algo concreto que cuestionar.

Eso es sano. Es mucho mejor discutir por un párrafo que por una feature mergeada.

La spec debería estar cerca del trabajo

No me importa mucho si la spec vive en Notion, GitHub, Linear o un Markdown en el repo. Me importa que siga conectada a la implementación.

Un workflow práctico suele verse así:

1. escribir la spec en lenguaje llano
2. revisarla con las personas afectadas
3. convertir los criterios de aceptación en tareas de implementación
4. construir contra la spec
5. validar el comportamiento shippeado contra los criterios originales

Si la spec está demasiado lejos del código, se pudre. Si es demasiado vaga, se ignora. Si es demasiado grande, nadie puede retenerla en la cabeza.

La spec correcta es el artefacto más pequeño que deja el trabajo sin ambigüedad.

Las specs deberían escalar hacia abajo además de hacia arriba

No toda tarea necesita un documento multi-sección.

Spec-driven development es un mindset, no una plantilla fija. Un bugfix de una hora puede seguir siendo spec-driven si defines:

• comportamiento actual
• comportamiento esperado
• pasos de reproducción
• condición de aceptación

Eso sigue siendo una spec. Solo que proporcionada.

Lo que importa no es el tamaño del artefacto. Lo que importa es si el equipo programa contra comportamiento explícito en vez de intuición.

Mi regla de oro

Si una feature tiene algo de lo siguiente, quiero una spec real antes de implementar:

• múltiples estados de usuario
• workflows asíncronos
• dependencias cross-team
• dinero, permisos o concerns de integridad de datos
• copy visible o UX interpretable de varias formas

Esos son exactamente los casos donde "we'll figure it out while building" sale caro.

Por qué sigo volviendo a ello

Spec-driven development es una de esas prácticas que solo se siente más lenta si mides la primera hora.

Medida en todo el lifecycle de una feature, suele ser más rápida porque reduce:

• retrabajo
• asunciones ocultas
• churn de review
• ambigüedad de QA
• sorpresas en producción

También mejora la calidad del pensamiento de ingeniería. Escribir una spec te obliga a preguntarte si realmente entiendes el problema o solo crees entenderlo.

Esa es disciplina valiosa.

El punto real

El propósito de una spec no es hacer que el trabajo se sienta formal.

El propósito es hacer explícita la intención antes de que el código endurezca la idea equivocada.

Por eso importa spec-driven development. No es burocracia. Es una forma de shippear con menos guesswork.

There is a common failure mode in product engineering that looks productive from the outside.

Someone has an idea. A ticket gets created. A developer starts coding quickly. A few pull requests later, everyone realizes they were solving slightly different versions of the problem.

Then the expensive part begins:

• product clarifies intent after the fact
• design patches edge cases that were never described
• engineering rewrites flows that technically work but miss the point
• QA reports behavior that is “wrong” even though nobody wrote down what “right” meant

That is the cost of building from assumptions instead of from a spec.

When I say spec-driven development, I do not mean heavyweight documents written for their own sake. I mean something much more practical: define the behavior clearly enough that implementation becomes an execution step, not a discovery process.

That shift sounds small. It changes a lot.

A spec is a decision record

The biggest misconception about specs is that they are documentation.

They are not primarily documentation. They are a way to force decisions early.

A useful spec answers questions like:

• what problem are we solving?
• who is this for?
• what should happen in the normal path?
• what should happen in the failure path?
• what is explicitly out of scope?
• how will we know this is done?

If those answers are vague, implementation gets vague too.

The point of the spec is not to predict every detail. The point is to reduce ambiguity to a level where the team can move with confidence.

Most engineering waste is ambiguity waste

Teams often talk about waste in terms of bad code, poor abstractions, or slow infrastructure. Those matter. But a lot of wasted time happens earlier.

It shows up as:

• building the wrong thing correctly
• discovering requirements after merging
• reworking UI because state transitions were never defined
• backend and frontend implementing different assumptions
• tests passing while the feature still feels broken

That is not really an execution failure. It is a specification failure.

A strong spec does not eliminate iteration. It eliminates low-quality iteration.

What “spec-driven” looks like in practice

A good spec is usually smaller than people think.

For product and application work, I want a spec to cover at least these areas:

1. Goal

What user or business outcome should change?

Bad:

Add a better onboarding flow.

Better:

Reduce onboarding drop-off by removing unnecessary steps before account creation.

The second version tells you what matters. The first one just sounds ambitious.

2. User flow

What is the exact path through the feature?

For example:

1. user clicks “Start trial”
2. user enters email and password
3. account is created immediately
4. company details are collected after login
5. if the email already exists, show an inline error and preserve entered fields

That level of clarity prevents a surprising amount of churn.

3. States and edge cases

This is where many features fall apart.

You do not only spec the happy path. You spec the actual behavior:

• loading
• empty
• validation failure
• permission failure
• timeout
• partial success
• retry path

If a feature touches money, auth, messaging, or destructive actions, edge cases are not secondary. They are the feature.

4. Constraints

What must remain true?

Examples:

• this action must be idempotent
• mobile layout must support one-handed use
• no personally identifiable information in logs
• API response must stay under a certain latency budget

Constraints stop implementation from drifting into locally convenient but globally wrong decisions.

5. Acceptance criteria

This is the part teams skip most often, then regret later.

Acceptance criteria should be specific enough that QA, product, and engineering can all evaluate the same thing.

For example:

• user can submit the form with keyboard only
• duplicate submissions do not create duplicate records
• failed payment shows a recoverable state and preserves entered billing data
• confirmation email is sent only after persistence succeeds

That is much better than “works as expected.”

Specs improve speed, not just quality

Some engineers hear “spec-driven development” and immediately worry about process drag.

That concern is understandable if you have seen bloated specs nobody reads. But that is not a problem with specs. That is a problem with bad specs.

A sharp spec speeds teams up because:

• fewer decisions are deferred into code review
• implementation is easier to split across people
• QA has a concrete target
• design feedback becomes objective faster
• regressions are easier to spot because intended behavior is written down

The fastest teams I have worked on were not the ones that started coding first. They were the ones that removed uncertainty first.

Specs make code reviews better

Code review quality rises a lot when there is a spec behind the change.

Without a spec, reviews often drift into style arguments or local implementation preferences:

• “I would structure this hook differently.”
• “Can we rename this variable?”
• “Maybe use a different pattern here.”

Those comments are sometimes useful, but they are not enough.

With a spec, reviewers can ask higher-value questions:

• does this implementation match the intended behavior?
• are the failure states covered?
• is any acceptance criterion missing?
• does the data model support the described flow?

That is a much more serious review.

Specs help teams disagree earlier, which is good

One underrated benefit of spec-driven development is that it creates a place for disagreement before code exists.

That matters because disagreement gets more expensive once implementation starts.

If product, design, and engineering have different mental models, you want that collision to happen while the artifact is still cheap to change. A spec gives the team something concrete to challenge.

That is healthy. It is much better to argue over a paragraph than over a merged feature.

The spec should be close to the work

I do not care much whether the spec lives in Notion, GitHub, Linear, or a Markdown file in the repo. I care that it stays connected to the implementation.

A practical workflow often looks like this:

1. write the spec in plain language
2. review it with the people affected
3. turn the acceptance criteria into implementation tasks
4. build against the spec
5. validate the shipped behavior against the original criteria

If the spec is too far away from the code, it rots. If it is too vague, it gets ignored. If it is too big, nobody can hold it in their head.

The right spec is the smallest artifact that makes the work unambiguous.

Specs should scale down as well as up

Not every task needs a multi-section document.

Spec-driven development is a mindset, not a fixed template. A one-hour bugfix can still be spec-driven if you define:

• current behavior
• expected behavior
• reproduction steps
• acceptance condition

That is still a spec. It is just proportionate.

What matters is not the size of the artifact. What matters is whether the team is coding against explicit behavior instead of intuition.

My rule of thumb

If a feature has any of the following, I want a real spec before implementation:

• multiple user states
• asynchronous workflows
• cross-team dependencies
• money, permissions, or data integrity concerns
• user-facing copy or UX that can be interpreted several ways

Those are exactly the cases where “we’ll figure it out while building” becomes expensive.

Why I keep coming back to it

Spec-driven development is one of those practices that feels slower only if you measure the first hour.

Measured over the whole lifecycle of a feature, it is usually faster because it reduces:

• rework
• hidden assumptions
• review churn
• QA ambiguity
• production surprises

It also improves the quality of engineering thinking. Writing a spec forces you to ask whether you actually understand the problem or only think you do.

That is valuable discipline.

The real point

The purpose of a spec is not to make work feel formal.

The purpose is to make intent explicit before code hardens the wrong idea.

That is why spec-driven development matters. It is not bureaucracy. It is a way to ship with less guesswork.