Desarrollo guiado por especificaciones: del requisito al código con IA

El objetivo no es producir más documentación. Es dejar un acuerdo breve que permita al fundador rechazar un comportamiento incorrecto, a un ingeniero cuestionar el diseño propuesto y a quien revisa el cambio identificar qué evidencias necesita para aprobar su integración.

Para empezar, elige una funcionalidad acotada en el repositorio que ya usas. Una exportación, una regla de aprobación o una preferencia de notificaciones muestra el valor del método con más claridad que pedirle a un agente que especifique una aplicación entera.

¿Qué es el desarrollo guiado por especificaciones?

El desarrollo guiado por especificaciones con agentes de IA, o spec driven development, consiste en partir de una descripción revisada del comportamiento deseado para orientar la planificación, la creación de tareas, la implementación y la verificación. La especificación define qué debe ocurrir y por qué. El plan explica cómo se conseguirá dentro de la aplicación existente. Las tareas dividen ese plan en trabajo que se puede comprobar.

Antes de la IA, otras prácticas de desarrollo basadas en especificaciones ya las usaban como pruebas ejecutables, como ocurre en el desarrollo guiado por comportamiento o BDD. Esa tradición es compatible con este proceso, pero una especificación en Markdown no es, por sí misma, una prueba ejecutable. Documentación de Cucumber sobre BDD.

El cambio práctico es que los agentes de programación pueden consultar esos documentos durante toda la implementación. GitHub Spec Kit, un conjunto de herramientas de código abierto para estructurar el trabajo de un agente, aporta el proceso que lo rodea. Kiro, el entorno de programación de AWS, integra ese proceso en el producto. Ninguno evita tener que decidir qué experiencia debe recibir el cliente.

Documentación verificada el 13 de octubre de 2026: los nombres de los comandos, las rutas de los archivos y las capacidades que se describen a continuación proceden de la documentación vigente de GitHub, Kiro, Anthropic y OpenAI. El ejemplo de la funcionalidad es ilustrativo; no presenta un despliegue real en producción ni un ensayo con mediciones de productividad.

Para quienes desarrollan, esto acota la implementación: el agente debe aprovechar la aplicación que rodea a la funcionalidad en lugar de rediseñarla. Para responsables de operaciones y fundadores, la revisión más valiosa llega antes: decidir quién puede exportar datos antes de revisar el botón de exportación. Para quienes deciden qué herramientas comprar, adoptar el método no exige trasladar a todo el equipo a otro editor. Empieza con el agente que ya tienes; invierte en más estructura cuando mantener los documentos se convierta en un problema.

Cómo aplicar el desarrollo guiado por especificaciones, paso a paso

Mantén separados los documentos porque cada uno responde a una pregunta distinta. Un diagrama de arquitectura no resuelve una regla de producto pendiente, y una lista de tareas no demuestra que la funcionalidad funcione.

La decisión sobre el comportamiento corresponde al fundador o al responsable de producto. Evaluar si el diseño encaja en el sistema corresponde a quien lidera ingeniería. El agente puede redactar ambas propuestas, pero un texto convincente no demuestra que las decisiones sean correctas.

Herramientas de desarrollo basado en especificaciones: cuánta estructura necesitas

Elige las herramientas según dónde falle la coordinación. GitHub Spec Kit encaja en un repositorio donde buscas un proceso repetible alrededor del agente que ya usas. Kiro sirve a quienes quieren gestionar los requisitos, el diseño y la ejecución de tareas dentro del entorno de programación. Los archivos de texto bastan para una primera funcionalidad o para un equipo que ya revisa el trabajo de forma sistemática.

GitHub Spec Kit: comandos y archivos que debes revisar

GitHub Spec Kit aporta instrucciones reutilizables, plantillas y scripts de apoyo; el trabajo lo realiza el agente de programación que elijas. Su README actual detalla la secuencia principal: establecer los principios del proyecto, especificar la funcionalidad, planificarla, crear tareas, implementarlas y comprobar qué queda pendiente.

El README actual exige Python 3.11 o posterior, uv —un instalador de paquetes de Python— y un agente compatible. El ejemplo de configuración utiliza GitHub Copilot, el asistente de programación de GitHub. Ejecuta lo siguiente en la terminal:

uv tool install specify-cli
specify init my-project --integration copilot
cd my-project

Después, inicia el agente de programación en ese directorio. Ejecuta cada instrucción del proceso en el chat del agente y revisa el resultado antes de continuar. No son comandos de shell.

