Daftar Periksa Ekspor Basis Kode yang Dibuat AI untuk Penyerahan yang Rapi

Mengapa proyek yang diekspor gagal setelah penyerahan

Kebanyakan proyek yang diekspor gagal karena alasan sederhana: mereka berjalan baik di dalam platform asal, di mana default, rahasia, status database, dan langkah build sudah tersedia. Begitu kode keluar dari gelembung itu, pengembang berikutnya harus menebak apa yang diasumsikan.

Penyerahan yang bersih berarti proyek bisa di-clone, dikonfigurasi, dan dijalankan oleh orang yang bukan pembuatnya, di mesin baru, tanpa bolak-balik panjang. Ini tidak perlu kode yang sempurna. Yang diperlukan adalah dasar-dasar yang eksplisit dan bisa diulang.

Ekspor sering rusak karena masalah yang sama berulang: konfigurasi tersembunyi, penanganan rahasia yang tidak jelas, langkah setup lokal yang samar, kejutan database, dan CI yang hanya bekerja di satu lingkungan.

Itulah mengapa daftar periksa ekspor basis kode yang dibuat AI kebanyakan tentang dokumentasi dan reproduksibilitas, bukan menyalin file. Jika Anda membangun aplikasi di platform vibe-coding seperti Koder.ai dan kemudian mengekspor sumber kode, tim berikutnya tetap membutuhkan peta: apa yang harus diset, apa yang harus dijalankan, dan apa arti “berfungsi”.

Daftar periksa ini fokus pada hal esensial penyerahan: variabel lingkungan, rahasia, setup pengembangan lokal, bootstrap database, pengaturan CI, dan README “cara menjalankan” yang praktis. Ini tidak membahas keputusan produk, penyempurnaan UX, atau merancang ulang arsitektur.

Kepemilikan juga harus jelas. Pembuat bertanggung jawab membuat asumsi terlihat (dokumen, skrip, default aman). Penerima bertanggung jawab menyesuaikan proyek ke lingkungan mereka (secret manager, hosting, aturan CI yang lebih ketat). Bila kedua pihak tahu perannya, penyerahan menjadi rutin.

Sebelum Anda ekspor: putuskan kontrak penyerahan

Penyerahan yang bersih dimulai dengan kesepakatan sederhana: apa arti “selesai” saat kode keluar dari platform. Tanpa itu, tim akan berdebat nanti tentang skrip yang hilang, dependensi mengejutkan, atau versi mana yang sebenarnya.

Pilih momen ekspor

Pilih satu titik waktu yang stabil dan anggap itu sebagai sumber kebenaran. Mengekspor saat perubahan sedang berlangsung adalah bagaimana tim berakhir dengan repo yang hampir berjalan.

Titik ekspor yang baik biasanya salah satu dari ini:

• Commit stabil dengan catatan rilis singkat (apa yang berubah, apa yang diuji)
• Release yang ditandai (meskipun hanya v0.1.0)
• Snapshot platform (misalnya, snapshot Koder.ai yang bisa Anda rollback jika ekspor perlu diulang)

Tambahkan satu kalimat yang menjelaskan mengapa ini titik ekspor yang tepat. Contoh: “Semua flow inti lulus dan skema database final untuk milestone ini.”

Tentukan apa yang termasuk dalam penyerahan

Tulis inventaris singkat tentang apa yang penerima harus harapkan. Jelaskan secara eksplisit apa yang termasuk dan apa yang sengaja tidak disertakan.

Sertakan dasar-dasarnya: kode sumber (app, layanan, paket bersama), template konfigurasi (contoh file env), skrip (build, dev, test, migrasi, seed), dan catatan deployment. Sertakan data contoh hanya jika sudah disanitasi dan aman.

Kemudian beku versi sehingga “berfungsi di mesin saya” tidak menjadi baseline baru. Tangkap versi runtime dan toolchain (Node, Go, Flutter, package manager), plus versi database (versi mayor PostgreSQL penting).

Akhirnya, daftarkan prasyarat yang harus dilakukan sebelum menjalankan apa pun. Buat singkat dan konkret: akun yang dibutuhkan, alat yang harus diinstal, port yang harus bebas, dan langkah setup satu kali bila ada.

