# Desarrollo guiado por especificaciones con agentes de IA URL: https://agentvera.dev/es/blog/spec-driven-development-with-ai/ · Publicado: 2026-10-28 Desarrollo guiado por especificaciones con agentes de IA: spec, plan, tareas, código y verificación. Spec Kit, Kiro, OpenSpec y plan modes comparados, con ejemplo. **En resumen:** - En el desarrollo guiado por especificaciones primero escribes en un archivo de spec qué construir y cómo comprobarlo; luego el agente planifica, divide el trabajo en tareas, lo construye y se verifica contra la spec. - GitHub Spec Kit, las specs de Kiro y OpenSpec te dan archivos y comandos para este ciclo; el plan mode de Claude Code y Codex solo cubre el paso de planificación. - No necesitas ninguna herramienta para empezar: un spec.md corto con criterios de aceptación, un plan que de verdad leas y una tarea por prompt te dan la mayor parte del beneficio. El desarrollo guiado por especificaciones (spec-driven development) es una forma de trabajar con agentes de código con IA en la que una spec escrita va antes que cualquier línea de código. Describes qué construir, por qué y cómo sabrás que está terminado. El agente convierte esa spec en un plan técnico, divide el plan en tareas pequeñas, las implementa una a una y el resultado se verifica contra los criterios de aceptación de la spec. La spec, el plan y las tareas son archivos de tu repositorio, no mensajes perdidos en un chat, así que sobreviven a la sesión y se pueden revisar como el código. Esta guía explica el ciclo, compara las herramientas que lo soportan a octubre de 2026 (GitHub Spec Kit, las specs de Kiro, OpenSpec y los plan modes de Claude Code y Codex), recorre un ejemplo pequeño con un archivo de spec real y sus prompts, y enumera los errores habituales. Los datos de cada herramienta se comprobaron en octubre de 2026 en su documentación oficial y su repositorio. ## Por qué la spec importa más con agentes Un desarrollador que recibe un ticket vago hace preguntas. Un agente que recibe un prompt vago suele adivinar, escribe código verosímil y te dice que ha terminado. La distancia entre «el código está escrito» y «la funcionalidad hace lo que querías» es de donde sale casi todo el retrabajo. Una spec cierra esa distancia de tres maneras: - **Obliga a decidir antes.** Los casos límite, los estados de error y lo que queda fuera quedan por escrito antes de que el agente elija por ti. - **Da a cada paso la misma fuente de verdad.** El plan, las tareas y la revisión apuntan a un archivo, no a lo que recuerdas de una conversación. - **Hace que «terminado» se pueda comprobar.** Los criterios de aceptación convierten la revisión de «parece que está bien» en «el criterio 3 pasa, este es el test». Nada de esto es nuevo: los documentos de requisitos y las pruebas de aceptación son ideas antiguas. Lo que ha cambiado es que los agentes son tan rápidos que escribir la spec es ahora la parte lenta y valiosa, y el código, la barata. ## El ciclo: spec, plan, tareas, implementación, verificación | Paso | Qué produces | Quién trabaja | Qué compruebas | | --- | --- | --- | --- | | Spec | Qué y por qué: objetivo, usuarios, lo que queda fuera, criterios de aceptación | Tú, con el agente haciendo preguntas | ¿Hay algo ambiguo o que falte? | | Plan | Cómo: arquitectura, archivos, modelo de datos, riesgos | Agente | ¿Encaja con el código y las restricciones? | | Tareas | Pasos pequeños y ordenados, cada uno con una forma de probarlo | Agente | ¿Cada tarea se puede revisar de una sentada? | | Implementación | Código, una tarea cada vez | Agente | Diff, tests, nada fuera de la tarea | | Verificación | Pruebas para cada criterio de aceptación | Agente o un segundo revisor | Cada criterio pasa con pruebas, no con una afirmación | Dos reglas hacen que el ciclo funcione. Primera: la **spec habla de comportamiento** y el **plan de implementación**. «Los usuarios pueden restablecer su contraseña por correo» va en la spec; «añadir una tabla `reset_tokens`» va en el plan. Segunda: **para y revisa en cada paso**. Todas las herramientas de abajo están construidas alrededor de esa pausa; si te la saltas, el desarrollo guiado por especificaciones vuelve a ser un prompt largo. ## Herramientas para el desarrollo guiado por especificaciones | Herramienta | Qué es | Dónde vive la spec | Comandos clave | Licencia o precio (octubre de 2026) | | --- | --- | --- | --- | --- | | GitHub Spec Kit | Una CLI más skills/comandos para tu agente actual | `spec.md`, `plan.md`, `tasks.md` por funcionalidad | `/speckit-specify`, `/speckit-plan`, `/speckit-tasks`, `/speckit-implement` | MIT, gratis | | Specs de Kiro | Integradas en el IDE, la CLI y la app web de Kiro | `.kiro/specs//` | `/spec new `, `/spec run ` en la CLI | Plan gratuito con 50 créditos, planes de pago desde 20 $ al mes | | OpenSpec | Una CLI más comandos para tu agente actual | `openspec/changes//` | `/opsx:propose`, `/opsx:apply`, `/opsx:archive` | MIT, gratis | | Plan mode de Claude Code | Un modo de permisos: investiga y planifica, sin editar | En la conversación, salvo que lo guardes | Shift+Tab, `/plan`, `--permission-mode plan` | Incluido en Claude Code | | Plan mode de Codex | Un modo de trabajo de la CLI de Codex | En la conversación, salvo que lo guardes | `/plan`, más `/goal` para un objetivo persistente | Incluido en Codex | ### GitHub Spec Kit [Spec Kit](https://github.com/github/spec-kit "GitHub Spec Kit") es el kit de GitHub para el desarrollo guiado por especificaciones. Llegó a la 1.0 este año y, a octubre de 2026, la última versión es la v1.2.4. No sustituye a tu agente: la CLI `specify` instala plantillas y comandos en el proyecto, y tú ejecutas los pasos en el chat de tu agente. Necesita Python 3.11 o superior, [uv](https://docs.astral.sh/uv/ "uv") y un agente compatible en macOS, Linux o Windows. ```bash uv tool install specify-cli specify init my-project --integration claude # en un repositorio existente: specify integration install claude ``` La lista de integraciones cubre más de 40 agentes, entre ellos Claude Code (`claude`), Codex CLI (`codex`), Gemini CLI (`gemini`), GitHub Copilot (`copilot`), Cursor (`cursor-agent`), Kiro CLI (`kiro-cli`), opencode, Qwen Code y Amp. La documentación escribe los comandos como `/speckit.specify` y similares; cómo los teclees depende del agente. En Claude Code se instalan como skills en `.claude/skills/` y se invocan como `/speckit-specify`; en Codex son `$speckit-specify`. El camino corto es `specify → plan → tasks → implement → converge`. Para funcionalidades que van a producción, la documentación recomienda el camino completo: 1. `/speckit-constitution`, una vez por proyecto, para principios como las reglas de testing. 2. `/speckit-specify` escribe la spec de la funcionalidad a partir de una descripción sencilla. 3. `/speckit-clarify` hace hasta cinco preguntas concretas y escribe las respuestas en la spec. 4. `/speckit-plan` escribe el plan técnico según tu stack y tus restricciones. 5. `/speckit-checklist` genera «tests unitarios para tus requisitos». 6. `/speckit-tasks` produce un `tasks.md` ordenado por dependencias. 7. `/speckit-analyze` es una comprobación de coherencia de solo lectura entre spec, plan y tareas. 8. `/speckit-implement` va completando las tareas en orden. 9. `/speckit-converge` compara el código con la spec y añade a `tasks.md` el trabajo que falte. Repites implement y converge hasta que converge informa `Converged`. La documentación aconseja ejecutar cada comando por separado y revisar el resultado antes del siguiente. ### Specs de Kiro [Kiro](https://kiro.dev/docs/specs/ "Specs de Kiro") integra las specs en el propio producto. Cada spec tiene tres archivos en `.kiro/specs//`: `requirements.md` (o `bugfix.md` para un bug), `design.md` y `tasks.md`. Los requisitos se escriben en notación EARS, con la forma «WHEN [condición] THE SYSTEM SHALL [comportamiento]». Las specs de funcionalidades pueden empezar por los requisitos o por el diseño, y Quick Spec genera los tres archivos de una vez sin las paradas de aprobación intermedias. En la CLI de Kiro empiezas con `/spec new ` y ejecutas las tareas con `/spec run `. Cuando ejecutas todas las tareas, Kiro construye un grafo de dependencias a partir de `tasks.md` y lanza las tareas independientes en oleadas paralelas. A octubre de 2026, Kiro tiene un plan gratuito con 50 créditos y planes de pago desde 20 $ por usuario y mes. Kiro es la mejor opción si quieres el flujo de specs con una interfaz de revisión integrada y no te importa trabajar dentro de Kiro. Si prefieres seguir en Claude Code o Codex, Spec Kit u OpenSpec encajan mejor. ### OpenSpec [OpenSpec](https://github.com/Fission-AI/OpenSpec "OpenSpec") es una alternativa más ligera, con licencia MIT, organizada en torno a cambios. `/opsx:propose add-dark-mode` crea `openspec/changes/add-dark-mode/` con `proposal.md`, una carpeta `specs/` de requisitos y escenarios, `design.md` y `tasks.md`. `/opsx:apply` completa las tareas y `/opsx:archive` mueve el cambio al archivo y actualiza las specs. `/opsx:explore` es un paso para pensar antes de comprometerte con una propuesta. ```bash npm install -g @fission-ai/openspec@latest # requiere Node.js 20.19.0+ cd your-project openspec init ``` También hay un binario independiente y una fórmula de Homebrew. La forma de escribir los comandos cambia según el agente, por ejemplo `$openspec-propose` en Codex; `openspec init` muestra la forma correcta para las herramientas que elijas. A octubre de 2026, la última versión es la v1.15.0. ### Plan mode en Claude Code y Codex Los plan modes cubren un paso del ciclo: el plan. En el [plan mode de Claude Code](/es/blog/claude-code-plan-mode/ "Plan mode de Claude Code") el agente lee archivos, explora y después propone un plan; las ediciones siguen bloqueadas hasta que apruebas. Se activa con Shift+Tab, con `/plan` delante de un prompt o con `claude --permission-mode plan`. La CLI de Codex tiene `/plan`, que pasa el chat a plan mode y admite la primera petición en la misma línea, por ejemplo `/plan Propose a migration plan for this service`. Codex tiene además `/goal`, que fija un objetivo persistente para una tarea grande y se puede pausar, reanudar o borrar. Los plan modes encajan bien en un flujo guiado por specs sin herramientas extra. Lo que falta es persistencia: pide al agente que escriba el plan aprobado y las tareas en archivos, para que la siguiente sesión parta de ellos y no de cero. ## Un ejemplo práctico: un archivo de spec y cuatro prompts Esta es la versión hazlo-tú-mismo, que funciona con Claude Code, Codex o cualquier agente que lea archivos. La funcionalidad: limitar los inicios de sesión fallidos en una pequeña aplicación web. ### 1. Escribe la spec Guárdala como `specs/login-rate-limit/spec.md`: ```markdown # Login rate limiting ## Goal Slow down password guessing on POST /login without bothering normal users. ## Non-goals - No CAPTCHA. - No change to how passwords are stored. ## Acceptance criteria 1. WHEN an IP has 5 failed logins within 15 minutes, THE SYSTEM SHALL answer further attempts with HTTP 429 for 15 minutes. 2. WHEN a login succeeds, THE SYSTEM SHALL reset that IP's failure count. 3. The 429 response SHALL include a Retry-After header in seconds. 4. Limits SHALL be configurable through LOGIN_MAX_FAILS and LOGIN_WINDOW_MIN. 5. Existing login tests SHALL still pass, and new tests SHALL cover 1–4. ## Constraints - Use the existing Redis connection; no new services. ## Open questions - Should the limit be per IP, per account, or both? ``` Que no pase de una pantalla. La sección de preguntas abiertas está ahí a propósito: le da al agente un sitio para poner pegas antes de planificar. También puedes escribir la spec en español; los agentes leen ambos idiomas. ### 2. Aclara y planifica Empieza en plan mode y señala el archivo al agente: ```text Read specs/login-rate-limit/spec.md and the auth code. First, ask me about anything ambiguous, starting with the open questions. Then write a plan to specs/login-rate-limit/plan.md: files to change, data stored in Redis and its expiry, how each acceptance criterion will be tested, and risks. Don't edit any source files. ``` Responde a las preguntas y luego lee el plan. Pon pegas a todo lo que ignore una restricción. ### 3. Divídelo en tareas ```text Turn plan.md into specs/login-rate-limit/tasks.md: a numbered checklist of tasks small enough to review in one diff. For each task, list the files it touches and the test that proves it. Order them by dependency. ``` ### 4. Implementa una tarea cada vez ```text Do task 1 from specs/login-rate-limit/tasks.md only. Run the tests, tick the task in tasks.md, and stop. Tell me if the spec or plan turned out to be wrong. ``` Una tarea por prompt mantiene los diffs pequeños y te da un punto natural de revisión. Si una tarea revela que la spec estaba mal, corrige primero la spec y luego sigue. ### 5. Verifica contra la spec Cuando terminen las tareas, comprueba el resultado contra la spec, mejor en una sesión nueva o con otro agente, para que quien revisa no sea quien escribió el código: ```text Read specs/login-rate-limit/spec.md. For each acceptance criterion, find the code and the test that cover it, run the tests, and report PASS or FAIL with evidence. Don't change any code. ``` Ese es el ciclo completo. Haz commit de la carpeta `specs/` junto al código, para que la siguiente persona, o el siguiente agente, vea por qué el código es como es. Para escribir bien los prompts en sí, mira [prompts para agentes de código con IA](/es/blog/prompts-for-ai-coding-agents/ "Prompts para agentes de código con IA"). ## Errores habituales - **Specs que en realidad son planes.** Si la spec nombra tablas y funciones, el agente no puede proponer un diseño mejor y quien revisa no distingue comportamiento de implementación. Deja el «cómo» en `plan.md`. - **Specs demasiado largas.** Una spec de diez páginas se come el contexto y nadie la lee, tampoco el agente. Una pantalla por funcionalidad es un buen límite; divide las grandes. - **Aprobar sin leer.** Una spec o un plan sin leer es solo un prompt más lento. La pausa de revisión es la clave. - **Tareas demasiado grandes.** Si una tarea produce un diff que no puedes revisar de una sentada, divídela. - **Dejar que la spec se desactualice.** Cuando el código te enseñe algo, actualiza la spec. Una spec que contradice el código es peor que no tener ninguna. - **Que verifique quien lo escribió.** El agente que escribió el código tiende a dar por bueno su propio trabajo. Usa una sesión nueva, otro modelo o una persona para la comprobación final. - **Usarlo para todo.** Un arreglo de una línea no necesita spec. Reserva el proceso para funcionalidades con casos límite o varios archivos. - **Meter las reglas del proyecto en cada spec.** Las reglas fijas, como los comandos de test y el estilo de código, van en [CLAUDE.md o AGENTS.md](/es/blog/claude-md-agents-md/ "CLAUDE.md y AGENTS.md") o en una constitution de Spec Kit, no en cada spec de funcionalidad. ## Desarrollo guiado por especificaciones en AgentVera AgentVera es una app de escritorio para macOS, Windows y Linux que ejecuta Claude Code, Codex, Kiro y otras CLI de código una al lado de otra. Cada panel es la CLI real, así que los comandos de Spec Kit, los de OpenSpec, el `/spec` de Kiro y el plan mode funcionan igual que por separado. Algunas funciones de AgentVera siguen la misma forma de spec, plan, construcción y verificación: - **[Task line](/es/features/task-line/ "Task line"):** una línea fija de agentes de Análisis, Plan, Construcción y Revisión. Cada tarea lleva criterios de aceptación, Análisis escribe `01-analiz.md`, Plan escribe `02-plan.md` y el revisor marca cada criterio con pruebas. Una tarea rechazada vuelve a Construcción con los hallazgos. - **[AgentVera Verify](/es/features/verify/ "AgentVera Verify"):** toma los criterios de aceptación del mensaje que envías a un agente y, cuando termina su turno, un verificador aparte lee el diff, ejecuta los comandos de test permitidos y marca cada criterio como superado o fallido. El verificador no puede editar archivos. - **[Equipo paralelo](/es/features/parallel-team/ "Equipo paralelo"):** un agente divide un trabajo grande en hasta 8 partes, cada una con su prompt, criterios de aceptación, archivos esperados y dependencias, las ejecuta en worktrees separados y las une en una rama y un PR. - **Kanban de equipo:** puedes enviar una tarjeta a un agente de código como tarea y su respuesta vuelve como comentario. Mira [kanban para agentes de IA](/es/blog/kanban-for-ai-agents/ "Kanban para agentes de IA"). - **Revisión de código automática:** cuando termina un turno, el modelo de Claude que elijas revisa el código y lista los hallazgos con enlaces archivo:línea. La task line, Verify, el equipo paralelo y el kanban de equipo están en los planes Pro y Team. Si solo necesitas los archivos de spec y los comandos, Spec Kit y OpenSpec son gratis y funcionan en cualquier terminal; AgentVera ayuda cuando varios agentes trabajan con specs a la vez. ## Conclusión El desarrollo guiado por especificaciones consiste en escribir el «qué» y el «cómo sabré que está bien» antes de que el agente escriba código, y en atar cada paso posterior a ese archivo. Empieza con un `spec.md` de una pantalla y el plan mode. Pasa a Spec Kit u OpenSpec cuando quieras plantillas y comprobaciones de coherencia, o a Kiro si quieres el flujo integrado en el editor. Elijas lo que elijas, revisa en cada paso y verifica contra los criterios, no contra el resumen del agente. Sigue leyendo: - [Plan mode de Claude Code](/es/blog/claude-code-plan-mode/ "Plan mode de Claude Code") - [Prompts para agentes de código con IA](/es/blog/prompts-for-ai-coding-agents/ "Prompts para agentes de código con IA") - [Task line](/es/features/task-line/ "Task line") Para probar AgentVera, [descárgalo](/es/download/ "Descargar AgentVera"). ## Preguntas frecuentes **¿Qué es el desarrollo guiado por especificaciones?** Es una forma de trabajar con agentes de código con IA en la que una especificación escrita va antes que el código. Describes qué construir, por qué y cómo sabrás que funciona; el agente lo convierte en un plan y en tareas, escribe el código y el resultado se comprueba contra la spec. **¿En qué se diferencia del plan mode?** El plan mode de Claude Code o Codex hace que el agente proponga un plan antes de editar nada, pero el plan vive en una sola conversación. En el desarrollo guiado por especificaciones, la spec, el plan y las tareas son archivos del repositorio que sobreviven a la sesión y se pueden revisar, versionar y usar después para comprobar. **¿Necesito GitHub Spec Kit o Kiro?** No. Un spec.md con objetivo, lo que queda fuera y criterios de aceptación, un plan que revisas y una tarea por prompt ya es desarrollo guiado por especificaciones. Spec Kit, Kiro y OpenSpec añaden plantillas, comandos y comprobaciones de coherencia. **¿GitHub Spec Kit es gratis?** Sí. Spec Kit tiene licencia MIT. A octubre de 2026, la CLI specify se instala con uv tool install specify-cli y necesita Python 3.11 o superior y un agente de código compatible. **¿Cuándo no compensa?** En arreglos de una línea, experimentos rápidos y cambios que puedes describir por completo en una frase. Escribir una spec lleva tiempo; resérvala para funcionalidades que tocan varios archivos, tienen casos límite o las van a construir varios agentes. --- **Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/