Claude Code greenfield workflow: dari repo kosong ke slice pertama

Apa yang ingin Anda hindari saat memulai greenfield

Memulai dari repo kosong terasa bebas, tetapi sering berubah menjadi kekacauan awal: banyak file ter-generate, build setengah jalan, dan tidak ada tempat jelas untuk perubahan berikutnya. Tujuan workflow greenfield Claude Code adalah menghindari kekacauan minggu pertama itu.

Beberapa kegagalan muncul berulang kali:

• Kode yang “berjalan di mesin saya” karena setup hanya ada di kepala seseorang, bukan di skrip.
• Struktur folder yang mencerminkan urutan pembuatan, bukan bagaimana aplikasi harus tumbuh.
• Siklus di mana setiap prompt baru menulis ulang pilihan sebelumnya, sehingga tidak ada yang menjadi stabil.

Keputusan awal sulit dibalik karena semuanya menumpuk di atasnya. Struktur yang membingungkan terus diperkuat. Build manual berubah menjadi sepuluh setup berbeda. Jika Anda tidak mengunci satu perintah dev sederhana sejak awal, Anda tidak bisa tahu apakah perubahan memecahkan aplikasi atau hanya memecahkan lingkungan.

Saat tulisan ini menyebut “aplikasi berjalan”, itu berarti sesuatu yang spesifik: satu perintah yang memulai proyek, mencetak output yang dapat diprediksi, dan gagal dengan jelas ketika sesuatu hilang. Anda harus bisa menghapus instalasi lokal, clone repo, menjalankan perintah itu, dan melihat hasil yang sama.

“Vertical slice” adalah fitur end-to-end terkecil yang membuktikan aplikasi Anda nyata. Bukan mock UI. Bukan tabel basis data sendirian. Ini seutas alur tipis melalui seluruh sistem: misalnya satu halaman dengan form, satu endpoint API yang menyimpan data, satu penulisan dan pembacaan basis data, dan satu hasil yang terlihat kembali di halaman.

Jika Anda bisa menjalankan aplikasi dengan satu perintah dan mengirim satu vertical slice, Anda punya basis untuk iterasi tanpa menebak-nebak.

Putuskan slice pertama sebelum menghasilkan apa pun

Slice pertama yang jelas menjaga repo tetap rapi dan prompt tetap fokus. Saat inilah memutuskan apa yang ingin Anda demo end-to-end, bukan apa yang Anda harapkan produk penuh nanti.

Pilih user story terkecil yang membuktikan aplikasi bekerja di sepanjang jalur itu. Slice yang baik menyentuh UI, data, dan satu aksi nyata. Contoh: “Sebagai pengguna, saya bisa menambahkan tugas dan melihatnya muncul di daftar setelah refresh.” Kecil, tapi memaksa routing, validasi, penyimpanan, dan layar dasar.

Pilih satu platform target untuk minggu pertama dan patuhi itu. Jika mulai web, fokus hanya web. Jangan tambahkan layar mobile “untuk berjaga-jaga.” Bahkan jika Anda berencana menggunakan platform seperti Koder.ai nanti, hasilnya akan lebih baik jika slice pertama tetap pada satu jalur (React web, atau API Go, atau Flutter).

Tentukan apa arti “selesai untuk minggu 1” dengan istilah sederhana:

• Berjalan lokal dari clone baru dengan satu perintah
• Satu fitur yang bekerja yang bisa Anda klik hingga selesai
• Error menampilkan pesan yang bisa dimengerti manusia (bukan stack trace)
• Data dipertahankan di tempat yang sederhana (bahkan basis data lokal)

Lalu tulis tiga non-goal untuk melindungi ruang lingkup. Contoh: tanpa auth, tanpa sistem tema, tanpa background jobs.

Setelah keputusan itu tertulis, prompt generasi Anda bisa ketat: bangun hanya yang mendukung slice, dan sisakan sisanya sebagai TODO.

Beberapa keputusan awal yang menghemat kerja ulang

Sebelum meminta Claude menghasilkan apa pun, kunci beberapa default. Mereka terlihat kecil, tapi mencegah kekacauan “ubah nama nanti”.

Pertama, putuskan bentuk aplikasi. Jika Anda benar-benar butuh UI browser dan backend, mulai dengan dua bagian yang jelas (frontend + API) dan tempat bersama untuk kontrak (tipe API atau skema sederhana). Jika aplikasi bisa berupa server-rendered tunggal, jaga satu codebase supaya dev lokal tetap sederhana.

