Sistema de templates

Qué son los templates y dónde se encuentran

Los templates son archivos Markdown que definen la estructura estándar de los artefactos que los slash commands generan. Cuando el agente IA ejecuta /speckit.specify, no improvisa la estructura del spec.md desde cero. En su lugar, lee el template correspondiente (spec-template.md) y utiliza las secciones, placeholders y directrices que contiene para producir un documento con un formato predecible y consistente.

Los templates se almacenan en el directorio .specify/templates/ del proyecto:

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

Cada archivo corresponde a un tipo de artefacto del flujo SDD. El agente IA sabe qué template usar porque los archivos de slash command (en .claude/commands/, .gemini/commands/, etc.) contienen referencias explícitas a la ruta del template correspondiente.

Los templates son la conexión entre la estructura estándar del flujo SDD y los artefactos concretos de cada proyecto. Modificar un template modifica la estructura de todos los artefactos futuros que se generen con el slash command asociado.

Cómo funciona un template

Un template no es un documento estático que se copia. Es un conjunto de instrucciones estructuradas que el agente IA interpreta para generar el artefacto. El template combina secciones fijas, placeholders que el agente completa con información del proyecto y directrices que guían el comportamiento del agente durante la generación.

Anatomía de un template

Un template típico contiene tres tipos de elementos:

Secciones fijas: definen la estructura del documento resultante. El template de especificaciones, por ejemplo, establece que todo spec.md debe tener secciones de user stories, criterios de aceptación y requisitos no funcionales. Estas secciones aparecen en todos los artefactos generados con ese template.

Placeholders: marcadores que el agente reemplaza con información específica de la feature. Por ejemplo, {{FEATURE_NAME}} se sustituye por el nombre de la feature actual, {{FEATURE_NUMBER}} por el número de feature asignado.

Directrices para el agente: instrucciones en lenguaje natural que indican al agente cómo debe comportarse durante la generación. Estas directrices no aparecen en el artefacto final, sino que guían las decisiones del agente.

# Spec Template

## Feature: {{FEATURE_NAME}}

### User Stories

Generate user stories from the user's input.
Each user story must follow the format:
"As a [role], I want [capability] so that [benefit]"

Include acceptance criteria for each user story.

### Non-Functional Requirements

List NFRs related to performance, security,
accessibility and scalability.

Mark any requirement that cannot be determined
from the input with [NEEDS CLARIFICATION].

### Edge Cases

Identify and document edge cases for each
user story.

El template de especificaciones (spec-template.md)

El spec-template.md define la estructura de los archivos spec.md generados por /speckit.specify. Este template establece las secciones obligatorias que toda especificación debe contener:

• User stories con el formato "As a... I want... so that..." y criterios de aceptación para cada una.
• Requisitos no funcionales (NFRs) organizados por categoría (rendimiento, seguridad, accesibilidad).
• Edge cases identificados para cada user story.
• Marcadores [NEEDS CLARIFICATION] en los puntos que requieren clarificación.

Cuando el agente ejecuta /speckit.specify, lee este template y genera un spec.md que respeta esta estructura. El resultado es un documento donde las secciones son predecibles y la información está organizada de forma estándar.

El template de planificación (plan-template.md)

El plan-template.md define la estructura de los archivos plan.md generados por /speckit.plan. Este template incluye directrices específicas:

• Constitution Check: instrucciones para que el agente verifique la constitución del proyecto antes de empezar a planificar.
• Technical Context: sección para el stack tecnológico, dependencias y restricciones del proyecto.
• Complexity Tracking: tabla para documentar violaciones de principios constitucionales aceptadas.
• Pre-Implementation Gates: checkpoints de simplicidad, anti-abstracción e integración que el plan debe superar.

El template de planificación es particularmente detallado porque la fase de planificación involucra decisiones técnicas que deben ser coherentes con la constitución del proyecto. Las directrices del template guían al agente para que cada decisión pase por los filtros de los principios constitucionales.

El template de tareas (tasks-template.md)

El tasks-template.md define la estructura del tasks.md generado por /speckit.tasks. Este template establece:

• El formato de las tareas individuales con task ID, marcador [P], etiqueta [US] y file path.
• La organización en fases (Setup, Foundational, User Stories, Polish).
• Los checkpoints de validación entre fases.
• La sección de dependencias y orden de ejecución.

El template de checklist (checklist-template.md)

El checklist-template.md define la estructura de los informes de validación generados por /speckit.checklist. Establece los cinco criterios de evaluación (completitud, claridad, consistencia, cobertura y medibilidad) y el formato para reportar los gaps detectados.

