Prompt Patterns

Instruksi ke agent bukan lagi "prompt engineering" gaya 2023 (mantra ajaib, role-play berlebihan). Yang menentukan hasil adalah kejelasan spesifikasi dan verifikasi — persis seperti mendelegasikan ke engineer baru yang sangat cepat tapi belum kenal repomu.

Pola yang terbukti efektif

1. Plan-first

Untuk task non-trivial, minta rencana dulu sebelum eksekusi. Semua agent CLI modern punya plan mode bawaan.

❌ Langsung eksekusi

Migrasi semua endpoint dari Express ke Fastify.

✅ Plan-first

Pelajari struktur apps/api, lalu buat rencana migrasi Express → Fastify:
urutan file, risiko, dan cara memverifikasi tiap tahap. Jangan ubah
apa pun sebelum aku setujui rencananya.

Biaya me-review rencana: 2 menit. Biaya me-review 40 file yang berubah ke arah yang salah: satu sore.

2. Definition of done eksplisit

Sebutkan bukti selesai yang bisa diperiksa mesin — bukan "tolong perbaiki".

✅ Definition of done

Perbaiki bug #142 (upload avatar gagal untuk file >2MB).
Selesai artinya:
1. Ada test yang mereproduksi bug ini dan sekarang hijau.
2. `pnpm test` dan `pnpm check` lolos semua.
3. Tidak ada perubahan di luar modul upload.

3. Checkpoint kecil

Pecah pekerjaan besar menjadi tahap yang masing-masing bisa diverifikasi dan di-commit. Batas kerusakan = satu checkpoint, bukan seluruh task.

✅ Checkpoint kecil

Kerjakan bertahap, commit tiap tahap selesai dan test hijau:
1. Ekstrak logika kalkulasi pace ke packages/shared (test lama tetap hijau).
2. Tambah dukungan satuan mil (dengan test baru).
3. Update UI settings untuk pilihan satuan.
Berhenti dan lapor kalau ada tahap yang gagal — jangan lanjut menumpuk.

4. Instruksi verifikasi ("tunjukkan buktinya")

Suruh agent membuktikan klaimnya dengan menjalankan sesuatu — bukan sekadar menyatakan berhasil.

✅ Verifikasi

Setelah selesai, jalankan `pnpm test` dan tempelkan ringkasan hasilnya.
Lalu jalankan servernya dan curl endpoint baru — tunjukkan respons aslinya.

5. Beri konteks "kenapa", bukan hanya "apa"

Agent yang tahu tujuan bisa mengambil keputusan kecil dengan benar tanpa bolak-balik bertanya.

✅ Dengan kenapa

Tambahkan rate limiting di endpoint /api/register. Konteks: kita kena
serangan bot signup semalam (±50 req/detik dari IP berganti-ganti).
Prioritaskan solusi yang tidak menghukum user di belakang NAT kampus.

6. Sebutkan file/anchor spesifik

Setiap path yang kamu sebutkan menghemat satu putaran eksplorasi.

✅ Dengan anchor

Ikuti pola handler yang sudah ada di apps/api/src/routes/activities.ts
untuk membuat route baru /api/plans. Validasi pakai skema Zod seperti
di packages/shared/schemas/.

7. Sediakan jalur eskalasi

Beri tahu agent kapan harus berhenti dan bertanya — supaya dia tidak "kreatif" saat menabrak dinding.

✅ Jalur eskalasi

Kalau ternyata butuh mengubah skema DB, berhenti dan tanya dulu.
Kalau ada test lama yang gagal karena memang testnya salah, jangan
hapus — tandai dan laporkan.

Anti-pattern

Anti-pattern	Kenapa gagal	Perbaikan
Instruksi kabur — "tolong rapikan kodenya"	"Rapi" tidak terdefinisi; agent mereformat 80 file dan diff-nya tak bisa di-review	Sebutkan target dan batasnya: "ekstrak duplikasi di 3 file ini, jangan sentuh yang lain"
Task raksasa — "buatkan seluruh aplikasinya"	Melebihi horizon kerja andal agent; hasilnya setengah jadi dan saling tidak konsisten	Pecah per fitur vertikal, tiap potongan punya definition of done
"Fix everything" — "perbaiki semua error"	Agent menyembunyikan gejala (skip test, silence error) demi mencapai "nol error"	Satu bug = satu task dengan reproduksi jelas
Melanjutkan sesi keracunan	Sesi yang sudah 3x salah arah membawa konteks salahnya terus	Mulai sesi baru dengan instruksi yang diperbaiki; pindahkan pelajaran ke AGENTS.md
Koreksi berulang hal yang sama	Kamu jadi linter manusia	Setiap koreksi kedua kalinya = tambahkan aturannya ke AGENTS.md
Percaya klaim tanpa bukti	"Sudah kuperbaiki dan semua test lolos" kadang halusinasi	Selalu minta output test/run asli (pola #4)

Aturan ibu jari

Kalau instruksimu tidak cukup jelas untuk engineer manusia baru di hari pertamanya, instruksi itu tidak cukup jelas untuk agent.

Bedanya: engineer manusia akan bertanya; agent (secara default) akan menebak. Semua pola di atas pada dasarnya satu hal — mengganti tebakan dengan spesifikasi dan verifikasi.