BAB 1: Dari Vibe Coding ke Spec-Driven

Ada fase yang hampir semua developer lewati saat pertama kali serius menggunakan Claude Code: fase euforia. Kamu ketik satu kalimat, Claude langsung menulis puluhan baris kode yang masuk akal. Terasa seperti memiliki programmer handal yang siap kapan saja. Productivitas terasa melonjak.

Lalu realita mulai menghantam. Kamu minta satu perbaikan kecil, Claude memperbaikinya tapi merusak bagian lain. Kamu koreksi bagian yang rusak, hasilnya malah berbeda dari yang kamu bayangkan awalnya. Setiap putaran koreksi terasa seperti mundur satu langkah untuk maju setengah langkah. Setelah dua jam sesi yang panjang, kamu punya kode yang teknis berjalan tapi tidak persis yang kamu inginkan — dan kamu tidak yakin bagian mana yang harus dipercaya.

Masalahnya Bukan Claude Code-nya

Cara kerja seperti itu punya nama: vibe coding. Kamu memulai dengan gambaran samar di kepala, lalu mendeskripsikan keinginan sedikit demi sedikit sambil merespons output Claude. Tidak ada spesifikasi tertulis, tidak ada rencana yang disetujui — hanya percakapan yang terus mengalir, dengan harapan hasilnya sesuai intuisi.

Vibe coding bukan masalah kecakapan Claude. Masalahnya ada di titik awal yang tidak jelas. Claude sangat baik dalam mengisi celah dengan asumsi yang masuk akal — tapi “masuk akal” bagi model tidak selalu berarti “sesuai niat kamu”. Setiap giliran percakapan yang baru, konteks tambahan masuk dan keputusan lama bisa tergusur. Di sesi yang panjang, ini terakumulasi menjadi drift yang signifikan antara apa yang kamu minta dan apa yang dihasilkan.

Satu masalah lain yang sering diabaikan: konteks percakapan tidak bertahan antar sesi. Semua keputusan desain yang sudah dibahas, semua trade-off yang sudah dipertimbangkan — semuanya hilang begitu sesi berakhir. Keesokan harinya kamu mulai dari nol lagi.

Tiga Langkah yang Mengubah Segalanya

Spec-Driven Workflow membalikkan urutan kerja. Sebelum satu baris kode ditulis, ada tiga dokumen yang harus ada:

Pertama, spesifikasi — deskripsi high-level tentang apa yang ingin dibangun, ditulis dari perspektif pengguna, tanpa detail implementasi teknis. Ini adalah kontrak antara kamu dan Claude tentang apa yang sedang dikerjakan.

Kedua, rencana implementasi — dokumen teknis yang menerjemahkan spec ke dalam file changes, data flow, dan keputusan arsitektur. Ini yang akan kamu review dan setujui sebelum implementasi dimulai.

Ketiga, daftar tugas — breakdown atomic dari rencana implementasi menjadi langkah-langkah kecil yang bisa dieksekusi satu per satu dan diverifikasi setelah selesai.

Alih-alih percakapan yang mengalir bebas, kamu punya tiga dokumen tertulis yang bertahan lintas sesi, bisa di-review, dan bisa dimodifikasi sebelum implementasi berjalan. Claude bukan lagi mitra ngobrol yang harus ditebak keinginannya — ia jadi eksekutor yang bekerja dari instruksi yang sudah kamu setujui.

Kenapa Git Wajib Ada di Sini

Sebelum masuk ke implementasi workflow, ada satu fondasi yang tidak bisa ditawar: Git.

Setiap kali memulai fitur baru dalam spec-driven workflow, Claude Code akan pindah ke branch baru. Ini bukan detail kecil — ini safety net yang kritis. Kalau implementasi berjalan ke arah yang salah, kamu bisa hapus branch dan kembali ke kondisi bersih tanpa bekas. Tanpa Git, kesalahan yang dibuat AI akan langsung memodifikasi kode utama kamu, dan rollback jadi jauh lebih menyakitkan.

Pastikan proyek kamu sudah punya Git repository sebelum melanjutkan. Semua contoh di ebook ini berasumsi kamu familiar dengan perintah dasar seperti git status, git checkout, dan git stash.

Membuat Slash Command /spec

Langkah pertama dalam membangun workflow ini adalah membuat custom slash command bernama /spec. Command ini yang akan mengotomatisasi proses membuat spesifikasi — mulai dari memilih nama fitur, membuat branch baru, sampai menghasilkan file spec dalam format yang konsisten.

Custom slash command di Claude Code disimpan sebagai file Markdown di dalam folder .claude/commands/. Nama file menentukan nama command: file spec.md di dalam folder tersebut akan bisa dipanggil dengan /spec.

Membuat Folder dan File Command

Buat folder .claude/commands/ di root proyek kalau belum ada, lalu buat file spec.md di dalamnya:

mkdir -p .claude/commands
touch .claude/commands/spec.md

Frontmatter Command

Setiap file command dimulai dengan frontmatter YAML yang mendefinisikan metadata command. Buka file spec.md dan tambahkan bagian ini di paling atas:

# .claude/commands/spec.md
---
description: Buat spec file dan branch baru dari deskripsi fitur singkat
argument-hint: <deskripsi singkat fitur>
allowed-tools: Read, Write, Glob, Bash
---

Field description menjelaskan fungsi command — Claude menggunakan ini untuk memahami kapan command relevan. Field argument-hint menampilkan petunjuk di autocomplete saat kamu mengetik /spec. Field allowed-tools membatasi tool yang bisa digunakan Claude saat command ini berjalan, tanpa perlu approval satu per satu.

