AI 4 min

🚀 CHEATSHEET: El Ciclo SDD en Google Antigravity con Spec Kit

Machete de referencia rápida con todos los comandos, flujos y diagramas para dominar el Spec-Driven Development en tu día a día.

Escrito por Samir El Azem Crovetto • Senior Backend Engineer & DevSecOps

Este "machete" de referencia rápida resume todos los comandos, archivos, flujos y bucles de retroalimentación necesarios para aplicar Spec-Driven Development (SDD) en tu día a día usando Google Antigravity como tu IDE agéntico y Spec Kit como tu motor de gobernanza.

🛠️ FASE 0: El Setup Global (Solo una vez en tu máquina)

Para instalar de forma ultra rápida la CLI de Spec Kit (specify-cli) utilizando el gestor de paquetes moderno de Python (uv), ejecuta en la terminal de tu sistema:

# Instalar uv (si no lo tienes ya instalado)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Instalar la herramienta globalmente
uv tool install specify-cli

📂 FASE 1: Inicializar un Proyecto (Una vez por repositorio)

Ya sea para un proyecto nuevo de cero o para integrarlo en un proyecto existente (brownfield):

1. Comandos de terminal:

# Navega al directorio raíz de tu proyecto
cd ~/proyectos/tu-proyecto

# Inicializa con la integración específica de Antigravity ('agy')
specify init --here --integration agy

(Si la carpeta no está vacía y quieres forzar el andamiaje, añade --force al final del comando).

2. Estructura de archivos generada:

  • 📂 .specify/: Carpeta de configuración interna de Spec Kit. No la toques.
  • 📝 .specify/memory/constitution.md: El archivo canónico donde redactarás tus reglas arquitectónicas y de negocio.
  • 📂 .agents/workflows/: Los archivos que definen los slash commands (/speckit.*) para que el chat lateral de Antigravity los reconozca de inmediato.

⚖️ FASE 2: La Constitución (Establecer la Gobernanza)

Antes de escribir código, define las leyes inmutables del sistema.

1. Comando en el Chat lateral de Antigravity (Ctrl + L):

Lanza el comando de constitución pasándole los principios de arquitectura de tu proyecto:

/speckit.constitution

El truco de trinchera: El agente te ayudará a maquetar el archivo canónico .specify/memory/constitution.md. Una vez redactado, crea un archivo ligero en .agents/rules/00-gobernanza.md que actúe como Adapter de Cursor/Antigravity diciendo:

\"Para cualquier decisión de diseño o refactorización de código, lee y respeta el archivo @.specify/memory/constitution.md de forma obligatoria.\"

🎯 FASE 3: El Ciclo Diario por Feature (Rifle de un solo disparo y Bucles de Corrección)

Sigue este flujo estricto para cada User Story de Jira/Agility en una rama limpia aislada. Nunca mezcles dos funcionalidades en el mismo ciclo de desarrollo.

                    [ 1. CREAR RAMA (git checkout) ]
                                   │
                                   ▼
          ┌──────────────► 2. ESPECIFICAR (spec.md) ◄─────────────────────────┐
          │                        │                                          │
          │                        ▼                                          │
          │               3. CLARIFICAR (/speckit.clarify)                    │
          │                        │                                          │
          │                        ▼                                          │
          │               4. PLANIFICAR (plan.md / contracts) ◄────────────┐  │ (Bucle de
          │                        │                                       │  │  Refinamiento o
          │                        ▼                                       │  │  Rediseño UI)
          │               5. TAREAS (tasks.md) ◄─────────────────────────┐ │  │
          │                        │                                     │ │  │
          │                        ▼                                     │ │  │
          │               6. ANALIZAR (/speckit.analyze)                 │ │  │
          │                        │                                     │ │  │
          │                        ├─► [Violación de Constitución] ──────┼─┴──┘
          │                        │                                     │
          │                        ▼ (Consistencia OK)                   │
          │               7. IMPLEMENTAR (/speckit.implement) ◄────────┐ │ (Bucle de
          │                        │                                   │ │  Tareas
          │                        ▼                                   │ │  Pendientes)
          └─────────────── 8. CONVERGER (/speckit.converge)            │ │
                                   │                                   │ │
                                   ├─► [Falta cobertura o test] ───────┼─┘
                                   │   (Tareas nuevas añadidas)        │
                                   │                                   │
                                   ├─► [No te gusta la UI / Reglas] ───┘
                                   │   (Modificar especificación)
                                   │
                                   ▼ (Convergido OK 🟢)
                            9. INTEGRAR (git merge)

1. Crear rama en tu terminal local (Manual):

git checkout -b feature/S-143562_pasarela-pago

