Después del desarrollo guiado por especificaciones: articula siempre, especifica a veces

El 29 de octubre de 2026, revisé los trabajos empíricos de 2026 sobre desarrollo guiado por especificaciones (SDD), la documentación actual de Claude Code y Kiro, las notas de lanzamiento de Spec Kit 1.0.0 y los análisis retrospectivos de profesionales. Los estudios y documentos de proveedores se citan en el texto. La escala de decisión es mi síntesis. Cuando va más allá de la evidencia, lo señalo.

TL;DR

• No abandones el desarrollo guiado por especificaciones. Deja de usarlo por defecto. Los profesionales estudiados en 2026 ya usan SDD de forma selectiva: principalmente para nuevas funcionalidades y rara vez para cambios pequeños o hotfixes (Agarwal et al., 2026).
• La afirmación más contundente sobre la reducción de defectos no superó la prueba empírica. En 88,052 pull requests de 119 repositorios de código abierto, ninguna de las cinco hipótesis derivadas de afirmaciones de proveedores sobre la reducción de defectos o retrabajo mediante especificaciones obtuvo respaldo (Hill, ESEM 2026). Eso no demuestra que las especificaciones causen defectos: los desarrolladores las usan para su trabajo más difícil. Pero ahora la carga de la prueba ha cambiado. La única señal protectora apareció en repositorios sin adopción de IA, donde las especificaciones se asociaron con menos retrabajo. El beneficio apareció donde ningún agente lee el archivo.
• Para las personas, es probable que el ingrediente activo sea la articulación. Agarwal et al. proponen que el beneficio individual podría provenir de aclarar la intención antes de delegar, algo que puede lograrse con cualquier práctica de planificación. Ese mecanismo es plausible, pero no se ha puesto a prueba. Sugieren que los beneficios para los equipos podrían depender de que SDD se convierta en un proceso compartido.
• Más planificación no siempre implica más seguridad. En 21,120 trayectorias de agentes, un plan malo o incompleto perjudicó más que no tener plan (Liu et al., ASE 2026). El resultado corresponde a planes de ejecución de agentes; aplicarlo a especificaciones de funcionalidades es mi inferencia.
• Usa una escala: diff describible en una frase → construye directamente; enfoque incierto o varios archivos → plan efímero; trabajo de larga duración, con varios agentes, revisión de equipo o auditoría → especificación persistente.
• Sea cual sea el nivel que elijas, agrega una verificación que el agente pueda ejecutar. Un test, build o eval que pase aporta más confianza que otra página de prosa (buenas prácticas de Claude Code, consultadas el 29 de octubre de 2026).

El entusiasmo, en pocas palabras

SDD llegó como la respuesta disciplinada al vibe coding: primero escribe la especificación —objetivos, restricciones, plan y tareas—, revísala y deja que el agente implemente a partir de ella. Spec Kit de GitHub, Kiro de Amazon y OpenSpec de Fission AI prescriben alguna versión de esa secuencia, y la práctica se extendió rápidamente: Agarwal et al. encontraron archivos de especificación en más de 73,000 repositorios públicos de GitHub, casi todos incorporados por primera vez en 2025 o después.

Después llegó, como era de esperar, la reacción en contra: «SDD ha muerto, larga vida al plan mode», «la especificación ha muerto, larga vida al párrafo». La mayor parte de esos textos son opiniones. Lo que cambió en 2026 fue la llegada de evidencia, y esta favorece menos a ambos bandos de lo que cualquiera de ellos admite.

Si buscas una comparación herramienta por herramienta, consulta OpenSpec vs GitHub Spec Kit. Este artículo plantea la pregunta previa: ¿cuánta especificación merece realmente esta tarea?

Qué dice realmente la evidencia de 2026

Hay tres conclusiones que defendería:

