Anatomía de una especificación

Estructura general del spec.md

El archivo spec.md es el artefacto central de la fase de especificación en SDD. No es un documento de texto libre, sino un documento estructurado con secciones predefinidas que el agente IA genera a partir de la plantilla spec-template.md del proyecto.

Esta estructura estandarizada cumple dos funciones. Para el equipo humano, proporciona un formato predecible que facilita la revisión y la comparación entre especificaciones de diferentes features. Para el agente IA, proporciona un formato que puede interpretar de forma determinista durante las fases de planificación e implementación.

El spec.md no es documentación para archivar. Es un artefacto ejecutable que el agente IA lee y procesa en cada fase posterior del flujo SDD.

Un spec.md completo se organiza en las siguientes secciones principales:

flowchart LR
    SPEC["spec.md"] --> SUM["Resumen de la feature"]
    SPEC --> US["User stories"]
    SPEC --> AC["Criterios de aceptación"]
    SPEC --> NFR["Requisitos no funcionales"]
    SPEC --> EDGE["Edge cases"]
    SPEC --> REVIEW["Checklist de revisión"]

Cada sección tiene un propósito específico y un nivel de detalle calibrado para que la información sea suficiente sin ser redundante.

Resumen de la feature

La primera sección del spec.md contiene una descripción concisa de la funcionalidad: qué hace, para quién y qué valor aporta. Este resumen actúa como el contexto de alto nivel que el agente IA consulta cuando necesita entender la intención general de la feature.

## Feature Summary

Users can create custom calendar events and download
them as .ics files compatible with Google Calendar,
Apple Calendar and Outlook. The system provides a
form-based interface for event creation with real-time
preview before download.

Un buen resumen responde a tres preguntas en dos o tres frases:

• Qué hace la funcionalidad (crear eventos de calendario).
• Quién la usa (los usuarios de la plataforma).
• Por qué es valiosa (permite integrar eventos en aplicaciones de calendario existentes).

El resumen no debe incluir detalles técnicos ni mencionar tecnologías específicas. Si el resumen dice "implementar con React y una API REST en Node.js", está violando la separación entre especificación y planificación técnica.

User stories

Las user stories son el cuerpo principal de la especificación. Cada user story describe una interacción completa entre un actor (usuario, administrador, sistema externo) y la funcionalidad que se está especificando.

Spec Kit genera user stories que siguen el formato estándar "As a... I want... So that...":

## User Stories

### US-1: Create a basic event
As a user, I want to fill in event details (title, date,
start time, end time) so that I can generate a calendar
event with the essential information.

#### Acceptance Criteria
- [ ] The form requires title, date, start time and end time
- [ ] Start time must be before end time
- [ ] The generated .ics file contains all provided fields
- [ ] The .ics file follows RFC 5545 format

### US-2: Add optional event details
As a user, I want to optionally add a location and
description to my event so that attendees have complete
context about the event.

#### Acceptance Criteria
- [ ] Location and description fields are optional
- [ ] Empty optional fields are omitted from the .ics file
- [ ] Location supports free-text input up to 200 characters

Cada user story tiene tres componentes:

• Identificador: un código como US-1, US-2 que permite referenciar la historia en otros documentos (plan, tareas, tests).
• Narrativa: la descripción en formato "As a... I want... So that..." que articula el actor, la acción deseada y la motivación.
• Criterios de aceptación: condiciones específicas y verificables que deben cumplirse para considerar la historia como implementada.

Cómo se escriben buenos criterios de aceptación

Los criterios de aceptación son la parte más importante de cada user story desde la perspectiva del agente IA. Son las condiciones que el agente verifica durante la implementación para determinar si ha completado la tarea correctamente.

Un criterio de aceptación efectivo es:

• Específico: describe un comportamiento observable, no una intención vaga. "El formulario valida los campos" es vago. "El formulario muestra un mensaje de error cuando el título está vacío" es específico.

• Verificable: puede comprobarse con un test automatizado o una verificación manual. "La experiencia del usuario es buena" no es verificable. "La respuesta del servidor se produce en menos de 200ms" sí lo es.

• Independiente: cada criterio describe una condición que puede validarse de forma aislada, sin depender de otros criterios de la misma historia.

Los criterios de aceptación se convierten en tests durante la implementación. Si un criterio no puede traducirse en un test, probablemente es demasiado vago o abstracto.

Requisitos no funcionales

Los requisitos no funcionales (NFRs) definen atributos de calidad que la implementación debe cumplir y que no están directamente relacionados con la funcionalidad visible. Mientras las user stories describen "qué hace el sistema", los NFRs describen "cómo de bien lo hace".

## Non-Functional Requirements

### Performance
- The .ics file generation must complete in under 500ms
  for single events
- The preview must render within 200ms of form changes

### Security
- All user input must be sanitized before inclusion in
  the .ics file to prevent injection attacks
- Generated files must not contain metadata about the
  server or framework

### Accessibility
- The form must be navigable by keyboard
- All form fields must have associated labels for
  screen readers
- Error messages must be announced by assistive
  technology

### Compatibility
- Generated .ics files must be valid according to
  RFC 5545
- Files must import correctly in Google Calendar,
  Apple Calendar and Outlook

Los NFRs se organizan por categorías. Las más comunes son:

• Rendimiento: tiempos de respuesta, capacidad de procesamiento, uso de recursos.
• Seguridad: validación de entrada, sanitización, protección contra ataques.
• Accesibilidad: navegación por teclado, compatibilidad con lectores de pantalla, contraste.
• Compatibilidad: navegadores soportados, dispositivos, formatos de integración.
• Escalabilidad: número de usuarios concurrentes, volumen de datos.

