Claude Code untuk onboarding codebase: prompt yang memetakan aplikasi Anda

Apa yang ingin Anda pelajari (dan apa yang bisa ditunda)

Membuka file secara acak terasa lambat karena kebanyakan codebase tidak disusun seperti sebuah cerita. Anda membuka folder, melihat sepuluh nama yang kelihatannya penting, klik satu, dan berakhir di helpers, config, dan kasus tepi. Setelah satu jam, Anda punya banyak detail tapi masih tidak bisa menjelaskan bagaimana aplikasi bekerja.

Tujuan yang lebih baik untuk Claude Code selama onboarding adalah membangun peta mental sederhana. Peta itu harus menjawab tiga pertanyaan:

• Apa modul utama?
• Apa alur kunci yang dipicu pengguna?
• Di mana area berisiko yang bisa merusak produksi atau menimbulkan bug?

Onboarding yang cukup baik dalam 1–2 hari bukanlah "Saya bisa menjelaskan setiap class." Lebih dekat ke ini:

• Anda bisa menyebut 5–8 modul yang penting dan apa yang dimiliki masing-masing.
• Anda bisa menelusuri 2–3 alur pengguna nyata ujung-ke-ujung (dari entry UI atau API ke database dan kembali).
• Anda tahu risiko teratas (pembayaran, auth, penulisan data, background jobs) dan di mana letaknya.
• Anda bisa melakukan perubahan kecil dengan aman karena tahu apa yang harus diuji dan siapa yang ditanya.

Beberapa hal bisa ditunda. Refactor mendalam, pemahaman sempurna tentang setiap abstraksi, dan membaca kode lama yang jarang disentuh jarang memberi hasil paling cepat.

Pikirkan onboarding sebagai membangun peta, bukan menghafal jalan. Prompt Anda harus terus mengarahkan kembali ke: "Di mana saya di sistem ini, apa yang terjadi selanjutnya, dan apa yang bisa salah di sini?" Setelah itu Anda akan lebih mudah mempelajari detail saat diperlukan.

Persiapan: dapatkan konteks tanpa harus menelusuri semuanya

Sebelum mulai bertanya, kumpulkan dasar yang biasanya Anda butuhkan di hari pertama. Claude Code bekerja paling baik ketika bisa bereaksi terhadap file nyata, konfigurasi nyata, dan perilaku nyata yang bisa Anda reproduksi.

Mulai dengan akses dan kemampuan menjalankan. Pastikan Anda bisa clone repo, menginstal dependensi, dan menjalankan aplikasi (atau setidaknya potongan kecil) secara lokal. Jika setup lokal sulit, dapatkan akses ke staging dan ke tempat log disimpan, sehingga Anda dapat memverifikasi apa yang sebenarnya dilakukan kode.

Selanjutnya, temukan dokumen “sumber kebenaran”. Anda mencari apa saja yang tim benar-benar perbarui saat sesuatu berubah: README, catatan arsitektur singkat, folder ADR, runbook, atau catatan deploy. Sekalipun berantakan, dokumen itu memberi nama pada modul dan alur, yang membuat Q&A jauh lebih tepat.

Tentukan cakupan sejak awal. Banyak repo berisi beberapa aplikasi, layanan, dan package bersama. Pilih batas seperti "hanya API dan billing worker" atau "hanya web app dan alur auth-nya." Cakupan yang jelas mencegah penyimpangan tanpa akhir.

Tuliskan asumsi yang tidak ingin Anda biarkan asisten tebak. Ini terdengar kecil, tapi mencegah model mental salah yang membuang-buang waktu kemudian.

Berikut checklist persiapan sederhana:

• Konfirmasi akses repo, izin yang diperlukan, dan cara menjalankan test.
• Kumpulkan catatan setup environment (env vars, seeds, feature flags) dan tempat melihat log serta metrik.
• Identifikasi file kebenaran saat ini (README, catatan arsitektur, ADR, runbook).
• Definisikan apa yang termasuk dalam cakupan dan apa yang secara eksplisit keluar dari cakupan untuk pass onboarding ini.
• Tetapkan aturan keselamatan: jangan pernah menempelkan secrets, API keys, token, data pelanggan pribadi, atau log produksi dengan detail sensitif.

