Pelajari cara membuat spesifikasi fitur Claude Code dari kode dengan mengekstrak perilaku aplikasi nyata dari rute dan komponen, lalu menghasilkan spesifikasi hidup dan daftar celah.
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.Mulailah dari satu bagian kecil yang terlihat oleh pengguna (misalnya “reset password” atau “undang rekan tim”). Baca routes/handlers untuk menangkap aturan dan hasil, lalu periksa aliran UI untuk menangkap apa yang benar-benar dilihat pengguna (status nonaktif, pesan error, pengalihan). Tulis menggunakan template yang konsisten dan catat ketidakjelasan sebagai daftar celah terpisah.
Default: anggap perilaku kode saat ini sebagai sumber kebenaran dan dokumentasikan itu.\n\nJika perilaku tampak tidak sengaja atau tidak konsisten, jangan “memperbaikinya” di spesifikasi—tandai sebagai gap dengan bukti (di mana Anda menemukannya dan apa yang terjadi), lalu minta keputusan untuk memperbarui kode atau spesifikasi.
Buat format yang membosankan dan bisa diulang. Template praktisnya adalah:\n\n- Purpose\n- Entry points\n- Preconditions (auth/role/data)\n- Main flow (5–10 langkah)\n- Data dan side effects\n- Errors dan edge cases\n- Open questions\n\nIni membuat spesifikasi tetap mudah dibaca dan memudahkan menemukan ketidaksesuaian.
Tulis aturan sebagai kebutuhan yang terlihat oleh pengguna, bukan catatan kode.\n\nContoh:\n\n- “Email harus valid”\n- “Quantity minimal 1”\n- “Hanya admin yang bisa membatalkan semua pesanan; pengguna biasa hanya bisa membatalkan pesanan mereka sendiri dalam 10 menit”\n\nTangkap apa yang memicu error dan apa yang pengguna alami ketika itu terjadi.
Fokus pada yang bisa diamati:\n\n- Hasil sukses (apa yang berubah, apa yang dilihat pengguna)\n- Jenis kegagalan umum (tidak masuk, tidak diizinkan, tidak ditemukan, error validasi)\n- Side effects (record diperbarui, email/pemberitahuan dikirim, job background di-antri)\n\nSide effects penting karena mempengaruhi fitur lain serta ekspektasi support/ops.
Jika UI memblokir sesuatu tetapi API mengizinkan (atau sebaliknya), catat sebagai gap sampai ada keputusan.\n\nCatat:\n\n- Apa yang UI katakan/lakukan\n- Apa yang backend tegakkan\n- Dampaknya (kebingungan, keamanan, masalah data)\n\nLalu sepakati satu aturan dan perbarui kode serta spesifikasi agar konsisten.
Jaga daftar gap kecil dan berbasis bukti. Setiap item harus memiliki:\n\n- Tipe: bug vs keputusan yang hilang\n- Dampak: minor vs serius (kebingungan, keamanan, hilangnya data)\n- Bukti: tempat Anda melihatnya (route/handler/component) dan perilaku konkret\n\nHindari menjadikannya jadwal atau backlog kedua.
Dokumentasikan secara eksplisit, jangan sembunyikan.\n\nSertakan:\n\n- Empty states (tidak ada hasil, tidak ada izin)\n- Retry/timeouts dan apa yang bisa dilakukan pengguna selanjutnya\n- Duplikat pengiriman (double-click, refresh)\n- Concurrency (dua orang mengedit record yang sama)\n- Aturan berbasis waktu (kedaluwarsa, cooldown)\n\nIni biasanya tempat munculnya kejutan dan bug.
Singkat: sesi baca 20–30 menit dengan satu engineer dan satu product person.\n\nUbah pernyataan menjadi cek ya/tidak (mis. “Apakah kita selalu mengembalikan 403 saat tidak diizinkan?”). Selaraskan kosakata menggunakan kata yang ada di UI (label tombol, judul halaman, pesan) agar semua pihak memahami arti yang sama.
Letakkan spesifikasi dekat dengan kode dan jadikan pembaruan bagian dari proses rilis.\n\nDefault praktisnya:\n\n- Satu pemilik yang menggabungkan perubahan spesifikasi\n- Pemicu pembaruan: setiap perubahan perilaku yang di-merge atau setiap rilis\n- Tambahkan item di PR checklist: “Spec updated?”\n- Simpan gaps terpisah dan tinjau secara berkala\n\nTujuannya: edit kecil dan sering—bukan rewrites besar.