1. No encontré ningún estudio que demuestre que el archivo cause mejoras de calidad en el trabajo asistido por IA. La afirmación de los proveedores de que «las especificaciones reducen los defectos» no obtuvo respaldo en una prueba empírica de gran escala. Su única señal protectora apareció en repositorios sin IA. Los participantes de un estudio cualitativo no pudieron separar SDD de las mejoras simultáneas de los modelos.
2. Los profesionales demuestran con sus decisiones que prefieren la proporcionalidad. Los entrevistados por Agarwal omiten SDD para tareas pequeñas, bugs, scripts y hotfixes («no hay tiempo para el desarrollo guiado por especificaciones y todo el proceso») y recurren a él para funcionalidades grandes y cambios de alto impacto.
3. La calidad del plan es un umbral, no una escala gradual. El resultado de Liu —un mal plan es peor que ninguno, y las fases adicionales desalineadas degradan el rendimiento— se refiere a planes de ejecución. Extenderlo a especificaciones de funcionalidades es mi inferencia, pero coincide con el hallazgo de Agarwal de que el 77.6% de las especificaciones reales contiene detalles de implementación (nombres de clases, versiones de bibliotecas), que son los que se desactualizan más rápido. Una especificación larga, incorrecta y desactualizada no es una red de seguridad; es una segunda base de código que mantener.

Planificar no es lo mismo que tener un plan

El relato más incisivo de un profesional es el análisis retrospectivo de Ayman Nadeem, El plan mode ha muerto (24 de septiembre de 2026). Nadeem creó Nuanced, una aplicación de escritorio para programar, en torno a especificaciones persistentes y vivas, y luego la canceló:

«La especificación contenía más información sin aportar más claridad».

Su diagnóstico separa dos cosas que el marketing de SDD mezcla:

• Planificación: el proceso colaborativo de sacar a la luz decisiones, compromisos e incógnitas. Más valioso que nunca.
• Un plan: un artefacto extenso generado por IA que entierra esas decisiones en prosa estructurada que nadie vuelve a leer. «Si necesitábamos generar una representación más corta de la especificación para poder usarla, ¿qué sentido tenía el documento completo desde un principio?».

Esta es la experiencia de una persona que creó un producto, no un estudio. Agarwal et al. ofrecen un mecanismo que la hace plausible (Sección V-D del preprint). Si el beneficio individual de SDD proviene de que el desarrollador haya articulado los objetivos antes de delegar, una función cognitiva que obliga a pensar deliberadamente, entonces plan mode, una conversación de diseño o cualquier práctica que obligue a pensar debería producir el mismo beneficio. El archivo de especificación sería entonces una formalidad después de que ya ocurrió la parte valiosa.

Hasta donde sé, nadie ha realizado aún este experimento. Agarwal et al. lo proponen con las mismas tareas y tres grupos: especificación escrita y entregada al agente, especificación escrita y retenida, ninguna especificación. Hasta que alguien lo haga, «articula siempre» se apoya indirectamente en la evidencia; «guarda siempre» es una cuestión de fe.

La escala proporcional

Cada nivel sigue teniendo respaldo en una fuente primaria. Un artículo complementario, Cuándo el desarrollo guiado por especificaciones es excesivo, aborda cuánto tiempo debe durar una especificación y cuándo promover sus tareas. Este artículo contrasta cada nivel con la evidencia de 2026.

flowchart TD
    A[Nueva tarea] --> F{"¿Perdurará más allá de la sesión?<br/>¿Otros agentes, compañeros,<br/>aprobación o auditoría después?"}
    F -->|No| B{"¿Puedes describir<br/>el diff en una frase?"}
    B -->|Sí| C["Nivel 0: Construir directamente<br/>prompt + verificación para ejecutar"]
    B -->|No| D{"¿Enfoque incierto,<br/>varios archivos o código desconocido?"}
    D -->|Sí, una sesión| E["Nivel 1: Plan mode<br/>explorar, planear, iterar, implementar"]
    D -->|No / bien entendido| C
    E --> G[Implementar<br/>plan o intención como guía]
    F -->|Sí| H["Nivel 2: Guardar un contrato de intención<br/>objetivo + criterios de aceptación en git"]
    H --> I{"¿Cumple alguna de estas condiciones: alta complejidad,<br/>aprobaciones de equipo, riesgo regulatorio o de sistemas existentes?"}
    I -->|Sí| J["Nivel 3: SDD completo<br/>flujo de Spec Kit / Kiro / OpenSpec"]
    I -->|No| G