Jika sesuatu hilang, catat sebagai pertanyaan untuk rekan. Jangan "mengakali" konteks yang hilang dengan tebakan.

Peta mental: apa yang harus dicatat saat Anda menjelajah

Peta mental adalah satu set catatan kecil yang menjawab: apa bagian utama aplikasi ini, bagaimana mereka saling berbicara, dan di mana hal bisa salah. Jika dilakukan dengan baik, onboarding menjadi lebih sedikit tentang menjelajah file dan lebih banyak tentang membangun gambaran yang bisa digunakan ulang.

Mulai dengan mendefinisikan keluaran Anda. Anda ingin daftar modul yang praktis, bukan sempurna. Untuk setiap modul, catat apa yang dilakukannya, siapa pemiliknya (tim atau orang jika Anda tahu), dan dependensi utamanya (modul lain, layanan, database, API eksternal). Juga catat titik entry utama: route UI, endpoint API, background job, dan tugas terjadwal.

Selanjutnya, pilih beberapa perjalanan pengguna yang penting. Tiga sampai lima sudah cukup. Pilih alur yang menyentuh uang, izin, atau perubahan data. Contoh: signup dan verifikasi email, membuat plan berbayar atau pembelian, tindakan admin yang mengubah akses pengguna, dan alur harian kritis yang diandalkan kebanyakan pengguna.

Tentukan bagaimana Anda akan memberi label risiko sebelum mulai mengumpulkan catatan. Buat kategori sederhana agar mudah discan nanti. Satu set yang berguna: security, integritas data, uptime, dan biaya. Saat menandai sesuatu sebagai berisiko, tambahkan satu kalimat yang menjelaskan mengapa, plus apa yang membuktikan aman (tes, log, pengecekan permission).

Gunakan format konsisten supaya Anda bisa mengubah catatan menjadi dokumen onboarding tanpa menulis ulang semuanya:

• Modules: tujuan, entry points, dependensi, owner
• Key flows: trigger, langkah, data yang ditulis, titik gagal
• Data: tabel atau koleksi yang disentuh, field penting, constraint
• Risks: kategori, dampak terburuk, cara memonitor, cara rollback
• Open questions: apa yang masih tidak Anda ketahui, siapa yang ditanya

Contoh: jika Checkout memanggil Billing yang menulis ke payments dan invoices, tandai sebagai integritas data dan biaya. Kemudian catat di mana retry terjadi dan apa yang mencegah double-charging.

Langkah demi langkah prompt Q&A untuk menjelajah codebase

Saat bergabung ke repo baru, Anda ingin orientasi cepat, bukan pemahaman sempurna. Prompt berikut membantu Anda membangun peta mental dalam langkah-langkah kecil dan aman.

Mulai dengan memberi asisten pohon repo (atau subset yang ditempel) dan minta tur. Jaga tiap putaran fokus, lalu akhiri dengan satu pertanyaan yang memberitahu Anda apa yang harus dibaca selanjutnya.

1) Repo tour
"Here is the top-level folder list: <paste>. Explain what each folder likely contains and which ones matter for core product behavior."

2) Entry points
"Find the app entry points and boot process. What files start the app, set up routing, configure DI/env, and start background jobs? Name the exact files and what they do."

3) Module index
"Create a module index: module name, purpose, key files, and important external dependencies. Keep it to the modules that affect user-facing behavior."

4) Data model hints
"Based on migrations/models, list the key tables/entities, critical fields, and relationships. Call out fields that look security-sensitive or used for billing/permissions."

5) Flow trace
"Trace this flow end-to-end: <flow>. Where does the request/event start, where does it end, and what does it call in between? List the main functions/files in order."

