Pengembangan Berbasis Spesifikasi dengan Claude Code: Tutorial Terbimbing

Apa Itu Pengembangan Berbasis Spesifikasi?

Pengembangan berbasis spesifikasi adalah alur kerja yang dibangun di atas tiga dokumen secara berurutan: satu yang menjelaskan apa yang harus dilakukan suatu perubahan, sebuah rencana yang merinci langkah-langkahnya, dan kode yang ditulis mengikuti rencana tersebut, dengan tinjauan manusia di antara setiap pasangan.

Tiga titik tinjauan yang dilewati sebuah fitur dalam pengembangan berbasis spesifikasi.

Sebuah spesifikasi adalah dokumen singkat, ditulis dengan bahasa lugas sebelum ada kode, yang menjelaskan apa yang harus dilakukan suatu perubahan. Ambil contoh fitur seperti "biarkan pengguna mengekspor data mereka." Spesifikasinya menetapkan jawaban yang jika tidak akan ditebak oleh agen. Spesifikasi itu mencantumkan 

• Format file yang didukung
• Mode pengiriman
• Perilaku saat ekspor setengah jalan
• Bagian-bagian fitur yang sengaja dikecualikan

Berikut pembukaan nyata dari spesifikasi yang ditulis Claude Code untuk perubahan workout-shape-verification pada aplikasi akuntabilitas berbasis Telegram milik saya. Perubahan ini mengganti ambang detak jantung yang rapuh dengan pemeriksaan bentuk kurva detak jantung dari waktu ke waktu:

# Workout Shape-Based Verification — Design Spec
 
**Created:** 2026-05-05
**Status:** Draft
**Supersedes (partially):** [2026-03-17-calisthenics-verification-design.md]
  — replaces the absolute-HR thresholds for the Workout activity type.
  Run / Ride / Walk verification is unchanged.
 
## Problem
 
The current Workout verifier accepts an activity only if absolute heart-rate
levels clear fixed cutoffs: avg ≥ 120, max ≥ 140, range ≥ 30, suffer_score ≥ 3.
Two failures in production:
 
1. **False-negative risk.** As cardiovascular fitness improved
   (resting HR ~80), real calisthenics sessions with disciplined rest now
   average 115–125 bpm. Recent sessions have come within 4 bpm of the 120 floor.
 
<!-- ... continues for hundreds of lines through Solution, Risks,
 	Out of scope, and What is removed / added / changed / unchanged -->

Rencana adalah dokumen berikutnya. Rencana memecah spesifikasi di atas menjadi tugas-tugas bernomor yang bisa dikerjakan agen satu per satu, tiap tugas menyebutkan file, perubahan, urutan, dan ujiannya. Jika spesifikasi menjawab "apa," rencana menjawab "dalam langkah apa." 

Kode datang terakhir, ditulis mengikuti rencana satu tugas setiap kali.

Tiga dokumen. Ada tinjauan manusia di antara setiap pasangan. Anda meninjau spesifikasi sebelum menjadi rencana. Anda meninjau rencana sebelum menjadi kode. Anda meninjau kode sebelum melakukan merge.

Perbedaan pengembangan berbasis spesifikasi dari mode rencana

Anda mungkin pernah menggunakan mode rencana bawaan Claude Code (tekan Shift+Tab dua kali untuk masuk) dan bertanya-tanya apa bedanya ini. Mode rencana menghasilkan rencana dalam satu giliran percakapan. Rencana itu hidup di memori, tanpa spesifikasi yang disimpan dan tanpa langkah tinjauan di antara fase.

Pengembangan berbasis spesifikasi menyimpan spesifikasi dan rencana sebagai file di disk. Masing-masing melewati tinjauan manusia sebelum fase berikutnya dimulai, dan artefaknya bertahan lintas sesi. Mode rencana memadatkan dua fase pengembangan perangkat lunak menjadi satu giliran chat. Itu bekerja untuk pekerjaan kecil dan gagal begitu basis kode tumbuh dan mulai melayani pengguna nyata.

Mengapa Vibe-Coding Mentok

