Agentes soportados y limitaciones reales

Panorama de agentes compatibles

Spec Kit está diseñado para funcionar con múltiples agentes IA de código. El comando specify init genera la estructura de archivos necesaria para que el agente seleccionado pueda ejecutar los slash commands del flujo SDD. La lista de agentes soportados se ha ido ampliando con cada versión de Spec Kit, y actualmente supera los 16 agentes.

Los agentes se clasifican en dos categorías según su nivel de integración:

Agentes con soporte completo: el directorio de comandos se genera correctamente, los slash commands se descubren de forma automática y el flujo SDD funciona sin intervención manual adicional.

Agentes con soporte parcial: el directorio se genera, pero existen limitaciones en el descubrimiento de comandos, en el formato de los argumentos o en la capacidad de ejecutar ciertos flujos. Estas limitaciones requieren configuración manual o workarounds documentados.

La compatibilidad de un agente con Spec Kit no depende solo de la generación de archivos. Depende de cómo el agente descubre los slash commands en su directorio, cómo interpreta los argumentos y cómo gestiona el contexto entre ejecuciones.

Tabla de agentes soportados

La siguiente tabla recoge los agentes soportados, el directorio donde Spec Kit genera los archivos de comando y el formato que utiliza cada agente:

| Agente | Directorio | Formato | Herramienta CLI | |---|---|---|---| | Claude Code | .claude/commands/ | Markdown | claude | | GitHub Copilot | .github/agents/ | Markdown | IDE | | Cursor | .cursor/commands/ | Markdown | cursor-agent | | Gemini CLI | .gemini/commands/ | TOML | gemini | | Codex CLI | .codex/commands/ | Markdown | codex | | Windsurf | .windsurf/workflows/ | Markdown | IDE | | Qwen Code | .qwen/commands/ | TOML | qwen | | opencode | .opencode/command/ | Markdown | opencode | | Kilo Code | .kilocode/rules/ | Markdown | IDE | | Auggie CLI | .augment/rules/ | Markdown | auggie | | Roo Code | .roo/rules/ | Markdown | IDE | | CodeBuddy CLI | .codebuddy/commands/ | Markdown | codebuddy | | Qoder CLI | .qoder/commands/ | Markdown | qoder | | Amazon Q Developer | .amazonq/prompts/ | Markdown | q | | Amp | .agents/commands/ | Markdown | amp | | SHAI | .shai/commands/ | Markdown | shai |

Cada entrada de la tabla representa una combinación de directorio y formato que specify init --ai <agente> genera automáticamente. Un mismo proyecto puede tener múltiples directorios de agente si se inicializa varias veces con diferentes valores de --ai.

Claude Code: el agente de referencia

Claude Code es el agente con el mayor nivel de compatibilidad con Spec Kit. Todos los slash commands (/speckit.constitution, /speckit.specify, /speckit.clarify, /speckit.plan, /speckit.analyze, /speckit.tasks, /speckit.implement, /speckit.checklist) se descubren automáticamente y se ejecutan sin configuración adicional.

La razón de esta compatibilidad total es que Spec Kit fue desarrollado inicialmente con Claude Code como agente principal. El sistema de slash commands de Claude Code lee los archivos .md del directorio .claude/commands/ y los presenta al usuario en el menú de comandos de forma nativa. Cada archivo se convierte en un slash command que el usuario puede invocar directamente.

Claude Code también soporta el modelo de subagentes que /speckit.implement utiliza para la ejecución paralela de tareas. Cuando el agente principal delega una tarea a un subagente, Claude Code crea una instancia independiente con contexto limpio que opera sobre el repositorio y devuelve el control al agente principal al terminar.

$ claude
> /speckit.specify
Create a calendar event management system...

Archivos de contexto de Claude Code

Además de los slash commands, Claude Code utiliza archivos de contexto que complementan el flujo SDD:

• CLAUDE.md: archivo de contexto general del proyecto que Claude Code lee automáticamente al iniciar una sesión. Spec Kit puede incluir directivas aquí para que el agente conozca la estructura SDD del proyecto.
• AGENTS.md: archivo con instrucciones específicas para el agente que define convenciones, restricciones y patrones del proyecto.

Estos archivos no son parte de Spec Kit propiamente dicho, pero su presencia mejora la calidad de los artefactos generados al proporcionar contexto adicional al agente.

Limitaciones reales por agente

Gemini CLI y Qwen Code