Variabel lingkungan: dokumentasikan agar tak ada yang tersembunyi

Kebanyakan ekspor yang “bekerja di platform” rusak karena pengaturan kunci tidak pernah dituliskan. Variabel lingkungan adalah penyebab umum: mereka hidup di luar repo, sehingga anggota tim baru meng-clone proyek dan tidak tahu nilai yang diharapkan.

Anggap ini wajib untuk ekspor yang bersih: setiap variabel harus dapat ditemukan, dijelaskan, dan mudah diset tanpa menebak.

Buat satu sumber kebenaran di README penyerahan Anda: daftar nama env var, apa yang mereka kendalikan, dan dari mana nilai berasal. Jaga penjelasan dalam bahasa sederhana, dan tandai apa pun yang terkait keamanan.

Format sederhana untuk setiap variabel:

• Name: kunci persis (copy/paste friendly)
• Meaning: apa yang diubah di aplikasi
• Required?: wajib atau opsional (dan apa yang terjadi jika tidak ada)
• Example: contoh nilai aman (jangan pernah menggunakan rahasia nyata)
• Where it differs: dev vs staging vs production

Selain dokumentasi itu, sertakan file .env.example di repo. Itu harus memuat setiap variabel yang mungkin diperlukan, dengan nilai placeholder aman sehingga aplikasi bisa dimulai dengan sedikit edit.

# Required
APP_ENV=development
PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/app_dev

# Optional
LOG_LEVEL=info
CORS_ORIGINS=http://localhost:5173

# Environment specific
PUBLIC_BASE_URL=http://localhost:3000

Beberapa detail mencegah kebingungan paling banyak:

Jelaskan “wajib vs opsional” dengan eksplisit. Jika variabel yang hilang menyebabkan crash, katakan. Jika itu mengaktifkan fitur (pengiriman email, pembayaran, penyimpanan file), sebutkan fiturnya dan jelaskan apa yang terjadi jika tidak diset.

Tunjukkan apa yang berubah per lingkungan. DATABASE_URL dan PUBLIC_BASE_URL sering berbeda antara dev, staging, dan production, sementara LOG_LEVEL mungkin sama di mana pun. Jika Anda menggunakan Koder.ai untuk mengekspor dan mendeploy, periksa kembali bahwa default platform (port, base URL, allowed origins) tercermin di dokumen sehingga perilaku tetap konsisten di luar platform.

Terakhir, nyatakan bagaimana env var dimuat secara lokal. Jika proyek mengharapkan file .env, katakan di mana letaknya dan apakah aplikasi membacanya otomatis atau membutuhkan perintah/alat.

Rahasia: jangan disimpan di repo dan mudah diset

Rahasia adalah nilai yang bisa menyebabkan kerusakan jika bocor: API key, password database, token otentikasi, OAuth client secret, private key, webhook signing secret, dan sejenisnya.

Untuk ekspor, jadikan sederhana: repo hanya berisi placeholder, jangan nilai rahasia nyata. Jika rahasia diperlukan untuk menjalankan, sertakan sebagai placeholder yang jelas di .env.example dan jelaskan cara membuat nilai asli.

Pola praktis adalah memisahkan tiga hal: file sampel, file lokal, dan store rahasia CI/deployment. Kode yang diekspor harus menyertakan sampel, mengabaikan file lokal, dan mendokumentasikan bagaimana CI/hosting menerima rahasia.

Tempat menyimpan rahasia

Pilih satu pendekatan per lingkungan dan konsisten.

• Pengembangan lokal: .env (di-gitignore) yang dimuat oleh aplikasi, atau secret manager lokal tim Anda
• CI: variabel terenkripsi di provider CI
• Deployment/hosting: rahasia disimpan di hosting dan disuntikkan saat runtime

Contoh: repo berisi PAYMENTS_API_KEY=replace_me. Penerima membuat kunci sendiri di dashboard provider dan menyetnya di .env lokal dan di CI. Kode tetap sama.

Tambahkan satu langkah rotasi

Penyerahan adalah waktu yang baik untuk merotasi rahasia, terutama jika pernah digunakan di sesi platform bersama.