Vibe-coding bekerja untuk prototipe, file tunggal, dan skrip yang dibuang setelahnya. Ini makin buruk pada aplikasi nyata dengan pengguna serta pada basis kode besar yang sudah ada. Batas yang layak ditarik adalah sekitar 4 file. Perubahan apa pun yang menyentuh sebanyak itu perlu spesifikasi, begitu juga refactor dengan kondisi akhir yang koheren, atau tugas apa pun di mana "sebenarnya ini harus melakukan apa?" adalah bagian tersulitnya.

Kegagalannya punya penyebab jelas. Prompt samar seperti "tambahkan berbagi foto ke aplikasi saya" membuat model menebak ribuan kebutuhan yang tidak dinyatakan.

Ambil satu saja dari kebutuhan itu: preferensi notifikasi. Manajer produk mengasumsikan toggle per kanal. Backend membangun sakelar hidup/mati. Frontend mengasumsikan integrasi tingkat OS. Empat pembacaan yang masuk akal dari tiga kata, empat produk berbeda.

Setiap langkah tinjauan dalam pengembangan berbasis spesifikasi menangkap kelas kesalahan yang berbeda sebelum menjadi mahal. Tinjauan spesifikasi menangkap pelebaran ruang lingkup dan perumusan penyebab-akarnya yang keliru. Tinjauan rencana menangkap implementasi setengah jadi dan pola yang bertentangan. Tinjauan kode menangkap rencana yang terlihat baik namun patah pada uji gagal pertama.

Imbalannya nyata, dan dibangun perlahan. Fase spesifikasi memakan waktu berjam-jam menulis sebelum ada kode yang berjalan, dan beberapa fitur pertama terasa lebih lambat daripada vibe-coding. Titik impas saya sendiri muncul sekitar fitur keempat atau kelima. Pada saat itu, spesifikasi mulai menangkap kesalahan desain yang jika tidak akan saya kirimkan dan tulis ulang seminggu kemudian.

Tiga bagian berikut menelusuri tiga pendekatan open-source yang menjalankan alur kerja ini di dalam Claude Code. Urutannya dari yang paling ringan hingga terberat dalam struktur yang ditegakkannya.

Superpowers

Superpowers adalah yang paling ringan dari ketiganya. Ini yang saya gunakan sehari-hari, dan yang akan kita bahas paling detail.

Apa itu Superpowers?

Superpowers adalah plugin Claude Code karya Jesse Vincent (obra/superpowers, berlisensi MIT), dengan sekitar 194k bintang di GitHub. 

Plugin ini menyertakan satu set skill. Skill Claude dalam Claude Code adalah file instruksi bernama yang dimuat agen sesuai permintaan untuk mengikuti alur kerja tertentu. Superpowers menyertakan skill yang menahan Claude Code pada loop berbasis spesifikasi alih-alih membiarkannya langsung melompat ke penulisan kode.

Halaman proyek Superpowers di GitHub.

Cara memasang Superpowers

Pasang melalui marketplace plugin resmi Claude Code:

/plugin install superpowers@claude-plugins-official

Hook SessionStart memuat otomatis skill using-superpowers, jadi alur kerja aktif saat Anda mulai mengetik. (Hook Claude code adalah skrip yang dijalankan agen pada peristiwa siklus hidup tertentu.) Tidak ada yang perlu dikonfigurasi per proyek.

Alur kerja Superpowers

Setelahnya, empat skill mengelola pekerjaan harian Anda:

Subagent adalah instance Claude Code terpisah yang dipanggil induk untuk mengerjakan tugas terfokus dalam jendela konteksnya sendiri. Subagent peninjau pada tabel di atas berjalan sebagai subagent, sehingga mereka membaca kode tanpa konteks induknya.

Cara menggunakan Superpowers

Anda memanggil empat skill ini dengan menjelaskan apa yang Anda inginkan dalam bahasa lugas. Skill brainstorming mengenali "mari kita diskusikan fitur baru ini" dan memulai percakapan spesifikasi dengan sendirinya. Skill lainnya terpicu dengan cara yang sama.

Empat skill Superpowers berurutan, dengan dua titik tinjauan manusia di antara brainstorming dan writing-plans.

