Prompt panduan gaya Claude Code untuk review kode yang konsisten

Mengapa pelanggaran panduan gaya menyebar begitu cepat

Pelanggaran panduan gaya jarang muncul sebagai satu kesalahan besar. Mereka dimulai dari pilihan kecil “cukup dekat” yang terlihat tidak berbahaya di sebuah pull request, lalu menumpuk sampai basis kode terasa tidak merata dan lebih sulit dibaca.

Drift gaya sering terlihat seperti ini: satu berkas menggunakan userID, berkas lain menggunakan userId, berkas ketiga menggunakan uid. Satu handler mengembalikan { error: "..." }, yang lain melempar, yang lain mencatat dan mengembalikan null. Setiap perubahan kecil, tetapi bersama-sama mereka menciptakan repo di mana pola berhenti dapat diprediksi.

Iterasi cepat dan banyak kontributor membuatnya semakin buruk. Orang menyalin apa yang mereka lihat, terutama saat tertekan waktu. Jika kode terbaru di repo menggunakan jalan pintas, jalan pintas itu menjadi pola untuk perubahan berikutnya. Setelah beberapa minggu, “gaya default” bukan lagi panduan tertulis Anda. Itu adalah apa pun yang terjadi terakhir.

Itulah mengapa tujuannya harus konvensi yang konsisten, bukan preferensi pribadi. Pertanyaannya bukan “Apakah saya suka nama ini?” Melainkan “Apakah ini sesuai aturan yang kita sepakati sehingga orang berikutnya bisa mengikutinya tanpa berpikir?”

Menangkap pelanggaran sejak dini berarti menghentikan pola buruk sebelum mereka menjadi bahan copy-paste. Fokus pada kode baru dan yang diubah, perbaiki kemunculan pertama dari inkonsistensi baru, dan blokir merge yang memperkenalkan drift baru. Saat Anda menandai masalah, tambahkan contoh singkat yang disukai agar orang bisa menirunya berikut kali.

Satu contoh realistis: seorang developer menambahkan endpoint API baru dan mencatat body request mentah “hanya untuk debugging.” Jika itu masuk, endpoint berikutnya menyalin, dan segera data sensitif muncul di log. Menangkapnya di PR pertama murah. Menangkapnya setelah menyebar menyakitkan dan berisiko.

Ubah panduan gaya Anda menjadi aturan yang jelas dan dapat diuji

Panduan gaya hanya berfungsi dalam review jika dibaca seperti checklist, bukan sekumpulan preferensi. Tulis ulang setiap pedoman sebagai aturan yang bisa diperiksa pada diff.

Atur aturan ke dalam empat keranjang supaya sulit terlewat: penamaan, layering, penanganan error, dan logging. Untuk setiap keranjang, tulis dua hal: apa yang harus benar dan apa yang dilarang.

Tentukan kekuatan setiap aturan di depan:

• Mandatory: gagal memenuhinya akan memblokir perubahan.
• Recommended: perbaiki kecuali ada alasan jelas untuk tidak melakukannya.
• Optional: bagus dimiliki, tidak pernah memblokir.

Atur ruang lingkup agar review tidak berubah jadi refaktor tanpa akhir. Aturan sederhana bekerja baik: “kode baru dan yang diubah harus patuh; kode lama yang tidak disentuh tidak ditulis ulang kecuali menghalangi perbaikan.” Jika Anda mau pembersihan, batasi waktunya sebagai tugas terpisah.

Juga definisikan keluaran yang Anda inginkan dari review supaya mudah ditindaklanjuti: keputusan lulus/gagal, daftar pelanggaran dengan referensi file dan baris, perbaikan yang disarankan dituliskan sebagai edit konkret, dan catatan risiko singkat saat sesuatu bisa menyebabkan bug atau kebocoran.

Contoh: jika sebuah PR mencatat token pengguna mentah, review harus gagal di bawah “logging: jangan pernah mencatat rahasia” dan menyarankan mencatat request ID sebagai gantinya.

Struktur prompt yang menegakkan aturan alih-alih opini

