Desarrollo guiado por especificaciones con IA: escribe el plan antes que el código (2026)

¿Qué es el desarrollo guiado por especificaciones?

El desarrollo guiado por especificaciones es un método que trata la especificación (spec) como la única fuente de verdad: anotas "qué hay que construir, por qué y cómo se ve lo terminado" antes de la primera línea de código, y luego dejas que un agente de IA genere código, pruebas y docs que sigan esa spec. En pocas palabras: la spec conduce a la IA, en lugar de que la IA adivine lo que quisiste decir.

El corazón de todo es esa frase, "única fuente de verdad". En la forma antigua de trabajar, los requisitos viven dispersos en tu cabeza, en unos cuantos mensajes de chat y en un ticket flaco. La IA puede leer muy poco de eso, así que tiene que inferir el resto — y la inferencia es donde nacen los bugs. El SDD te obliga a reunir cada restricción importante en un único documento que tanto humanos como agentes pueden leer: el objetivo, el alcance, los criterios de aceptación e incluso las cosas que deliberadamente no quieres que se hagan (no-objetivos).

Esto no es un regreso al "escribe un documento gigante antes de programar" del waterfall. Una spec en SDD es corta, viva y normalmente ocupa solo una o dos pantallas. Es contexto antes del código — el contexto justo para que un agente listo lo acierte a la primera, en vez de que tú lo parchees a mano tres o cuatro veces. Thoughtworks lo llama un patrón que está rediseñando cómo se escribe el software con IA (Thoughtworks, 2025).

¿Por qué escribir un plan primero le gana al "puro vibe"?

Pongámosle un nombre que se pegue al problema central del "puro vibe": el "impuesto de la ambigüedad". En cada punto donde tu requisito sigue difuso, la IA se ve forzada a rellenar el hueco. Y lo rellena con una suposición promedio sacada de sus datos de entrenamiento, no con tu intención real. Ese impuesto lo pagas de vuelta en forma de ciclos de retrabajo: "no, no era eso lo que quería decir", "se te pasó este caso", "¿por qué cambiaste todo ese otro archivo?".

Si eres nueva en ese estilo de soltar las manos y dejar que la IA lleve el mando, lee primero qué es el vibe coding para tener contexto — el SDD es el paso que le pone disciplina al vibe coding, no un rechazo a él. El "puro vibe" es genial para explorar rápido; pero en el momento en que una tarea tiene requisitos claros, deja al descubierto tres riesgos:

• Desvío de requisitos: la IA entrega algo que corre pero no es lo que necesitabas — casos límite que faltan, lógica de negocio mal leída, nombres e interfaces que rompen tus convenciones.
• Desvío de arquitectura: cada prompt se vuelve una decisión de diseño improvisada. Tras diez prompts, la base de código es un remiendo que nadie diseñó a propósito.
• Coste de tokens que se dispara: cada ciclo de "por favor, arréglalo otra vez" hace que el agente relea el contexto y regenere el código. Tres o cuatro rondas de retrabajo cuestan muchas veces más tokens que una buena spec al principio.

El guiado por especificaciones invierte el orden: pagas el "coste de pensar" una vez, al frente, mientras aún es barato. Escribir criterios de aceptación te obliga a responder justo las preguntas que la IA, si no, tendría que adivinar. Una vez que el contexto está claro, casi no le queda hueco al agente para adivinar mal. Por eso también un flujo de trabajo de vibe coding maduro siempre lleva un paso de escribir el plan cosido en el medio, en vez de prompts sin parar.

Spec vs plan vs tarea — ¿cuál es la diferencia?

Estas tres palabras suelen mezclarse, pero trazar una línea limpia entre ellas es la clave del SDD. En resumen: una spec responde "qué y por qué", un plan responde "cómo, y en qué orden", y una tarea es la unidad de ejecución más pequeña.

Confusiones comunes: meter el "cómo" en la spec (la spec se microgestiona demasiado pronto y pierde flexibilidad), o escribir un plan que se salta los criterios de aceptación (el agente nunca sabe cuándo puede darlo por terminado). Un truco para mantener la línea: si la respuesta es sobre "lo que el usuario o el sistema necesita", pertenece a la spec; si es sobre "qué tecleamos, qué archivo editar primero", pertenece al plan.

Un ejemplo DE VERDAD: una spec + plan antes de cualquier código

Basta de teoría. Aquí tienes un artefacto real de una función pequeña que suelo usar para ilustrar esto: añadir un límite de tasa (rate limit) al endpoint de login. Copia estos dos archivos, ajusta unas líneas para tu proyecto y listo. Primero, el spec.md — solo dice "qué y por qué", nunca cómo:

# spec.md - Rate limit for the login API

## Goal
Block brute-force against POST /api/login by limiting the number of
attempts per IP + email, returning a clear error when the limit is passed.

## Why
Login currently has no limit -> passwords are easy to guess and the DB
can be overloaded.

## Acceptance criteria
- Max 5 failed attempts / 15 minutes per (IP, email) pair.
- Over the limit -> HTTP 429 + body { error: "too_many_attempts", retry_after }.
- A SUCCESSFUL login resets the counter for that (IP, email) pair.
- Automated tests for: under the limit, at the limit, over the limit, and reset.

## Non-goals
- NO CAPTCHA (deferred to a later phase).
- NO rate-limiting other endpoints this time.

## Edge cases
- Many users behind the same NAT/IP -> key on (IP, email), not IP alone.
- Clock/timezone: use UTC for the time window.

Luego viene el plan.md — ahora, y solo ahora, dice "cómo, y en qué orden". Fíjate en la columna de archivos a tocar y en la sección de rollback:

# plan.md - Implementing login rate limit

## Steps (in order)
1. Add an attempt-counter store (Redis, key = login:{ip}:{email}, TTL 15m).
 -> File: src/lib/rate-limit.ts (new)
2. Write a checkLoginRateLimit middleware that reads/increments the counter.
 -> File: src/middleware/login-rate-limit.ts (new)
3. Attach the middleware to POST /api/login BEFORE the auth handler.
 -> File: src/routes/auth.ts (edit)
4. On successful login -> delete the counter key for that (IP, email).
 -> File: src/routes/auth.ts (edit)
5. Write tests for the 4 cases in the acceptance criteria.
 -> File: tests/login-rate-limit.test.ts (new)

## How to test
- npm test tests/login-rate-limit.test.ts
- Manual: send 6 wrong requests in a row -> the 6th must return 429.

## Risk & rollback
- Redis down -> fail-open (let it through) or fail-closed? Choose fail-open +
 log a warning, so infra failures do not lock out every user.
- Rollback: removing the middleware in step 3 returns the system to its
 original state.

Qué pasa cuando dejas a la IA correr sobre este plan: el agente trabaja en el orden correcto, crea todos los archivos y se detiene en el punto justo porque los criterios de aceptación dejan claro qué significa "terminado". Se acabó eso de refactorizar todo el módulo de auth a la ligera u olvidar el caso de reiniciar el contador. Mismo agente, misma tarea — la diferencia es tener o no un mapa.

El flujo guiado por especificaciones con IA (6 pasos)

Este es el ciclo que uso para casi toda función de tamaño mediano a grande. Se mapea casi uno a uno con el flujo brainstorm -> plan -> cook -> ship:

1. Idea y contexto: plantea el problema a resolver y las restricciones reales (stack, convenciones, cosas que no se pueden tocar). Aquí es donde reúnes la "verdad" del proyecto.
2. Escribe la spec: completa Objetivo / No-objetivos / Criterios de aceptación / Casos límite. Oblígate a ser concreta en los criterios de aceptación — donde seas vaga, la IA adivinará.
3. Revisa la spec (humano + IA): pídele al agente que lea la spec y señale contradicciones, casos que faltan o requisitos imposibles — antes de que exista una sola línea de código.
4. Escribe el plan y divídelo en tareas: convierte la spec en pasos ordenados que nombren los archivos a tocar, cómo probar y el rollback. Trocéalo hasta que cada tarea sea verificable en una sola pasada.
5. Deja que el agente programe tarea por tarea: ejecuta una tarea a la vez, sin adelantarse. Después de cada tarea, haz que el agente compruebe su trabajo contra el plan.
6. Verifica contra los criterios de aceptación: corre las pruebas y repasa línea por línea los criterios. Solo cuando cada criterio esté en verde la función está terminada — no cuando "parece que corre".

La clave: los pasos 3 y 6 son donde el SDD más te salva. Cazar un bug en la fase de la spec es decenas de veces más barato que cazarlo en el código.

Hacer bien el guiado por especificaciones dentro de Claude Code

No necesitas ninguna herramienta especial para empezar — Claude Code ya trae tres cosas que bastan para levantar un ciclo SDD ligero:

• Plan Mode: Claude Code redacta un plan y te deja aprobarlo antes de tocar cualquier archivo — justo el espíritu de "primero el plan, el código después" (Anthropic docs, 2026). Mira cómo sacarle el máximo en planificación con Claude Code (Plan Mode).
• CLAUDE.md como barandilla permanente: pon las convenciones, límites y no-objetivos de larga vida en este archivo para que el agente siempre los lea — convierte las restricciones repetidas en "verdad" fija del repositorio. Esto es context engineering en su forma más simple.
• GitHub Spec Kit: un conjunto de comandos open-source que convierte el SDD en un flujo explícito, /specify -> /plan -> /tasks, usable con Claude Code y muchos otros agentes (GitHub Blog, 2025).

