Introducción a SPEC-KIT y su integración con CODEX

¿Qué es y por qué utilizarlo?

  • En el desarrollo tradicional, el código fuente suele ser la "fuente de verdad", mientras que los documentos de requisitos, especificaciones y diseño son solo apoyos complementarios.
  • En el enfoque SDD (Desarrollo Dirigido por Especificaciones), el flujo se invierte: la especificación es primaria, y el código es la "expresión de la implementación" de dicha especificación.
  • Una especificación debe ser "ejecutable" — suficientemente clara, completa y sin ambigüedades como para poder "generar" un sistema funcional.
  • El flujo de desarrollo se compone de "Especificación → Plan de Implementación → Tareas → Código", en lugar de "primero escribir código y luego completar la documentación".

Etapas clave del proceso

A continuación se describen las fases esenciales, cada una con su propósito, actividades y entregables.

Fase Nombre Objetivo Actividades clave Entregable
0 Constitución Establecer principios de gobernanza/directrices de desarrollo del proyecto Definir principios del proyecto (estilo de código, estándares de prueba, restricciones arquitectónicas, etc.) constitution.md
1 Especificación Definir "qué voy a hacer", por qué, y cuál es el alcance Aclarar objetivos, usuarios, alcance, criterios de éxito, restricciones spec.md
2 Planificación Una vez claro el "qué", definir el "cómo" Selección de pila tecnológica, diseño arquitectónico, modelo de datos, contratos de interfaz plan.md (+ subdocumentos)
3 Tareas Convertir el plan en una lista de tareas ejecutables y asignables Descomponer módulos del plan, definir tareas, responsables, condiciones de finalización tasks.md
4 Implementación Ejecutar las tareas, implementar código, pruebas y lanzamiento Escribir código, pruebas, integración, despliegue Sistema/funcionalidad completa + pruebas + documentación

Fases de soporte adicionales (opcionales)

  • Aclaración: Durante la fase de especificación, cuando hay elementos que necesitan clarificación ("NEEDS CLARIFICATION"), se lleva a cabo esta actividad.
  • Análisis: En fases como planificación/tareas, se realiza una verificación de consistencia y cobertura entre documentos.
  • Lista de verificación: Genera listas de verificación de calidad personalizadas, como "todas las historias de usuario tienen pruebas" o "las definiciones de interfaz incluyen códigos de error".
  1. Instalación e integración con CODEX

Instalar Specify

Existen dos métodos principales para la inicialización:

# Método 1: Instalación explícita y luego inicialización
# Primero, instalar la herramienta de línea de comandos
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Luego, inicializar el proyecto
specify init NOMBRE_DEL_PROYECTO  # Parámetros opcionales: --here, selección de codex, sh

# Método 2: Inicialización directa con uvx (todo en un paso)
uvx --from git+https://github.com/github/spec-kit.git specify init NOMBRE_DEL_PROYECTO

Comando rápido recomendado:

uvx --from git+https://github.com/github/spec-kit.git specify init mi-proyecto --ai codex --script sh

Estructura de directorios después de la inicialización

.
├── .codex
│   └── prompts
│       ├── speckit.analyze.md
│       ├── speckit.checklist.md
│       ├── speckit.clarify.md
│       ├── speckit.constitution.md
│       ├── speckit.implement.md
│       ├── speckit.plan.md
│       ├── speckit.specify.md
│       └── speckit.tasks.md
└── .specify
    ├── memory
    │   └── constitution.md
    ├── scripts
    │   └── bash
    │       ├── check-prerequisites.sh
    │       ├── common.sh
    │       ├── create-new-feature.sh
    │       ├── setup-plan.sh
    │       └── update-agent-context.sh
    └── templates
        ├── agent-file-template.md
        ├── checklist-template.md
        ├── plan-template.md
        ├── spec-template.md
        └── tasks-template.md

Uso de los comandos speckit.* en CODEX

A diferencia de otros asistentes como claude-code, en CODEX no se pueden invocar directamente los comandos speckit.*. En su lugar, se utilizan haciendo referencia a los archivos de instrucciones correspondientes.

Ejemplo de uso en CODEX:

.codex/prompts/speckit.constitution.md [Argumentos de la tarea]

Este enfoque sigue el principio de "desarrollo dirigido por especificaciones".

  1. Ejemplo práctico: Módulo de comentarios ("Comentarios y respuestas de usuarios")

Supongamos que deseamos añadir una funcionalidad de "Comentarios y respuestas de usuarios" a una plataforma online de productos.

Fase 0: Constitución (Principios y acuerdos del proyecto)

Objetivo

Establecer los principios a nivel de proyecto, acuerdos del equipo y límites técnicos que guiarán todas las especificaciones, planes y tareas posteriores.