Prompt gaya gagal ketika terdengar seperti preferensi. Prompt review yang baik dibaca seperti kontrak: non-negotiable yang jelas, pengecualian yang diberi nama jelas, dan keluaran yang dapat diprediksi.

Mulailah dengan dua blok pendek: apa yang harus benar dan apa yang bisa dilonggarkan. Lalu tambahkan aturan keputusan: “Jika tidak jelas, tandai sebagai Needs Clarification. Jangan menebak.”

Paksa bukti. Saat alat menandai pelanggaran, minta ia mengutip identifier dan jalur file persis, bukan deskripsi samar. Satu batasan ini menghilangkan banyak bolak-balik.

Persempit ruang lingkup: komentari hanya baris yang diubah dan jalur kode yang langsung terdampak. Jika Anda mengizinkan refaktor yang tidak terkait, penegakan gaya berubah menjadi “tulis ulang berkas,” dan orang berhenti percaya pada umpan balik.

Berikut struktur yang bisa Anda pakai ulang:

Role: strict style guide reviewer.
Input: diff (or files changed) + style guide rules.
Non-negotiables: [list].
Allowed exceptions: [list].
Scope: ONLY comment on changed lines and directly impacted code paths. No unrelated refactors.
Evidence: Every finding MUST include (a) file path, (b) exact identifier(s), (c) short quote.
Output: structured compliance report with pass/fail per category + minimal fixes.

Minta laporan mempertahankan bagian yang sama setiap kali, walau beberapa berisi “No issues found”: Naming, Layering, Error handling, Logging.

Jika mengatakan “service layer leaking DB details,” harus mengutip sesuatu seperti internal/orders/service/order_service.go dan panggilan persis (misal db.QueryContext) supaya Anda bisa memperbaiki kebocoran tanpa berdebat apa maksudnya.

Langkah demi langkah: bangun workflow prompt pemeriksaan gaya

Panduan gaya menempel ketika prosesnya bisa diulang. Tujuannya membuat model memeriksa aturan, bukan berdebat soal rasa, dan melakukannya dengan cara yang sama setiap kali.

Gunakan workflow dua lintasan sederhana:

1. Tempel standar Anda sebagai daftar aturan bernomor yang ringkas (10–25 baris). Jaga setiap aturan tetap dapat diuji.
2. Tambah konteks untuk perubahan: diff, berkas yang disentuh, dan satu kalimat tentang niat.
3. Minta laporan pelanggaran terlebih dulu. Minta file dan referensi baris, alasan singkat, dan nomor aturan yang persis.
4. Hanya setelah laporan, minta patch sekecil mungkin untuk mencapai kepatuhan.
5. Jalankan ulang prompt yang sama pada kode yang telah diperbarui untuk konfirmasi tidak ada yang tersisa.

Contoh: sebuah PR menambah endpoint baru. Lintasan 1 menandai handler yang berbicara langsung ke PostgreSQL (layering), menggunakan penamaan campuran untuk struct request (naming), dan mencatat email lengkap (logging). Lintasan 2 membuat perbaikan minimal: pindahkan panggilan DB ke service atau repository, ubah nama struct, dan mask email di log. Tidak ada yang lain berubah.

Penamaan: prompt yang menangkap hal-hal kecil

Masalah penamaan terasa sepele, tetapi menimbulkan biaya nyata: orang salah membaca maksud, pencarian menjadi lebih sulit, dan nama "hampir sama" berkembang biak.

Nyatakan aturan penamaan yang harus ditegakkan reviewer di seluruh perubahan: nama berkas, tipe yang diekspor, fungsi, variabel, konstanta, dan test. Tegaskan casing (camelCase, PascalCase, snake_case) dan pilih satu aturan akronim (misal APIClient vs ApiClient). Lalu terapkan di mana-mana.

Standarkan juga kosakata bersama: tipe error, field log, dan kunci konfigurasi. Jika log menggunakan request_id, jangan izinkan reqId di satu berkas dan requestId di berkas lain.

Instruksi reviewer yang tetap praktis:

Check every new or renamed identifier. Enforce casing + acronym rules.
Flag vague names (data, info, handler), near-duplicates (userId vs userID), and names that contradict behavior.
Prefer domain language: business terms over generic tech words.

Minta laporan singkat: tiga nama paling membingungkan, near-duplicates dan mana yang dipertahankan, plus nama log/konfig/error yang tidak cocok standar.

Aturan layering: jaga tanggung jawab agar tidak bercampur

Aturan layering bekerja terbaik dalam bahasa biasa: handler menangani HTTP, service menampung aturan bisnis, repository berinteraksi dengan database.

Kunci arah dependensi. Handler boleh memanggil service. Service boleh memanggil repository. Repository tidak boleh memanggil service atau handler. Handler tidak boleh mengimpor kode database, helper SQL, atau model ORM. Jika Anda memakai paket bersama (config, time, IDs), jaga agar bebas logika aplikasi.

Tetapkan pekerjaan lintas-potong ke rumah tunggal. Validasi biasanya di boundary untuk bentuk request dan di service untuk aturan bisnis. Otorisasi sering dimulai di handler (identitas, scope), tetapi service harus menegakkan keputusan akhir. Mapping berada di tepi layer: handler map HTTP ke domain input, repository map baris DB ke tipe domain.

Masukkan ini ke prompt untuk membuat review konkret:

Check layering: handler -> service -> repository only.
Report any leaks:
- DB types/queries in handlers or services
- HTTP request/response types inside services or repositories
- repository returning DB models instead of domain objects
- auth/validation mixed into repository
For each leak, propose the smallest fix: move function, add interface, or rename package.

Buat laporannya eksplisit: sebutkan file, layer yang seharusnya, import atau panggilan yang melanggar aturan, dan perubahan minimal yang mencegah pola itu menyebar.

Konvensi penanganan error: konsisten saat tekanan

Kebanyakan perdebatan gaya memanas saat ada yang rusak di produksi. Kebijakan penanganan error yang jelas menenangkan perbaikan karena semua orang tahu seperti apa “baik”.

Tuliskan filosofi dan tegakkan. Misal: “Wrap errors untuk menambah konteks; buat error baru hanya saat mengubah makna atau memetakan ke pesan pengguna. Kembalikan error mentah hanya di boundary sistem.” Satu kalimat ini mencegah pola acak menyebar.

Pisahkan teks yang tampil ke pengguna dari detail internal. Pesan pengguna harus singkat dan aman. Error internal boleh menyertakan nama operasi dan identifier kunci, tapi bukan rahasia.

Dalam review, periksa kegagalan yang sering muncul: error yang ditelan (dicatat tapi tidak dikembalikan), return ambigu (nilai nil dengan error nil setelah kegagalan), dan pesan pengguna yang membocorkan stack trace, teks query, token, atau PII. Jika mendukung retry atau timeout, wajibkan eksplisititasnya.

Contoh: panggilan checkout timeout. Pengguna melihat “Payment service is taking too long.” Secara internal, bungkus timeout dengan op=checkout.charge dan order ID sehingga mudah dicari dan ditindaklanjuti.

Konvensi logging: terbaca, bisa dicari, dan aman

Log hanya membantu saat semua orang menulisnya dengan cara yang sama. Jika setiap developer memilih kata, level, dan field sendiri, pencarian berubah jadi menebak-nebak.

Buat level log tidak bisa dinegosiasikan: debug untuk detail pengembangan, info untuk milestone normal, warn untuk situasi tak terduga tapi ditangani, dan error saat aksi yang terlihat pengguna gagal atau butuh perhatian. Jaga “fatal” atau “panic” jarang dan terkait kebijakan crash yang jelas.

Log terstruktur lebih penting daripada kalimat sempurna. Wajibkan nama key yang stabil supaya dashboard dan alert tidak rusak. Pilih set inti kecil (misal event, component, action, status, duration_ms) dan konsisten.

Perlakukan data sensitif sebagai batas keras. Jelaskan apa yang tidak boleh pernah dicatat: password, token otentikasi, kartu kredit lengkap, rahasia, dan data pribadi mentah. Sebutkan hal yang tampak tidak berbahaya tapi bukan, seperti link reset password, session ID, dan body request penuh.

