Crea una App de Flashcards con GitHub SpecKit + VS Code Codex (Tutorial Basado en Especificaciones)

En este post, construiremos una aplicación local de Flashcards usando GitHub SpecKit + la extensión Codex de VS Code. Seguiremos el flujo de Desarrollo Basado en Especificaciones de extremo a extremo: Especificación → Plan → Tareas → Implementación.

¿Por qué SpecKit para este proyecto? #why-speckit-for-this-project

El “vibe-coding” tradicional hace que los resultados sean difusos. SpecKit cambia el guion: escribes una especificación clara, creas un plan técnico, lo divides en tareas y dejas que tu agente de código implemente pequeñas porciones comprobables contigo en el bucle.

Prerrequisitos #prerequisites

• VS Code con la extensión Codex (inicia sesión con tu cuenta de ChatGPT).
• Git, Python 3.11+, y uv (lanzador/gestor de paquetes).
• macOS, Linux, o Windows (WSL recomendado para la mejor experiencia de Codex en Windows).

Repositorio público: https://github.com/nicklaunches/flashcards-speckit

Instalar Specify CLI #install-specify-cli

Instalación persistente (recomendada):

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify check

Iniciar proyecto conectado a Codex #init-project-wired-to-codex

Crea una carpeta e inicializa SpecKit para Codex:

mkdir flashcards-speckit && cd flashcards-speckit
specify init . --ai copilot
# Los usuarios de Windows pueden añadir: --script ps

Abre la carpeta en VS Code y confirma que el panel de Copilot ha iniciado sesión.

Establecer límites: Constitución #set-guardrails-constitution

En el chat de Copilot, ejecuta:

/speckit.constitution
Crea principios enfocados en:
- cortes verticales; 90% de las tareas < 30 minutos
- React + Next.js + TypeScript; SQLite vía Drizzle
- unit tests para lógica core; Playwright smoke
- accesibilidad (WCAG AA); presupuesto de rendimiento: First Load JS < 160KB
- offline-first (sin servicios externos, todo local)

Esto crea/actualiza un archivo de constitución que los pasos futuros deben seguir.

Escribir la Especificación (qué y por qué) #write-the-spec-what-and-why

/speckit.specify
Construye una aplicación local, offline-first de Flashcards para sesiones de estudio rápidas.

Historias de Usuario:
1) Como aprendiz, puedo crear Mazos (nombre y descripción).
2) Puedo añadir, editar y eliminar Tarjetas (anverso/reverso).
3) Puedo estudiar un Mazo con un flujo de cuestionario (mostrar anverso → voltear → marcar Fácil/Difícil).
4) Repetición espaciada: promover/demover tarjetas por dificultad para reaparecer más tarde.
5) Búsqueda: filtrar mazos y tarjetas por texto.
6) Los datos se almacenan localmente; la aplicación funciona sin red.
7) Buena UX: atajos de teclado (J/K/Space), diseño responsivo, modo oscuro.

Criterios de Aceptación:
- CRUD persiste entre sesiones
- Cuestionario muestra progreso y precisión
- Responsivo para móvil + escritorio

Mantén el enfoque en qué/por qué. Guarda las decisiones técnicas para la siguiente fase.

Crear el Plan Técnico (cómo) #create-the-technical-plan-how

/speckit.plan
Tecnología y Arquitectura:
- Next.js + React + TypeScript; Tailwind para UI
- Archivo SQLite con ORM Drizzle; abstracción de repositorio
- App Router; Server Actions para mutaciones
- Unit: Vitest; E2E: Playwright (flujos smoke)
- Utilidad de atajos de teclado; modo oscuro vía variables CSS
- Code-splitting en página de estudio; mantener bundle pequeño

Esto se convierte en el plano que seguirá Codex.

Dividirlo en Tareas #break-it-into-tasks

/speckit.tasks

Espera un tasks.md generado con pasos ordenados, rutas de archivos y stubs de pruebas. Pases de calidad opcionales:

• /speckit.clarify — ajusta partes poco especificadas
• /speckit.analyze — verifica cobertura especificación ↔ plan
• /speckit.checklist — genera una lista de verificación QA (“unit tests for English”)

Implementar con Codex #implement-with-codex

/speckit.implement

Codex sigue tasks.md para esqueletar la aplicación, escribir código y conectar pruebas bajo tus aprobaciones.

Ejecutar y probar #run-and-test

pnpm i
pnpm dev
# abre http://localhost:3000

Una vez que hayas completado todas las tareas del plan: Prueba: crear Mazo → añadir Tarjetas → pulsa Estudiar → usa J/K/Space durante el cuestionario.

Añadir repetición espaciada #add-spaced-repetition

Pide a Codex que extienda la funcionalidad:

/speckit.tasks
Añadir planificador:
- Cada tarjeta tiene un bucket de dificultad (1..3)
- FÁCIL → +1 bucket (máx 3); DIFÍCIL → −1 (mín 1)
- La sesión extrae más de los buckets inferiores
- Persistir lastReviewed, nextDue

Luego ejecuta /speckit.implement de nuevo.

Estructura de repositorio recomendada #recommended-repo-structure

flashcards-speckit/
  .specify/          # especificación, plan, tareas, artefactos de investigación
  .github/           # prompts/plantillas añadidos por SpecKit
  app/               # rutas y UI de Next.js
  db/                # esquema drizzle + seed
  tests/             # unit + e2e
  README.md

Solución de problemas #troubleshooting

• Los comandos de barra inclinada no aparecen en el menú de Codex: asegúrate de que inicializaste con --ai codex, estás en la raíz del proyecto y la CLI/extensión de Codex está actualizada. Si solo aparece /speckit.constitution, actualiza herramientas y plantillas; algunas integraciones de agentes reciben correcciones con el tiempo.
• Fallo en verificaciones del agente: añade --ignore-agent-tools a specify init para saltar las comprobaciones y obtener las plantillas de todos modos.
• Windows: Codex es experimental en Windows—usa WSL para mejores resultados.

Próximas ideas #next-ideas

• Importar/exportar mazos como JSON
• Soporte de Markdown en las caras de las tarjetas
• Tarjetas con imágenes
• Rachas + vista de estadísticas
• Mazo inteligente “Estudiar de nuevo” usando nextDue

Fuentes #sources

• Repositorio SpecKit (README: instalación, agentes, comandos de barra inclinada) — https://github.com/github/spec-kit
• Blog de GitHub: Desarrollo basado en especificaciones con IA: Comienza con un nuevo kit de herramientas de código abierto — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
• Blog de GitHub: Desarrollo basado en especificaciones — Usando Markdown como lenguaje de programación — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-using-markdown-as-a-programming-language-when-building-with-ai/
• Documentación de la extensión IDE de Codex — https://developers.openai.com/codex/ide/