Selanjutnya, sepakati aturan konfigurasi. Gunakan file env lokal, jangan masukkan ke git, dan commit template saja (misalnya .env.example) dengan placeholder aman dan komentar singkat. Ini memudahkan onboarding dan mengurangi kebocoran secret.

Pilih port dev default dan jaga agar stabil. Port muncul di skrip, dokumen, dan pesan error, jadi mengubahnya nanti menyebalkan. Lakukan hal sama untuk penamaan: folder, service, dan package harus mengikuti satu konvensi. Konsistensi lebih penting daripada konvensi “sempurna”.

Set keputusan awal sederhana:

• Bentuk aplikasi: satu aplikasi atau frontend + API
• Konfigurasi: .env lokal, .env.example di-commit
• Port: satu untuk web, satu untuk API, satu untuk DB (jika perlu)
• Nama: satu gaya penamaan untuk folder, nama service konsisten
• Secret: jangan di-commit, rotasi jika terekspos

Contoh: Anda pilih web di port 3000 dan api di port 8080. Template env Anda menyertakan API_URL=http://localhost:8080 dan DATABASE_URL=.... Ketika Claude nanti menghasilkan skrip dan dokumen, semuanya langsung cocok alih-alih menyimpang.

Cara mem-prompt Claude Code agar tetap terstruktur

Mulailah dengan meminta scaffold yang dapat dijalankan, bukan “seluruh aplikasi.” Jalur tercepat menuju output berantakan adalah meminta fitur sebelum Anda punya tempat menaruhnya.

Jadilah eksplisit tentang struktur. Minta layout folder dengan komentar singkat yang menjelaskan apa yang masuk ke mana, dan apa yang tidak. Itu memaksa keputusan di awal daripada menyebarkan file sembarangan.

Cara sederhana untuk menjaga disiplin adalah menetapkan aturan di prompt:

• Buat skeleton runnable terkecil dulu (hello page, health endpoint, atau satu layar).
• Usulkan struktur folder dan jelaskan setiap folder dengan 1 kalimat.
• Tambahkan skrip yang bekerja di mesin baru (install, dev, test, build) dan nyatakan pra-syarat.
• Jaga perubahan dalam satu PR-sized chunk dan daftar persis file mana yang akan dibuat atau diedit.
• Berhenti setelah scaffolding dan beri tahu cara menjalankannya.

Berikut prompt yang bisa Anda gunakan dan sesuaikan:

You are working in an empty repo. Create a minimal runnable skeleton.

Constraints:
- Keep it small: no real features yet.
- Propose a clear folder structure and add brief comments in each folder’s README.
- Add scripts for: setup, dev, test, build. They must work on a fresh machine.
- Tell me exactly how to run it, and what output I should see.
- After generating, stop and wait for my “ran it” confirmation.

Output:
1) File tree
2) Key files (only)
3) Run instructions

Lalu jaga loopnya ketat. Jangan minta lima perubahan sekaligus. Generate satu perubahan kecil, jalankan, tempelkan error (atau sukses) yang persis, lalu minta perbaikan minimal. Ritme generate-jalankan-sesuaikan itu menjaga proyek dapat diprediksi dan membuat struktur sulit melenceng.

Langkah demi langkah: dari repo kosong ke skeleton yang dapat dijalankan

Mulailah dengan satu janji: siapa pun bisa clone repo dan menjalankan satu perintah untuk melihat sesuatu yang bekerja. Itu memberi Anda basis stabil sebelum meminta AI menambah fitur nyata.

Buat repo dan tulis README kecil selagi semuanya masih segar. Jaga praktis: pra-syarat, satu perintah dev, dan cara menjalankan tes (meskipun tes kosong untuk sekarang).

Selanjutnya, pilih layout top-level yang sesuai bentuk aplikasi yang Anda pilih.

Jika Anda membangun beberapa bagian yang dapat dideploy (misalnya frontend + API), layout workspace bisa membantu:

/
  apps/
  packages/
  scripts/
  docs/
  README.md

Jika Anda membangun satu aplikasi, jaga lebih sederhana dan hindari level ekstra sampai diperlukan.

Sekarang tambahkan pagar-pagar minimum agar kode tetap konsisten. Pilih satu formatter dan satu linter, terima defaultnya, dan tambahkan satu file config untuk masing-masing. Tujuannya diffs bersih, bukan aturan sempurna hari pertama.

