Menentukan ruang lingkup tugas Claude Code: dari permintaan samar ke commit

Mengapa permintaan fitur yang samar membuang waktu

Permintaan yang samar terdengar sepele: “Tambahkan pencarian yang lebih baik,” “Permudah onboarding,” “Pengguna butuh notifikasi.” Di tim nyata sering datang sebagai pesan chat satu baris, screenshot dengan panah, atau hasil panggilan pelanggan yang setengah diingat. Semua setuju, tapi setiap orang membayangkan hal yang berbeda.

Biayanya terlihat belakangan. Saat ruang lingkup tidak jelas, orang bekerja berdasarkan tebakan. Demo pertama berubah jadi putaran klarifikasi lagi: “Bukan itu yang saya maksud.” Pekerjaan dikerjakan ulang, dan perubahan diam-diam membesar. Penyesuaian desain memicu perubahan kode, yang memicu lebih banyak pengujian. Review melambat karena perubahan yang samar sulit diverifikasi. Jika tak seorang pun bisa mendefinisikan apa yang “benar”, reviewer malah berdebat soal perilaku alih-alih memeriksa kualitas.

Anda biasanya bisa mengenali tugas samar lebih awal:

• Tidak ada contoh langkah demi langkah apa yang harus bisa dilakukan pengguna
• Tidak ada kasus tepi (empty state, permission, error)
• Pekerjaan "sekadar berjaga-jaga" yang membesar menjadi PR besar
• Komentar review berdebat soal perilaku, bukan implementasi
• “Kita akan cari saat berjalan” menjadi rencana

Tugas yang ter-skoped memberi tim garis finish: kriteria penerimaan yang jelas, rencana UI dan API minimal, dan batasan eksplisit tentang apa yang tidak termasuk. Itulah perbedaan antara “perbaiki pencarian” dan perubahan kecil yang mudah dibangun dan ditinjau.

Kebiasaan praktis: pisahkan “definition of done” dari “nice-to-have.” “Selesai” adalah daftar cek singkat yang bisa Anda jalankan (contoh: “Pencarian mengembalikan hasil berdasarkan judul, menampilkan ‘No results’ saat kosong, dan menjaga query di URL”). “Nice-to-have” adalah semua yang bisa menunggu (sinonim, penyetelan ranking, highlighting, analytics). Menandai itu sejak awal mencegah pertumbuhan ruang lingkup yang tidak sengaja.

Mulai dari outcome, bukan solusi

Permintaan samar sering dimulai sebagai usulan perbaikan: “Tambahkan tombol,” “Ganti flow,” “Gunakan model lain.” Berhenti sejenak dan terjemahkan saran itu menjadi outcome dulu.

Format sederhana membantu: “Sebagai [user], saya ingin [melakukan sesuatu], supaya saya bisa [mencapai tujuan].” Jaga tetap ringkas. Jika Anda tidak bisa mengatakannya dalam sekali napas, itu masih terlalu kabur.

Selanjutnya, jelaskan apa yang berubah untuk pengguna saat selesai. Fokus pada perilaku yang terlihat, bukan detail implementasi. Contoh: “Setelah saya mengirimkan formulir, saya melihat konfirmasi dan bisa menemukan record baru di daftar.” Itu menciptakan garis finish yang jelas dan membuat sulit bagi "sebentar lagi satu tweak" untuk menyelinap masuk.

Tulis juga apa yang tetap sama. Non-goals melindungi ruang lingkup. Jika permintaan adalah “perbaiki onboarding,” non-goal bisa jadi “tanpa redesign dashboard” atau “tanpa perubahan logika tier harga.”

Terakhir, pilih satu jalur utama untuk didukung dulu: satu irisan end-to-end yang membuktikan fitur bekerja.

Contoh: daripada “tambahkan snapshots di mana-mana,” tulis: “Sebagai pemilik proyek, saya bisa mengembalikan snapshot terbaru dari app saya, supaya saya bisa membatalkan perubahan yang buruk.” Non-goals: “tanpa bulk restore, tanpa redesign UI.”

Tanyakan beberapa pertanyaan yang menghilangkan ambiguitas

Permintaan samar jarang kekurangan usaha. Ia kekurangan keputusan.

Mulailah dengan constraint yang diam-diam mengubah ruang lingkup. Deadline penting, tapi begitu juga aturan akses dan kebutuhan kepatuhan. Jika Anda membangun di platform dengan tier dan peran, tentukan lebih awal siapa yang mendapatkan fitur dan di paket mana.

Lalu minta satu contoh konkret. Screenshot, perilaku pesaing, atau tiket sebelumnya menyingkap apa yang dimaksud dengan “lebih baik.” Jika peminta tidak punya, minta mereka mengulang terakhir kali mereka merasakan masalah: layar mana, apa yang diklik, apa yang mereka harapkan?

