GitHub SpecKit ve VS Code Codex ile Flashcards Uygulaması Geliştirin (Spec-Driven Öğretici)

Bu yazıda, GitHub SpecKit + Codex VS Code uzantısını kullanarak yerel bir Flashcards uygulaması oluşturacağız. Spec-Driven Development akışını baştan sona takip edeceğiz: Spec Yaz → Planla → Görevlere Böl → Uygula.

Bu proje için neden SpecKit? #why-speckit-for-this-project

Geleneksel “vibe-coding” sonuçları belirsiz hale getirir. SpecKit bu durumu tersine çevirir: net bir spec yazarsınız, teknik bir plan oluşturursunuz, görevlere bölersiniz ve kodlama asistanınızla birlikte küçük, test edilebilir dilimleri uygulamasını sağlarsınız.

Önkoşullar #prerequisites

• Codex uzantılı VS Code (ChatGPT hesabınızla oturum açın).
• Git, Python 3.11+ ve uv (paket/çalıştırıcı).
• macOS, Linux veya Windows (Windows’ta en iyi Codex deneyimi için WSL önerilir).

Genel repo: https://github.com/nicklaunches/flashcards-speckit

Specify CLI’yi yükleyin #install-specify-cli

Kalıcı kurulum (önerilen):

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

Projeyi Codex’e bağlı başlatın #init-project-wired-to-codex

Bir klasör oluşturun ve SpecKit’i Codex için başlatın:

mkdir flashcards-speckit && cd flashcards-speckit
specify init . --ai copilot
# Windows kullanıcıları şunu ekleyebilir: --script ps

Klasörü VS Code’da açın ve Copilot panelinin oturum açmış olduğundan emin olun.

Koruma çemberleri oluşturun: Anayasa #set-guardrails-constitution

Copilot sohbetinde çalıştırın:

/speckit.constitution
Odaklanan ilkeler oluştur:
- Dikey dilimler; %90'ı 30 dakikadan az görevler
- React + Next.js + TypeScript; SQLite via Drizzle
- Temel mantık için birim testleri; Playwright dumansı testi
- Erişilebilirlik (WCAG AA); performans bütçesi: İlk Yükleme JS < 160KB
- Çevrimdışı öncelikli (harici hizmet yok, hepsi yerel)

Bu, sonraki adımların uyması gereken bir anayasa dosyası oluşturur/günceller.

Spec’i yazın (ne ve neden) #write-the-spec-what-and-why

/speckit.specify
Hızlı çalışma oturumları için yerel, çevrimdışı öncelikli bir Flashcards uygulaması oluşturun.

Kullanıcı Hikayeleri:
1) Öğrenici olarak; Desteler (isim ve açıklama) oluşturabilirim.
2) Kartları (ön/arka) ekleyebilir, düzenleyebilir ve silebilirim.
3) Bir desteyi sınav akışıyla çalıştırabilirim (ön yüzü göster → çevir → Kolay/Zor olarak işaretle).
4) Aralıklı tekrar: zorluğa göre kartları ileri/geri alarak daha sonra yeniden yüzeye çıkar.
5) Arama: metne göre desteleri ve kartları filtrele.
6) Veriler yerel olarak saklanır; uygulama ağ olmadan çalışır.
7) İyi UX: klavye kısayolları (J/K/Space), duyarlı düzen, karanlık mod.

Kabul Kriterleri:
- CRUD oturumlar arasında kalıcı olur
- Sınav ilerlemeyi ve doğruluğu gösterir
- Mobil + masaüstü duyarlı

Bunu ne/neden üzerine odaklayın. Teknik seçimleri bir sonraki aşamaya bırakın.

Teknik Planı oluşturun (nasıl) #create-the-technical-plan-how

/speckit.plan
Teknik ve Mimari:
- Next.js + React + TypeScript; UI için Tailwind
- SQLite dosya veritabanı ve Drizzle ORM; depo soyutlama
- Uygulama Yönlendiricisi; mutasyonlar için Sunucu Eylemleri
- Birim testi: Vitest; E2E: Playwright (dumansı akışlar)
- Klavye kısayol utility'si; CSS değişkenleri aracılığıyla karanlık mod
- Çalışma sayfası kod bölmeli; paket boyutunu küçük tutun

Bu, Codex’in takip edeceği şablon haline gelir.

Görevlere bölün #break-it-into-tasks

/speckit.tasks

Sıralı adımlar, dosya yolları ve test taslakları içeren üretilmiş bir tasks.md dosyası bekleyin. İsteğe bağlı kalite kontrolleri:

• /speckit.clarify — belirsiz kısımları sıkılaştırır
• /speckit.analyze — spec ↔ plan kapsamını çapraz kontrol eder
• /speckit.checklist — bir QA kontrol listesi oluşturur (“İngilizce için birim testleri”)

Codex ile uygulayın #implement-with-codex

/speckit.implement

Codex, tasks.md’yi takip ederek uygulamayı oluşturur, kod yazar ve onaylarınız altında testleri bağlar.

Çalıştırın ve test edin #run-and-test

pnpm i
pnpm dev
# http://localhost:3000 adresini açın

Plandaki tüm görevleri tamamladıktan sonra şunu deneyin: Deste oluştur → Kart ekle → Çalıştır’a basın → Sınav sırasında J/K/Space kullanın.

Aralıklı tekrarı ekleyin #add-spaced-repetition

Codex’ten özelliği genişletmesini isteyin:

/speckit.tasks
Zamanlayıcı ekle:
- Her kartın zorluk kovası olsun (1..3)
- KOLAY → +1 kova (maks 3); ZOR → −1 (min 1)
- Oturum daha düşük kovalardan daha fazla çeker
- lastReviewed, nextDue'yu kalıcı hale getir

Ardından tekrar /speckit.implement çalıştırın.

Önerilen repo yapısı #recommended-repo-structure

flashcards-speckit/
  .specify/          # spec, plan, tasks, araştırma artefaktları
  .github/           # SpecKit tarafından eklenen promptlar/şablonlar
  app/               # Next.js rotaları ve UI
  db/                # drizzle şeması + seed
  tests/             # birim + e2e
  README.md

Sorun giderme #troubleshooting

• Slash komutları Codex menüsünde görünmüyor: --ai codex ile başlattığınızdan, proje kök dizininde olduğunuzdan ve Codex CLI/uzantısının güncel olduğundan emin olun. Sadece /speckit.constitution görünüyorsa, araçları ve şablonları güncelleyin; bazı agent entegrasyonları zamanla düzeltilir.
• Agent kontrolleri başarısız oluyor: specify init’e --ignore-agent-tools ekleyerek kontrolleri atlayın ve şablonları yine de indirin.
• Windows: Codex Windows’ta deneyseldir—en iyi sonuçlar için WSL kullanın.

Sonraki fikirler #next-ideas

• Deste’leri JSON olarak içe/dışa aktar
• Kart yüzlerinde Markdown desteği
• Görsel kartlar
• Seriler + içgörü görünümü
• nextDue kullanan “Tekrar çalış” akıllı destesi

Kaynaklar #sources

• SpecKit deposu (README: kurulum, ajanlar, slash komutları) — https://github.com/github/spec-kit
• GitHub blogu: Spec-driven development with AI: Get started with a new open-source toolkit — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
• GitHub blogu: Spec-driven development — Using Markdown as a programming language — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-using-markdown-as-a-programming-language-when-building-with-ai/
• Codex IDE uzantısı dokümantasyonu — https://developers.openai.com/codex/ide/