Conviene distinguir las sintaxis. El README utiliza el formato predeterminado de skills de Copilot, /speckit-specify. La referencia detallada de comandos utiliza el formato con punto, /speckit.specify. La integración de skills de Codex utiliza $speckit-specify. Emplea la sintaxis de la integración que hayas instalado; esos signos no son intercambiables. Referencia de integraciones.

Estos nombres y funciones siguen la referencia de Agentic SDD de GitHub. Clarify, checklist y analyze añaden puntos de control de calidad. La constitución establece reglas permanentes para el proyecto; no la reescribas con cada funcionalidad pequeña.

En el ejemplo de exportación, la instrucción de especificación debe describir quién puede exportar, qué registros se incluyen, qué contiene el archivo y qué ocurre si algo falla. En la etapa de planificación, proporciona las tecnologías existentes y las restricciones del repositorio. Pide pruebas de aceptación de forma explícita: la documentación del comando de tareas indica que genera pruebas cuando se solicitan, así que una lista de tareas generada no demuestra que incluya las pruebas adecuadas.

Estos son los archivos que debes revisar:

• .specify/memory/constitution.md: principios del proyecto. Plantilla de constitución.
• specs/<feature-directory>/spec.md: comportamiento de la funcionalidad. Los directorios de funcionalidades suelen estar dentro de specs/; el nombre del directorio se genera o se configura. Plantilla de especificación.
• plan.md y tasks.md dentro de ese directorio: diseño de la implementación y desglose del trabajo. La planificación también produce research.md, data-model.md y quickstart.md, además de contracts/ para las interfaces externas que correspondan. Plantilla de planificación, referencia de tareas.

Después de la implementación, converge compara el código con la especificación, el plan y las tareas. Si detecta carencias, añade trabajo a tasks.md; no corrige el código por sí mismo. Implementa esas tareas y vuelve a comprobar. Un resultado «Converged» aporta información útil para la revisión, pero no sustituye las pruebas ni la aprobación.

Para una aplicación existente, la guía de adopción de GitHub parte de conservar el estado inicial y realizar la inicialización en el propio proyecto. El comando es specify init --here --force --integration <key>, sustituyendo <key> por la clave documentada de la integración, como claude o codex. La guía advierte que --force puede reemplazar los archivos gestionados que entren en conflicto. Revisa el diff resultante. No hace falta reconstruir las especificaciones de toda la aplicación antes de especificar su próximo cambio.

El límite: Spec Kit puede detectar contradicciones entre documentos y, aun así, dar por válida una regla de negocio equivocada si todos coinciden en ella. El mantenimiento de esos archivos adicionales compensa cuando varias personas o sesiones necesitan trabajar con el mismo acuerdo.

Kiro: especificaciones, steering y hooks

Kiro separa la intención de cada funcionalidad, las directrices permanentes del proyecto y las acciones automáticas. Usa specs para la funcionalidad concreta, steering para las convenciones del repositorio y hooks para las comprobaciones repetibles.

En el IDE, el editor de código de Kiro, haz clic en + dentro de Specs o elige Spec en el chat. Selecciona Feature y después Requirements-First. Revisa los requisitos antes de aceptar el diseño técnico y el desglose de tareas. El directorio resultante contiene .kiro/specs/<feature-name>/requirements.md, design.md y tasks.md. Tras revisar las tareas, ejecútalas desde su interfaz. Documentación de especificaciones de Kiro.

Kiro utiliza EARS, siglas de Easy Approach to Requirements Syntax, para expresar una condición y el comportamiento esperado del sistema. En este ejemplo: «Cuando un miembro solicite una exportación, el sistema deberá denegar la solicitud y no devolver ningún archivo de exportación». La formulación es lo bastante concreta para convertirse en una prueba. Especificaciones de funcionalidades.

Kiro también ofrece Design-First y Quick Spec. Design-First parte del diseño técnico; Quick Spec crea los documentos sin los puntos intermedios de aprobación. Si eres fundador y tu agente sigue interpretando mal lo que quieres, elige Requirements-First y aprovecha esas revisiones. Quitarlas eliminaría precisamente la parte del proceso que resuelve el problema.

Steering aporta contexto permanente en Markdown dentro de .kiro/steering/. Los archivos de base son product.md, tech.md y structure.md, que describen el producto, las tecnologías y la organización del repositorio. En el IDE, Generate Steering Docs crea ese contexto inicial. Contrástalo con el repositorio. Incluye aquí «reutilizar la política existente de autorización por pertenencia al espacio de trabajo» si se aplica a varias funcionalidades; reserva «solo los propietarios pueden exportar» para la especificación de exportación. Documentación de steering.

