Spec-Gatekeeper: Flujo de Trabajo de Desarrollo Guiado por Especificaciones
Usa esta habilidad siempre que la escritura de código fuente esté bloqueada por spec-gatekeeper, o al iniciar una nueva funcionalidad, servicio o refactorización importante.
El Desarrollo Guiado por Especificaciones (SDD) asegura claridad y elimina la desviación al requerir un contrato arquitectónico estructurado y acordado antes de comenzar la implementación.
Pasos del Flujo de Trabajo
Paso 1: Realizar la Entrevista de 4 Preguntas al Desarrollador
Antes de escribir cualquier código o crear archivos stub, haz al desarrollador las siguientes 4 preguntas enfocadas (o extrae las respuestas de los requisitos existentes y pide confirmación):
-
Alcance y Seguridad:
- ¿Cuáles son los objetivos principales y los no-objetivos explícitos de esta tarea?
- ¿Qué componentes arquitectónicos o límites del sistema están involucrados?
- ¿Cuáles son las restricciones de seguridad, permisos, autenticación o sandbox?
-
Contratos de Datos:
- ¿Cuáles son los esquemas exactos, interfaces de API, tipos y formas de protocolo?
- ¿Cuáles son los parámetros de entrada precisos y las cargas útiles de salida esperadas?
-
Casos Extremos y Resiliencia:
- ¿Cuáles son los modos de falla clave, interrupciones de red/E/S y entradas mal formadas?
- ¿Qué mecanismos de manejo de errores, validación y respaldo deben estar en su lugar?
-
Criterios de Aceptación:
- ¿Qué matriz de verificación determinista y casos de prueba definen 'Hecho'?
- ¿Cómo se validará cada criterio de aceptación?
Paso 2: Redactar SPEC.md
Crear o actualizar SPEC.md en la raíz resuelta del proyecto (<repo_root>/SPEC.md).
Estructura Requerida
El archivo de especificación debe cumplir con:
- Requisito de Tamaño: Al menos 300 bytes UTF-8 de contenido sustancial.
- Encabezados de Sección Canónicos: Encabezados Markdown de Nivel 1 a 3 fuera de bloques de código que coincidan con cada una de las 4 secciones requeridas:
- Alcance y Seguridad: Encabezados que contengan
Alcance,Seguridad,Arquitectura,Visión General,Límites,Modelo de AmenazasoPermisos. - Contratos de Datos: Encabezados que contengan
Contrato de Datos,Contratos de Datos,Esquema,Esquemas,Interfaz,Interfaces,API,Tipos,Carga ÚtiloProtocolo. - Casos Extremos: Encabezados que contengan
Caso Extremo,Casos Extremos,Manejo de Errores,Modo de Falla,Modos de Falla,Resiliencia,RestriccionesoRespaldos. - Criterios de Aceptación: Encabezados que contengan
Criterios de Aceptación,Prueba de Aceptación,Matriz de Pruebas,Verificación,Pruebas,Definición de HechooValidación.
- Alcance y Seguridad: Encabezados que contengan
Plantilla
# Especificación: <Nombre de la Funcionalidad o Servicio>
## 1. Alcance y Seguridad
### Objetivos y Límites Arquitectónicos
- Descripción detallada del alcance...
### Seguridad y Modelo de Amenazas
- Verificaciones de permisos y límites de seguridad...
## 2. Contratos de Datos
### Esquemas e Interfaces
- Tipos, firmas de API, formatos de solicitud/respuesta...
## 3. Casos Extremos y Resiliencia
### Manejo de Errores y Respaldos
- Condiciones límite, validación de entrada, modos de falla...
## 4. Criterios de Aceptación
### Verificación y Matriz de Pruebas
- CA-01: ...
- CA-02: ...
Paso 3: Aprobación del Desarrollador e Implementación
- Presenta el borrador de
SPEC.mdal desarrollador para su revisión y aprobación explícita. - Una vez que
SPEC.mdesté confirmado y sea válido (>= 300 bytes con las 4 secciones), el hook despec-gatekeeperpermitirá automáticamente la escritura de archivos fuente de implementación.