Crie um App de Flashcards com GitHub SpecKit + VS Code Codex (Tutorial Guiado por Especificação)

Neste post, vamos construir um app local de Flashcards usando GitHub SpecKit + a extensão Codex do VS Code. Seguiremos o fluxo de Desenvolvimento Guiado por Especificação do início ao fim: Especificar → Planejar → Tarefas → Implementar.

Por que SpecKit para este projeto? #why-speckit-for-this-project

O tradicional “vibe-coding” deixa os resultados imprecisos. O SpecKit inverte o jogo: você escreve uma especificação clara, cria um plano técnico, divide em tarefas e deixa seu agente de codificação implementar pequenos trechos testáveis com você no controle.

Pré-requisitos #prerequisites

• VS Code com a extensão Codex (faça login com sua conta ChatGPT).
• Git, Python 3.11+ e uv (gerenciador de pacotes/launcher).
• macOS, Linux ou Windows (WSL recomendado para melhor experiência Codex no Windows).

Repositório público: https://github.com/nicklaunches/flashcards-speckit

Instalar o Specify CLI #install-specify-cli

Instalação persistente (recomendado):

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

Inicializar o projeto conectado ao Codex #init-project-wired-to-codex

Crie uma pasta e inicialize o SpecKit para Codex:

mkdir flashcards-speckit && cd flashcards-speckit
specify init . --ai copilot
# Usuários do Windows podem adicionar: --script ps

Abra a pasta no VS Code e confirme que o painel Copilot está conectado.

Definir limites: Constituição #set-guardrails-constitution

No chat do Copilot, execute:

/speckit.constitution
Crie princípios focados em:
- fatias verticais; 90% das tarefas < 30 minutos
- React + Next.js + TypeScript; SQLite via Drizzle
- testes unitários para lógica central; smoke com Playwright
- acessibilidade (WCAG AA); orçamento de perf: First Load JS < 160KB
- offline-first (sem serviços externos, tudo local)

Isso cria/atualiza um arquivo de constituição que as próximas etapas devem seguir.

Escrever a Especificação (o que e por quê) #write-the-spec-what-and-why

/speckit.specify
Construa um app local e offline-first de Flashcards para sessões rápidas de estudo.

Histórias de Usuário:
1) Como aluno, posso criar Baralhos (nome e descrição).
2) Posso adicionar, editar e excluir Cartas (frente/verso).
3) Posso estudar um Baralhos com fluxo de quiz (mostrar frente → virar → marcar Fácil/Difícil).
4) Repetição espaçada: promover/descartar cartas por dificuldade para reaparecerem depois.
5) Busca: filtrar baralhos e cartas por texto.
6) Dados armazenados localmente; app roda sem rede.
7) Boa UX: atalhos de teclado (J/K/Espaço), layout responsivo, modo escuro.

Critérios de Aceitação:
- CRUD persiste entre sessões
- Quiz mostra progresso e precisão
- Responsivo para mobile + desktop

Mantenha o foco no o que/por quê. Salve as escolhas técnicas para a próxima fase.

Criar o Plano Técnico (como) #create-the-technical-plan-how

/speckit.plan
Tecnologia e Arquitetura:
- Next.js + React + TypeScript; Tailwind para UI
- Arquivo SQLite com ORM Drizzle; abstração de repositório
- App Router; Server Actions para mutações
- Unit: Vitest; E2E: Playwright (fluxos de smoke)
- Utilitário de atalhos de teclado; dark mode via variáveis CSS
- Code-split da página de estudo; manter bundle pequeno

Isso se torna o plano que o Codex seguirá.

Dividir em Tarefas #break-it-into-tasks

/speckit.tasks

Aguarde a geração de um tasks.md com passos ordenados, caminhos de arquivos e esboços de testes. Passos de qualidade opcionais:

• /speckit.clarify — ajusta partes pouco especificadas
• /speckit.analyze — verifica cobertura espécie ↔ plano
• /speckit.checklist — gera checklist de QA (ex: “testes unitários em inglês”)

Implementar com Codex #implement-with-codex

/speckit.implement

O Codex segue o tasks.md para esqueletar o app, escrever código e conectar testes sob suas aprovações.

Executar e testar #run-and-test

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

Assim que concluir todas as tarefas do plano: Tente: criar Baralho → adicionar Cartas → clique em Estudar → use J/K/Espaço durante o quiz.

Adicionar repetição espaçada #add-spaced-repetition

Peça ao Codex para estender a funcionalidade:

/speckit.tasks
Adicionar agendador:
- Cada carta tem faixa de dificuldade (1..3)
- FÁCIL → +1 faixa (máx 3); DIFÍCIL → −1 (mín 1)
- Sessão puxa mais das faixas inferiores
- Persistir lastReviewed, nextDue

Então execute /speckit.implement novamente.

Estrutura de repositório recomendada #recommended-repo-structure

flashcards-speckit/
  .specify/          # especificação, plano, tarefas, artefatos de pesquisa
  .github/           # prompts/templates adicionados pelo SpecKit
  app/               # rotas e UI do Next.js
  db/                # schema drizzle + seed
  tests/             # unit + e2e
  README.md

Solução de problemas #troubleshooting

• Comandos de barra não aparecem no menu Codex: certifique-se de que inicializou com --ai codex, está na raiz do projeto e a extensão/Codex CLI está atualizada. Se apenas /speckit.constitution aparecer, atualize ferramentas e templates; algumas integrações de agentes recebem correções com o tempo.
• Verificações do agente falhando: adicione --ignore-agent-tools ao specify init para ignorar verificações e buscar templates mesmo assim.
• Windows: o Codex é experimental no Windows—use WSL para melhores resultados.

Próximas ideias #next-ideas

• Importar/exportar baralhos como JSON
• Suporte a Markdown nas faces das cartas
• Cartas com imagens
• Sequências + visão de insights
• “Estudar novamente” baralho inteligente usando nextDue

Fontes #sources

• Repositório SpecKit (README: instalação, agentes, comandos de barra) — https://github.com/github/spec-kit
• Blog do GitHub: Desenvolvimento guiado por especificação com IA: Comece com um novo kit de ferramentas de código aberto — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
• Blog do GitHub: Desenvolvimento guiado por especificação — Usando Markdown como linguagem de programação — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-using-markdown-as-a-programming-language-when-building-with-ai/
• Documentação da extensão IDE Codex — https://developers.openai.com/codex/ide/