Nivel 0: Directo. Mi regla práctica de una frase: si puedes describir el diff en una frase —un error tipográfico, una línea de log, un cambio de nombre—, ningún artefacto de planificación justifica su costo de revisión. Según Nadeem, la carga de revisión puede superar la de la tarea. Las buenas prácticas actuales de Claude Code (consultadas el 29 de octubre de 2026) respaldan esto de forma más directa. En la mayoría de los casos, «tu primer prompt sencillo en una sesión nueva ya hace lo correcto». Así que agrega solo lo que Claude no pueda ver en el repositorio y una verificación para ejecutar. Su tabla «Qué puedes dejar de hacer» lo dice claramente sobre los archivos de contexto: «Claude lee el repositorio por sí mismo. Solo escribe lo que no esté allí».

Nivel 1: Plan efímero. Plan mode en Claude Code, Cursor o Kiro: el agente explora en modo de solo lectura, tú iteras sobre un plan breve y luego implementas en la misma sesión. La documentación de Kiro sitúa este nivel en tareas que requieren aproximadamente 15–60 minutos de implementación: suficiente tiempo para beneficiarse de la planificación, pero lo bastante poco como para que las especificaciones formales sean excesivas. El plan desaparece con la sesión, y eso está bien, porque su función era hacer que tú pensaras.

Nivel 2: Intención persistente. Cuando un segundo agente, un compañero, un revisor o tu yo del futuro necesita reconstruir el porqué sin que estés presente, el artefacto justifica su existencia. También aplica cuando varias sesiones o agentes implementan a partir de una misma intención, porque el historial de chat no perdurará. Es el contrato de intención de una página que aparece a continuación, que reemplaza el conjunto completo de especificación, plan y tareas.

Nivel 3: SDD completo. Kiro reserva Feature Specs (requirements.md, design.md y tasks.md persistentes, con pasos de aprobación) para «alta complejidad, colaboración de equipo y trazabilidad para auditoría». El README de Spec Kit (consultado el 29 de octubre de 2026) describe un ciclo que se repite «hasta que la convergencia informe Converged». Su versión 1.0.0 se lanzó el 21 de agosto de 2026. Interpretar su capacidad de composición como un harness de entrega es mi inferencia: el artículo de ThoughtWorks sobre el harness nunca menciona Spec Kit. El trabajo a escala de equipo y sujeto a controles sigue siendo donde corresponde un proceso más formal. Para conocer la mecánica, consulta por qué vale la pena estudiar las skills de Spec Kit.

Los proveedores ya muestran la escala. Amazon la ofrece de forma explícita, y la guía actual de Anthropic cubre sus dos extremos: prompting directo por defecto y un SPEC.md contra el cual vale la pena verificar un diff cuando el trabajo lo justifica. «Especificación vs plan» es una falsa dicotomía; la guía de ambos proveedores cubre más de un nivel.

Implementación: el contrato de intención de una página

Para el trabajo de Nivel 2 —la mayoría de las funcionalidades compartidas—, reemplaza el conjunto de especificaciones por una sola página que el agente produzca tras entrevistarte. Anthropic documenta este patrón directamente. Pídele a Claude que te entreviste hasta que pueda escribir la especificación, la guarde y luego inicie una sesión nueva para construir a partir de ella. Así, la implementación comienza con un contexto limpio y una definición escrita de cuándo se considera terminada.

# INTENT: <feature name>

## Why (2-3 sentences, human-owned)
What problem, for whom, and what happens if we do nothing.

## What "done" means (acceptance criteria)
- [ ] <observable behavior, testable>
- [ ] <edge case that must not regress>
- [ ] <explicit non-goal: what we are NOT building>

## Constraints Claude cannot see in the repo
- <decision made in a meeting, deploy quirk, external contract>

## Check to run
`pnpm test <path>` + `pnpm tsc --noEmit` — paste output as evidence.

Ejecútalo así:

I want to add rate limiting to the public API but haven't thought it
through yet. Interview me until you could write the intent contract:
per-user vs per-key, over-limit behavior, what is out of scope.
Write it to INTENT.md. Do not implement yet.

Después, en una sesión nueva:

Implement INTENT.md. For each acceptance criterion, write or name the
test that proves it. Run the check in the contract, paste the output,
and keep going until it passes. If a criterion is ambiguous, stop and
ask instead of guessing.

Por qué funciona:

• La entrevista obliga a pensar. Ese es el mecanismo de Agarwal.
• Los criterios de aceptación dan a un revisor —humano o un subagente nuevo— algo contra lo que verificar el diff. Ese es el patrón de Claude Code de «revisar contra tu especificación».
• La verificación indicada convierte «parece terminado» en evidencia de aprobación o fallo. Anthropic considera que esa es la diferencia entre una sesión que supervisas y una que puedes dejar trabajando.

Omite la organización de archivos, la estructura de componentes y la elección de bibliotecas. Los modelos actuales suelen poder leer esos detalles del repositorio, y escribirlos es la parte de una especificación que se desactualiza más rápido (Hallazgo 1 de Agarwal).

Cuándo SDD completo sigue justificando su proceso formal

Guarda el conjunto completo cuando se cumpla cualquiera de estas condiciones:

• Varias personas deben aprobar antes de que exista código: producto, arquitectura, cumplimiento normativo. La especificación es el objeto de revisión.
• Una auditoría o regulación exige una línea trazable desde el requisito hasta la implementación.
• Las restricciones de los sistemas existentes son invisibles en el código: contratos entre servicios, orden de migración, invariantes documentadas solo en especificaciones anteriores. Los participantes de Agarwal reportaron precisamente este fallo: un comportamiento que satisface la tarea inmediata, pero viola una restricción de una especificación anterior.
• El costo de construir lo equivocado supera ampliamente el costo de planificar. SDD traslada el gasto del retrabajo a la planificación (Hallazgo 9 de Agarwal: tokens, tiempo, carga cognitiva). Ese intercambio solo se justifica en trabajos grandes y costosos de revertir.

Reserva recursos para tres modos de fallo conocidos:

• Desviación de la implementación: el agente se aparta de la especificación.
• Desactualización de la especificación: la especificación queda obsoleta a medida que cambia el código. En la muestra de repositorios de Agarwal, el 81.5% de los archivos de especificación tienen un solo commit registrado.
• Deuda de verificación: el mismo agente escribe la especificación, el código y los tests, por lo que un malentendido se propaga a los tres.

Las medidas de mitigación que usaría son: criterios de aceptación bajo responsabilidad humana incluso cuando los agentes redactan todo lo demás, criterios de aceptación convertidos en tests que el agente debe pasar y un revisor que no haya escrito el código.

Alrededor de cada nivel: el harness

El otro cambio de 2026 es que la inversión duradera se desplazó hacia lo que rodea la tarea. El artículo de ThoughtWorks sobre ingeniería del harness (29 de septiembre de 2026) lo plantea como Agente = Modelo + Harness. Las guías orientan antes de actuar (archivos de contexto, restricciones, AGENTS.md/CLAUDE.md). Los sensores verifican después de actuar (tests, linters, CI, agentes de revisión). Entre ambos hay puntos selectivos de aprobación humana.

Esa capa es independiente del nivel y su valor se acumula. Contiene un archivo breve de contexto que solo registra lo que el agente no puede encontrar leyendo el repositorio, además de un comando de verificación en ese archivo. Agrega un hook (un script que se ejecuta automáticamente en un punto determinado del flujo de trabajo del agente) para las reglas que no admiten excepciones. Una especificación corresponde a un cambio y se desactualiza. Un harness corresponde a un repositorio, y cada fallo que detecta lo mejora. Si tienes una hora para invertir, el harness devuelve esa inversión en cada tarea; la especificación, en una sola.

Para la pregunta más amplia sobre la infraestructura de apoyo —cuándo basta un prompt y cuándo los agentes necesitan herramientas, evals y un flujo de trabajo a su alrededor—, consulta ¿Cuándo basta un prompt?.

Ejecuta tu propio experimento

La afirmación central de este artículo es que, para el trabajo individual, probablemente articular sea lo que aporta el beneficio, mientras que guardar el resultado depende de la situación. Tu equipo puede ponerla a prueba en dos semanas con un diseño adaptado de la propuesta de Agarwal:

Distribuye funcionalidades de complejidad media comparables entre los grupos. Registra: tokens totales, tiempo transcurrido, rondas de revisión, defectos o retrabajo en el plazo de una semana y, para los grupos B y C, si alguien necesitó después el artefacto ausente y no pudo reconstruir la intención. Si B ≈ A en calidad y lo supera en costo, guardar el artefacto es una formalidad para trabajos como el tuyo. Si A resulta mejor para el traspaso y reduce las dificultades de auditoría, habrás medido dónde debe situarse el límite de tu Nivel 3. Cualquiera de los dos resultados vale más que este artículo.

