Spesifikasi fitur Claude Code dari kode: alur kerja sederhana

Mengapa Anda butuh spesifikasi yang sesuai dengan kode\n\nOrang sering tak sepakat tentang apa yang dilakukan sebuah aplikasi karena mereka mengingat versi yang berbeda. Support mengingat tiket terakhir yang marah. Sales mengingat jalur demo. Engineer mengingat apa yang fitur seharusnya lakukan. Tanyakan pada tiga orang dan Anda akan mendapatkan tiga jawaban yang percaya diri, dan tidak satu pun cocok dengan build saat ini.\n\nSeiring waktu, kode menjadi satu-satunya sumber yang tetap mutakhir. Dokumentasi melenceng, tiket ditutup, dan perbaikan cepat menumpuk. Sebuah rute mendapat aturan validasi baru. Toggle UI mengubah nilai default. Handler mulai mengembalikan error yang berbeda. Tak ada yang memperbarui spesifikasi karena terasa opsional, dan setiap perubahan terasa terlalu kecil untuk didokumentasikan.\n\nItu menciptakan masalah yang dapat diprediksi. Tim merilis perubahan yang memecah kasus tepi yang tidak mereka ketahui. QA menguji jalur bahagia dan melewatkan aturan yang tersembunyi di handler. Rekan baru meniru perilaku dari UI tanpa memahami batasan nyata. Pemangku kepentingan berdebat berdasarkan opini daripada menunjuk ke perilaku yang disepakati.\n\nHasil yang baik bukanlah dokumen sempurna. Itu adalah kejelasan bersama. Semua orang harus bisa menjawab: "Apa yang terjadi jika saya melakukan X?" dan "Apa yang dijamin sistem?" tanpa menebak. Anda akan mendapat lebih sedikit kejutan, siklus review lebih pendek, dan lebih sedikit momen "Tunggu, itu sudah ada" karena tim melihat kebenaran yang sama.\n\nSaat spesifikasi selaras dengan kode, menjadi aman untuk merencanakan perubahan. Anda bisa melihat apa yang stabil, apa yang kebetulan, dan apa yang hilang sebelum mengirimkan perubahan.\n\n## Apa itu spesifikasi hidup dan daftar celah\n\nSpesifikasi hidup adalah deskripsi singkat dan dapat diedit tentang apa yang aplikasi lakukan hari ini. Ini bukan dokumen sekali jadi. Ia berubah ketika perilaku berubah, sehingga tim bisa mempercayainya.\n\nSaat orang membicarakan spesifikasi fitur yang ditulis dari kode (misalnya menggunakan Claude Code), tujuannya sederhana: baca perilaku nyata dari rute, handler, dan layar, lalu tuliskan dalam bahasa biasa.\n\nSpesifikasi hidup yang berguna fokus pada apa yang bisa dilihat pengguna dan apa yang dijanjikan sistem. Ia harus mencakup:\n\n- Perilaku yang terlihat pengguna (apa yang terjadi ketika seseorang klik, submit, masuk)\n- Aturan dan batasan (field wajib, limit, perhitungan)\n- Kasus tepi (state kosong, error, retry, timeout)\n- Izin (siapa yang bisa melihat, membuat, mengedit, menghapus)\n- Output penting (email dikirim, record dibuat, status berubah)\n\nYang tidak perlu dicakup adalah bagaimana kode diorganisir. Jika Anda mulai menyebut nama file dan rencana refactor, Anda memasuki detail implementasi. Hindari:\n\n- Nama fungsi dan kelas, pohon komponen\n- Debat arsitektur dan rencana rewrite\n\nDaftar celah berbeda. Ini daftar kecil mismatch dan hal yang tidak jelas yang Anda temukan saat menulis spesifikasi.\n\n- Bug: kode melanggar perilaku saat ini atau aturan yang disepakati.\n- Permintaan fitur: Anda menginginkan perilaku baru.\n- Celah: Anda tidak bisa memastikan perilaku yang benar, atau perilaku tidak konsisten di antar layar/role.\n\nContoh: satu rute menolak file di atas 10MB, tapi UI mengatakan 25MB. Itu adalah celah sampai tim memutuskan aturan mana yang benar dan memperbarui kode atau spesifikasi.\n\n## Pilih cakupan dan format spesifikasi sederhana\n\nMulai dari yang kecil. Jika Anda mencoba mendokumentasikan seluruh aplikasi, Anda akan berakhir dengan tumpukan catatan yang tak ada yang percaya. Pilih satu irisan yang bisa dijelaskan pengguna dengan satu kalimat, seperti "mengundang rekan tim", "checkout", atau "reset password." Cakupan yang baik adalah satu area fitur, satu modul, atau satu perjalanan pengguna dari titik masuk sampai hasil.\n\nPilih titik masuk berdasarkan di mana kebenaran berada:\n\n- Jika Anda butuh aturan nyata, mulai dari rute dan handler.\n- Jika Anda butuh pengalaman nyata, mulai dari titik masuk UI.\n- Jika fiturnya rumit, mulai dari halaman/controller tingkat tinggi dan kerjakan ke luar.\n\nSebelum membaca kode, kumpulkan beberapa input agar mismatch terlihat cepat: dokumentasi API yang ada, catatan produk lama, tiket support, dan "pain points" yang diketahui orang. Ini tidak menggantikan kode, tapi membantu Anda melihat state yang hilang seperti error, kasus tepi, dan izin.\n\nJaga format spesifikasi tetap membosankan dan konsisten. Tim lebih cepat selaras ketika setiap spesifikasi dibaca dengan cara yang sama.\n\n### Template spesifikasi (ulang untuk setiap alur yang terlihat pengguna)\n\n- Purpose: apa yang ingin dicapai pengguna\n- Entry points: dari mana alur dimulai (URL, menu, tombol)\n- Preconditions: auth, peran, data yang diperlukan\n- Main flow: 5–10 langkah dalam bahasa biasa\n- Data dan side effects: record yang dibuat/diperbarui, email, log\n- Errors dan kasus tepi: apa yang terjadi saat ada masalah\n- Open questions: perilaku yang tidak jelas dan perlu dikonfirmasi\n\nGunakan struktur ini berulang-ulang supaya spesifikasi fitur tetap mudah dibaca, mudah dibandingkan, dan gampang diperbarui.\n\n## Mengekstrak perilaku dari rute dan handler\n\nMulai dari titik masuk server. Rute dan handler menunjukkan "apa yang aplikasi lakukan" dalam istilah konkret: siapa yang bisa memanggilnya, apa yang harus mereka kirim, apa yang mereka dapatkan kembali, dan apa yang berubah di sistem.\n\nDaftar rute dalam cakupan dan petakan masing-masing ke intent pengguna. Jangan tulis "POST /api/orders." Tulis "Place an order" atau "Save a draft." Jika Anda tidak bisa menamai intent dengan kata sederhana, itu sudah merupakan celah spesifikasi.\n\nSaat membaca setiap handler, tangkap input dan aturan validasi sebagai kebutuhan yang terlihat pengguna. Sertakan field wajib, format yang diizinkan, dan aturan yang menyebabkan error nyata. Contoh: "Email harus valid", "Quantity minimal 1", "Start date tidak boleh di masa lalu."\n\nTulis pengecekan auth dan role dengan cara yang sama. Alih-alih "middleware: requireAdmin," dokumentasikan: "Hanya admin yang bisa membatalkan semua order. Pengguna biasa hanya bisa membatalkan order mereka sendiri dalam 10 menit." Jika kode memeriksa kepemilikan, feature flag, atau batas tenant, sertakan juga.\n\nKemudian catat hasil dan output. Apa yang dikembalikan saat sukses (ID yang dibuat, objek yang diperbarui)? Seperti apa kegagalan umum (401 tidak masuk, 403 tidak diizinkan, 404 tidak ditemukan, 409 konflik, 422 error validasi)?\n\nTerakhir, catat side effects karena itu bagian dari perilaku: record yang dibuat atau diperbarui, email atau notifikasi yang dikirim, event yang dipublikasikan, background job yang di-antri, dan apa pun yang memicu alur lain. Detail ini mencegah kejutan saat tim mengandalkan spesifikasi nanti.\n\n## Mengekstrak perilaku dari komponen dan alur UI\n\nRute memberitahu apa yang aplikasi bisa lakukan. Komponen memberitahu apa yang sebenarnya dialami pengguna. Perlakukan UI sebagai bagian dari kontrak: apa yang muncul, apa yang diblokir, dan apa yang terjadi saat ada masalah.\n\nMulailah dengan menemukan layar entry untuk fitur. Cari komponen halaman, pembungkus layout, dan beberapa komponen "keputusan" yang mengatur fetching, izin, dan navigasi. Biasanya di situlah perilaku nyata berada.\n\nSaat membaca komponen, tangkap aturan yang bisa dirasakan pengguna: kapan aksi dinonaktifkan, langkah wajib, field kondisional, state loading, dan bagaimana error muncul (error field inline vs toast, auto-retry, tombol "coba lagi"). Catat juga perilaku state dan caching seperti data usang yang tampil duluan, optimistic updates, atau stempel waktu "last saved."\n\nWaspadai alur tersembunyi yang diam-diam mengubah apa yang dilihat pengguna. Cari feature flag, eksperimen, dan gate khusus admin. Catat juga redirect diam-diam, seperti mengirim pengguna yang belum login ke sign-in atau mengirim pengguna tanpa akses ke layar upgrade.\n\nContoh konkret: pada layar "Change Email", dokumentasikan bahwa tombol Save tetap nonaktif sampai email valid, spinner muncul selama request, sukses memicu banner konfirmasi, dan error validasi backend dirender di bawah input. Jika kode menunjukkan flag seperti newEmailFlow, catat kedua varian dan apa bedanya.\n\nTulis setiap alur UI sebagai langkah singkat (apa yang pengguna lakukan, apa yang UI lakukan sebagai respons) dan letakkan kondisi serta error di samping langkah yang terpengaruh. Itu menjaga spesifikasi tetap mudah dibaca dan membuat celah lebih mudah terlihat.\n\n## Ubah temuan menjadi spesifikasi fitur yang mudah dibaca\n\nCatatan mentah dari rute dan komponen berguna, tetapi sulit untuk didiskusikan. Tulis ulang apa yang Anda amati menjadi spesifikasi yang bisa dibaca dan disetujui oleh PM, desainer, QA, dan engineer.\n\nPolanya praktis: satu user story per rute atau layar. Jaga kecil dan spesifik. Contoh: "Sebagai pengguna yang sudah masuk, saya bisa mereset kata sandi agar saya bisa mendapatkan kembali akses." Jika kode menunjukkan perilaku berbeda menurut peran (admin vs user), pisahkan menjadi cerita terpisah daripada menyembunyikannya di catatan kaki.\n\nKemudian tulis acceptance criteria yang mencerminkan jalur kode nyata, bukan produk ideal. Jika handler mengembalikan 401 saat token hilang, itu menjadi kriteria. Jika UI menonaktifkan submit sampai field valid, itu juga kriteria.\n\nSertakan aturan data dalam bahasa biasa, terutama yang menyebabkan kejutan: batas, urutan, keunikan, field wajib. "Username harus unik (diperiksa saat save)" lebih jelas daripada "unique index."\n\nKasus tepi sering menjadi pembeda antara dokumen yang bagus dan dokumen yang berguna. Sebutkan empty states, nilai null, retry, timeout, dan apa yang dilihat pengguna saat panggilan API gagal.\n\nSaat menemukan hal yang tidak jelas, tandai daripada menebak:\n\n- Unknown: pesan apa yang harus muncul ketika email tidak ditemukan?\n- Unknown: bolehkah 0 item, atau minimal 1?\n- Unknown: apakah error ini untuk ditampilkan ke pengguna atau hanya dicatat?\n\nPenanda ini berubah menjadi pertanyaan cepat untuk tim daripada asumsi diam-diam.\n\n## Buat daftar celah tanpa mengubahnya jadi backlog\n\nDaftar celah bukanlah Jira kedua. Ini catatan singkat berbasis bukti tentang tempat kode dan perilaku yang dimaksud tidak cocok, atau tempat yang tidak jelas. Jika dilakukan dengan benar, ia menjadi alat untuk kesepakatan, bukan arena perencanaan.\n\nKetatkan aturan apa yang dihitung sebagai celah:\n\n- Perilaku tidak jelas: aplikasi melakukan sesuatu tetapi aturan tidak tertulis di mana pun.\n- Ketidakkonsistenan: dua tempat berperilaku berbeda untuk kasus yang sama.\n- Aturan hilang: ada kasus tepi tapi tidak ada keputusan terlihat di kode atau dokumen.\n\nSaat mencatat celah, sertakan tiga bagian supaya tetap berbasis bukti:\n\n- Tipe: bug (kode tampak salah) atau missing decision (intent tidak jelas)\n- Dampak: kebingungan pengguna, risiko keamanan, kehilangan data, atau minor\n- Bukti: di mana Anda melihatnya dan apa yang diamati (route/handler/component)\n\nBukti menjaga daftar tetap dari opini. Contoh: "POST /checkout/apply-coupon menerima kupon kadaluarsa, tetapi CouponBanner.tsx memblokirnya di UI. Dampak: pendapatan dan kebingungan pengguna. Tipe: bug atau missing decision (konfirmasi aturan)."\n\nJaga agar tetap singkat. Tetapkan batas keras, misalnya 10 item untuk putaran pertama. Jika Anda menemukan 40 isu, kelompokkan menjadi pola (ketidakkonsistenan validasi, pengecekan izin, empty states) dan simpan hanya contoh teratas.\n\nHindari tanggal dan penjadwalan di daftar celah. Jika perlu pemilik, buat ringan: catat siapa yang harus mengambil keputusan (product) atau siapa yang bisa memverifikasi perilaku (engineering), lalu pindahkan perencanaan nyata ke backlog Anda.\n\n## Contoh: mendokumentasikan fitur nyata dari kode\n\nPilih cakupan kecil yang sering dipakai: checkout dengan kode promo dan opsi pengiriman. Tujuannya bukan menulis ulang seluruh produk, melainkan menangkap apa yang aplikasi lakukan hari ini.\n\nMulai dengan rute backend. Di sanalah aturan sering muncul pertama kali. Anda mungkin menemukan rute seperti POST /checkout/apply-promo, GET /checkout/shipping-options, dan POST /checkout/confirm.\n\nDari handler tersebut, tulis perilaku dalam kata biasa:\n\n- Kode promo divalidasi di server (kedaluwarsa, batas penggunaan, kelayakan pelanggan).\n- Total dihitung ulang setelah promo diterapkan, tetapi hanya setelah inventaris diperiksa ulang.\n\n- Opsi pengiriman bergantung pada tujuan, berat, dan apakah ada item yang ditandai sebagai restricted.\n- Konfirmasi gagal jika stok item berubah sejak cart dimuat.\n- Pajak dihitung setelah opsi pengiriman dipilih (bukan saat promo diterapkan).\n\nLalu periksa komponen UI. PromoCodeInput mungkin menampilkan total hanya setelah respons sukses dan error dirender inline di bawah input. Komponen ShippingOptions mungkin memilih opsi termurah pada pemuatan pertama dan memicu refresh rincian harga penuh saat pengguna mengubahnya.\n\nSekarang Anda punya spesifikasi yang dapat dibaca dan daftar celah kecil. Misalnya: pesan error berbeda antara route promo dan UI ("Invalid code" vs "Not eligible"), dan tak ada yang bisa menjelaskan aturan pembulatan pajak (per baris vs total order).\n\nDalam perencanaan, tim setuju pada realitas dulu, lalu memutuskan apa yang diubah. Daripada berdebat opini, Anda meninjau perilaku yang terdokumentasi, pilih satu ketidakkonsistenan untuk diperbaiki, dan biarkan sisanya sebagai "perilaku saat ini yang diketahui" sampai layak ditinjau lagi.\n\n## Validasi spesifikasi dengan tim dan jaga agar tetap mutakhir\n\nSpesifikasi hanya berguna jika tim setuju bahwa itu mencerminkan realitas. Lakukan baca cepat dengan satu engineer dan satu product person. Jaga singkat: 20–30 menit fokus pada apa yang pengguna bisa lakukan dan apa yang sistem lakukan sebagai respons.\n\nSaat read-through, ubah pernyataan menjadi pertanyaan ya/tidak. "Saat pengguna memanggil rute ini, apakah kita selalu mengembalikan 403 tanpa sesi?" "Apakah empty state ini disengaja?" Ini memisahkan perilaku yang diinginkan dari yang kebetulan masuk seiring waktu.\n\nSepakati kosakata sebelum Anda mengedit apa pun. Gunakan kata yang terlihat pengguna di UI (label tombol, judul halaman, pesan). Tambahkan nama internal hanya jika membantu engineer menemukan kode (nama route, nama komponen). Ini mencegah mismatch seperti produk menyebut "Workspace" sementara spesifikasi mengatakan "Org."\n\nUntuk menjaganya mutakhir, buat kepemilikan dan ritme eksplisit:\n\n- Pemilik spesifikasi: satu orang yang menggabungkan perubahan spesifikasi (sering pemilik fitur atau tech lead)\n- Pemicu pembaruan: pada merge PR untuk perubahan perilaku, atau setiap rilis\n- Cek singkat: tambahkan kotak centang "spec updated?" ke template PR Anda\n- Penyimpanan: simpan dekat dengan kode sehingga berubah seiring kode berubah\n\nJika Anda menggunakan alat seperti Koder.ai, snapshot dan rollback bisa membantu membandingkan "sebelum" dan "sesudah" perilaku saat memperbarui spesifikasi, terutama setelah refactor besar.\n\n## Kesalahan umum dan jebakan\n\nCara tercepat kehilangan kepercayaan terhadap spesifikasi adalah mendeskripsikan produk yang Anda inginkan, bukan produk yang Anda miliki. Terapkan aturan keras: setiap pernyataan harus didukung oleh sesuatu yang bisa Anda tunjuk di kode atau layar nyata.\n\nJebakan lain adalah menyalin bentuk kode ke dokumen. Spesifikasi yang berbunyi seperti "Controller -> Service -> Repository" bukanlah spesifikasi, melainkan peta folder. Tulis dalam istilah yang terlihat pengguna: apa yang memicu aksi, apa yang pengguna lihat, apa yang disimpan, dan seperti apa error.\n\nIzin dan peran sering diabaikan sampai akhir, lalu semuanya runtuh. Tambahkan aturan akses lebih awal, bahkan jika berantakan. Sebutkan peran yang bisa melihat, membuat, mengedit, menghapus, mengekspor, atau menyetujui, dan di mana aturan ditegakkan (UI saja, API saja, atau keduanya).\n\nJangan lewatkan jalur non-happy. Perilaku nyata tersembunyi di retry, kegagalan parsial, dan aturan berbasis waktu seperti kedaluwarsa, cooldown, job terjadwal, atau batas "hanya sekali per hari." Perlakukan ini sebagai perilaku kelas satu.\n\nCara cepat untuk menemukan celah adalah memeriksa:\n\n- Kegagalan validasi dan pesan error yang tepat yang dilihat pengguna\n- Penanganan pengiriman duplikat (idempotency)\n- Pekerjaan background (queue, cron) dan apa yang terjadi jika gagal\n- Masalah konkurensi (dua pengguna mengubah record sama)\n- Perilaku berbasis waktu (timeout, kedaluwarsa, rate limits)\n\nTerakhir, gerakkan daftar celah Anda. Setiap celah harus dilabeli sebagai salah satu: "unknown, needs decision," "bug, fix," atau "missing feature, plan." Jika tidak ada yang diberi label, daftar akan mandek dan spesifikasi berhenti menjadi "hidup."\n\n## Checklist cepat sebelum Anda membagikan spesifikasi\n\nLakukan pemeriksaan cepat untuk kejelasan, cakupan, dan keterlaksanaan. Seseorang yang tidak menulisnya harus mengerti apa yang fitur lakukan hari ini, dan apa yang masih tidak jelas.\n\n### Kejelasan dan pemahaman bersama\n\nBaca spesifikasi seperti rekan baru di hari pertama. Jika mereka bisa merangkum fitur dalam satu menit, Anda hampir selesai. Jika mereka terus bertanya "dari mana mulai?" atau "apa jalur bahagia?" perbaiki bagian pembuka.\n\nPeriksa:\n\n- Tes satu halaman: pembuka menyatakan tujuan pengguna, dari mana alur dimulai, dan ke mana berakhir.\n- Peran dan akses: peran kunci dan apa yang masing-masing bisa dan tidak bisa lakukan.\n- Hasil: seperti apa sukses dan apa yang pengguna lihat saat gagal (pesan, redirect, retry).\n- Tepi dan batas: batas ukuran, rate limit, timeout, aturan validasi, dan apa yang terjadi ketika data hilang.\n- Bahasa: gunakan istilah yang terlihat pengguna terlebih dahulu; definisikan jargon yang tak bisa dihindari sekali saja.\n\n### Celah yang membantu, bukan bising\n\nSetiap celah harus spesifik dan bisa diuji. Daripada menulis "Penanganan error tidak jelas," tulis: "Jika penyedia pembayaran mengembalikan 402, UI menampilkan toast generik; konfirmasi pesan yang diinginkan dan perilaku retry." Tambahkan satu tindakan selanjutnya (tanya product, tambah test, periksa logs) dan catat siapa yang harus menjawab.\n\n## Langkah selanjutnya untuk mulai minggu ini\n\nPilih satu area fitur dan batasi waktu 60 menit. Pilih sesuatu yang kecil tapi nyata (login, checkout, pencarian, layar admin). Tulis satu kalimat cakupan: apa yang termasuk dan apa yang tidak.\n\nJalankan workflow sekali end-to-end: intip rute/handler utama, telusuri alur UI utama, dan tulis perilaku yang bisa diamati (input, output, validasi, state error). Jika terhenti, catat pertanyaannya sebagai celah dan lanjutkan.\n\nSaat selesai, bagikan spesifikasi agar tim bisa memberi komentar, dan tetapkan satu aturan: setiap perubahan perilaku yang dikirim harus memperbarui spesifikasi di jendela delivery yang sama, meskipun hanya lima baris.\n\nSimpan daftar celah terpisah dari backlog. Kelompokkan menjadi "perilaku tidak diketahui," "perilaku tidak konsisten," dan "test yang hilang," lalu tinjau singkat setiap minggu untuk memutuskan apa yang penting sekarang.\n\nJika menyusun dan mengiterasi terasa lambat, builder berbasis chat seperti Koder.ai dapat membantu Anda mendapatkan versi awal dengan cepat. Deskripsikan fitur, tempel snippet atau nama route kunci, perbaiki kata-kata lewat percakapan, dan ekspor sumber saat diperlukan. Intinya adalah kecepatan dan kejelasan bersama, bukan proses yang lebih besar.