Los hooks ejecutan comandos de shell o prompts para el agente cuando ocurre un evento. Actualmente, los archivos de hooks del proyecto se guardan en .kiro/hooks/<id>.json; PostFileSave es uno de los eventos documentados. Un hook acotado podría ejecutar las pruebas de exportación existentes al cambiar el código correspondiente. Mantén las mismas comprobaciones en la integración continua —las verificaciones automáticas de los cambios de código propuestos— para que no dependan únicamente de un hook local. La tabla actual de capacidades de Kiro indica que los hooks funcionan en el IDE y la CLI, pero no en Web ni Mobile. Documentación de hooks.

El límite: un requisito generado automáticamente puede formalizar una suposición que nadie ha aprobado. Revisa los permisos, los resultados vacíos y el comportamiento ante fallos antes de pasar al diseño. El modo de especificaciones aporta estructura, pero no toma por ti las decisiones de producto que faltan.

Cómo trabajar con especificaciones en Claude Code

Claude Code, el agente de programación de Anthropic, puede seguir este proceso con una especificación de la funcionalidad y Plan Mode. No necesitas instalar un framework de especificaciones para probar el método.

Crea specs/workspace-export/spec.md o revisa un borrador del agente. Después inicia la sesión de terminal en modo de planificación:

claude --permission-mode plan

Pide a Claude que lea el archivo, examine el código existente relacionado con la exportación y proponga un plan de implementación vinculado a los criterios de aceptación. Antes de aprobar la implementación, solicita las preguntas pendientes y las comprobaciones exactas que pretende ejecutar.

Plan Mode está pensado para investigar y proponer un enfoque. Anthropic documenta una excepción en las sesiones interactivas de terminal donde está disponible la omisión de permisos: en ellas no se aplican los bloqueos de edición del modo de planificación. Si necesitas que se respete el paso de aprobación, inicia la sesión sin habilitar esa omisión. Documentación de modos de permisos.

Tras revisar la propuesta, guarda el enfoque aceptado en specs/workspace-export/plan.md y la lista de tareas en tasks.md; después autoriza la implementación. Estas rutas son una convención sugerida en este artículo, no archivos que Plan Mode prometa crear automáticamente. La guía de Plan Mode de Claude Code explica los controles y el paso de la planificación a la aprobación.

Guarda las instrucciones permanentes del repositorio en CLAUDE.md, siguiendo la guía de memoria de equipo, y el comportamiento específico de la funcionalidad en su especificación. De lo contrario, un requisito temporal de exportación puede convertirse en una instrucción permanente que afecte a trabajos sin relación.

El límite: un plan que solo vive en una conversación puede perderse o contradecirse con facilidad. Guardarlo solo sirve si la implementación y la revisión posteriores lo toman como referencia explícita.

Codex: modo de planificación con el mismo archivo de especificación

Codex, el agente de programación de OpenAI, permite trabajar con estos mismos archivos y pocos pasos adicionales. En un chat de la CLI que esté inactivo, /plan inicia la planificación y puede incluir la petición en la misma línea. Documentación oficial de comandos.

Una petición útil sería: «Lee specs/workspace-export/spec.md. Examina la política de pertenencia al espacio de trabajo, la consulta de tareas y las pruebas existentes. Propón el plan de implementación más pequeño que cumpla todos los requisitos. Identifica las decisiones pendientes antes de implementar».

Revisa el plan, guarda los archivos acordados y después pide a Codex que implemente las tareas y entregue un informe final que relacione cada requisito con su prueba. Usa AGENTS.md para las instrucciones permanentes del repositorio; /init puede generar su estructura inicial. La guía de configuración de Codex CLI explica cómo preparar el entorno.

OpenAI también documenta el uso de Markdown para conservar especificaciones, planes y avances en trabajos largos. Lo valioso es que una sesión posterior pueda volver a consultar el acuerdo. El límite: Plan Mode no mantiene actualizada por sí solo una especificación de funcionalidad guardada aparte. Incluye esa actualización en la revisión de los cambios. Proceso documentado por OpenAI.

Ejemplo práctico: exportar las tareas de un espacio de trabajo a CSV

Una exportación sencilla a CSV —un archivo de registros con valores separados por comas— muestra por qué definir primero el comportamiento puede evitar rehacer varios archivos. «Añade una exportación a CSV» obliga al agente a adivinar el rol del usuario, el alcance de los datos, la paginación y el formato del archivo. Un botón atractivo puede ocultar una respuesta equivocada a cada una de esas preguntas.