• Terbitkan kunci baru untuk layanan eksternal dan cabut yang lama.
• Reset password database dan token admin apa pun.
• Update rahasia CI dan hosting dulu, lalu update file .env lokal.
• Konfirmasi aplikasi berjalan, tes lulus, dan kunci lama tidak lagi berfungsi.

Jika Anda mengekspor dari Koder.ai, anggap ekspor sebagai lingkungan baru dan buat rahasia baru untuk tim penerima.

Setup pengembangan lokal: buat first run jadi membosankan

Penyerahan berhasil ketika pengembang baru bisa meng-clone repo, menjalankan beberapa perintah, dan melihat aplikasi bekerja tanpa menebak. Tujuannya adalah prasyarat yang dapat diprediksi, urutan perintah yang jelas, dan blok “cara menjalankan” singkat yang sesuai kenyataan.

Prasyarat (jelaskan)

Letakkan ini di bagian atas README agar tidak perlu ditafsirkan dari pesan error:

• Catatan OS: “Diuji di macOS dan Ubuntu” (tambahkan catatan Windows hanya jika dilakukan pengujian)
• Versi runtime: Node.js (untuk React), Go (untuk API), PostgreSQL (untuk DB)
• Alat: npm/pnpm/yarn, Make (jika dipakai), Docker (hanya jika bergantung padanya)

Jika proyek dibangun di Koder.ai, selaraskan setup lokal dengan yang Anda ekspor (struktur folder sama, perintah start sama). Jangan berasumsi “Postgres sudah berjalan” kecuali Anda menuliskannya.

Perintah instalasi dan dev (satu per baris)

Taruh perintah tepat dalam urutan yang harus dijalankan rekan baru. Buat bisa copy-paste:

# 1) Install dependencies
cd web
npm ci

cd ../server
go mod download

# 2) Buat file env Anda
cp .env.example .env

# 3) Start dependencies (jika perlu)
# mis. jalankan Postgres secara lokal atau via docker compose

# 4) Jalankan aplikasi
cd server
go run ./cmd/api

cd ../web
npm run dev

Tambahkan bagian test dan build minimal tepat di bawahnya:

# Tests
cd server && go test ./...
cd web && npm test

# Build
cd web && npm run build
cd server && go build ./...

Troubleshooting: kegagalan first-run yang paling umum

Kebanyakan masalah “tidak jalan” masuk ke beberapa kategori:

1. Versi salah (Node/Go). Gejala: error dependency atau kompilasi. Solusi: pasang versi yang dipin dan jalankan ulang install.

2. Nilai env hilang. Gejala: konfigurasi “undefined”, kegagalan otentikasi, error 500. Solusi: bandingkan .env dengan .env.example dan isi nilai wajib.

3. Database tidak tersambung. Gejala: connection refused, “database does not exist.” Solusi: jalankan Postgres, verifikasi host/port/user, dan jalankan langkah inisialisasi database persis seperti tertulis.

Bootstrap database: migrasi, seed, dan reset

Saat proyek diekspor dari platform, database sering jadi hal pertama yang rusak di mesin baru. Tujuannya sederhana: rekan harus bisa dari “saya meng-clone repo” ke “aplikasi berjalan dengan data nyata” tanpa menebak.

Apa yang harus didokumentasikan (dan tetap di repo)

Tulis langkah minimum untuk setup PostgreSQL fresh, dan taruh perintah dalam skrip bila mungkin. Handoff Anda harus menjawab empat pertanyaan:

• Bagaimana cara membuat database dan role (nama, permission, dan dari mana password berasal)?
• Bagaimana cara menjalankan migrasi dari nol ke versi terbaru?
• Bagaimana cara memuat seed data yang membuat aplikasi berguna untuk demo?
• Bagaimana cara mereset database dengan aman selama pengembangan?

Jika Anda sudah memiliki skrip (target Makefile, shell script, task runner), gunakan itu alih-alih menjelaskan langkah manual. Jika belum, tambahkan beberapa skrip kecil sekarang.

Alur bootstrap sederhana yang bekerja

Pertahankan alur konsisten di seluruh lingkungan (lokal, CI, staging). Baseline yang baik terlihat seperti ini:

# 1) Create role + database (example names)
createuser app_user --pwprompt
createdb app_db --owner=app_user

