Desarrollo guiado por especificaciones con agentes de IA

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

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

GitHub Spec Kit

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 y un agente compatible en macOS, Linux o Windows.

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 integra las specs en el propio producto. Cada spec tiene tres archivos en .kiro/specs/<nombre>/: 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 <nombre> y ejecutas las tareas con /spec run <nombre>. 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 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.

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 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:

# 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:

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

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

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:

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.

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 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: 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: 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: 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.
• 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
• Prompts para agentes de código con IA
• Task line

Para probar AgentVera, descárgalo.