El siguiente caso ilustra el proceso en una aplicación de gestión de tareas existente. Las rutas, los identificadores de requisitos y las pruebas propuestas son ejemplos didácticos; no corresponden a un repositorio probado ni a cambios integrados para este artículo.

La especificación en una página

Guarda lo siguiente como spec.md de la funcionalidad o incorpora el mismo contenido sobre su comportamiento en el archivo requirements.md de Kiro:

Observa la decisión que encierra R2: «todos los resultados que coincidan» no equivale a «la página visible». Resolverla antes de implementar cambia de inmediato la consulta y el plan de pruebas. Resolverla después de la demostración puede obligar a revisar ambos.

R4 señala de forma deliberada una decisión que necesita ejemplos concretos. Antes de aprobar la especificación, acuerda cómo se tratarán los valores de entrada que puedan interpretarse como fórmulas en una hoja de cálculo y registra los ejemplos. Escribir «hacer que las exportaciones sean seguras» dejaría en manos del agente una política que te corresponde decidir.

El plan: encajar en la aplicación existente

El plan debe reutilizar la política de sesión y pertenencia al espacio de trabajo, extraer o reutilizar la lógica de filtros de la lista de tareas y añadir una respuesta de exportación sin modificar la respuesta de la lista. La exportación debe pasar por el control de autorización del servidor. Determina el acceso al espacio de trabajo a partir de la pertenencia autenticada y, después, aplica los filtros solicitados dentro de ese ámbito.

Si el repositorio ya utiliza un serializador CSV, elígelo. Define las cabeceras de contenido y descarga, la política de seguridad de los campos, el comportamiento ante errores y las pruebas. Añade el botón utilizando los estados de carga y error que ya tiene la aplicación.

El plan también debe contrastar el tamaño esperado de los resultados con los límites de solicitudes y memoria de la aplicación. Si no es viable exportarlos todos, devuelve el conflicto al responsable de la funcionalidad. Acuerden una exportación acotada o definan por separado el alcance del procesamiento en segundo plano. El agente no debe inventar un máximo sin avisar ni añadir un sistema de trabajos que contradiga R6.

Las tareas: que cada cambio se pueda verificar

Convierte el plan en trabajo que quien revisa pueda reconocer:

1. Recoge el comportamiento actual de la lista de tareas y las reglas compartidas de filtrado en comprobaciones de regresión.
2. Añade pruebas de autorización de solicitudes para un propietario, un miembro, un antiguo propietario y otro espacio de trabajo.
3. Implementa la consulta limitada al ámbito autorizado y la respuesta CSV con la política de campos acordada.
4. Añade el control de exportación, el estado de carga y la presentación de errores.
5. Completa las comprobaciones de aceptación y examina el diff para detectar cambios ajenos a la funcionalidad.

Este desglose corresponde al ejemplo. Una herramienta puede generar una lista distinta; evalúala según cubra o no lo acordado.

En una aplicación TypeScript, el cambio de código que se somete a revisión podría incluir server/exports/tasks.ts para la autorización, el filtrado y la respuesta; ui/tasks/ExportButton.tsx para la interacción; y tests/task-export.test.ts para los casos de aceptación. Son rutas ilustrativas, no convenciones obligatorias de un framework. Un nuevo proceso de colas o una migración de base de datos indicarían un cambio de alcance que debe resolverse antes de integrar el código.

De los criterios de aceptación a la aprobación del cambio

Pide evidencias del comportamiento, no una lista de los archivos que editó el agente. La descripción de la pull request debe conectar los requisitos con comprobaciones como estas:

Quien revise debe contrastar estas comprobaciones con la especificación, examinar el código de autorización y consultas, y probar el flujo de usuario acordado en el entorno habitual de revisión del proyecto. Si el agente escribió tanto la implementación como las pruebas, revisa de forma independiente los resultados esperados. Una prueba puede confirmar fielmente la misma suposición errónea que contiene el código.

Por ejemplo, imagina que la revisión descubre que el endpoint solo lee la página actual. Mantén R2 si el responsable sigue queriendo todos los resultados que coincidan; corrige la consulta y añade una prueba con coincidencias más allá de esa página. Si el responsable cambia el alcance, actualiza R2, el plan y las pruebas de forma conjunta antes de aprobar.

Integra la funcionalidad cuando las evidencias coincidan con lo acordado: incluye en la misma pull request la especificación revisada, el plan final, el registro de tareas completadas, la implementación y las pruebas. Deja allí constancia de cualquier cambio de alcance aceptado. Después de integrar, mantén la especificación como referencia vigente o identifícala como registro histórico de la funcionalidad. Dejar una especificación antigua con apariencia de autoridad prepara la siguiente confusión.