Contenido (Ejemplo)

  • Principios del proyecto:
    • Toda funcionalidad nueva debe seguir el enfoque de Especificación Primera (Spec First): la documentación de especificaciones es el artefacto principal, el código es su implementación.
    • Las funcionalidades deben soportar internacionalización (i18n) y ser aptas para dispositivos móviles.
    • Los datos de comentarios deben cumplir con políticas de privacidad y normativas (p.ej., no almacenar información personal sensible).
    • El servicio debe ser escalable, considerando escenarios de alto volumen de comentarios concurrentes.
  • Acuerdos técnicos:
    • Backend principal: Java + Spring Boot; Base de datos: PostgreSQL.
    • Tiempo de respuesta de la API objetivo: ≤ 300 ms.
    • Todas las nuevas interfaces deben incluir pruebas automatizadas (unitarias + de integración) con cobertura ≥ 80%.
  • Acuerdos de documentación:
    • Cada funcionalidad debe contar con tres documentos: spec.md (especificación), plan.md (plan) y tasks.md (lista de tareas).
    • La ruta de almacenamiento de documentos seguirá el patrón specs/feature-xxx/.

Entregable

Archivo constitution.md (o una página dedicada en la Wiki del proyecto) que registre estos principios y acuerdos.

Fase 1: Especificación

Objetivo

Definir con claridad "qué vamos a hacer", por qué, cuáles son los criterios de éxito, y cuál es el alcance y los límites. Evitar requisitos ambiguos.

Contenido (Ejemplo)

Contexto

El módulo de exhibición de productos actual de la plataforma no soporta comentarios de usuarios. Los usuarios desean poder publicar comentarios en la página de un producto, ver los comentarios de otros y responderlos. Esta funcionalidad fomentará la interacción comunitaria y aumentará la retención de usuarios.

Objetivos funcionales
  • Permitir que los usuarios publiquen comentarios sobre un producto.
  • Permitir que los usuarios respondan a un comentario existente (una única respuesta; no se soportará anidamiento multinivel, solo un nivel).
  • La lista de comentarios se mostrará en orden cronológico inverso (más reciente primero).
  • Soportar carga de comentarios paginada (20 comentarios por página).
  • Los comentarios deben pasar por un proceso de revisión (aprobación por un administrador antes de mostrarse públicamente).
Alcance & Fuera de alcance
  • Dentro del alcance: Publicar comentarios, responder y ver (usuario estándar); revisar comentarios (administrador).
  • Fuera del alcance: Publicación anónima; votos positivos/negativos (likes/dislikes) en comentarios; respuestas multinivel anidadas.
Criterios de éxito
  • Tasa de uso de la funcionalidad de comentarios ≥ 5% diario tras el lanzamiento.
  • Tiempo de carga de la lista de comentarios ≤ 500ms.
  • Tasa de error en la API de publicación de comentarios < 1%.
Restricciones
  • Todos los datos de comentarios deben almacenarse de forma anonimizada, mostrando el nombre de usuario como alias.
  • El servicio de comentarios debe ser horizontalmente escalable, soportando la publicación concurrente de 1000 usuarios.
  • La interfaz de usuario debe ser compatible con dispositivos móviles y de escritorio.

Entregable

Documento spec.md que contenga el contexto, objetivos, lista de funcionalidades, alcance, criterios de éxito y restricciones descritos anteriormente.

Fase 2: Planificación

Objetivo

Una vez definido el "qué", establecer el "cómo": selección tecnológica, división en módulos, contratos de interfaz, modelo de datos, identificación de riesgos, etc.

Contenido (Ejemplo)

  • Pila tecnológica: Backend: Spring Boot 3 + Hibernate; Frontend: React 18; Base de datos: PostgreSQL.
  • División en módulos:
    • Módulo de servicio de comentarios (CommentService)
    • Módulo de servicio de revisión (ReviewService)
    • Capa de API (CommentController)
    • Componentes frontend (CommentList, CommentForm, ReplyForm)
  • Modelo de datos (simplificado):
    • Tabla comments: comment_id, product_id, author_id, body_text, parent_comment_id (nullable), moderation_status (PENDING/APPROVED/REJECTED), creation_timestamp, last_modified_timestamp.
  • Contratos de interfaz (ejemplo):
    • POST /api/v1/products/{productId}/comments — Envía un comentario. Cuerpo de la petición: { text: string }. Retorna el objeto comentario o un error.
    • GET /api/v1/products/{productId}/comments?page=1&size=20 — Obtiene la lista de comentarios. Retorna una estructura paginada: { data: Comment[], total: number, currentPage: number, itemsPerPage: number }.
    • POST /api/v1/comments/{commentId}/replies — Responde a un comentario. Cuerpo de la petición: { text: string }.
  • Riesgos y elementos fuera del objetivo:
    • Riesgos: Conflictos de escritura en comentarios bajo alta concurrencia; demoras en la revisión que afecten la experiencia del usuario.
    • Fuera del objetivo: Notificación en tiempo real a otros usuarios cuando se responde a un comentario; soporte para multimedia (imágenes/videos) en comentarios.
  • Presupuesto de rendimiento: Bajo una carga de 1000 escrituras concurrentes por segundo, el tiempo de respuesta en el percentil 95 debe ser < 300ms.
  • Seguridad / Privacidad: El contenido debe ser filtrado para palabras sensibles; los usuarios deben estar autenticados para poder comentar.

