Spec-Driven Multi-Agente: agtx, GSD y spec-kit

TL;DR: El desarrollo spec-driven resuelve el mayor problema de los agentes de IA: que actúen sobre intenciones vagas en lugar de especificaciones concretas. Herramientas como agtx, GSD y spec-kit permiten orquestar múltiples agentes asignando cada fase del desarrollo a un modelo diferente mediante configuración TOML, sin abandonar la terminal. Este artículo explica cómo funciona cada capa y cómo combinarlas en un flujo real.

El problema del "vibe coding" a escala

¿Cuántas veces has lanzado un agente de IA con una descripción vaga y esperado que el resultado fuera útil? Al principio funciona. El agente escribe código, añade tests, hace commits. Pero en proyectos de más de dos o tres días, algo se rompe: el agente pierde el hilo, empieza a "reparar" lo que ya funcionaba, o decide que el módulo de autenticación necesita una refactorización completa cuando tú solo pedías corregir un bug de validación.

Este fenómeno tiene nombre: context rot. A medida que la ventana de contexto se llena de conversación, decisiones parciales e intentos fallidos, la calidad del output del agente cae. No es que el modelo empeore: es que su memoria de trabajo se satura de ruido hasta que la señal queda enterrada.

La respuesta que está emergiendo en 2026 no es usar un modelo más grande. Es cambiar el enfoque: spec-driven development, donde el agente trabaja contra una especificación formal en lugar de una conversación libre. Y cuando hay múltiples agentes involucrados, necesitas una capa de orquestación que asigne el agente correcto a cada fase.

¿Qué es el desarrollo spec-driven con agentes de IA?

El desarrollo spec-driven aplicado a IA es un enfoque en el que se formaliza una especificación completa antes de que el agente escriba una línea de código. Esa especificación incluye historias de usuario, criterios de aceptación y un desglose de tareas concreto, todo en archivos de texto versionados junto al código.

La diferencia con el flujo habitual es fundamental: en lugar de una conversación abierta donde el agente infiere qué quieres, el agente opera contra documentos como requirements.md, design.md y tasks.md que actúan como fuente de verdad inmutable. Esto no es nuevo en ingeniería de software, pero aplicarlo sistemáticamente con agentes de IA es lo que diferencia proyectos funcionales de caos.

Si ya trabajas con patrones como los descritos en Claude Code Auto-Memory, entenderás por qué la persistencia de contexto es crítica: los archivos de spec son exactamente eso, memoria externa estructurada que el agente puede consultar en cualquier punto del ciclo de vida.

El ecosistema en 2026: tres capas complementarias

Herramienta	Nivel	Rol principal	Instalación
spec-kit	Plantillas	Genera estructura de specs y comandos por agente	GitHub CLI / manual
GSD	Workflow	Ciclo PLAN → BUILD → COMMIT sin context rot	`npx get-shit-done-cc@latest`
agtx	Orquestación	Kanban terminal: asigna agentes distintos por fase	Script curl (binario Rust)

Las tres herramientas resuelven problemas distintos y se pueden usar de forma independiente o combinada. spec-kit es el punto de entrada: te da la estructura de archivos. GSD es el método de ejecución: te dice cómo usar esa estructura con el agente. agtx es la capa de orquestación: gestiona qué agente trabaja en cada fase del kanban.

spec-kit: la estructura que ancla al agente

spec-kit es el toolkit oficial de GitHub para spec-driven development con agentes de IA, actualmente en v0.1.4 a febrero de 2026. Su objetivo es resolver el problema central del agentic coding: que los agentes necesitan guía frecuente para hacer lo correcto.

La estructura que genera es simple: tres archivos markdown que sirven como especificación viva del proyecto.

# Estructura generada por spec-kit
specs/
  requirements.md    # Historias de usuario + criterios de aceptación
  design.md          # Decisiones de arquitectura y estructura
  tasks.md           # Lista priorizada de tareas concretas

Lo relevante de spec-kit desde la perspectiva multi-agente es su sistema de adaptadores. Soporta Claude Code, Gemini CLI, GitHub Copilot, Cursor y Windsurf, y genera los archivos de comandos en el formato nativo de cada agente. La distinción clave es el formato de placeholder: $ARGUMENTS para agentes basados en Markdown y {{args}} para agentes basados en TOML. Un mismo template de workflow se convierte en comandos compatibles con cada runtime sin edición manual.

GSD: cero context rot con tres pasos

GSD (Get Stuff Done) es un sistema de meta-prompting y context engineering que combate el context rot con un mecanismo concreto: máximo tres tareas por plan, cada plan ejecutado en un sub-agente con 200.000 tokens limpios. Cuando el sub-agente termina, su contexto se descarta. Solo persiste el output como artefacto de archivo. El hilo principal nunca acumula el peso del trabajo de implementación.

El ciclo es un embudo de tres fases:

PLANNING: el agente analiza el gap entre spec y código actual, genera una lista priorizada de máximo tres tareas. Sin implementación, sin commits.
BUILDING: asume que el plan existe, implementa, ejecuta tests y hace commit por cada tarea. Si los tests fallan, aplica backpressure antes de continuar.
Loop: repite hasta que todas las tareas estén completadas, cada iteración con contexto limpio.

La instalación cubre los tres runtimes principales de forma simultánea:

# Instala GSD para Claude Code (global)
npx get-shit-done-cc --claude --global

# Para Gemini CLI
npx get-shit-done-cc --gemini --global

# Para OpenCode
npx get-shit-done-cc --opencode --global

# Verifica la instalación en Claude Code
ls ~/.claude/commands/
# → gsd-plan.md  gsd-build.md  gsd-review.md

Una vez instalado, el flujo desde Claude Code es directo:

# Fase 1: genera el plan (sin tocar código)
/gsd-plan

# Fase 2: implementa las tareas del plan
/gsd-build

# GSD hace commit de cada tarea individualmente
# git log --oneline muestra:
# a3f1b2c feat: add user authentication endpoint
# 9e4d7a1 feat: add JWT validation middleware
# 2c8f3e0 test: add auth integration tests

El enfoque git-céntrico es intencional: cada tarea es un commit separado, reversible y trazable. Si el agente se equivoca en la tarea 2, puedes hacer git revert sin perder el trabajo de las tareas 1 y 3. Esto conecta con los patrones de reducción de tokens en Claude Code: GSD no solo reduce el context rot, también optimiza el consumo de tokens al limpiar el contexto entre iteraciones.

agtx: kanban multi-agente en la terminal

agtx es donde el spec-driven se convierte en orquestación multi-agente real. Es un kanban board nativo de terminal, escrito en Rust, que gestiona tareas con ciclo de vida completo: Backlog → Planning → Running → Review → Done. Lo que lo diferencia es que cada fase puede ejecutarse con un agente diferente.

La configuración global vive en ~/.config/agtx/config.toml:

[agents]
planning = "claude"    # Claude analiza y genera el plan
running  = "codex"     # Codex implementa (más rápido en generación)
review   = "claude"    # Claude revisa con más criterio

[plugins]
default = "gsd"        # Plugin activo por defecto

Cada proyecto puede sobreescribir la configuración global con su propio .agtx/config.toml. Cuando una tarea pasa de Planning a Running, agtx termina el agente de planificación y lanza el de implementación automáticamente, preservando el estado del worktree de git. Si ya usas Hooks y Skills de Claude Code, agtx despliega automáticamente tus skills al directorio .claude/commands/ de cada worktree.

La arquitectura de aislamiento usa tmux más git worktrees: cada tarea recibe su propia ventana tmux y su propio worktree, lo que significa que puedes tener cinco tareas en Running simultáneamente sin interferencias entre ellas.

Plugins spec-driven en agtx

agtx incluye cuatro plugins integrados: void (sesión limpia sin prompting automático), agtx (workflow por defecto), gsd (integración directa con GSD) y spec-kit (workflow de GitHub con tracking de artefactos). Un plugin personalizado es un único archivo TOML:

# .agtx/plugins/mi-workflow/plugin.toml

[commands]
planning = "/project:spec-analyze"
running  = "/project:implement"
review   = "/project:review-checklist"

[artifacts]
# La fase Planning termina cuando existe este archivo
planning = ["specs/tasks.md"]
running  = ["src/", "tests/"]

[prompts]
planning = "Analiza el spec en specs/requirements.md y genera tasks.md con máximo 3 tareas para: {task}"

El sistema de artefactos actúa como barrera de calidad declarativa: agtx verifica la existencia de los archivos especificados antes de permitir el avance al siguiente estado. Si specs/tasks.md no existe, la tarea no puede pasar de Planning a Running.

Implementación práctica: flujo completo

El flujo completo para un proyecto nuevo combina las tres capas. El paso manual y deliberado es el segundo: el humano escribe el spec, no el agente.

# 1. Copiar plantillas de spec-kit al proyecto
git clone https://github.com/github/spec-kit /tmp/spec-kit
cp -r /tmp/spec-kit/templates/. specs/

# 2. Editar specs/requirements.md con historias de usuario reales
# (este paso es intencionalmente manual)

# 3. Instalar GSD para Claude Code
npx get-shit-done-cc --claude --global

# 4. Inicializar agtx con plugin gsd
agtx init --plugin gsd

# 5. Añadir primera tarea al kanban
agtx task add "Implementar endpoint de autenticación JWT"

# 6. Mover a Planning (Claude planifica contra el spec)
agtx task move  planning

# 7. Mover a Running (Codex implementa el plan generado)
agtx task move  running

