Membangun Aplikasi Flashcards dengan GitHub SpecKit + VS Code Codex (Tutorial Berbasis Spesifikasi)

Di postingan ini, kita akan membangun aplikasi Flashcards lokal menggunakan GitHub SpecKit + ekstensi Codex di VS Code. Kita akan mengikuti alur Spec-Driven Development dari ujung ke ujung: Specify → Plan → Tasks → Implement.

Mengapa SpecKit untuk proyek ini? #why-speckit-for-this-project

Pemrograman “vibe-coding” tradisional membuat hasil menjadi kabur. SpecKit membalikkan keadaan: Anda menulis spesifikasi yang jelas, membuat rencana teknis, memecahnya menjadi tugas, dan membiarkan agen coding Anda mengimplementasikan potongan-potongan kecil yang dapat diuji bersama Anda dalam loop.

Prasyarat #prerequisites

• VS Code dengan ekstensi Codex (masuk dengan akun ChatGPT Anda).
• Git, Python 3.11+, dan uv (package/launcher).
• macOS, Linux, atau Windows (WSL direkomendasikan untuk pengalaman Codex terbaik di Windows).

Repositori publik: https://github.com/nicklaunches/flashcards-speckit

Instal Specify CLI #install-specify-cli

Instalasi persisten (direkomendasikan):

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

Init proyek yang terhubung ke Codex #init-project-wired-to-codex

Buat folder dan inisialisasi SpecKit untuk Codex:

mkdir flashcards-speckit && cd flashcards-speckit
specify init . --ai copilot
# Pengguna Windows dapat menambahkan: --script ps

Buka folder di VS Code dan konfirmasi panel Copilot sudah masuk.

Atur batasan: Constitution #set-guardrails-constitution

Di chat Copilot, jalankan:

/speckit.constitution
Buat prinsip yang berfokus pada:
- irisan vertikal; 90% tugas < 30 menit
- React + Next.js + TypeScript; SQLite via Drizzle
- unit test untuk logika inti; smoke Playwright
- aksesibilitas (WCAG AA); anggaran performa: First Load JS < 160KB
- offline-first (tidak ada layanan eksternal, semua lokal)

Ini membuat/memperbarui file konstitusi yang harus diikuti oleh langkah-langkah selanjutnya.

Tulis Spesifikasi (apa dan mengapa) #write-the-spec-what-and-why

/speckit.specify
Bangun aplikasi Flashcards lokal, offline-first untuk sesi belajar cepat.

User Stories:
1) Sebagai pelajar, saya dapat membuat Deck (nama & deskripsi).
2) Saya dapat menambahkan, mengedit, dan menghapus Kartu (depan/belakang).
3) Saya dapat mempelajari Deck dengan alur kuis (tampilkan depan → balik → tandai Mudah/Sulit).
4) Spaced repetition: promosikan/demosikan kartu berdasarkan kesulitan untuk muncul kembali nanti.
5) Pencarian: filter deck dan kartu berdasarkan teks.
6) Data disimpan secara lokal; aplikasi berjalan tanpa jaringan.
7) UX yang bagus: shortcut keyboard (J/K/Space), tata letak responsif, mode gelap.

Kriteria Penerimaan:
- CRUD bertahan antar sesi
- Kuis menunjukkan kemajuan & akurasi
- Responsif seluler + desktop

Pertahankan fokus pada apa/mengapa. Simpan pilihan teknis untuk fase berikutnya.

Buat Rencana Teknis (bagaimana) #create-the-technical-plan-how

/speckit.plan
Teknis & Arsitektur:
- Next.js + React + TypeScript; Tailwind untuk UI
- File DB SQLite dengan Drizzle ORM; abstraksi repositori
- App Router; Server Actions untuk mutasi
- Unit: Vitest; E2E: Playwright (alur smoke)
- Util shortcut keyboard; mode gelap via variabel CSS
- Code-split halaman belajar; jaga bundle tetap kecil

Ini menjadi cetak biru yang akan diikuti oleh Codex.

Pecah menjadi Tugas #break-it-into-tasks

/speckit.tasks

Harapkan file tasks.md yang dihasilkan dengan langkah-langkah terurut, path file, dan tes awal. Pass kualitas opsional:

• /speckit.clarify — perketat bagian yang kurang spesifik
• /speckit.analyze — cross-check cakupan spesifikasi ↔ rencana
• /speckit.checklist — buat daftar periksa QA (“unit tests for English”)

Implementasi dengan Codex #implement-with-codex

/speckit.implement

Codex mengikuti tasks.md untuk membuat kerangka aplikasi, menulis kode, dan menghubungkan tes di bawah persetujuan Anda.

Jalankan dan uji #run-and-test

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

Setelah Anda menyelesaikan semua tugas dari rencana: Coba: buat Deck → tambahkan Kartu → tekan Study → gunakan J/K/Space selama kuis.

Tambahkan spaced repetition #add-spaced-repetition

Minta Codex untuk memperluas fitur:

/speckit.tasks
Tambahkan scheduler:
- Setiap kartu memiliki kesulitan bucket (1..3)
- MUDAH → +1 bucket (maks 3); SULIT → −1 (min 1)
- Sesi mengambil lebih banyak dari bucket bawah
- Simpan lastReviewed, nextDue

Lalu jalankan /speckit.implement lagi.

Struktur repositori yang direkomendasikan #recommended-repo-structure

flashcards-speckit/
  .specify/          # spesifikasi, rencana, tugas, artefak riset
  .github/           # prompt/template yang ditambahkan oleh SpecKit
  app/               # rute & UI Next.js
  db/                # skema drizzle + seed
  tests/             # unit + e2e
  README.md

Pemecahan masalah #troubleshooting

• Perintah slash tidak muncul di menu Codex: pastikan Anda menginisialisasi dengan --ai codex, Anda berada di root proyek, dan Codex CLI/ekstensi mutakhir. Jika hanya /speckit.constitution yang muncul, perbarui alat dan templat; beberapa integrasi agen mendapatkan perbaikan seiring waktu.
• Pemeriksaan agen gagal: tambahkan --ignore-agent-tools ke specify init untuk melewati pemeriksaan dan mengambil templat tetap.
• Windows: Codex bersifat eksperimental di Windows—gunakan WSL untuk hasil terbaik.

Ide selanjutnya #next-ideas

• Impor/ekspor deck sebagai JSON
• Dukungan Markdown pada sisi kartu
• Kartu gambar
• Poin + tampilan wawasan
• Dek belajar lagi cerdas menggunakan nextDue

Sumber #sources

• Repositori SpecKit (README: instalasi, agen, perintah slash) — https://github.com/github/spec-kit
• Blog GitHub: 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/
• Blog GitHub: 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/
• Dokumen ekstensi IDE Codex — https://developers.openai.com/codex/ide/