Entregable

Documento plan.md que incluya la arquitectura técnica, división en módulos, definiciones de interfaces, estructuras de datos, lista de riesgos y objetivos de rendimiento.

Fase 3: Tareas

Objetivo

Descomponer el plan en una lista de tareas ejecutables, asignables y rastreables. Cada tarea debe especificar su producto, responsable y criterios de aceptación.

Contenido (Ejemplo de lista de tareas)

ID Título de la tarea Descripción Responsable Criterio de aceptación
T-01 Crear la tabla de datos comments Definir y crear la tabla en la base de datos. Backend La estructura de la tabla es correcta; el script de migración se ejecuta sin errores; los campos cumplen con la definición del plan.
T-02 Implementar endpoint para enviar comentarios POST /api/v1/products/{productId}/comments Backend El endpoint responde exitosamente; el contenido se almacena; el estado inicial es PENDING; retorna código 201.
T-03 Implementar endpoint de consulta paginada de comentarios GET /api/v1/products/{productId}/comments Backend El ednpoint de paginación funciona correctamente; el ordenamiento es el esperado; tiene cobertura de pruebas.
T-04 Implementar endpoint para responder a un comentario POST /api/v1/comments/{commentId}/replies Backend La respuesta se crea exitosamente; parent_comment_id se establece correctamente; la respuesta cumple con el contrato de API.
T-05 Desarrollar componente frontend para mostrar la lista de comentarios Componente React CommentList Frontend La lista de comentarios se muestra correctamente; soporta carga paginada; la estética cumple con las especificaciones de diseño.
T-06 Desarrollar componente de formulario para enviar comentarios Componente React CommentForm Frontend El formulario valida los campos; tras el envío exitoso, la lista se actualiza; los errores se muestran adecuadamente.
T-07 Implementar funcionalidad de revisión de comentarios en el panel de administración Interfaz y lógica de revisión (Admin) Backend + Frontend Los administradores pueden ver comentarios pendientes; pueden aprobarlos o rechazarlos; la interfaz funciona en coordinación con el backend.
T-08 Realizar pruebas de rendimiento y simulación de alta concurrencia Crear y ejecutar scripts de pruebas de carga. Testing/QA Se simula una carga de 1000 escrituras/segundo; el tiempo de respuesta es < 300ms; se genera un informe de resultados.

Entregable

Documento tasks.md que liste todas las tareas, su prioridad, dependencias, responsables y criterios de aceptación.

Fase 4: Implementación

Objetivo

Ejecutar según la lista de tareas y el plan: programar, probar, integrar y lanzar. Mantener la consistencia con la especificación y el plan.

Contenido (Ejemplo)

  • Proceso de desarrollo: Ejecutar las tareas T-01 a T-08 de forma secuencial o paralela según sea posible, completando cada una.
  • Pruebas: Escribir pruebas unitarias y de integración. Por ejemplo, pruebas para el endpoint de envío de comentarios, el endpoint de consulta paginada y el endpoint de respuestas.
  • Pruebas de integración frontend: Verificar que después de enviar un comentario, la lista se actualiza; que la carga paginada funciona como se espera.
  • Pruebas de rendimiento: Utilizar herramientas (como JMeter, k6) para simular escenarios de alta concurrencia y validar el cumplimiento del presupuesto de rendimiento.
  • Puesta en marcha de la funcionalidad de revisión: Probar completamente el flujo de revisión por parte del administrador y la coordinación entre las partes frontal y trasera.
  • Despliegue: Desplegar el nuevo módulo en el entorno de pruebas; realizar revisión de código antes del lanzamiento en producción; configurar métricas de monitoreo de rendimiento.

Criterios de finalización

  • Todas las tareas están completadas.
  • La cobertura de pruebas es ≥ 80%.
  • Toda la documentación de las APIs está actualizada.
  • No se detectan defectos críticos durante las pruebas de rendimiento o seguridad.
  • La tasa de uso de la funcionalidad de comentarios alcanza el objetivo esperado tras el lanzamiento.

Etiquetas: SPEC-KIT CODEX especificaciones de software Spring Boot React

Publicado el 6-30 20:23

Etiquetas populares

©2026 Friki Work