Penjelasan berikut menggunakan fitur yang sama workout-shape-verification dari kutipan spesifikasi di atas.

Tahap 1: brainstorming ke spesifikasi

Saya membuka Claude Code dan mengetik:

Let's discuss a new feature. The Workout verifier in make-me-work uses absolute heart-rate cutoffs and is now misfiring as my resting HR drops. I want to replace the absolute cutoffs with a check on the shape of the HR curve over the session.

Skill brainstorming mengambil alih dan mengajukan sekitar sepuluh pertanyaan balik, di antaranya:

• Apa yang dianggap sebagai "bentuk" yang benar
• Aliran data mana yang dikombinasikan
• Apa yang harus dilakukan pada sesi yang bentuknya terlihat benar tetapi gagal ambang lama
• Apakah perubahan juga berlaku untuk Run dan Ride

Dua titik tinjauan manusia terjadi di sini. Yang pertama adalah tinjauan desain, saat saya mengonfirmasi jawaban yang saya berikan sesuai dengan yang saya inginkan. Yang kedua adalah tinjauan spesifikasi. Saya membaca file yang ditulis Claude dan menyetujuinya sebelum pekerjaan rencana dimulai.

Tahap 2: spesifikasi ke rencana

Saya menjalankan skill writing-plans. Skill ini membaca spesifikasi yang disetujui dan menulis file rencana dengan empat bagian:

• Definisi arti “Selesai”
• Peta file dari file yang disentuh
• Perjalanan pengguna melalui jalur demo
• Daftar tugas bernomor berupa sub-langkah dengan kotak centang. 

Saya meninjau rencana, menolak tugas yang terlihat tidak berurutan atau terlalu kasar, dan menyetujuinya.

Tahap 3: rencana ke kode

Saya menjalankan subagent-driven-development. Mulai titik ini loop berjalan tanpa saya. Untuk tiap tugas dalam rencana, skill ini:

1. Menulis uji yang gagal
2. Menulis kode untuk meloloskannya
3. Merapikan (refactor)
4. Memanggil subagent code-review yang membaca diff secara dingin

Jika peninjau menandai masalah, loop memperbaikinya sebelum pindah ke tugas berikutnya. Tidak ada titik tinjauan manusia di dalam tahap ini. Tinjauan yang penting bagi tahap ini adalah dua yang sebelumnya.

Tahap 4: tinjauan full-diff

Setelah rencana selesai, saya menjalankan requesting-code-review. Subagent baru membaca seluruh diff terhadap spesifikasi dan rencana, lalu memposting tinjauan. Saya mengambil sarannya sebelum melakukan merge.

Ketika sebuah tugas dalam rencana mengungkap kontradiksi dengan spesifikasi, loop berhenti dan bertanya. Saya dapat mengedit spesifikasi (atau membiarkan Claude melakukannya) dan menjana ulang tugas yang terdampak. Opsi lain adalah koreksi satu kali pada tugas itu sendiri. Superpowers tidak akan diam-diam mengakali kesalahan spesifikasi.

Spesifikasi dan rencana nyata di disk

Berikut adalah spesifikasi untuk fitur workout-shape-verification, terbuka di editor:

File spesifikasi seperti yang tersimpan di disk setelah skill brainstorming menulisnya.

Header memuat field Created, Status, dan Supersedes yang ditulis skill brainstorming secara default. Bagian Problem menyusul. Tidak ada bagian yang berupa kode. File berlanjut melampaui tangkapan layar melalui bagian solusi yang diusulkan serta batasan tentang apa yang seharusnya disentuh dan tidak disentuh perubahan.

Rencana yang cocok dibuka dengan User Journey:

File rencana yang dihasilkan skill writing-plans dari spesifikasi yang disetujui.

Perjalanan ini menapaki jalur demo lima langkah sekaligus, menyebutkan perintah, file, dan argumen yang tepat di setiap langkah. Tugas-tugas bernomor yang menyusul menerjemahkan setiap langkah menjadi sub-langkah dengan kotak centang yang bisa dikerjakan skill subagent-driven-development.