# 2) Apply migrations
# Replace with your repo's migration command
./scripts/migrate up

# 3) Seed minimal demo data
./scripts/seed

Untuk seed, pilih data minimal yang membuat aplikasi bekerja daripada dump produksi. Seed harus aman dijalankan berkali-kali (insert idempoten, atau aturan “jalankan hanya jika DB kosong”).

Untuk reset, jelaskan tentang keselamatan. Perintah reset sebaiknya hanya menargetkan pengembangan lokal secara default. Jika Anda menyediakan skrip destruktif, tambahkan pengaman (mis. memerlukan CONFIRM_RESET=1, atau memeriksa APP_ENV=development). Juga definisikan apa arti “reset”: drop dan recreate, bersihkan tabel, atau pulihkan snapshot yang diketahui.

Kebersihan repo: apa yang boleh dan tidak boleh ada di source

Penyerahan berantakan ketika repo terasa seperti laci barang. Orang baru harus bisa tahu apa yang penting, apa yang dihasilkan, dan di mana mengubah pengaturan.

Commit hal yang membuat proyek dapat diulang: lockfiles, file migrasi, template konfigurasi kecil seperti .env.example, dan skrip yang bootstrap aplikasi.

Jaga file personal, yang dihasilkan, atau sensitif tetap keluar dari version control: file environment lokal, pengaturan editor, output build, log, cache, dan apa pun yang memberi akses (API key, password DB, file akun layanan).

Aturan sederhana: jika mengubahnya memengaruhi semua orang, commit. Jika berubah per mesin atau lingkungan, dokumentasikan dan jangan commit.

Jika Anda menyertakan catatan singkat “commit vs ignore”, buat singkat:

• Commit: README, lockfiles, migrasi, skrip seed, .env.example
• Ignore: .env, file rahasia, folder build, log, cache lokal

Tambahkan peta direktori singkat agar struktur jelas tanpa klik sana-sini. Contoh: “/backend layanan API, /web frontend, /mobile app, /db migrasi dan seed, /scripts helper setup.”

Jika Anda mengekspor dari Koder.ai, anggap ekspor ini sebagai awal dari sesi pembersihan: hapus sampah yang dihasilkan, konfirmasi aturan ignore, dan tulis peta direktori.

CI: buat pipeline yang dapat direproduksi

Penyerahan gagal diam-diam ketika CI hampir sama dengan lokal. Jika seseorang bisa menjalankan proyek di laptop, CI harus menjalankan perintah yang sama dan mendapatkan hasil yang sama.

Putuskan apa yang harus dibuktikan CI di setiap pull request. Kebanyakan tim hanya butuh set kecil:

• Lint/format
• Unit tests
• Build (frontend dan backend kompilasi bersih)

Tes integrasi dan langkah deploy boleh juga, tapi hanya jika dapat diandalkan dan cakupannya jelas.

Jaga langkah CI mendekati perintah lokal untuk menghindari drift. Jika lokal adalah make test, CI juga harus menjalankan make test. Jika Anda tidak punya Makefile atau task runner setara, pertimbangkan menambahkannya dan menggunakannya sebagai entry point bersama.

Buat env var dan rahasia CI eksplisit

CI paling sering rusak karena bergantung pada konfigurasi tersembunyi. Tambahkan bagian singkat “CI variables” di README yang mencantumkan nama-nama yang CI harapkan. Pisahkan konfigurasi publik dari rahasia.

Contoh nama (sesuaikan dengan stack Anda): APP_ENV, DATABASE_URL, PORT, JWT_SECRET, S3_BUCKET, STRIPE_API_KEY. Di CI, rahasia harus datang dari secret store CI, bukan dari file yang di-commit. Untuk backend Go + Postgres (umum pada ekspor dari Koder.ai), juga catat apakah migrasi dijalankan otomatis atau membutuhkan langkah eksplisit.

Lindungi merge dengan status check

Putuskan cek mana yang wajib sebelum merge dan tuliskan. “lint + unit tests + build” biasanya cukup. Jika Anda menambah job opsional (mis. build mobile), buat non-blocking kecuali benar-benar diperlukan.

Juga buat output CI mudah di-debug: cetak versi alat dan fail dengan pesan yang jelas. Tambahkan caching setelah pipeline stabil.