Nota: Spec Kit detectará automáticamente que estás en esta rama y usará su nombre como el identificador ("slug") para aislar los archivos en su subcarpeta sin inventar números secuenciales.

2. Especificar el "Qué" (Chat de Antigravity o Manual):

/speckit.specify Diseña la pasarela de pago para aceptar tarjetas de crédito e implementa reintentos automáticos si el proveedor falla.
  • ¿Qué ocurre? Spec Kit crea la carpeta specs/S-143562_pasarela-pago/ y genera dentro el archivo spec.md.
  • Acción recomendada ✍️: Abre spec.md en tu editor y tómate 5 minutos para refinar los requisitos a mano en formato EARS (\"CUANDO ocurre X, ENTONCES el sistema DEBERÁ...\"). Es más rápido que chatear.

3. Clarificar vacíos lógicos (Opcional - Chat de Antigravity):

/speckit.clarify
  • ¿Qué ocurre? El agente analiza tu spec, detecta lagunas lógicas y te hace 3 o 4 preguntas de opción múltiple. Al responderlas, el agente reescribe e integra las respuestas en tu spec.md.

4. Planificar el "Cómo" (Chat de Antigravity):

/speckit.plan
  • ¿Qué ocurre? El agente lee tu spec y genera la arquitectura en la carpeta de la feature:
  • 📂 plan.md: El diseño de archivos a crear, modificar o eliminar.
  • 📂 data-model.md: Definición de esquemas de bases de datos, APIs y tipos de datos.
  • 📂 research.md: Evaluación de dependencias y librerías externas.

5. Desglosar las Tareas Atómicas (Chat de Antigravity):

/speckit.tasks
  • ¿Qué ocurre? Traduce el plan técnico en un checklist secuencial con estados y prioridades en:
  • 📂 tasks.md: Con estados reales de ejecución del agente ([ ] pendiente, [>] en progreso, [x] completada, [!] fallida).

6. Validar la Consistencia (Chat de Antigravity):

/speckit.analyze
  • ¿Qué ocurre? Compara el plan y las tareas contra tu Constitución.
  • 🔄 Bucle de Fallo de Consistencia: Si violas un estándar de diseño (ej. saltarte la arquitectura hexagonal o usar librerías inseguras), frena el flujo y te avisa antes de que se tire código de forma errónea. Deberás volver al Paso 2 (Reespecificar) o al Paso 4 (Replanificar) para resolver el conflicto.

7. Implementación Aislada (Chat de Antigravity):

/speckit.implement
  • ¿Qué ocurre? El agente levanta un Sandbox local (contenedor Linux aislado), lee tasks.md, escribe el código en el Sandbox, ejecuta las pruebas y se auto-corrige si hay errores de consola. Cuando está todo en verde, traslada los cambios a tu repositorio local.

8. Comprobar la Convergencia y Validación (Chat de Antigravity):

/speckit.converge
  • ¿Qué ocurre? Hace una última auditoría del código generado contra tu spec.md original para garantizar que cubre el 100% de la lógica requerida.
  • 🔄 Bucle de Falta de Cobertura: Si la IA olvidó implementar algún caso de prueba o validación, /speckit.converge lo detectará y añadirá automáticamente nuevas tareas pendientes al final de tu tasks.md. Deberás volver al Paso 5/7 para re-implementar lo que falta.
  • 🔄 Bucle de Refinamiento (No te gusta la UI): Si el componente frontend no te gusta visualmente o hay que refinar estilos/reglas de negocio, modifica el spec.md (Paso 2), actualiza el plan (Paso 4), las tareas (Paso 5) e implementa de nuevo (Paso 7). ¡La IA reescribirá el código limpiamente sin dejar parches!

9. Merge e Integración (Terminal local de Git):

git add .
git commit -m "feat: implementar pasarela de pago S-143562"
git push origin feature/S-143562_pasarela-pago

Una vez aprobada la Pull Request por humanos (y tras pasar la validación del comando /speckit.analyze en el pipeline de Integración Continua), fusiona con main y borra la rama local. ¡Listo para el siguiente ciclo!

📚 Serie Spec-Driven Development (SDD)

  1. Spec-Driven Development (SDD): Gobernanza de Agentes IA y el Fin del 'Vibe Coding'
  2. El Chasis de la Gobernanza: Constitución vs. AGENTS.md (Y cómo no ahogarte en deuda de sincronización)
  3. El Pipeline SDD en la Práctica: De la Sintaxis EARS a las Tareas Atómicas
  4. La Entrevista de Requisitos y el Bucle "SpecOps": Cómo usar la IA de Sparring y rehacer código sin dolor
  5. El Reto del Código Existente (Brownfield) y la Gestión de Múltiples Specs con Jira/Git
  6. Google Antigravity y MCP: Sandboxing, Autocorrección y la Nube