6) Next inspection
"What should I inspect next and why? Give me 3 options: fastest clarity, riskiest area, and best long-term payoff."

Contoh konkret: jika Anda memetakan "user signs up and creates their first project," minta route handler API, validasi, penulisan DB, dan job async yang mengirim email atau menyediakan resource. Lalu ulangi flow trace untuk "user deletes project" untuk mencari celah pembersihan.

Agar jawaban tetap dapat ditindaklanjuti, minta artefak spesifik, bukan sekadar ringkasan:

• Path file dan nama fungsi
• Asumsi dan yang belum diketahui disebutkan jelas
• Dependensi diformulasikan sebagai "Jika saya mengubah X, apa yang rusak?"
• Satu tugas membaca kecil yang bisa Anda lakukan dalam 10 menit

Cara menangkap jawaban supaya tetap berguna

Kemenangan terbesar onboarding adalah mengubah Q&A terpencar menjadi catatan yang bisa dipakai developer lain. Jika catatan hanya masuk akal untuk Anda, Anda akan mengulang pekerjaan yang sama nanti.

Struktur sederhana lebih baik daripada halaman panjang. Setelah tiap sesi eksplorasi, simpan jawaban ke dalam lima artefak kecil (satu file atau dokumen cukup): tabel modul, glosarium, alur kunci, unknowns, dan risk register.

Berikut template ringkas yang bisa Anda tempel ke catatan dan isi seiring berjalannya:

Module table
- Module:
  Owns:
  Touches:
  Entry points:

Glossary
- Term:
  Meaning:
  Code name(s):

Key flow (name)
1.
2.
3.

Unknowns
- Question:
  Best person to ask:
  Where to look next:

Risk register
- Risk:
  Location:
  Why it matters:
  How to verify:

Jaga alur singkat dengan sengaja. Contoh: 1) user signs in, 2) backend creates a session, 3) client loads the dashboard, 4) API fetches data, 5) UI merender dan menangani error. Jika Anda tidak bisa merangkum alur dalam lima langkah, pecah (login vs dashboard load).

Saat menggunakan Claude Code, tambahkan satu baris ke setiap jawaban: "How would I test this?" Baris ini mengubah catatan pasif menjadi checklist yang bisa Anda jalankan nanti, terutama saat unknowns dan risks mulai tumpang tindih.

Jika Anda membangun di platform vibe-coding seperti Koder.ai, jenis pencatatan ini juga membantu Anda melihat di mana perubahan yang dihasilkan mungkin punya efek samping. Modul yang menyentuh banyak bagian cenderung menjadi magnet perubahan.

Menemukan area berisiko dengan cepat (tanpa membaca setiap file)

Risiko dalam codebase jarang acak. Ia berkumpul di tempat aplikasi menentukan siapa Anda, mengubah data, berbicara ke sistem lain, atau menjalankan pekerjaan di background. Anda bisa menemukan sebagian besar dengan pertanyaan terarah dan beberapa pencarian fokus.

Mulai dari identitas. Tanyakan di mana autentikasi terjadi (login, session, token) dan di mana keputusan otorisasi berada (cek role, feature flags, aturan kepemilikan). Perangkap umum adalah cek tersebar di UI, handler API, dan query DB tanpa sumber kebenaran tunggal.

Selanjutnya, petakan jalur penulisan. Temukan endpoint atau fungsi yang membuat, mengubah, atau menghapus record, plus migrasi yang mengubah data dari waktu ke waktu. Sertakan background job juga. Banyak bug misterius datang dari worker asinkron yang menulis nilai tak terduga setelah request selesai.

Prompt yang menampilkan risiko dengan cepat:

• "List every place that enforces permissions for [resource X]. Which one is the final gate?"
• "Show the full path for writing [table/entity X]: API handler -> service -> DB call. Where are validations?"
• "What external integrations exist (payments, email, webhooks, third-party APIs)? Where are retries and timeouts set?"
• "Where can work run twice (queues, goroutines, cron)? What makes it idempotent?"
• "What can break silently, and how would we notice (logs, metrics, alerts, dashboards)?"