El resultado es un pipeline donde Claude planifica contra los docs de spec, Codex implementa con velocidad, y Claude vuelve para la revisión final. Cada commit es atómico, trazable y revertible. Este patrón se complementa bien con revisión cruzada multi-agente, donde un segundo modelo actúa como crítico independiente antes de mergear.

En Producción

Antes de adoptar este stack en un equipo, hay consideraciones importantes que cambian respecto a los tutoriales.

Coste por sesión. GSD lanza un sub-agente por cada iteración del loop, lo que implica múltiples sesiones de Claude Code o Codex en paralelo. En el plan Pro de Claude (~20 euros/mes a enero de 2026), el límite de sesiones concurrentes puede convertirse en un cuello de botella si tienes tres o cuatro tareas en Running simultáneamente. Asignar Codex como agente de Running en agtx puede reducir costes, ya que su modelo de precios es diferente. Vale la pena monitorizar el consumo con las técnicas descritas en el post sobre control de tokens en tiempo real.

Tamaño del spec. Un requirements.md demasiado detallado consume tokens en cada llamada al agente. El equilibrio práctico: historias de usuario en requirements.md (2-4 líneas por historia), decisiones de arquitectura en design.md (listas, no prosa) y tasks.md generado por el agente durante el PLANNING, no escrito a mano.

Compatibilidad con tmux. agtx requiere tmux 3.3 o superior. En entornos CI/CD sin tmux disponible, el flujo de agtx no funciona directamente. Para pipelines automatizados, GSD standalone es más portable.

Context rot residual. GSD limita el context rot, pero no lo elimina completamente en tareas complejas. Si una tarea individual implica más de 200 líneas de cambios, divídela antes de asignarla al agente. El límite de 3 tareas por plan es una heurística, no una garantía de calidad.

Errores Comunes y Depuración

Error: el agente ignora el spec y empieza desde cero.
Causa: el archivo specs/requirements.md no está referenciado en el prompt del plugin.
Solución: añadir en la sección [prompts] del plugin TOML una referencia explícita: "Trabaja contra specs/requirements.md. No implementes nada que no esté en ese documento."

Error: agtx no detecta el cambio de agente al mover de fase.
Causa: el proceso tmux del agente anterior no ha terminado de forma limpia.
Solución: agtx session clean <task-id> elimina la sesión tmux del worktree y permite relanzar desde cero.

Error: GSD hace commit de todas las tareas en uno solo.
Causa: versión de GSD anterior al soporte de sub-agentes por tarea.
Solución: npx get-shit-done-cc@latest --claude --global actualiza a la versión con aislamiento por sub-agente.

¿Son incompatibles spec-kit, GSD y agtx entre sí?

No, son complementarias. spec-kit genera la estructura de archivos. GSD define el ciclo de ejecución. agtx orquesta qué agente ejecuta cada fase. Puedes usar spec-kit más GSD sin agtx si solo tienes un agente. Puedes usar agtx sin GSD si prefieres tus propios plugins. La combinación de las tres capas es la opción más estructurada para proyectos de varios días.

¿Funciona este stack con Gemini CLI además de Claude Code?

Sí. GSD se instala simultáneamente para Claude Code, OpenCode y Gemini CLI con el mismo paquete npm. agtx soporta Gemini como agente asignable por fase. Si ya usas Gemini CLI con soporte MCP, puedes asignarlo a la fase de Planning aprovechando su ventana de contexto de 1 millón de tokens para analizar specs grandes sin perder información.

¿Cuánto tiempo lleva configurar este stack desde cero?

Entre 20 y 40 minutos para un desarrollador que ya usa Claude Code o Gemini CLI. La instalación de GSD es inmediata vía npm. agtx requiere tmux y descarga un binario Rust precompilado. spec-kit es copiar plantillas y editarlas. La curva de aprendizaje está en definir bien el spec inicial, no en la configuración técnica.

El spec es el contrato, no el prompt

La transición de vibe coding a spec-driven no es solo una cuestión de herramientas. Es un cambio de mentalidad: el spec es el contrato entre tú y el agente, y cualquier ambigüedad en ese contrato se convierte en comportamiento inesperado del modelo. Herramientas como agtx, GSD y spec-kit reducen la fricción operativa de este enfoque, pero el trabajo de definir qué quieres construir sigue siendo tuyo.

Lo que cambia es que ahora tienes una infraestructura que hace que el agente respete esa definición de principio a fin, con commits atómicos, contexto limpio por iteración y el agente correcto en cada fase. Si estás construyendo algo con más de tres días de trabajo agéntico, vale la pena invertir una hora en configurar este stack. El tiempo que pierdes en configuración lo recuperas en la primera sesión donde el agente no improvisa lo que tú no especificaste.

¿Has probado algún enfoque spec-driven en tus proyectos con agentes? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. El siguiente tema que quiero explorar es cómo los sistemas de aprobación remota encajan con este stack para sesiones completamente autónomas.