Personalización de templates

Los templates se pueden editar directamente en .specify/templates/ para adaptar la estructura de los artefactos a las necesidades del equipo. Esta personalización es útil cuando el formato estándar no se ajusta al flujo de trabajo o a las convenciones internas del proyecto.

Casos de uso para personalizar templates

Añadir secciones obligatorias: si el equipo necesita que toda especificación incluya una sección de "Impacto en documentación" o "Requisitos de migración de datos", se puede añadir esa sección al spec-template.md. El agente generará artefactos que incluyan esa sección.

### Data Migration Requirements

If this feature modifies existing data structures,
document the migration strategy:
- Backward compatibility requirements
- Rollback plan
- Estimated data volume affected

Modificar directrices del agente: si el equipo quiere que los planes técnicos siempre incluyan un análisis de costes de infraestructura, se puede añadir esa directriz al plan-template.md:

### Infrastructure Cost Analysis

Estimate the infrastructure cost impact of
the proposed architecture. Include compute,
storage and network costs for the expected
traffic volume.

Adaptar el formato de tareas: si el equipo utiliza un sistema de gestión de tareas externo (Jira, Linear, GitHub Issues), se puede modificar el tasks-template.md para que cada tarea incluya un campo de referencia externa:

Task format:
- [ ] T001 [US1] [JIRA-XXX] Description in src/path

Restricciones de la personalización

La personalización de templates tiene una limitación importante: las actualizaciones de Spec Kit sobrescriben los templates. Cuando se ejecuta specify init --here --force para actualizar Spec Kit, los archivos de .specify/templates/ se reemplazan por las versiones más recientes del toolkit.

flowchart LR
    CUSTOM["Templates<br>personalizados"] --> UPDATE["specify init<br>--here --force"]
    UPDATE --> OVERWRITE["Templates<br>sobrescritos"]
    BACKUP["Backup de<br>templates"] --> RESTORE["Restaurar<br>personalizaciones"]
    OVERWRITE --> RESTORE

La práctica recomendada para mantener personalizaciones es:

• 1. Crear un backup de los templates personalizados antes de actualizar Spec Kit.
• 2. Ejecutar la actualización con specify init --here --force --ai <agente>.
• 3. Comparar los templates actualizados con el backup para identificar cambios relevantes introducidos por la nueva versión.
• 4. Reintegrar las personalizaciones en los templates actualizados, adaptándolas si la nueva versión ha modificado la estructura base.

Mantener los templates personalizados en un archivo separado (por ejemplo, templates-custom-notes.md) facilita la reintegración tras las actualizaciones. Este archivo no forma parte de Spec Kit y no se sobrescribe.

Relación entre templates y slash commands

Los templates no funcionan de forma aislada. Son referenciados por los archivos de slash command del directorio del agente. Cada archivo de slash command contiene una instrucción que indica al agente qué template leer antes de generar el artefacto.

flowchart LR
    USER["Usuario invoca<br>/speckit.plan"] --> CMD[".claude/commands/<br>speckit.plan.md"]
    CMD -->|Lee| TPL[".specify/templates/<br>plan-template.md"]
    CMD -->|Lee| CONST[".specify/memory/<br>constitution.md"]
    CMD -->|Genera| PLAN["specs/NNN/plan.md"]

Esta arquitectura significa que modificar un template afecta a todos los agentes configurados en el proyecto. Si se personaliza plan-template.md, los planes generados por Claude Code, Gemini CLI y Cursor utilizarán la misma estructura personalizada, porque todos leen el mismo template.

El archivo de slash command también puede añadir instrucciones específicas del agente que complementan las directrices del template. Por ejemplo, el archivo speckit.implement.md de Claude Code puede incluir instrucciones para utilizar subagentes durante la implementación, una capacidad que no tiene sentido para agentes sin soporte de subagentes.

Templates y calidad de los artefactos

La calidad de los artefactos SDD depende directamente de la calidad de los templates. Un template bien diseñado produce artefactos completos, coherentes y fáciles de revisar. Un template pobre produce artefactos con secciones faltantes, información desorganizada o directrices ambiguas que el agente interpreta de forma inconsistente.

Los templates que incluye Spec Kit por defecto están diseñados para cubrir la mayoría de los casos de uso sin necesidad de personalización. La recomendación para equipos que empiezan con SDD es utilizar los templates estándar durante los primeros proyectos y personalizarlos solo cuando se identifiquen patrones recurrentes que justifiquen el cambio.