Correlation ID memungkinkan debugging lintas layer. Minta request_id di setiap baris log dalam sebuah request. Jika Anda mencatat user_id, definisikan kapan diizinkan dan bagaimana merepresentasikan pengguna anonim atau jika nil.

Blok prompt yang bisa dipakai ulang:

Review the changes for logging conventions:
- Check level usage (debug/info/warn/error). Flag any level that does not match impact.
- Verify structured fields: require stable keys and avoid free-form context in the message.
- Confirm correlation identifiers: request_id on all request-bound logs; user_id only when allowed.
- Flag any sensitive data risk (tokens, secrets, personal data, request/response bodies).
- Identify noisy logs (in loops, per-item logs, repeated success messages) and missing context.
Return: (1) violations with file/line, (2) suggested rewrite examples, (3) what to add or remove.

Sebelum merge, lakukan “safety pass” cepat: log baru tanpa request_id untuk pekerjaan request-bound, kunci baru yang mengubah nama existing (userId vs user_id), error log tanpa apa yang gagal (operasi, resource, status), log volume tinggi yang akan men-trigger setiap request, dan potensi rahasia atau data pribadi muncul di field atau pesan.

Cara menangkap pelanggaran sebelum menyebar

Perlakukan drift gaya seperti build break, bukan saran. Tambahkan gerbang ketat yang berjalan sebelum merge dan mengembalikan pass atau fail yang jelas. Jika aturan mandatory dilanggar (penamaan, batas layer, keamanan logging, penanganan error), gerbang gagal dan menunjuk file dan baris yang tepat.

Jaga gerbang tetap singkat. Trik praktis: minta checklist YES/NO per aturan, dan tolak persetujuan jika ada item NO.

Checklist seukuran PR yang menangkap sebagian besar masalah:

• Naming: sesuai pola yang disetujui untuk berkas, tipe, dan fungsi
• Layering: tidak ada pemanggilan langsung yang melewati layer (misal handler memanggil DB)
• Errors: dikembalikan konsisten dengan konteks, tidak ada yang dibungkam
• Logging: field konsisten, tidak ada rahasia, dan level sesuai dampak
• Tests/docs: diperbarui saat perilaku atau API publik berubah

Saat alat menyarankan perbaikan, minta snippet kecil yang patuh untuk setiap aturan yang disentuh. Itu mencegah umpan balik samar seperti “ganti nama untuk jelas.”

Perangkap umum saat menggunakan prompt untuk penegakan gaya

Cara tercepat panduan gaya gagal adalah membiarkan ruang untuk interpretasi. Jika dua reviewer bisa membaca aturan yang sama dan menghasilkan kesimpulan berbeda, alat akan menegakkan selera, bukan standar.

Penamaan contoh umum. “Gunakan nama yang jelas” tidak dapat diuji. Perketat menjadi sesuatu yang bisa diverifikasi: “fungsi adalah kata kerja (misal createInvoice), boolean dimulai dengan is/has/can, tipe yang diekspor PascalCase.”

Perangkap lain adalah meminta semuanya sekaligus. Saat satu prompt mencoba mencakup penamaan, layering, error, logging, test, dan performa, umpan balik menjadi dangkal. Bagi review menjadi lintasan fokus jika butuh kedalaman, atau batasi prompt gerbang ke aturan mandatory.

Masalah yang sering menyebabkan penegakan melenceng:

• Vague rules: ganti “bersih” dan “konsisten” dengan bahasa terukur.
• Mixing style fixes with redesign: jangan biarkan prompt gaya mengusulkan arsitektur baru.
• No quoted evidence: minta setiap komentar mengutip identifier atau snippet persis.
• Silent exceptions: jika Anda mengizinkan pengecualian, minta catatan singkat mengapa dan kapan harus dihapus.

Jika Anda memperlakukan prompt seperti tes, Anda mendapat penegakan yang dapat diprediksi. Jika dianggap nasihat, pelanggaran menyusup dan berkembang.