Kedua dokumen berpasangan seperti ini:

Spesifikasi dan rencana berdampingan. Spesifikasi menjawab apa yang berubah dan mengapa. Rencana menjawab dalam langkah apa.

Untuk spesifikasi dan rencana yang lebih besar, saya menambahkan satu langkah yang tidak ada di loop resmi: red-team pass. Sebelum saya menyetujui, saya meminta satu atau beberapa subagent Opus membaca spesifikasi tanpa konteks, mencari celah dari sudut berbeda. Itu kebiasaan pribadi, bukan fitur Superpowers. Cukup banyak asumsi buruk yang tertangkap sehingga saya terus melakukannya.

Kapan Superpowers bukan pilihan tepat

Superpowers cocok untuk kerja solo pada satu repo. Ini bekerja terbaik saat seluruh basis kode muat dalam satu sesi Claude Code, dan Anda benar-benar akan membaca spesifikasi 2 halaman. Perbandingan detailnya ada di Cara memilih di antara mereka lebih bawah. Versi singkat: Superpowers kesulitan dengan fitur multi-repo dan pekerjaan yang butuh pemisahan peran yang jelas.

Seorang pengembang menangkap mode kegagalan keempat dalam keluhan publik tentang plugin ini: “Bahkan tugas terkecil memakan waktu lama, dengan Claude memunculkan subagent dan menulis rencana yang benar-benar berlebihan. Mengubah sedikit CSS sekarang butuh selamanya.”

Solusinya adalah melewati Superpowers untuk perubahan kecil. Skill hanya aktif pada pemicu brainstorming. Penyuntingan CSS satu baris bisa dilakukan lewat Claude Code tanpa pernah memanggil loop spesifikasi. Mode kegagalan sebenarnya di sini adalah menerapkan alur kerja berlebihan pada pekerjaan yang tidak memerlukan spesifikasi.

GitHub Spec Kit

Spec Kit adalah pilihan ketika spesifikasi harus bertahan melampaui satu sesi Claude Code. Ini juga tepat ketika orang yang tidak pernah membuka Claude Code perlu membaca spesifikasi.

Apa itu GitHub spec-kit?

Spec Kit adalah proyek GitHub (github/spec-kit, lisensi MIT), dikelola oleh GitHub sendiri, dengan lebih dari 100k bintang. Ia menyertakan CLI plus alur kerja yang berjalan sama di setiap agen pengodean AI utama. Claude Code, Cursor, Aider, Cline, dan Roo Code semuanya didukung. Desain yang netral terhadap agen inilah yang memungkinkan spesifikasi hidup di luar Claude Code.

Halaman proyek Spec Kit di GitHub.

Cara memasang GitHub spec-kit

Belum ada paket PyPI resmi, jadi pasang CLI dari tag Git menggunakan uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Ganti vX.Y.Z dengan tag rilis saat ini. Paketnya adalah specify-cli, dan perintah yang didaftarkannya adalah specify.

Alur kerja GitHub spec-kit

Alur kerja berjalan melalui sembilan perintah garis miring yang diinstal CLI ke daftar perintah garis miring agen Anda. Enam inti untuk loop, tiga opsional untuk kasus yang tidak tercakup oleh loop inti.

Pemisah antara grup perintah dan verba adalah titik, bukan titik dua: /speckit.specify, bukan /speckit:specify. 

Sembilan perintah garis miring Spec Kit: enam perintah inti pada pipa, tiga perintah opsional menggantung darinya.

Artefak yang dihasilkan perintah-perintah ini adalah spesifikasi dan rencana yang sama seperti pada bagian Superpowers, juga ditulis ke disk dan dilacak oleh Git. Bedanya adalah portabilitas: artefak Spec Kit dirancang untuk bekerja dengan agen pengodean AI mana pun, bukan hanya Claude Code, dan alur kerjanya dibangun untuk tinjauan pemangku kepentingan melalui pull request GitHub alih-alih sebagai produk sampingan dari loop satu alat.

Kapan menggunakan GitHub spec-kit