Buat pengalaman developer dapat diprediksi dengan satu perintah yang selalu bekerja dari root repo. Bentuk sederhana:

{
  "scripts": {
    "dev": "echo \"start dev server here\"",
    "build": "echo \"build here\"",
    "test": "echo \"tests here\"",
    "lint": "echo \"lint here\""
  }
}

Sebelum menghasilkan apa pun lagi, jalankan perintah dev itu, pastikan keluar bersih (atau menjalankan server placeholder), lalu buat commit pertama hanya dengan scaffolding. Jika seorang rekan (atau Anda di masa depan) bisa mereproduksi setup dari awal, Anda siap membangun slice pertama.

Struktur folder yang bisa dipertahankan seiring aplikasi tumbuh

Struktur greenfield yang baik melakukan dua hal: membantu Anda menemukan kode dengan cepat, dan memberi Claude lebih sedikit ruang untuk menciptakan pola baru setiap kali Anda minta perubahan. Tujuannya bukan kesempurnaan. Ini stabilitas.

Jika Anda bekerja di satu aplikasi (atau di dalam folder apps/<name>/), layout internal sederhana biasanya tahan lama:

• src/ kode aplikasi (fitur, bagian bersama, titik masuk)
• config/ konfigurasi non-rahasia
• tests/ tes level tinggi yang dibaca seperti perilaku pengguna
• scripts/ skrip bantu (setup dev, reset db, tugas release)
• docs/ catatan singkat dan checklist yang benar-benar Anda pelihara

Di dalam src/, pisahkan kode fitur dari kode bersama berdasarkan pola perubahan. Kode fitur sering berubah dan sebaiknya diletakkan berdekatan. Kode bersama harus membosankan dan dapat digunakan ulang.

Aturan praktis: letakkan layar UI, handler, dan logika spesifik fitur di src/features/<featureName>/.... Letakkan hal seperti logging, client API, komponen design system, dan utilitas generik di src/shared/.... Jika helper hanya masuk akal untuk satu fitur, tetap di fitur itu meskipun terlihat dapat dipakai ulang. Pindahkan nanti saat Anda punya penggunaan nyata kedua.

Nama folder harus menggambarkan tujuan, bukan teknologi. “features” dan “shared” tetap bermakna saat stack Anda berubah. Hindari nama seperti “misc” atau “new.”

Jaga docs/ kecil. Starter yang baik adalah docs/checklists.md dengan beberapa baris: cara menjalankan, cara mengetes, cara menambah folder fitur baru, dan apa arti “selesai.”

Skrip build yang membuat proyek dapat diprediksi

Sebuah repo terasa nyata ketika siapa pun dapat menjalankan perintah yang sama dan mendapatkan hasil yang sama. Skrip adalah pagar-pagar: mengurangi tebak-tebakan, menjaga perubahan kecil, dan membuatnya jelas saat sesuatu rusak.

Mulailah dengan set perintah kecil dan biarkan mereka membosankan. Jika orang baru bergabung (atau Anda kembali dua minggu kemudian), mereka tak perlu flag khusus atau langkah tersembunyi.

Berikut baseline sederhana yang dapat Anda adaptasi ke stack apa pun:

{
  "scripts": {
    "dev": "node ./scripts/dev.js",
    "build": "node ./scripts/build.js",
    "test": "node ./scripts/test.js",
    "test:quick": "node ./scripts/test.js --quick",
    "test:full": "node ./scripts/test.js --full",
    "format": "node ./scripts/format.js",
    "lint": "node ./scripts/lint.js",
    "smoke": "node ./scripts/smoke.js"
  }
}

Jadikan script dev jalur bahagia. Itu harus memulai aplikasi, mencetak di mana ia berjalan, dan menjaga log tetap terbaca. Jika server tidak bisa mulai, gagal cepat dengan satu pesan jelas (env var hilang, port sudah digunakan, database tidak terjangkau).

Skrip build harus selalu membuat direktori output bersih. Hapus output lama dulu, lalu hasilkan artefak baru. Itu menghindari bug aneh karena file kemarin.

Untuk tes, pisahkan quick checks dari slow checks. Tes cepat berjalan di setiap perubahan (unit test, pemeriksaan tipe). Tes penuh mencakup integrasi dan dijalankan sebelum merge.

Jaga gaya konsisten dengan satu perintah. Aturan sederhana: format memperbaiki, lint mengeluh.