A diferencia de los criterios de aceptación de las user stories, los NFRs aplican de forma transversal a toda la funcionalidad. Un requisito de seguridad como "sanitizar toda entrada de usuario" afecta a todas las user stories que reciben datos del usuario.

Edge cases

La sección de edge cases documenta situaciones límite que requieren un tratamiento explícito. Estas son las situaciones que se descubren cuando alguien pregunta "y qué pasa si..." sobre cada aspecto de la funcionalidad.

## Edge Cases

- What happens if the user sets the same start and end
  time? → Treat as a zero-duration event (allowed in
  RFC 5545)
- What happens if the event date is in the past?
  → Allow it. Users may need to create historical events
  for record-keeping
- What if the title contains special characters like
  semicolons or newlines? → Escape according to
  RFC 5545 rules (section 3.3.11)
- What if the user's browser blocks the file download?
  → Show a fallback link that the user can right-click
  to save

Los edge cases son valiosos porque documentan decisiones de diseño que de otro modo quedarían implícitas. Sin esta sección, el agente IA tomaría decisiones propias sobre cada situación límite, y esas decisiones podrían no alinearse con las expectativas del equipo.

Un edge case bien documentado tiene dos partes: la situación (qué pasa si...) y la decisión (cómo debe comportarse el sistema). Cuando la decisión no está clara, se utiliza el marcador [NEEDS CLARIFICATION].

Marcadores NEEDS CLARIFICATION

Cuando el agente IA genera la especificación y no tiene suficiente información para tomar una decisión, marca el punto con [NEEDS CLARIFICATION]. Estos marcadores son señales explícitas de que hay ambigüedades que el equipo debe resolver antes de avanzar a la fase de planificación.

### US-4: Share event via link
As a user, I want to share my created event via a
public link so that other people can add it to their
calendars without receiving a file attachment.

#### Acceptance Criteria
- [ ] Each event generates a unique shareable URL
- [ ] The URL displays a preview page with event details
- [ ] The preview page includes an "Add to Calendar"
      button
- [ ] [NEEDS CLARIFICATION] Should shared links expire?
      If so, after how long?
- [ ] [NEEDS CLARIFICATION] Should the creator be able
      to revoke a shared link?

Los marcadores [NEEDS CLARIFICATION] cumplen varias funciones:

• Hacen visible la incertidumbre: en lugar de que el agente IA invente una respuesta, marca el punto como pendiente de decisión humana.
• Guían al comando /speckit.clarify: cuando se ejecuta el comando de clarificación, el agente prioriza los puntos marcados con [NEEDS CLARIFICATION] para generar preguntas específicas.
• Actúan como bloqueantes: la checklist de revisión verifica que no queden marcadores [NEEDS CLARIFICATION] sin resolver antes de pasar a la planificación.

Un spec.md con marcadores [NEEDS CLARIFICATION] es un spec.md honesto. Es preferible reconocer ambigüedades explícitamente a generar requisitos inventados que crearán problemas durante la implementación.

Es habitual que la primera versión del spec.md contenga varios marcadores [NEEDS CLARIFICATION]. Esto no indica un fallo del agente, sino que la descripción proporcionada no era lo suficientemente detallada para cubrir todos los aspectos de la funcionalidad. El comando /speckit.clarify está diseñado precisamente para resolver estos puntos de forma estructurada.

Checklist de revisión y aceptación

La última sección del spec.md es una checklist de validación que el equipo utiliza para verificar la calidad y completitud de la especificación antes de avanzar a la fase de planificación.

## Review & Acceptance Checklist

### Content Quality
- [ ] All user stories follow the "As a... I want...
      So that..." format
- [ ] Each user story has at least 2 acceptance criteria
- [ ] Acceptance criteria are specific and testable
- [ ] Non-functional requirements are quantified where
      possible

### Requirement Completeness
- [ ] All NEEDS CLARIFICATION markers have been resolved
- [ ] Edge cases are documented with explicit decisions
- [ ] Error states and empty states are defined
- [ ] No implementation details or technology choices
      are present

### Feature Readiness
- [ ] The spec is self-contained and understandable
      without external context
- [ ] A developer unfamiliar with the project could
      understand the requirements
- [ ] The scope is appropriate (3-8 user stories)

La checklist se organiza en tres bloques:

• Calidad del contenido: verifica que las user stories y los criterios de aceptación cumplen los estándares de formato y precisión.
• Completitud de requisitos: verifica que no quedan ambigüedades, que los edge cases están documentados y que la especificación no contiene detalles técnicos.
• Preparación de la feature: verifica que la especificación es autosuficiente y tiene el alcance adecuado.

Esta checklist no es burocracia adicional. Es un mecanismo de calidad que previene problemas en fases posteriores. Una especificación que pasa la checklist produce planes técnicos más precisos, tareas más accionables e implementaciones más fieles a los requisitos originales.

Archivo requirements.md

Además del spec.md, el comando /speckit.specify genera un archivo requirements.md dentro del subdirectorio checklists/ de la feature. Este archivo complementa la checklist del spec.md con criterios adicionales que el agente IA consulta durante la implementación.

specs/001-crear-eventos-calendario/
  spec.md
  checklists/
    requirements.md

El requirements.md contiene items que verifican la coherencia entre la especificación y la implementación una vez que el código está generado. Mientras la checklist del spec.md se usa antes de planificar, el requirements.md se usa durante y después de la implementación para validar que el resultado final cumple con lo especificado.