El beneficio está en resolver los permisos y la paginación antes de que las suposiciones se extiendan por la implementación. Después de integrar el cambio, la especificación, las pruebas y el código conservan la misma decisión.

Cuánto cuesta y cuándo compensa

El coste del método es el tiempo de revisión y mantenimiento, además del trabajo del agente para redactar e implementar. Spec Kit es de código abierto, pero el agente de programación que conectes conserva sus propias condiciones de uso. Usar archivos Markdown no añade una suscripción específica para gestionar especificaciones; tampoco hace gratuito el uso del modelo.

Las tarifas comerciales estándar de Kiro, en USD, incluyen Free por $0 al mes con 50 créditos y Pro por $20 por usuario al mes con 1,000 créditos, antes de los impuestos aplicables. Por tanto, cuatro suscripciones Pro cuestan 4 × $20 = $80 al mes, sin incluir créditos adicionales ni impuestos. Es un cálculo del coste de las licencias, no una predicción de cuántas funcionalidades podrás entregar. Página de precios de Kiro.

Los créditos adicionales de pago cuestan $0.04 cada uno. Kiro indica que refinar especificaciones, ejecutar tareas y ejecutar hooks del agente consume créditos, y que una tarea compleja de una especificación puede consumir más de un crédito. No se puede establecer una conversión defendible de «créditos» a «funcionalidades terminadas» sin observar la carga de trabajo real. Definición de los créditos de Kiro.

La prueba económica es sencilla: el coste adicional de especificar, revisar y mantener la funcionalidad debe ser menor que el trabajo de reconstrucción que evita. Registra esos costes en tu propio proceso. Un método que añade documentos pero sigue dejando las mismas decisiones para la revisión del código no justifica el trabajo extra.

¿Qué promesas se exageran y cuándo resulta excesivo?

La promesa exagerada es que un documento lo bastante detallado hará que el agente acierte de forma fiable. No es así. La especificación puede estar equivocada, la implementación puede ignorarla y las pruebas pueden repetir sus suposiciones erróneas.

La distinción útil está entre la intención declarada y el comportamiento que el sistema hace cumplir. Un requisito dice que los miembros no pueden exportar; una comprobación en el servidor y sus pruebas ayudan a imponer esa regla. Una lista de comprobación de requisitos evalúa la descripción. No ejecuta la aplicación. Confundir ambas cosas crea una falsa seguridad.

Otro fallo es que la documentación se aleje del código. Si alguien cambia el comportamiento de los permisos y solo edita el código, el siguiente agente podría «corregir» la aplicación para devolverla a la especificación obsoleta. Exige que los cambios de comportamiento actualicen el acuerdo correspondiente o que este se archive de forma explícita. Conservar más contexto solo ayuda si sigue siendo correcto.

Aplícalo ahora si tu agente pasa por alto de forma repetida permisos, casos límite, integraciones o criterios de aceptación. Usa el proceso en una funcionalidad cuya ambigüedad afecte a varios componentes o revisores.

Pospón la especificación formal si todavía estás averiguando si alguien necesita la funcionalidad. Primero crea un prototipo desechable o investiga lo que aún no sabes. Una especificación impecable de una idea sin validar puede dar por acertada una inversión equivocada.

Mantén simples las correcciones pequeñas cuando el cambio deseado sea evidente y esté localizado: una errata, un ajuste que siga el estilo establecido o un fallo acotado con una prueba de regresión clara. Define el comportamiento esperado y verifícalo. Un ciclo completo de constitución, plan y tareas puede exigir más atención de la que necesita ese cambio.

El criterio para decidir no es el número de líneas de código. Es la cantidad de suposiciones con consecuencias que, de otro modo, tendría que hacer el agente.

Tu primera semana de desarrollo guiado por especificaciones

Elige una funcionalidad pequeña que ya esté entre las tareas pendientes. Pide a su responsable que apruebe una especificación de comportamiento de una página, incluidas las exclusiones y los casos de fallo. Usa el agente que ya tienes en modo de planificación, o el proceso correspondiente de Spec Kit o Kiro, para proponer un plan basado en el repositorio real.

Revisa las preguntas antes de implementar. Pide una lista de tareas vinculada a los requisitos. Al revisar la pull request, contrasta las evidencias con el mismo acuerdo y registra las decisiones que hayan cambiado. Ajusta el peso del proceso al grado de ambigüedad.

Suscríbete al boletín para conocer formas prácticas de crear y operar con IA.