Terakhir, tambahkan smoke check yang memvalidasi dasar sebelum Anda membuang-buang waktu debugging:

• Env var yang diperlukan diset (dan tidak kosong)
• Port yang dipilih tersedia
• Aplikasi bisa mulai dan merespon satu permintaan sederhana
• Koneksi database bekerja (jika dipakai)
• Output build ada setelah build

Bangun fitur vertical slice pertama

Vertical slice pertama Anda harus membuktikan aplikasi bekerja end-to-end, bukan sekadar UI terlihat bagus. Itu berarti satu fitur kecil yang menyentuh layar, logika, dan semacam penyimpanan, walau penyimpanan bersifat sementara.

Pilih sesuatu yang membosankan dan berguna, seperti “Tambah catatan” atau “Buat tugas.” Jaga cukup kecil untuk diselesaikan dalam satu sesi, tapi lengkap sehingga Anda bisa klik dan melihat perubahan status nyata.

Slice yang baik punya empat bagian: satu route atau layar, satu form, satu aksi simpan, dan satu tampilan. Contoh: halaman “Tugas Baru” dengan input judul, tombol Simpan yang memanggil satu fungsi, dan daftar yang menampilkan tugas tersimpan.

Mulai dengan store placeholder supaya Anda bisa bergerak cepat. Array in-memory, file JSON lokal, atau stub interface sederhana cukup. Intinya menciptakan boundary yang akan Anda ganti nanti. Jika hari ini kode memanggil taskRepository.save(task), menggantinya ke database nyata nanti menjadi perubahan kecil, bukan penulisan ulang.

Jaga UI polos. Lewati debat design system, empty state, dan animasi.

Pemeriksaan penerimaan yang bisa Anda lakukan dalam dua menit:

• Halaman terbuka tanpa error
• Anda bisa mengetik nilai dan tekan Simpan
• Item baru muncul langsung
• Reload menunjukkan perilaku yang diharapkan (persist jika penyimpanan nyata, reset jika palsu)
• Input buruk ditangani (judul kosong menunjukkan pesan dan tidak tersimpan)

Buat cukup stabil untuk diiterasi

Setelah Anda punya skeleton yang dapat dijalankan dan satu vertical slice, tujuan bergeser: buat kegagalan jelas, dan perbaikan cepat. Di sinilah banyak greenfield gagal, bukan karena fiturnya susah, tapi karena perubahan kecil mulai menyebabkan kejutan.

Tetapkan ambang stabilitas kecil yang Anda penuhi setiap kali menambah slice:

• Satu smoke test yang membuktikan aplikasi bisa boot dan route/layar utama merender
• Satu smoke test yang melewati slice end-to-end (bahkan jika memakai database tes)
• Pesan error jelas yang dapat ditindaklanjuti pengguna biasa (bukan stack trace)
• Log dev yang menjelaskan apa yang terjadi tanpa mencetak secret
• Dependensi minimal, versi dipin, upgrade dilakukan dengan sengaja

Contoh konkret: slice pertama Anda memungkinkan pengguna membuat “Project” dan melihatnya di daftar. Tambahkan tes yang memulai server, memanggil endpoint create, lalu mengambil daftar dan memeriksa item baru muncul. Jika gagal, harus gagal dengan jelas satu pesan membantu, seperti “Create Project endpoint returned 500”, bukan output panjang.

Untuk penanganan error, patuhi satu set respons konsisten. Error validasi mengembalikan pesan singkat (“Nama wajib diisi”) dan nama field. Error tak terduga mengembalikan “Terjadi kesalahan. Coba lagi.” Simpan detailnya untuk log.

Logging paling berguna ketika menjawab: permintaan apa, pengguna siapa (atau anonymous), apa yang gagal, dan di mana. Di dev, sertakan request id dan timing, tapi hindari membuang token, password, API key, atau payload penuh secara default.

Tambahkan health check kecil. Di web, bisa endpoint /health yang mengembalikan ok. Di mobile, bisa status “Connected” yang berubah jadi “Offline” saat app tidak bisa menjangkau backend. Sinyal cepat sebelum Anda salah debug hal yang salah.

Perangkap umum saat menggunakan AI untuk proyek greenfield

Jalur tercepat membuang-buang awal greenfield adalah meminta model membuat seluruh aplikasi, lalu baru menjalankannya nanti. Generasi besar menyembunyikan kesalahan kecil: dependency hilang, path import salah, skrip yang mengasumsikan tools yang tidak Anda punya. Perlakukan setiap output sebagai sesuatu yang harus bisa Anda jalankan dalam menit.