Pada proyek solo, Anda mungkin tidak memerlukan Spec Kit. Gunakan ketika:

• Proyek tumbuh melampaui satu orang
• Spesifikasi Anda perlu ditinjau oleh orang yang tidak pernah membuka Claude Code
• Anda menjalankan agen non-Claude Code untuk sebagian pekerjaan
• Anda menginginkan format spesifikasi yang hidup di luar alat mana pun dan tetap terbaca berbulan-bulan kemudian

Metode BMAD

Jika Spec Kit mengorganisasi artefak, BMAD mengorganisasi orang. Ia membagi alur kerja dari spesifikasi ke kode menjadi empat fase, masing-masing dijalankan oleh role-agent bernama.

Apa itu BMAD?

BMAD-METHOD (bmad-code-org/BMAD-METHOD, lisensi MIT, sekitar 47k bintang) sudah pada versi 6. Akronimnya, menurut dokumentasi proyek, adalah "Breakthrough Method for Agile AI-Driven Development." Ia berjalan di atas Claude Code dan agen lain, dan terpasang sebagai ekosistem modul. Instalasi default memberi Anda modul inti yang memuat enam role-agent, empat fase alur kerja, dan 34 atau lebih alur kerja bernama.

Halaman proyek BMAD-METHOD di GitHub.

Cara memasang BMAD

Pasang BMAD dengan Node:

npx bmad-method install

Enam role-agent adalah persona prompt yang diaktifkan pengguna berdasarkan nama dari dalam host agen. Di Claude Code, itu berarti mengetik perintah aktivasi yang dipasang BMAD. Lihat README untuk sintaks tepatnya, yang bisa berubah antar rilis. 

Mengenalkan agen rekan BMAD dan artefaknya

Setelah diaktifkan, agen mengambil instruksi, suara, dan keluaran peran tersebut sampai Anda mengganti persona. Keenamnya adalah:

• Mary, Analis
• Paige, Penulis Teknis
• John, Manajer Produk
• Sally, Desainer UX
• Winston, Arsitek
• Amelia, Pengembang

Dua peran yang mungkin Anda harapkan tidak ada di v6: tidak ada agen Scrum Master dan tidak ada agen QA mandiri. Perencanaan sprint dan persiapan story jatuh ke agen Pengembang, dan pembuatan uji QA adalah alur kerja yang dipicu oleh Pengembang.

Set artefaknya lebih berat daripada satu spesifikasi. Anda mendapatkan:

• ringkasan produk
• PRD (Product Requirements Document)
• spesifikasi UX
• dokumen arsitektur
• epic yang dipecah menjadi user story (apa yang bisa dilakukan pengguna setelah pekerjaan dirilis)

PRD dan dokumen arsitektur bersama-sama memainkan peran yang sama seperti spesifikasi Superpowers. Pembagiannya menempatkannya pada dua role-agent dan ke format yang lebih formal. Set artefak secara keseluruhan mencakup siklus hidup pengembangan perangkat lunak penuh, dengan tiap fitur mewarisi konteks dari lapisan di atasnya.

Alur kerja BMAD

Alur kerja v6 berjalan dalam empat fase.

Empat fase BMAD dan role-agent yang menjalankan masing-masing. Jalur Quick Flow melewati tiga fase pertama untuk pekerjaan kecil.

Fase 1, analisis, bersifat opsional. Mary (Analis) dan Paige (Penulis Teknis) menjalankan riset dan menghasilkan ringkasan produk. Lewati fase ini jika Anda sudah tahu apa yang akan dibangun.

Fase 2, perencanaan, wajib. John (PM) menulis PRD. Sally (Desainer UX) menambahkan spesifikasi UX ketika fiturnya memiliki UI.

Fase 3, perancangan solusi (solutioning), adalah fasenya Winston. Arsitek menyusun arsitektur terlebih dahulu, lalu John memecah kebutuhan menjadi epic dan story. Menempatkan story setelah arsitektur adalah pilihan v6 yang menyesuaikannya dengan batas implementasi yang nyata. Winston kemudian menjalankan pemeriksaan kesiapan implementasi yang berakhir dengan vonis PASS, CONCERNS, atau FAIL.

