spec-gatekeeper

Realiza una entrevista enfocada de 4 preguntas al desarrollador y redacta un archivo SPEC.md determinista (Alcance y Seguridad, Contratos de Datos, Casos Extremos, Criterios de Aceptación) antes de escribir el código fuente.

¿Qué es spec-gatekeeper?

Spec-Gatekeeper es una habilidad para asistentes de codificación basados en IA que impone un flujo de trabajo de Desarrollo Guiado por Especificaciones (SDD). Antes de permitir la escritura de código fuente, esta habilidad guía a un desarrollador a través de una entrevista estructurada de 4 preguntas que cubren el Alcance y la Seguridad, los Contratos de Datos, los Casos Extremos y los Criterios de Aceptación. Luego, redacta automáticamente un archivo SPEC.md canónico (de al menos 300 bytes) en la raíz del repositorio, el cual sirve como un contrato arquitectónico vinculante. Una vez que el desarrollador aprueba la SPEC, se permite la implementación, eliminando la ambigüedad y la desviación de requisitos. La habilidad es compatible con flujos de trabajo de agentes de IA (Claude Code, Cursor, Codex) y sistemas de revisión manual de código, asegurando claridad, verificabilidad y un claro estado de 'Hecho'.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dansierrasam79/spec-gatekeeper/tree/main/skills/spec-gatekeeper

Installed? Explore more Productividad y colaboración skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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):

  1. 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?
  2. 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?
  3. 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?
  4. 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:

  1. Requisito de Tamaño: Al menos 300 bytes UTF-8 de contenido sustancial.
  2. 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 Amenazas o Permisos.
    • Contratos de Datos: Encabezados que contengan Contrato de Datos, Contratos de Datos, Esquema, Esquemas, Interfaz, Interfaces, API, Tipos, Carga Útil o Protocolo.
    • Casos Extremos: Encabezados que contengan Caso Extremo, Casos Extremos, Manejo de Errores, Modo de Falla, Modos de Falla, Resiliencia, Restricciones o Respaldos.
    • Criterios de Aceptación: Encabezados que contengan Criterios de Aceptación, Prueba de Aceptación, Matriz de Pruebas, Verificación, Pruebas, Definición de Hecho o Validación.

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

  1. Presenta el borrador de SPEC.md al desarrollador para su revisión y aprobación explícita.
  2. Una vez que SPEC.md esté confirmado y sea válido (>= 300 bytes con las 4 secciones), el hook de spec-gatekeeper permitirá automáticamente la escritura de archivos fuente de implementación.

Skills relacionados