¿Quieres un flujo guiado por especificaciones ya prehecho? Si prefieres no cablear a mano CLAUDE.md + Plan Mode + Spec Kit, el paquete AgentKit — ahora $149 (antes $198) para Claude Code empaqueta skills de brainstorm/plan/cook/ship y subagentes de review que siguen el mismo flujo spec -> plan -> code -> verify. Tengo un texto completo en qué es AgentKit — léelo para decidir por tu cuenta, sin prisa por comprar.

Herramientas guiadas por especificaciones en 2026

Algunas opciones populares, de lo más ligero a lo totalmente empaquetado:

No hay una única herramienta "correcta". Markdown puro + Plan Mode basta para la mayoría de las funciones; los kits más pesados solo compensan cuando haces SDD a menudo y quieres estandarizarlo en un equipo.

¿Cuándo NO necesitas el guiado por especificaciones?

El SDD es una herramienta, no una religión. Forzar una spec en todo sale mal. Sáltate el SDD cuando:

• Scripts de una sola vez o tareas desechables — escribir la spec tarda más que simplemente hacerlo.
• Prototipos/spikes exploratorios: el objetivo es aprender rápido, no acertar todavía. El "puro vibe" encaja mejor en esta etapa.
• Un arreglo de bug de una línea cuya causa ya entiendes — no necesitas criterios de aceptación para cambiar un carácter.
• Requisitos que cambian cada hora: la spec quedará obsoleta más rápido de lo que puedes escribirla.

Dos trampas que vigilar incluso cuando el SDD sí encaja: over-spec (escribir una spec tan detallada que se vuelve rígida y mata la flexibilidad) y spec rot (la spec nunca se actualiza cuando el código cambia y se vuelve un documento que miente). Una buena spec es la que es justo lo suficiente para que el agente acierte y sigue siendo fácil de cambiar — no la más larga.

Preguntas frecuentes (FAQ)

¿En qué se diferencia el desarrollo guiado por especificaciones del vibe coding?

El vibe coding es lanzar prompts y dejar que la IA lleve el mando, lo que va bien para explorar rápido. El guiado por especificaciones pone una spec con criterios de aceptación como fuente de verdad antes de cualquier código, lo que va bien para funciones con requisitos claros. El SDD es el paso que le añade disciplina al vibe coding, no un rechazo a él.

¿Una spec es distinta de un plan?

Sí. Una spec responde "qué y por qué" (objetivo, alcance, criterios de aceptación, no-objetivos). Un plan responde "cómo, y en qué orden" (pasos, archivos a tocar, cómo probar, rollback). La spec es más estable; el plan puede cambiar cuando cambia el enfoque.

¿Necesito herramientas dedicadas o basta con Markdown?

Markdown puro basta para empezar — solo un spec.md y un plan.md. Herramientas como GitHub Spec Kit o Kiro solo ayudan a estandarizar el proceso cuando haces SDD con regularidad o en equipo.

¿El guiado por especificaciones te vuelve más lenta?

Más lenta al principio, más rápida en conjunto. Gastas unos minutos extra escribiendo la spec, pero recortas muchos ciclos de retrabajo en los que la IA se habría desviado. Para tareas pequeñas/desechables de verdad no vale la pena — ahí ve a lo vibe.

¿Puedo usar el guiado por especificaciones con Cursor o Copilot?

Sí. El SDD es un método, no está atado a una herramienta. Puedes mantener spec.md/plan.md en el repositorio y hacer que cualquier agente (Claude Code, Cursor, Copilot) los siga. GitHub Spec Kit se diseñó para ser multiagente desde el principio.

¿Cuánto debe medir una spec?

Lo bastante larga para que el agente no tenga que adivinar nada importante, normalmente una o dos pantallas. Si la spec es más larga que el código que produce, te estás pasando de spec. La prueba real es: criterios de aceptación claros y no-objetivos claros.

Conclusión + próximos pasos

El principio cabe en cuatro palabras: primero la spec, luego el código. Pagas el coste de pensar una vez al frente — donde es más barato — para que la IA no te devuelva el impuesto de la ambigüedad con costosos ciclos de retrabajo. Lo que sigue: lee el flujo brainstorm -> plan -> cook -> ship para ver dónde encaja el SDD en un ciclo de trabajo completo, y planificación con Claude Code (Plan Mode) para poner manos a la obra ya.