Perangkap lain adalah merancang arsitektur sempurna sebelum ada fitur. Debat nama folder terasa produktif, tapi tanpa slice nyata Anda tak bisa tahu apa yang canggung. Struktur sederhana yang mendukung satu jalur kerja lebih baik daripada struktur jenius yang belum diuji.

Command drift juga umum. AI menambahkan cara baru memulai server, Anda menambahkan lagi untuk tes, dan segera tidak ada yang tahu mana perintah “yang” digunakan. Jika rekan clone repo dan tanya “Bagaimana cara menjalankannya?”, Anda sudah bayar bunga.

Kesalahan yang paling banyak menyebabkan kerja ulang:

• Menghasilkan banyak service, layar, dan konfigurasi sekaligus bukannya membangun satu jalur runnable terlebih dulu
• Menarik auth, pembayaran, styling kompleks, dan model data penuh sebelum fitur pertama end-to-end bekerja
• Membiarkan instruksi setup hidup di chat alih-alih skrip (atau README tunggal)
• Lupa template env yang bersih, sehingga mesin berikutnya tidak bisa mulai tanpa tebak-tebakan

Contoh sederhana: Anda generate aplikasi “lengkap” dengan login, theming, dan billing, tetapi run pertama gagal karena kunci rahasia hilang dan tidak ada .env.example. Anda kemudian menghabiskan waktu memperbaiki setup alih-alih belajar apakah fiturnya berguna.

Jaga kejujuran: satu perintah runnable, satu fitur kecil, satu template env, lalu berkembang.

Checklist cepat sebelum mulai iterasi

Sebelum menambah “satu fitur lagi,” pastikan proyek mudah diambil besok (atau oleh orang lain). Kecepatan bukan tujuan sendirian. Prediktabilitaslah yang penting.

• Satu-perintah run: orang baru bisa menyalin template env, mengisi beberapa nilai yang diperlukan, dan memulai aplikasi dengan satu perintah. Jika perlu langkah ekstra (setup DB, migrasi, seed), tangkap itu di skrip.
• Skrip menutupi dasar: perintah jelas untuk dev, test, build, dan smoke check cepat.
• Struktur jelas: layout menceritakan sebuah cerita (kode app, config, skrip, tes) tanpa membaca seluruh codebase.
• Jalur demo vertical slice: Anda bisa mendeskripsikannya dalam satu kalimat, mis. “buat item, lihat di daftar, refresh, masih ada.”
• Titik rollback: sebelum perubahan besar, Anda punya titik aman untuk kembali (commit bersih, tag, atau snapshot/rollback).

Jika ada item yang gagal, perbaiki sekarang. Menyempurnakan skrip dan penamaan murah saat repo masih kecil.

Langkah berikutnya: ubah workflow menjadi kebiasaan yang dapat diulang

Awalan greenfield hanya berguna jika bisa diulang. Setelah slice pertama Anda berjalan end-to-end, bekukan bagian baiknya menjadi template kecil: pola folder yang sama, nama skrip yang sama, dan cara yang sama menghubungkan UI, API, dan data.

Perlakukan slice pertama sebagai implementasi referensi. Saat memulai slice #2, salin bentuknya, bukan kodenya. Jika slice #1 punya route, handler, lapisan akses data, dan tes dasar, slice #2 harus mengikuti jalur yang sama.

Jaga perencanaan ringan. Catatan satu halaman cukup untuk 2–3 slice berikutnya: tujuan dan aksi pengguna untuk tiap slice (satu kalimat), data yang diperlukan, pemeriksaan “done”, dan risiko yang harus diuji awal.

Lalu jadikan pemeliharaan sebuah kebiasaan. Seminggu sekali, lakukan pembersihan singkat: rapikan skrip, perbarui README dengan langkah setup baru, dan segarkan file env example agar onboarding tetap mudah.

Jika Anda lebih suka loop build berbasis chat, Koder.ai (koder.ai) adalah salah satu opsi yang mendukung planning mode plus snapshot dan rollback, dan dapat mengekspor source code saat Anda ingin memindahkan proyek.

Tujuannya adalah workflow yang bisa Anda jalankan tanpa berpikir: rencanakan 2–3 slice, bangun satu slice, stabilkan, ulangi.