Kemudian periksa konfigurasi dan penanganan secrets. Cari env var, file konfigurasi runtime, dan fallback default. Default berguna, tapi berisiko ketika menyembunyikan miskonfigurasi (mis. memakai key dev di produksi karena nilai hilang).

Contoh cepat: di backend Go dengan PostgreSQL, Anda mungkin menemukan job "send email" yang retry saat gagal. Jika retry terjadi tanpa idempotency key, pengguna bisa menerima email duplikat. Jika kegagalan hanya mencatat warning dan tak ada alert, itu rusak tanpa terlihat. Itu area berisiko tinggi yang layak didokumentasikan dan diuji lebih awal.

Contoh walkthrough: memetakan satu alur pengguna nyata

Gunakan satu alur nyata untuk membangun thread ujung-ke-ujung pertama Anda melalui sistem. Login adalah starter yang baik karena menyentuh routing, validasi, session atau token, dan pembacaan DB.

Skenario: aplikasi React memanggil API Go, dan API membaca serta menulis PostgreSQL. Tujuan Anda bukan memahami setiap file. Tujuannya menjawab: "Ketika user klik Login, kode apa yang dijalankan selanjutnya, data apa yang bergerak, dan apa yang bisa rusak?" Ini membuat onboarding tetap konkret.

Petakan alur dari browser ke database

Mulai di UI dan maju satu hop pada satu waktu. Minta nama file spesifik, fungsi, dan bentuk request/response.

• "Find the React route or page for the login screen. What component renders it, and what action fires on submit?"
• "Where is the API client call made (fetch/axios/etc.)? What exact URL path, method, headers, and body does it send?"
• "On the Go side, where is the handler for that path registered? Show the router setup and the handler function."
• "Inside the handler, where does input validation happen (frontend, backend, both)? What rules exist, and where do errors get formatted?"
• "What database query runs for login? Point to the repository/SQL file, list touched tables/columns, and note any transactions or locks."

Setelah tiap jawaban, tulis satu baris pendek di peta mental: "UI component -> API endpoint -> handler -> service -> DB query -> response." Sertakan nama, bukan sekadar "beberapa fungsi."

Konfirmasi dengan uji cepat

Setelah Anda punya path, verifikasi dengan menjalankan uji kecil. Anda memeriksa bahwa path kode yang Anda petakan adalah path yang sebenarnya dipakai.

Pantau network request di dev tools browser (path, status code, response body). Tambahkan atau aktifkan log server di sekitar handler dan DB call (request ID jika tersedia). Query PostgreSQL untuk perubahan yang diharapkan (untuk login, mungkin last_login_at, sessions, atau baris audit). Paksa satu kegagalan (password salah, field hilang) dan catat di mana pesan error dibuat dan di mana ditampilkan. Rekam respons yang diharapkan untuk sukses dan gagal (status code dan field penting), supaya developer berikutnya bisa melakukan sanity-check dengan cepat.

Alur tunggal ini sering memaparkan batas kepemilikan: apa yang UI percayai, apa yang API tegakkan, dan di mana error menghilang atau ditangani dua kali.

Ubah peta mental menjadi dokumen onboarding singkat

Setelah Anda punya peta mental yang cukup, bekukan menjadi catatan 1–2 halaman. Tujuannya bukan lengkap. Tujuannya membantu developer berikutnya menjawab: apa aplikasi ini, ke mana saya lihat pertama kali, dan apa yang paling mungkin rusak?

Jika Anda menggunakan Claude Code, perlakukan dokumen itu sebagai output Q&A Anda: jelas, konkret, dan mudah dipindai.

Struktur 1–2 halaman sederhana

Jaga dokumen mudah diprediksi supaya orang bisa menemukan hal cepat. Struktur yang baik:

• Purpose: apa yang aplikasi lakukan, siapa penggunanya, dan apa arti "selesai"
• Architecture summary: layanan utama, penyimpanan data, dan bagaimana request bergerak melalui sistem
• How to run: prasyarat, perintah satu baris untuk memulai, dan perintah satu baris untuk menjalankan test
• Where things live: folder yang penting, plus 5–10 file yang menjadi entry point
• Key flows and risks: jejak singkat perjalanan penting, plus apa yang diverifikasi setelah perubahan

Buat supaya dapat ditindaklanjuti, bukan akademis

Untuk "Where things live," sertakan petunjuk seperti "Auth mulai di X, logika session di Y, route UI di Z." Hindari membuang seluruh pohon. Pilih hanya yang akan disentuh orang.

Untuk "Key flows," tulis 4–7 langkah per alur: trigger, controller/handler, modul inti, panggilan database, dan efek keluar (email dikirim, state diupdate, job dipesan). Tambahkan nama file di tiap langkah.

Untuk "Risky areas," sebutkan mode kegagalan dan pengecekan keselamatan tercepat (test spesifik, smoke run, atau log yang dipantau).

Akhiri dengan daftar tugas pertama kecil supaya seseorang bisa berkontribusi dengan aman:

• Perbarui teks kecil atau aturan validasi di satu layar yang terkotak rapi
• Tambah unit test kecil di helper rumit yang Anda temukan
• Perbaiki bug berisiko rendah dengan repro dan hasil yang jelas
• Tambah guardrail: pesan error yang lebih baik, cek input, atau timeout
• Tanyakan siapa pemilik deploy produksi dan siapa yang di-mention untuk pertanyaan domain

Kesalahan umum dan cara menghindarinya

Cara tercepat membuang asisten adalah meminta "penjelasan penuh tentang seluruh repo." Anda akan mendapat ringkasan panjang yang terdengar yakin tapi tetap samar. Sebagai gantinya, pilih irisan kecil yang penting (satu modul + satu alur pengguna), lalu perluas.

Kesalahan kedua adalah tidak menyebut alur yang penting. Jika Anda tidak mengatakan "checkout," "login," atau "admin edit," jawaban mudah melayang ke pembicaraan arsitektur umum. Mulai tiap sesi dengan satu tujuan konkret: "Bantu saya memahami alur signup ujung-ke-ujung, termasuk validasi, status error, dan tempat data disimpan."

Perangkap lain adalah membiarkan asisten menebak. Ketika sesuatu tidak jelas, paksa dia menandai ketidakpastian. Minta memisahkan apa yang bisa dibuktikan dari kode vs apa yang diinferensikan.

Jaga unknowns terlihat (agar bisa diselesaikan)

Gunakan aturan sederhana: setiap klaim harus diberi tag sebagai salah satu:

• Confirmed in code
• Confirmed by running the app
• Assumption (needs check)
• Unknown (missing context)

Catatan juga rusak saat dikumpulkan tanpa struktur. Tumpukan potongan chat sulit diubah menjadi peta mental. Gunakan template konsisten: modul yang terlibat, titik entry, fungsi dan file kunci, data yang disentuh, efek samping, jalur error, dan test yang dijalankan.

Jangan perlakukan output sebagai fakta mutlak

Bahkan dengan Claude Code, perlakukan output sebagai draf. Verifikasi alur kunci di aplikasi yang berjalan, terutama bagian yang bisa merusak produksi: auth, pembayaran, permission, background job, dan migrasi.

Contoh praktis: jika asisten mengatakan "password reset mengirim email via X," konfirmasi dengan memicu reset di lingkungan dev dan memeriksa log atau sandbox email. Pemeriksaan realitas ini mencegah Anda onboarding ke narasi yang tidak benar.

Checklist cepat sebelum Anda bilang "Saya sudah onboard"

Anda tidak perlu menghafal repo. Anda perlu cukup percaya diri untuk melakukan perubahan aman, debug masalah nyata, dan menjelaskan sistem ke orang berikutnya.