Checklist cepat yang bisa dijalankan pada setiap perubahan

Jalankan pass cepat pada diff (bukan seluruh repo) dan konfirmasi:

• Naming: identifier baru mengikuti pola Anda (case, prefix, suffix). Satu konsep diberi satu nama di seluruh berkas.
• Layering: dependensi hanya mengalir di arah yang diizinkan. Layer bawah tidak mengimpor layer atas.
• Errors: kegagalan dikembalikan dengan konteks. Tidak ada yang dibungkam.
• Logging: level tepat, field stabil, dan tidak ada rahasia atau data pribadi.
• Final pass: reviewer menyatakan tepat: “no mandatory violations found”, atau mencantumkan pelanggaran yang harus diperbaiki sebelum merge.

Simpan template prompt kecil dan tempelkan pada setiap perubahan:

Review ONLY the changed code against our rules for naming, layering, errors, and logging.
List mandatory violations first (with file + line if available). Then list optional suggestions.
End with either: “no mandatory violations found” or “mandatory violations found”.

Contoh: fungsi baru procUsr() di handler yang menulis langsung ke PostgreSQL harus gagal pada penamaan dan layering walau fiturnya berjalan. Menangkapnya di sini mencegah copy-paste menyebarkan kesalahan.

Contoh: review realistis yang memperbaiki masalah lebih awal

Seorang rekan menambahkan endpoint baru: POST /v1/invoices/{id}/send. Ia menyentuh handler, service, dan storage.

Pada pass pertama, Anda ingin laporan, bukan penulisan ulang:

Pass 1 (report only)
You are a strict style checker. Read the patch.
Rules: naming must match our guide, handlers call services only, services call storage only, no SQL in handlers,
errors must be wrapped with context, logs must be structured and not leak PII.
Output: a numbered list of violations with file:line, rule name, and one-sentence impact. Do not propose fixes.
If a rule might be intentionally broken, ask one clarification question.

Temuan tipikal: SendInvoiceNow() vs SendInvoice mismatch penamaan, handler memanggil db.QueryRow langsung, mengembalikan err mentah tanpa konteks, dan log berisik seperti log.Printf("sending invoice %v", invoice) yang membuang objek penuh.

Pass kedua meminta perubahan minimal yang aman:

Pass 2 (minimal fix suggestions)
Using the violations list, propose the smallest code edits to comply.
Constraints: keep behavior the same, no refactors beyond what is needed, show suggested function names and where code should move.
For each fix, include 1-2 lines of example code.

Jika melanggar aturan diperbolehkan, nyatakan di depan: “Exceptions are permitted only if you add a short comment explaining why, and you add a follow-up task to remove the exception.”

Setelah perbaikan, handler menjadi adapter tipis, service memegang alur kerja, storage memegang query, error menjadi fmt.Errorf("send invoice: %w", err), dan log menjadi satu baris rapi dengan field yang aman (invoice ID, bukan invoice penuh).

Langkah selanjutnya: jadikan rutin tanpa memperlambat

Pilih satu prompt yang disetujui tim dan perlakukan seperti alat bersama. Mulailah dari apa yang paling sering merepotkan di review (drift penamaan, kebocoran layer, error tidak konsisten, log tidak aman). Perbarui prompt hanya saat Anda melihat pelanggaran nyata di kode nyata.

Simpan blok aturan kecil di bagian atas prompt dan tempelkan di setiap review tanpa diubah. Jika setiap orang mengedit aturan tiap kali, Anda tidak punya standar. Anda punya perdebatan.

Irama sederhana membantu: satu orang mengumpulkan beberapa kesalahan gaya teratas minggu itu, dan Anda menambahkan tepat satu aturan yang lebih jelas atau satu contoh yang lebih baik.

Jika Anda bekerja dalam alur build berbasis chat seperti Koder.ai (koder.ai), ada baiknya menjalankan pemeriksaan gerbang yang sama selama perubahan, bukan hanya di akhir. Fitur seperti planning, snapshot, dan rollback dapat membantu menjaga perbaikan gaya kecil dan dapat dibalik sebelum Anda mengekspor source code.