Isi Command

Setelah frontmatter, tulis instruksi yang akan dijalankan Claude saat /spec dipanggil. Ini adalah isi lengkap yang perlu ada di spec.md:

# .claude/commands/spec.md
---
description: Buat spec file dan branch baru dari deskripsi fitur singkat
argument-hint: <deskripsi singkat fitur>
allowed-tools: Read, Write, Glob, Bash
---

Kamu akan membuat spesifikasi fitur baru berdasarkan input berikut:

$ARGUMENTS

Ikuti instruksi di CLAUDE.md jika ada. Lalu lakukan langkah-langkah berikut secara berurutan:

## Langkah 1: Cek Status Branch

Periksa apakah branch saat ini punya perubahan yang belum di-commit atau di-stage.
Jika ada, hentikan proses dan minta user untuk stash atau commit perubahan tersebut terlebih dahulu.

## Langkah 2: Ekstrak Nilai dari Input

Dari argumen yang diberikan, tentukan:
- **Feature title** — nama fitur dalam format yang mudah dibaca
- **Feature slug** — versi kebab-case dari feature title: huruf kecil, hanya huruf dan angka, spasi diganti tanda hubung. Contoh: `user-authentication-flow`
- **Branch name** — dengan format `claude/feature/<slug>`. Contoh: `claude/feature/user-authentication-flow`

## Langkah 3: Pindah ke Branch Baru

Buat dan pindah ke branch baru menggunakan branch name yang sudah ditentukan:

```bash
git checkout -b <branch-name>

Langkah 4: Buat File Spec

Buat file spec di folder _specs/ dengan nama file <feature-slug>.md. Gunakan struktur dari file template di _specs/template.md sebagai panduan.

Isi spec harus mencakup gambaran high-level fitur dari perspektif pengguna — bukan detail implementasi teknis atau contoh kode. Sertakan edge cases dan acceptance criteria yang jelas.

Jangan tambahkan detail teknis seperti nama fungsi, struktur database, atau contoh kode — itu untuk tahap planning selanjutnya.

Langkah 5: Balas dengan Ringkasan

Setelah selesai, jawab dengan ringkasan singkat yang mencantumkan:

• Branch yang dibuat
• Lokasi file spec
• Feature title

Perhatikan `$ARGUMENTS` di bagian awal isi command — ini adalah placeholder yang secara otomatis akan digantikan dengan teks yang kamu ketik setelah `/spec`. Jadi saat kamu menjalankan `/spec tambahkan fitur login dengan Google`, teks "tambahkan fitur login dengan Google" yang masuk ke instruksi Claude.

### Membuat Folder `_specs` dan Template

Command `/spec` akan menyimpan file spec ke folder `_specs/`. Buat folder ini beserta file template yang akan dijadikan panduan struktur:

```bash
mkdir _specs
touch _specs/template.md

Isi template.md dengan struktur berikut:

# _specs/template.md
# Feature Name

**Branch:** `claude/feature/...`

## Summary

Deskripsi singkat fitur — apa yang ingin dicapai dan mengapa.

## Functional Requirements

- Requirement 1
- Requirement 2

## Edge Cases

- Apa yang terjadi kalau...
- Bagaimana sistem merespons kalau...

## Acceptance Criteria

- [ ] Kriteria 1
- [ ] Kriteria 2

## Open Questions

Pertanyaan yang perlu dijawab sebelum implementasi bisa dimulai:

- ...

## Testing Guidelines

Aspek yang harus dicakup oleh test:

- ...

Template ini yang akan dijadikan acuan Claude saat mengisi spec. Dengan struktur yang sudah ditentukan, setiap spec yang dihasilkan akan konsisten dan punya bagian yang sama.

Cara Menjalankan Command

Setelah file command dan template siap, /spec langsung bisa digunakan. Ketik command diikuti deskripsi singkat fitur:

/spec tambahkan halaman profil pengguna dengan foto dan bio

Claude akan membaca instruksi dari spec.md, mengeksekusinya secara berurutan — mengecek status Git, mengekstrak nama fitur, membuat branch baru, lalu menulis file spec di _specs/ menggunakan struktur dari template.

Output yang kamu dapatkan bukan hanya file spec, tapi juga lingkungan kerja yang terisolasi: branch baru yang bersih, terpisah dari branch utama, siap untuk eksperimentasi tanpa risiko merusak kode yang ada.

Apa yang Terjadi Selanjutnya

Punya file spec adalah titik awal, bukan titik akhir. Spec yang dihasilkan Claude perlu kamu baca, koreksi, dan validasi — apakah semua requirement sudah tertangkap? Apakah ada edge case yang terlewat? Apakah acceptance criteria cukup konkret untuk bisa diverifikasi?

Setelah spec disetujui, proses berlanjut ke tahap planning: menggunakan Claude Code’s plan mode untuk menerjemahkan spec tersebut menjadi rencana implementasi teknis yang detail. Itulah yang akan kita kerjakan di bab selanjutnya — dan kamu akan melihat bagaimana spec yang ditulis dengan baik membuat tahap planning jauh lebih terarah.

Referensi

1. 1Claude Code Docs — Slash Commands & Skills
2. 2GitHub Blog — Spec-Driven Development: Using Markdown as a Programming Language
3. 3alexop.dev — Spec-Driven Development with Claude Code in Action