Kasus tepi adalah tempat ruang lingkup meledak, jadi sebutkan yang besar lebih awal: data kosong, error validasi, panggilan jaringan lambat atau gagal, dan apa arti “undo” sebenarnya.

Terakhir, tentukan bagaimana Anda akan memverifikasi keberhasilan. Tanpa outcome yang dapat diuji, tugas berubah menjadi opini.

Lima pertanyaan ini biasanya menghilangkan sebagian besar ambiguitas:

• Siapa yang mendapat akses (tier dan peran)?
• Apa deadline, dan apa versi terkecil yang dapat diterima?
• Apa satu contoh perilaku yang diharapkan?
• Apa yang terjadi pada empty state, error, dan koneksi lambat?
• Bagaimana kita akan memastikan ini bekerja (kriteria spesifik atau metrik)?

Contoh: “Tambahkan custom domains untuk klien” menjadi lebih jelas setelah Anda memutuskan tier mana, siapa yang dapat mengatur, apakah lokasi hosting relevan untuk kepatuhan, error apa yang muncul untuk DNS tidak valid, dan apa arti “selesai” (domain terverifikasi, HTTPS aktif, dan rencana rollback aman).

Ubah catatan berantakan menjadi kriteria penerimaan

Permintaan berantakan mencampur tujuan, tebakan, dan kasus tepi yang setengah diingat. Tugas Anda adalah mengubah itu menjadi pernyataan yang bisa diuji oleh siapa pun tanpa harus membaca pikiran Anda. Kriteria yang sama harus membimbing desain, pemrograman, review, dan QA.

Polanya sederhana menjaga semuanya jelas. Anda bisa menggunakan Given/When/Then, atau poin pendek yang berarti sama.

Template kriteria penerimaan singkat

Tulis setiap kriteria sebagai satu tes yang bisa dijalankan seseorang:

• Given keadaan awal, when pengguna melakukan X, then Y terjadi.
• Sertakan aturan validasi (input apa yang diizinkan).
• Sertakan setidaknya satu kasus kegagalan (error apa yang dilihat pengguna).
• Definisikan “sinyal selesai” (apa yang QA periksa, apa yang reviewer harapkan).

Sekarang terapkan. Misalkan catatan mengatakan: “Permudah snapshots. Saya ingin rollback jika perubahan terakhir merusak.” Ubah itu menjadi pernyataan yang bisa diuji:

• Given proyek dengan 2 snapshot, when saya membuka Snapshots, then saya melihat keduanya dengan waktu dan label singkat.
• Given sebuah snapshot, when saya klik Roll back dan konfirmasi, then proyek kembali ke snapshot itu dan app build berhasil.
• Given saya bukan pemilik proyek, when saya mencoba rollback, then saya melihat error dan tidak ada yang berubah.
• Given rollback sedang berlangsung, when saya refresh halaman, then saya tetap bisa melihat status dan hasil akhir.
• Given rollback gagal, when proses berhenti, then saya melihat pesan jelas dan versi saat ini tetap aktif.

Jika QA bisa menjalankan cek-cek ini dan reviewer bisa memverifikasinya di UI dan log, Anda siap merencanakan pekerjaan UI dan API dan membaginya menjadi commit kecil.

Rancang rencana UI minimal

Rencana UI minimal adalah janji: perubahan terlihat terkecil yang membuktikan fitur bekerja.

Mulai dengan menyebut layar mana yang akan berubah dan apa yang terlihat seseorang dalam 10 detik. Jika permintaan mengatakan “buat lebih mudah” atau “bersihkan tampilannya,” terjemahkan itu menjadi satu perubahan konkret yang bisa Anda tunjuk.

Tulis sebagai peta kecil, bukan redesign. Contoh: “Halaman Orders: tambahkan filter bar di atas tabel,” atau “Settings: tambahkan toggle baru di bawah Notifications.” Jika Anda tidak bisa menyebutkan layar dan elemen tepat yang berubah, ruang lingkup masih tidak jelas.

Definisikan state UI kunci

Sebagian besar perubahan UI membutuhkan beberapa state yang dapat diprediksi. Sebutkan hanya yang berlaku:

• Loading
• Empty
• Error (dan apakah ada retry)
• Success (toast, pesan inline, daftar terbarui)

Konfirmasi teks yang akan dilihat pengguna

Copy UI adalah bagian dari ruang lingkup. Tangkap label dan pesan yang harus disetujui: teks tombol, label field, helper text, dan pesan error. Jika kata-kata masih terbuka, tandai sebagai placeholder dan catat siapa yang mengonfirmasinya.

