Configuracion por agente

La opción --ai de specify init

El punto de partida para configurar Spec Kit con un agente concreto es la opción --ai del comando specify init. Esta opción determina qué directorio de comandos se genera, qué formato se utiliza para los archivos de slash command y qué archivos auxiliares se crean.

specify init mi-proyecto --ai claude

El valor de --ai acepta el nombre del agente en minúsculas: claude, copilot, gemini, cursor, codex, windsurf, qwen, opencode, kilo, auggie, roo, codebuddy, qoder, amazonq, amp, shai, entre otros.

Cuando se omite la opción --ai, Spec Kit genera la configuración para Claude Code como valor por defecto. Este comportamiento refleja el hecho de que Claude Code es el agente con mayor compatibilidad y el que se utilizó como referencia durante el desarrollo de Spec Kit.

El agente seleccionado con --ai no limita el contenido de los artefactos SDD. La constitución, las especificaciones, los planes y las tareas son idénticos independientemente del agente. Solo cambia la forma en que el agente accede a los slash commands.

Directorios y formatos por agente

Cada agente IA tiene su propia convención sobre dónde buscar los archivos de comando y en qué formato los espera. specify init respeta estas convenciones al generar la estructura del proyecto.

Claude Code

Claude Code utiliza el directorio .claude/commands/ con archivos en formato Markdown. Cada archivo .md dentro de este directorio se convierte automáticamente en un slash command disponible en el chat del agente.

.claude/
  commands/
    speckit.constitution.md
    speckit.specify.md
    speckit.clarify.md
    speckit.plan.md
    speckit.analyze.md
    speckit.tasks.md
    speckit.implement.md
    speckit.checklist.md

El nombre del archivo (sin la extensión) determina el nombre del slash command. El archivo speckit.specify.md se invoca como /speckit.specify en el chat.

El contenido de cada archivo es un prompt completo en lenguaje natural que instruye al agente sobre qué hacer cuando el usuario invoca el comando. Este prompt incluye referencias a los templates de .specify/templates/, a la constitución del proyecto y a los artefactos existentes en specs/.

Gemini CLI

Gemini CLI utiliza el directorio .gemini/commands/ con archivos en formato TOML en lugar de Markdown. TOML es un formato de configuración que Gemini CLI parsea para extraer las instrucciones del comando.

.gemini/
  commands/
    speckit.constitution.toml
    speckit.specify.toml
    speckit.clarify.toml
    speckit.plan.toml
    speckit.analyze.toml
    speckit.tasks.toml
    speckit.implement.toml
    speckit.checklist.toml

Un archivo TOML de comando tiene una estructura diferente a su equivalente Markdown. Las instrucciones del prompt se definen dentro de campos TOML con comillas y escapado de caracteres especiales:

[command]
name = "speckit.specify"
description = "Generate a feature specification"

[command.prompt]
content = """
Read the template at .specify/templates/spec-template.md
and generate a specification based on the user's input.
...
"""

El formato TOML impone restricciones de escapado que pueden causar problemas. Las barras invertidas (\) deben escribirse como dobles barras (\\). Si los archivos TOML contienen barras sin escapar, Gemini CLI no puede parsear el archivo y el slash command no aparece en el menú.

GitHub Copilot

GitHub Copilot utiliza el directorio .github/agents/ con archivos Markdown. La integración se produce dentro del IDE (VS Code, JetBrains) a través del panel de Copilot Chat.

.github/
  agents/
    speckit.constitution.agent.md
    speckit.specify.agent.md
    speckit.clarify.agent.md
    ...

En Copilot los archivos de comando usan el sufijo .agent.md. La particularidad de Copilot es que funciona como un agente dentro del IDE, no como una herramienta de línea de comandos independiente. Los slash commands se invocan desde el panel de chat de Copilot, y el agente tiene acceso al contexto del proyecto abierto en el editor.

Cursor

Cursor genera sus archivos de comando en .cursor/commands/ con formato Markdown:

.cursor/
  commands/
    speckit.constitution.md
    speckit.specify.md
    speckit.clarify.md
    ...

Cursor funciona dentro de su propio IDE (un fork de VS Code) y los slash commands se invocan desde el panel de chat integrado. La estructura es similar a la de Claude Code, pero con la diferencia de que Cursor procesa los argumentos de los comandos de forma distinta.

Codex CLI

Codex CLI utiliza .codex/commands/ con formato Markdown. Los comandos se invocan con el prefijo /prompts: en lugar del / estándar:

.codex/
  commands/
    speckit.constitution.md
    speckit.specify.md
    ...

Además del directorio de comandos, Codex CLI requiere que la variable de entorno CODEX_HOME apunte al directorio .codex del proyecto:

export CODEX_HOME=/ruta/al/proyecto/.codex

Sin esta variable configurada, Codex CLI no descubre los archivos de comando.

Windsurf

Windsurf utiliza una convención diferente al resto: .windsurf/workflows/ con archivos Markdown. El término "workflows" en lugar de "commands" refleja la arquitectura interna de Windsurf, donde cada archivo define un flujo de trabajo completo.

.windsurf/
  workflows/
    speckit.constitution.md
    speckit.specify.md
    ...

Archivos de contexto del agente

Más allá de los directorios de slash commands, cada agente puede leer archivos de contexto que proporcionan información general sobre el proyecto. Estos archivos no forman parte de Spec Kit, pero complementan la información que el agente utiliza al ejecutar los slash commands.

| Agente | Archivo de contexto | Ubicación | |---|---|---| | Claude Code | CLAUDE.md | Raíz del proyecto | | Claude Code | AGENTS.md | Raíz del proyecto | | Codex CLI | AGENTS.md | Raíz del proyecto | | Cursor | .cursorrules | Raíz del proyecto | | Gemini CLI | GEMINI.md | Raíz del proyecto |

El contenido de estos archivos varía según el proyecto, pero en el contexto de SDD suelen incluir:

• Referencia a la constitución del proyecto en .specify/memory/constitution.md.
• Convenciones de nombrado y estructura de directorios.
• Stack tecnológico y restricciones del proyecto.
• Instrucciones para respetar la estructura de artefactos SDD.

# CLAUDE.md (ejemplo para un proyecto SDD)

Este proyecto utiliza Spec-Driven Development con
GitHub Spec Kit.

La constitución del proyecto está en:
.specify/memory/constitution.md

Los artefactos SDD se almacenan en: specs/

Antes de implementar cualquier feature, consulta
la especificación y el plan correspondientes.

Configuración multi-agente

Un proyecto puede configurarse para múltiples agentes ejecutando specify init varias veces con diferentes valores de --ai. Cada ejecución crea el directorio correspondiente al agente especificado sin modificar los directorios de agentes anteriores.

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

Tras estas tres ejecuciones, el proyecto contiene tres directorios de comandos:

mi-proyecto/
  .claude/commands/    (8 archivos .md)
  .gemini/commands/    (8 archivos .toml)
  .cursor/commands/    (8 archivos .md)
  .specify/            (compartido)
  specs/               (compartido)

Los tres agentes comparten la misma infraestructura de Spec Kit: los templates, la constitución, los scripts y los artefactos en specs/. Lo único que difiere es el formato y la ubicación de los slash commands.

Esta configuración es útil en equipos donde cada desarrollador utiliza un agente diferente. Un miembro del equipo puede trabajar con Claude Code y otro con Cursor. Ambos generan y consumen los mismos artefactos SDD, lo que garantiza la consistencia del proceso.

La configuración multi-agente no duplica los artefactos SDD. Solo duplica los archivos de slash command en el formato que cada agente necesita. La fuente de verdad sigue siendo única: .specify/ y specs/.

flowchart TB
    subgraph Compartido["Infraestructura compartida"]
        SPEC[".specify/<br>templates, memory, scripts"]
        SPECS["specs/<br>artefactos SDD"]
    end
    subgraph Agentes["Directorios por agente"]
        CLAUDE[".claude/commands/"]
        GEMINI[".gemini/commands/"]
        CURSOR[".cursor/commands/"]
    end
    CLAUDE --> SPEC
    GEMINI --> SPEC
    CURSOR --> SPEC
    CLAUDE --> SPECS
    GEMINI --> SPECS
    CURSOR --> SPECS

Verificar la configuración

Después de inicializar el proyecto, es recomendable verificar que los archivos de comando se han generado correctamente. El comando specify check valida la instalación de la CLI, pero no verifica los archivos del proyecto.

La verificación manual consiste en listar el contenido del directorio de comandos y comprobar que los 8 archivos de slash command están presentes:

ls .claude/commands/

Si algún archivo falta o está malformado, la solución más directa es regenerar la configuración del agente:

specify init --here --force --ai claude

Esta operación sobrescribe los archivos de comando y los de .specify/templates/ (restaurándolos a la versión estándar), pero no modifica la constitución ni los artefactos en specs/.