Gemini CLI y Qwen Code utilizan archivos TOML en lugar de Markdown para definir los slash commands. Durante las primeras versiones de Spec Kit, los archivos TOML generados contenían caracteres de barra invertida (\) sin escapar, lo que provocaba errores de parseo. El resultado era que solo el comando /speckit.constitution se descubría correctamente, mientras que el resto fallaba con errores de "Unknown command".

Este problema se corrigió en versiones posteriores de Spec Kit con el escapado correcto de barras invertidas (\\). Sin embargo, proyectos inicializados con versiones anteriores pueden seguir afectados. La solución es regenerar los archivos de comando con specify init --here --force --ai gemini.

# Error típico en versiones anteriores
> /speckit.implement

✕ Unknown command: /speckit.implement

Gemini CLI tiene una particularidad adicional: el descubrimiento de slash commands depende de la versión de la CLI. Versiones antiguas pueden no soportar el formato TOML generado por Spec Kit. La recomendación es mantener Gemini CLI actualizada.

Codex CLI

Codex CLI utiliza una convención de invocación diferente al resto de agentes. Los slash commands no se invocan con /speckit., sino con el prefijo /prompts::

# Invocación estándar (Claude Code, Cursor, etc.)
/speckit.constitution

# Invocación en Codex CLI
/prompts:speckit.constitution

Además, Codex CLI requiere que la variable de entorno CODEX_HOME apunte al directorio .codex del proyecto para que los comandos se descubran correctamente. Sin esta configuración, el agente no encuentra los archivos de comando.

Otro problema documentado con Codex CLI es que algunos agentes de esta familia modifican los archivos de template durante la ejecución de /speckit.constitution, cuando el comportamiento esperado es escribir únicamente en .specify/memory/constitution.md. Si esto ocurre, es necesario restaurar los templates originales con specify init --here --force.

Cursor

Cursor descubre los slash commands correctamente, pero presenta un problema con el paso de argumentos. Cuando el usuario invoca un comando con argumentos adicionales (por ejemplo, /speckit.specify Create a calendar system), Cursor puede enviar solo el nombre del comando sin el argumento, lo que produce una ejecución incompleta.

La solución temporal es proporcionar los argumentos en un mensaje separado después de invocar el slash command, en lugar de incluirlos en la misma línea.

GitHub Copilot y Windsurf

GitHub Copilot y Windsurf funcionan dentro del entorno del IDE, no como herramientas de línea de comandos. El descubrimiento de slash commands depende de cómo cada IDE implementa la lectura de los directorios de comandos. En ambos casos, la integración es funcional pero el nivel de soporte para subagentes y ejecución paralela es más limitado que en Claude Code.

Cómo elegir un agente

La elección del agente depende de varios factores que van más allá de la compatibilidad técnica con Spec Kit:

Si se necesita el flujo SDD completo sin restricciones, Claude Code es la opción más fiable. Es el único agente que soporta todos los slash commands, subagentes para ejecución paralela y descubrimiento automático sin configuración adicional.

Si el equipo ya utiliza un agente específico y no quiere migrar, la recomendación es inicializar Spec Kit con ese agente y verificar que los slash commands se descubren correctamente. Si hay problemas, aplicar los workarounds documentados para cada agente.

Si se trabaja en un equipo con múltiples agentes, es posible inicializar Spec Kit para varios agentes en el mismo proyecto. Cada agente tendrá su propio directorio de comandos, pero todos comparten los mismos templates, la misma constitución y los mismos artefactos en specs/.

specify init --here --ai claude
specify init --here --force --ai gemini
specify init --here --force --ai cursor

Esta secuencia genera los directorios .claude/commands/, .gemini/commands/ y .cursor/commands/ en el mismo proyecto. Cada miembro del equipo puede usar el agente que prefiera, y los artefactos SDD producidos son compatibles entre todos.

La decisión del agente no condiciona la calidad de los artefactos SDD. Los templates y la constitución son los mismos independientemente del agente. Lo que cambia es la experiencia de usuario durante la ejecución de los comandos.

Estado actual y evolución

La compatibilidad entre Spec Kit y los diferentes agentes IA es un área en evolución activa. Cada actualización de Spec Kit mejora el soporte para agentes existentes y añade nuevos. Cada actualización de los propios agentes puede mejorar o romper la integración, dependiendo de los cambios en sus sistemas de descubrimiento de comandos.

La práctica recomendada es mantener actualizados tanto Spec Kit (uv tool upgrade specify-cli) como el agente IA en uso. Cuando una actualización del agente rompe la integración, regenerar los archivos de comando con specify init --here --force --ai <agente> suele resolver el problema.