Simpan catatan kecil “tidak sekarang” untuk hal yang tidak wajib untuk menggunakan fitur (polish responsif, sorting lanjutan, animasi, ikon baru).

Rancang rencana API dan data minimal

Tugas yang ter-skoped membutuhkan kontrak kecil dan jelas antara UI, backend, dan data. Tujuannya bukan merancang seluruh sistem. Ini menentukan set permintaan dan field paling sedikit yang membuktikan fitur bekerja.

Mulai dengan mendaftar data yang Anda butuhkan dan dari mana asalnya: field yang sudah ada yang bisa dibaca, field baru yang harus disimpan, dan nilai yang bisa dihitung. Jika Anda tidak bisa menyebutkan sumber untuk setiap field, Anda belum punya rencana.

Jaga permukaan API kecil. Untuk banyak fitur, satu read dan satu write cukup:

• GET /items/{id} mengembalikan state yang diperlukan untuk merender layar
• POST /items/{id}/update menerima hanya apa yang bisa diubah pengguna dan mengembalikan state yang diperbarui

Tulis input dan output sebagai objek jelas, bukan paragraf. Sertakan field required vs optional, dan apa yang terjadi pada error umum (not found, validation failed).

Lakukan pengecekan auth cepat sebelum menyentuh database. Tentukan siapa bisa baca dan siapa bisa tulis, dan nyatakan aturan itu dalam satu kalimat (misal: “setiap pengguna yang masuk bisa baca, hanya admin yang bisa tulis”). Melewatkan ini sering menyebabkan rework.

Terakhir, tentukan apa yang harus disimpan dan apa yang bisa dihitung. Aturan sederhana: simpan fakta, hitung view.

Gunakan Claude Code untuk menghasilkan tugas ter-skoped

Claude Code bekerja paling baik ketika Anda memberinya target jelas dan batas ketat. Mulailah dengan menempelkan permintaan berantakan dan constraint apa pun (deadline, pengguna terdampak, aturan data). Lalu minta output ter-skoped yang mencakup:

1. Restatement ruang lingkup dalam bahasa biasa dan checklist kriteria penerimaan singkat.
2. Urutan commit kecil (tujuannya 3–7), masing-masing dengan hasil yang jelas.
3. File atau folder yang kemungkinan disentuh per commit, dan perubahan di dalamnya.
4. Rencana pengujian singkat per commit (satu happy path dan satu kasus tepi).
5. Catatan eksplisit out-of-scope.

Setelah ia membalas, baca seperti reviewer. Jika Anda melihat frasa seperti “tingkatkan performa” atau “perbaiki tampilannya,” minta kata-kata yang dapat diukur.

Contoh mini (apa yang “baik” terlihat seperti)

Permintaan: “Tambahkan cara untuk pause subscription.”

Versi ter-skoped mungkin mengatakan: “Pengguna bisa pause selama 1 sampai 3 bulan; tanggal penagihan berikutnya diperbarui; admin bisa melihat status pause,” dan out-of-scope: “Tidak ada perubahan proration.”

Dari sana, rencana commit jadi praktis: satu commit untuk DB dan bentuk API, satu untuk kontrol UI, satu untuk validasi dan error states, satu untuk end-to-end tests.

Bagi pekerjaan menjadi commit kecil yang mudah ditinjau

Perubahan besar menyembunyikan bug. Commit kecil mempercepat review, memudahkan rollback, dan membantu Anda menyadari saat menyimpang dari kriteria penerimaan.

Aturan berguna: setiap commit harus membuka satu perilaku baru, dan menyertakan cara cepat untuk membuktikannya.

Urutan umum terlihat seperti ini:

• Model data atau migration (jika perlu) plus tes
• Perilaku API dan validasi
• Wiring UI dengan empty dan error states
• Logging atau analytics hanya jika diperlukan, lalu polish kecil

Jaga setiap commit tetap fokus. Hindari refactor “sekalian” saat melakukan fitur. Jaga aplikasi tetap berfungsi end-to-end, meski UI masih sederhana. Jangan gabungkan migration, perilaku, dan UI dalam satu commit kecuali ada alasan kuat.

Walkthrough: “Export reports”

Pemangku kepentingan berkata: “Bisa tambahkan Export reports?” Itu menyembunyikan banyak pilihan: laporan mana, format apa, siapa yang bisa ekspor, dan bagaimana pengiriman bekerja.

Tanyakan hanya pertanyaan yang mengubah desain:

• Jenis laporan mana yang masuk scope v1?
• Format apa yang dibutuhkan untuk v1 (CSV, PDF)?
• Siapa yang boleh ekspor (admin, peran tertentu)?
• Apakah langsung diunduh atau dikirim lewat email?
• Ada batasan (rentang tanggal max, cap jumlah baris, timeout)?