Fase 4, implementasi, adalah saat Amelia (Pengembang) bekerja per story: membuat story, membangunnya, dan melakukan code-review. Setelah satu epic penuh selesai, ia memicu alur kerja pembuatan uji QA untuk seluruh epic. Inilah fase tempat Claude Code melakukan pengodean sebenarnya, bekerja sebagai Amelia.

Untuk pekerjaan kecil yang ruang lingkupnya jelas, BMAD menyertakan jalur "Quick Flow" yang langsung mengaktifkan Amelia dan melewati tiga fase pertama. Perintah aktivasinya ada di README BMAD (sintaks tepatnya bisa berubah antar rilis). Quick Flow tidak menghasilkan PRD maupun dokumen arsitektur, hanya story singkat dan kode yang memenuhinya. Ini jawaban atas keberatan "ini berlebihan untuk perubahan tombol."

Ketika spesifikasi ternyata salah di tengah implementasi, BMAD memutar balik melalui vonis Fase 3 dari Winston. FAIL mengirim Anda kembali ke Fase 2 untuk menulis ulang PRD. CONCERNS melanjutkan dengan risiko yang dicatat Winston terlampir pada story. Pemisahan ini memungkinkan Anda terus bergerak pada inkonsistensi kecil dan berhenti keras pada yang besar.

Kapan kompleksitasnya terbayar

BMAD terbayar pada proyek jangka panjang dengan pengguna nyata yang harus dijawab. Ini juga cocok untuk tim multi-pengembang, dengan penyerahan pekerjaan antar orang. Pemisahan fase dan peran harus menghemat lebih banyak waktu daripada biayanya.

Ini bukan pilihan tepat untuk proyek sampingan seorang diri. Pada kerja solo, pemisahan empat fase dan enam agen kebanyakan menjadi overhead. Tidak ada orang kedua dalam tim sehingga pemisahan peran tidak berarti.

Cara Memilih di Antara Kerangka

Tiga aturan menentukan pilihan.

• Gunakan Spec Kit jika spesifikasi harus dibaca oleh orang yang tidak pernah membuka Claude Code, atau harus hidup di Git sebagai artefak jangka panjang.
• Jika beberapa orang bekerja dalam peran yang berbeda jelas, atau ada pemangku kepentingan ala PM di loop, gunakan BMAD.
• Jika tidak, gunakan Superpowers.

Tiga pertanyaan tentang proyek Anda, empat pilihan kerangka di sisi lainnya.

Ada opsi keempat yang dinamai pohon keputusan: menggabungkan Spec Kit dengan Superpowers. Gunakan Spec Kit untuk fase spesifikasi agar artefak hidup di Git untuk tinjauan lintas tim. Lalu arahkan skill subagent-driven-development milik Superpowers ke file rencana Spec Kit dengan satu baris konfigurasi. Anda mendapatkan spesifikasi yang tahan lama dari Spec Kit berdampingan dengan loop implementasi yang ketat dari Superpowers.

Penutup

Pengembangan berbasis spesifikasi adalah tiga dokumen berurutan. Spesifikasi menyatakan apa yang dibangun, rencana menyatakan dalam langkah apa, dan kode mengikuti rencana. Ada tinjauan manusia di antara setiap pasangan.

Jalankan pohon keputusan di atas untuk memilih kerangka, yang bagi sebagian besar pembaca akan jatuh pada Superpowers. Pasang dan pilih satu fitur yang sebaliknya akan Anda lakukan dengan vibe-coding, sesuatu yang menyentuh 3 hingga 5 file. Jalankan ujung-ke-ujung melalui brainstorming, spesifikasi, rencana, dan eksekusi. Satu kali praktik nyata mengajarkan alur kerja lebih baik daripada deskripsi apa pun.

Jika Anda ingin menyegarkan kembali dasar-dasar Claude Code terlebih dahulu, DataCamp memiliki tutorial Claude Code yang praktis, panduan praktik terbaik yang membahas mode rencana, CLAUDE.md, dan TDD, serta pembahasan mendalam tentang mode rencana itu sendiri.