Lista de decisiones

Antes de tu próxima funcionalidad, dedica treinta segundos:

1. ¿Diff describible en una frase? → Construye directamente, con una verificación para ejecutar.
2. ¿Enfoque incierto, varios archivos o código desconocido? → Plan mode, itera, implementa y deja que el plan expire.
3. ¿Alguien más —humano o agente— debe reconstruir el porqué después? → Contrato de intención de una página en git.
4. ¿Aprobaciones de equipo, auditoría, restricciones invisibles de sistemas existentes o trabajo costoso de revertir? → SDD completo, criterios de aceptación bajo responsabilidad humana y tests derivados de ellos.
5. En cualquier nivel: ¿puede el agente ejecutar una verificación de aprobación o fallo sin ti? Si no, escribe eso primero. Es más importante que otra página de especificación.

Las guerras de metodologías continuarán; los proveedores lanzarán nuevos niveles y nuevas siglas. La evidencia de 2026 respalda una conclusión más sobria: piensa antes de delegar, escribe solo lo que deba perdurar después de ese proceso de reflexión y asegúrate de que el resultado pueda verificarse. Articula siempre. Especifica a veces.

Fuentes

• Agarwal, Singhal, Macvean, Vasilescu, Breaux, El desarrollo guiado por especificaciones según se prescribe y según se practica — preprint de arXiv, 25 de agosto de 2026. Uso selectivo, desactualización de especificaciones y desviaciones, costos de planificación, hipótesis de la articulación como función que obliga a pensar y propuesta del experimento de entregar o retener la especificación.
• Hill, ¿El desarrollo guiado por especificaciones reduce los defectos? Una prueba empírica de las afirmaciones de la industria en 119 repositorios de código abierto — track Software Engineering in Practice de ESEM, ESEIW 2026, presentado el 9 de octubre de 2026. 88,052 PRs; ninguna hipótesis de proveedores obtuvo respaldo; única señal protectora en repositorios sin adopción de IA (menos retrabajo, p = 0.014); el autor señala la confusión por indicación.
• Liu, Dehghan, Ganhotra, Hirzel, Jabbarvand, Del plan a la acción: ¿qué tan bien siguen los agentes el plan? — ASE 2026. 21,120 trayectorias; un plan estándar ayuda, un mal plan es peor que ninguno y los recordatorios ayudan. Alcance: planes de ejecución de agentes, no especificaciones de funcionalidades.
• Anthropic, Buenas prácticas para Claude Code — página activa consultada el 29 de octubre de 2026 (reescrita; ya no cubre plan mode). Lo que dice realmente: un prompt sencillo en una sesión nueva suele hacer lo correcto por defecto; «Entrevístame hasta que puedas escribir la especificación y luego escríbela en SPEC.md»; una vez que existe SPEC.md, construye a partir de él en una sesión nueva; el revisor verifica el diff contra SPEC.md. Enfoque: «dile a Claude lo que no puede ver, dale una verificación para ejecutar y haz cumplir las reglas que no admiten excepciones».
• Amazon Kiro, Plan mode y Feature Specs — consultados el 29 de octubre de 2026. Niveles de plan y especificación, orientación de 15–60 minutos y pasos de aprobación para alta complejidad, trabajo en equipo y auditoría.
• Nadeem, El plan mode ha muerto — 24 de septiembre de 2026. Análisis retrospectivo de un profesional (n=1); «más información sin aportar más claridad»; planificación ≠ plan.
• GitHub, README de Spec Kit — consultado el 29 de octubre de 2026. Sobre el flujo: enumera /speckit-converge y dice «Repite la implementación y la convergencia hasta que la convergencia informe Converged».
• GitHub, lanzamiento de Spec Kit v1.0.0 — 21 de agosto de 2026. Citado solo por la fecha de lanzamiento; la página del lanzamiento no describe el flujo Converge.
• Reddy Nandyala & Pani, ThoughtWorks, Ingeniería del harness — 29 de septiembre de 2026. Agente = Modelo + Harness; guías, sensores y puntos selectivos de aprobación humana.