Asumsikan jawabannya: “Sales Summary, CSV saja, peran manager, download langsung, max 90 hari.” Sekarang kriteria penerimaan v1 menjadi konkret: manager bisa klik Export di halaman Sales Summary; CSV sesuai kolom tabel di layar; export menghormati filter saat ini; export >90 hari menampilkan error jelas; download selesai dalam 30 detik untuk hingga 50k baris.

Rencana UI minimal: satu tombol Export dekat aksi tabel, state loading saat menghasilkan, dan pesan error yang memberitahu pengguna cara memperbaiki (mis. “Pilih 90 hari atau kurang”).

Rencana API minimal: satu endpoint yang menerima filter dan mengembalikan CSV yang di-generate sebagai file response, menggunakan query yang sama seperti tabel sambil menegakkan aturan 90 hari di sisi server.

Lalu kirimkan dalam beberapa commit kecil: pertama endpoint untuk happy path tetap, lalu wiring UI, lalu validasi dan error ke pengguna, lalu tes dan dokumentasi.

Kesalahan scoping yang umum (dan cara menghindarinya)

Persyaratan tersembunyi menyelinap

Permintaan seperti “tambahkan peran tim” sering menyembunyikan aturan tentang undangan, pengeditan, dan apa yang terjadi pada pengguna yang ada. Jika Anda mendapati diri menebak, tulis asumsi itu dan ubah menjadi pertanyaan atau aturan eksplisit.

Polish UI tercampur dengan perilaku inti

Tim kehilangan hari ketika satu tugas mencakup “bikin jalan” dan “bikin cantik.” Fokus tugas pertama pada perilaku dan data. Masukkan styling, animasi, dan spacing ke tugas lanjutan kecuali itu diperlukan untuk menggunakan fitur.

Anda mencoba menyelesaikan semua kasus tepi di v1

Kasus tepi penting, tapi bukan semuanya harus diselesaikan segera. Tangani beberapa yang bisa merusak kepercayaan (double submits, konflik edit) dan tunda sisanya dengan catatan jelas.

Error state dan permission ditunda ke “nanti”

Jika Anda tidak menuliskannya, Anda akan melewatkannya. Sertakan setidaknya satu jalan tidak bahagia dan setidaknya satu aturan permission dalam kriteria penerimaan.

Kriteria yang tidak bisa Anda verifikasi

Hindari kata-kata seperti “cepat” atau “intuitif” kecuali Anda menambahkan angka atau cek konkret. Gantilah dengan sesuatu yang bisa dibuktikan saat review.

Checklist cepat sebelum mulai ngoding

Kunci tugas sehingga rekan bisa mereview dan menguji tanpa membaca pikiran Anda:

• Outcome dan non-goals: satu kalimat untuk outcome, plus 1–3 non-goals eksplisit.
• Acceptance criteria: 5–10 cek yang bisa diuji dalam bahasa biasa.
• UI states: minimal loading, empty, error, dan success.
• Catatan API dan data: bentuk endpoint terkecil dan perubahan data apa pun, plus siapa yang bisa baca/tulis.
• Rencana commit dengan tes: 3–7 commit, masing-masing dengan bukti cepat.

Contoh: “Add saved searches” menjadi “Pengguna bisa menyimpan filter dan menerapkannya lagi nanti,” dengan non-goals seperti “tidak ada sharing” dan “tidak ada perubahan sorting.”

Langkah selanjutnya: jaga ruang lingkup tetap stabil saat membangun

Setelah Anda punya tugas yang ter-skoped, lindungi itu. Sebelum ngoding, lakukan review singkat dengan orang yang meminta perubahan:

• Baca kriteria penerimaan dan konfirmasi itu cocok dengan outcome.
• Konfirmasi permission, empty state, dan perilaku kegagalan.
• Konfirmasi ulang apa yang out-of-scope.
• Sepakati perubahan UI dan API terkecil yang memenuhi kriteria.
• Tentukan bagaimana Anda akan mendemokan dan apa yang berarti “selesai”.

Lalu simpan kriteria di tempat kerja: tiket, deskripsi PR, dan di mana pun tim Anda benar-benar melihatnya.

Jika Anda membangun di Koder.ai (koder.ai), membantu untuk mengunci rencana dulu lalu menghasilkan kode dari sana. Planning Mode cocok dengan alur kerja itu, dan snapshots serta rollback bisa menjaga percobaan tetap aman ketika Anda perlu mencoba pendekatan dan membatalkannya.

Saat ide baru muncul saat pembangunan, jaga ruang lingkup: tulis mereka ke daftar follow-up, jeda untuk re-scope jika mereka mengubah kriteria penerimaan, dan pastikan commit terkait satu kriteria pada satu waktu.