Sebelum menyatakan diri onboarded, pastikan Anda bisa menjawab ini tanpa menebak:

• Bisa menjelaskan lima area kode paling penting dan apa yang masing-masing tangani (mis. UI, lapisan API, background jobs, akses data, integrasi)?
• Bisa berjalan melalui dua alur pengguna bernilai tinggi ujung-ke-ujung, dan menunjuk file atau fungsi pertama yang memulai tiap alur?
• Bisa menunjuk di mana autentikasi ditegakkan, dan di mana role atau permission didefinisikan serta dicek?
• Bisa menyebut penulisan database paling berisiko (uang, permission, penghapusan, transisi state), dan menjelaskan bagaimana Anda akan menguji setiap perubahan dengan aman?
• Bisa menyerahkan catatan onboarding singkat yang bisa dibaca dalam kurang dari 10 menit dan membuat orang tahu harus mulai di mana?

Jika satu item hilang, lakukan pass fokus kecil daripada pencarian luas. Pilih satu alur, ikuti sampai batas database, lalu berhenti dan tulis apa yang Anda pelajari. Saat sesuatu tidak jelas, catat sebagai pertanyaan, bukan paragraf. "Di mana role X dibuat?" lebih berguna daripada "auth membingungkan."

Tes akhir yang bagus: bayangkan diminta menambahkan fitur kecil di balik flag. Jika Anda bisa menyebut file yang akan disentuh, test yang dijalankan, dan mode kegagalan yang diwaspadai, berarti Anda cukup onboard untuk berkontribusi dengan tanggung jawab.

Langkah berikutnya: jaga peta tetap mutakhir dan permudah handoff

Peta mental berguna hanya selama ia masih mencerminkan kenyataan. Perlakukan itu sebagai artefak hidup, bukan tugas sekali jadi. Cara termudah menjaga kejujuran adalah memperbaruinya segera setelah perubahan yang memengaruhi perilaku.

Rutinitas ringan mengalahkan rewrite besar. Kaitkan pembaruan dengan pekerjaan yang sudah Anda lakukan:

• Setelah tiap fitur: perbarui daftar modul dan alur utama yang disentuh
• Setelah tiap insiden: tambahkan trigger, dampak, dan lokasi perbaikan yang tepat
• Setelah refactor berisiko: catat apa yang berubah dan apa yang tetap kompatibel
• Sebelum rilis: periksa ulang 3 area berisiko teratas dan jalur uji
• Sekali sebulan: hapus catatan usang dan konfirmasi pemilik modul kunci

Simpan dokumen onboarding dekat dengan kode dan versi-kan dengan disiplin yang sama seperti kode. Diff kecil dibaca. Rewrite dokumen besar biasanya dilewatkan.

Saat deploy berisiko, tuliskan apa yang membantu orang berikutnya pulih cepat: apa yang berubah, apa yang dipantau, dan bagaimana rollback. Jika platform Anda mendukung snapshot dan rollback, tambahkan nama snapshot, alasan, dan apa yang terlihat "baik" setelah perbaikan.

Jika Anda membangun dengan Koder.ai (koder.ai), planning mode dapat membantu merancang peta modul dan catatan onboarding yang konsisten dari Q&A Anda, dan ekspor kode sumber memberi reviewer cara rapi untuk memvalidasi hasil.

Terakhir, definisikan checklist handoff yang bisa diikuti developer berikutnya tanpa menebak:

• Apa yang harus dibaca pertama (2–3 file atau dokumen) dan mengapa
• Apa yang harus dijalankan secara lokal (perintah, env vars, seed data)
• Apa yang harus diverifikasi (satu happy path dan satu failure case)
• Di mana sudut tajamnya (modul berisiko, test flaky, konfigurasi rumit)
• Siapa yang ditanya untuk apa (pemilik alur kunci)

Jika dilakukan dengan baik, Claude Code untuk onboarding codebase menjadi kebiasaan: setiap perubahan meninggalkan peta yang lebih jelas untuk orang berikutnya.