Estructura de directorios de Spec Kit

Visión general del scaffolding

Cuando specify init se ejecuta, genera una estructura de directorios diseñada para separar la infraestructura SDD del código fuente del proyecto. Esta separación es intencional: los archivos de Spec Kit viven en directorios propios y no interfieren con la organización existente del código.

La estructura completa de un proyecto inicializado con --ai claude tiene este aspecto:

mi-proyecto/
  .specify/
    memory/
      constitution.md
    templates/
      spec-template.md
      plan-template.md
      tasks-template.md
      checklist-template.md
    scripts/
      bash/
        prepare-feature.sh
        post-checkout.sh
  .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
  specs/

Cada directorio tiene una responsabilidad clara dentro del flujo SDD. Los tres bloques principales son .specify/ (infraestructura interna), el directorio del agente (slash commands) y specs/ (artefactos generados).

La estructura generada sigue el principio de separación de responsabilidades: la infraestructura de Spec Kit, la configuración del agente y los artefactos de trabajo se almacenan en directorios independientes.

El directorio .specify/

El directorio .specify/ es el corazón de la infraestructura de Spec Kit. Contiene tres subdirectorios, cada uno con una función específica.

.specify/memory/

La carpeta memory/ almacena archivos que persisten contexto compartido entre sesiones y comandos. El archivo principal es constitution.md, que contiene los principios de gobernanza del proyecto. Este directorio actúa como la "memoria a largo plazo" de Spec Kit: la información que aquí se almacena está disponible para todos los slash commands y no depende de la sesión del agente IA.

.specify/memory/
  constitution.md

La constitución se genera con el slash command /speckit.constitution y define las reglas inmutables del proyecto: convenciones de código, patrones arquitectónicos, restricciones tecnológicas y preferencias del equipo.

.specify/templates/

La carpeta templates/ contiene las plantillas que definen la estructura de cada artefacto SDD. Cuando el agente IA ejecuta un slash command como /speckit.specify o /speckit.plan, utiliza estas plantillas para generar los documentos con un formato consistente.

.specify/templates/
  spec-template.md
  plan-template.md
  tasks-template.md
  checklist-template.md

Cada plantilla incluye secciones predefinidas, placeholders y directrices que guían al agente IA para producir artefactos con la estructura esperada. Por ejemplo, spec-template.md define las secciones de user stories, criterios de aceptación y requisitos no funcionales que toda especificación debe contener.

Los templates se pueden personalizar para adaptar la estructura de los artefactos a las necesidades del equipo. Sin embargo, cualquier personalización se sobrescribe al actualizar Spec Kit, por lo que conviene mantener un backup de las modificaciones.

.specify/scripts/

La carpeta scripts/ contiene scripts auxiliares que automatizan operaciones de soporte del flujo SDD. Según el sistema operativo (o la opción --script usada en la inicialización), esta carpeta contendrá un subdirectorio bash/ o powershell/:

.specify/scripts/
  bash/
    prepare-feature.sh
    post-checkout.sh

Los scripts típicos incluyen:

• prepare-feature: crea la estructura de directorios para una nueva feature dentro de specs/, generando el subdirectorio numerado y los archivos base.
• post-checkout: hook de Git que se ejecuta al cambiar de rama, actualizando el contexto de Spec Kit para apuntar a la feature correspondiente.

Estos scripts son auxiliares, no obligatorios. El flujo SDD funciona sin ellos, pero automatizan tareas repetitivas que de otro modo habría que realizar manualmente.

El directorio del agente IA

Cada agente IA espera encontrar los slash commands en un directorio y formato específicos. specify init genera este directorio según el valor de --ai:

| Agente | Directorio | |---|---| | Claude Code | .claude/commands/ | | GitHub Copilot | .github/agents/ | | Cursor | .cursor/commands/ | | Gemini CLI | .gemini/commands/ | | Codex CLI | .codex/commands/ | | Windsurf | .windsurf/workflows/ |

Dentro de este directorio, cada slash command tiene su propio archivo. Para Claude Code, la estructura es:

.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

Cada archivo contiene el prompt completo que el agente ejecuta cuando el usuario invoca el slash command correspondiente. Estos prompts referencian los templates de .specify/templates/, la memoria de .specify/memory/ y los artefactos existentes en specs/, construyendo así el contexto que el agente necesita para generar artefactos coherentes.

Los archivos del directorio del agente son la interfaz entre Spec Kit y el agente IA. Adaptan los mismos templates y flujos SDD al formato que cada agente espera.

Formato de los archivos de comando

El formato varía según el agente. La mayoría usa Markdown con instrucciones en lenguaje natural que el agente interpreta como directivas. Gemini CLI y Qwen Code usan TOML en lugar de Markdown. En todos los casos, el contenido define:

• Qué plantilla utilizar para generar el artefacto.
• Qué archivos de contexto leer (constitución, especificaciones previas, código existente).
• Qué estructura debe tener la salida generada.
• Qué validaciones aplicar antes de finalizar.

El directorio specs/

El directorio specs/ es donde se almacenan los artefactos generados durante el flujo SDD. A diferencia de .specify/ (que contiene infraestructura) y el directorio del agente (que contiene configuración), specs/ contiene el trabajo real del equipo: especificaciones, planes y tareas.

Inicialmente, specs/ está vacío. A medida que se trabaja con los slash commands, se van creando subdirectorios numerados para cada feature:

specs/
  001-autenticacion-usuarios/
    spec.md
    plan.md
    tasks.md
    research.md
    data-model.md
    contracts/
      api-auth.md
  002-gestion-notificaciones/
    spec.md
    plan.md

Cada subdirectorio sigue la convención de numeración NNN-nombre-feature, donde el número se asigna automáticamente y el nombre se deriva de la rama Git o de la descripción proporcionada al especificar.

Artefactos dentro de cada feature

Los archivos que se generan dentro de cada feature dependen de las fases del flujo SDD que se hayan completado:

| Archivo | Fase | Contenido | |---|---|---| | spec.md | Especificación | User stories, criterios de aceptación, NFRs | | plan.md | Planificación | Stack, arquitectura, contratos de API | | tasks.md | Tareas | Lista de tareas con dependencias | | research.md | Planificación | Investigación técnica previa | | data-model.md | Planificación | Modelo de datos del feature | | contracts/ | Planificación | Contratos de API detallados |

No todos los archivos se generan en cada feature. El flujo es progresivo: spec.md se crea con /speckit.specify, plan.md con /speckit.plan y tasks.md con /speckit.tasks. Si una feature es sencilla, puede que no necesite research.md ni contracts/.

El directorio specs/ está protegido durante las actualizaciones de Spec Kit. Ejecutar specify init --here --force nunca modifica ni elimina los archivos de specs/, garantizando que el trabajo realizado se preserve.

Relación entre los directorios

Los tres bloques de directorios funcionan de forma coordinada durante la ejecución de un slash command:

flowchart LR
    U["Usuario invoca<br>slash command"] --> AC["Directorio del agente<br>.claude/commands/"]
    AC -->|Lee templates| T[".specify/templates/"]
    AC -->|Lee contexto| M[".specify/memory/"]
    AC -->|Lee artefactos| S["specs/"]
    AC -->|Genera artefactos| S

Cuando el usuario ejecuta, por ejemplo, /speckit.plan:

• El agente lee el archivo speckit.plan.md de su directorio de comandos, que contiene las instrucciones del slash command.
• Las instrucciones referencian el template plan-template.md de .specify/templates/ para conocer la estructura esperada.
• El agente consulta la constitución en .specify/memory/ para aplicar los principios del proyecto.
• El agente lee la especificación (spec.md) de la feature actual en specs/.
• El agente genera el plan (plan.md) y lo escribe en el directorio de la feature dentro de specs/.

Esta arquitectura permite que los templates y la configuración del agente evolucionen de forma independiente. Se puede actualizar un template sin modificar los slash commands, o añadir soporte para un nuevo agente sin tocar la estructura de specs/.