Contoh skenario penyerahan: dari clone hingga aplikasi berjalan

Maya menerima proyek yang diekspor dari Koder.ai. Ini setup tipikal: web app React, API Go, dan database PostgreSQL. Dia seharusnya bisa meng-clone dan melihat layar kerja tanpa menebak.

30 menit pertamanya seharusnya seperti ini:

1. Clone repo dan buka README root.
2. Salin .env.example ke .env (atau set nilai yang sama di shell) untuk web dan api.
3. Jalankan PostgreSQL (lokal atau di Docker) dan buat database kosong.
4. Jalankan migrasi dan seed untuk mendapatkan dataset awal yang diketahui.
5. Jalankan backend, lalu frontend, dan buka aplikasi di browser.

Dalam penyerahan berantakan, dia biasanya menemui tiga hambatan.

Pertama: aplikasi boot, lalu crash dengan error samar “missing config”. Masalah sebenarnya adalah variabel yang tidak didokumentasikan seperti AUTH_JWT_SECRET atau format DATABASE_URL yang diperlukan. Jika README mencantumkan setiap variabel wajib, menunjukkan contoh nilai aman, dan menjelaskan penggunaannya, ini menjadi perbaikan cepat.

Kedua: API berjalan, tapi setiap halaman menunjukkan “no data” atau gagal dengan error 500. Database ada, tapi tidak ada tabel atau data seed. Penyerahan bersih mencakup satu atau dua perintah andal: jalankan migrasi, seed data demo minimal, dan perintah reset untuk saat terjadi masalah.

Ketiga: semua berjalan, tapi frontend menunjuk ke port yang salah. Maya membuka localhost:3000, tapi API mengharapkan localhost:8080, atau CORS memblokir permintaan. Di sinilah default yang konsisten membantu: satu tempat untuk mengatur WEB_PORT, API_PORT, dan API_BASE_URL, dengan README menyebutkan URL lokal yang diharapkan.

Daftar periksa akhir, jebakan umum, dan langkah selanjutnya

Penyerahan selesai ketika orang lain bisa menjalankan proyek dari clean clone tanpa bertanya. Buktikan proyek bisa bertahan di luar platform.

Lakukan satu tes “clean clone” di mesin baru atau container sekali pakai. Jangan pakai folder yang sudah ada, dependency yang di-cache, atau database lokal. Ikuti README Anda persis. Jika Anda harus improvisasi, perbaiki dokumen atau skrip sampai tidak perlu improvisasi lagi.

Pemeriksaan cepat yang menangkap sebagian besar kegagalan:

• README memiliki satu jalur “cara menjalankan” copy-paste untuk dev lokal, plus bagian singkat “cara mengetes.”
• .env.example ada, dan setiap variabel wajib dijelaskan dengan contoh nilai aman.
• Bootstrap database bekerja end-to-end: create DB, jalankan migrasi, seed opsional, dan perintah reset.
• CI berjalan di runner bersih dan cocok dengan perintah lokal.
• Pengembang baru bisa membuat satu perubahan kecil, menjalankan tes, dan melihatnya tercermin di aplikasi.

Jebakan umum cenderung membosankan, itulah kenapa sering terlewat:

• Langkah satu kali tersembunyi yang tidak pernah tercatat di dokumen
• README yang cocok dengan struktur folder lama atau nama perintah lama
• Nilai yang di-hardcode (API URL, feature flag, key) tertanam di kode alih-alih di konfigurasi
• Rahasia dibagikan secara informal tanpa jalur setup yang jelas dan aman
• CI lulus hanya karena bergantung pada artefak cache atau layanan lokal

Langkah selanjutnya: tetapkan satu pemilik untuk memvalidasi ekspor dalam 24–48 jam, jangan minggu kemudian. Minta mereka melakukan clean clone test dan melaporkan celah.

Jika Anda membangun di Koder.ai (Koder.ai), ada baiknya memperlakukan daftar periksa ini sebagai bagian dari alur kerja normal: gunakan planning mode untuk menulis path menjalankan, ambil snapshot sebelum perubahan besar, dan ekspor kode secara berkala sehingga paket penyerahan tetap mutakhir.