Wawancara Seri AI 16: Seperti Apa Spec Coding yang Baik?

Spec Coding yang baik (pemrograman berbasis spesifikasi) intinya adalah mengubah 'pikiran kabur' menjadi kontrak yang tepat, dapat diverifikasi, dan dapat dieksekusi. Ini bukan hanya menulis dokumen, tetapi membangun bahasa komunikasi yang tidak ambigu antara manusia dan AI (atau antarmanusia). Berikut ini saya akan memberikan gambaran spec yang baik dari empat dimensi: struktur konten spesifikasi, prinsip penulisan, alur kolaborasi dengan AI, dan verifikasi kualitas.

1. Struktur Standar Dokumen Spesifikasi (dengan modul fungsi sebagai contoh)

Bab	Konten Wajib	Contoh
1. Tujuan dan Ruang Lingkup	Jelaskan apa yang dilakukan dalam satu kalimat, jelaskan apa yang tidak dilakukan	"Mengimplementasikan API pendaftaran pengguna, tidak termasuk verifikasi email"
2. Kontrak Input/Output	Struktur data, tipe, field wajib/opsional, nilai contoh	`POST /register` body permintaan `{email: string, password: string}`, respons `201` atau `400` dengan kode kesalahan
3. Perilaku dan Logika	Aturan bisnis, kondisi batas, transisi status	"Panjang password 8-20 karakter, minimal satu angka; jika email sudah ada, kembalikan `409`"
4. Penanganan Error	Semua skenario pengecualian yang mungkin dan kode/pesan kesalahan yang sesuai	"Koneksi basis data gagal → kembalikan `503`, jangan ekspos stack trace"
5. Persyaratan Non-fungsional	Kinerja (waktu respons < 200ms), keamanan (query parameter), log, observabilitas	"Semua SQL harus menggunakan prepared statement; catat `email` tetapi jangan catat `password`"
6. Kasus Uji (Kunci)	Setidaknya 3 input tipikal + 2 input batas/pengecualian, berikan output yang diharapkan	Lihat tabel di bawah
7. Ketergantungan dan Batasan	Pustaka, versi, variabel lingkungan yang digunakan	"Python 3.10+, FastAPI, variabel lingkungan `DB_URL`"

Contoh Kasus Uji (tertanam dalam spec)

Skenario	Input	Output yang Diharapkan
Pendaftaran normal	email: `a@b.com`, pwd: `Pass1234`	`201`, kembalikan `user_id`
Password terlalu pendek	pwd: `Ab1`	`400`, kode kesalahan `WEAK_PASSWORD`
Email sudah ada	email yang sama	`409`, kode kesalahan `EMAIL_EXISTS`

Spec yang baik harus menulis kasus uji terlebih dahulu, karena AI dapat langsung menghasilkan uji unit berdasarkan kasus tersebut dan memverifikasinya secara otomatis setelah selesai.

2. Prinsip Inti Penulisan Spec (varian SMART)

Prinsip	Penjelasan	Contoh Buruk
Tepat (Precise)	Gunakan angka, tipe, kondisi boolean yang spesifik, hindari "sebisa mungkin", "biasanya"	❌ "Password harus cukup aman" → ✅ "Password minimal 8 karakter, mengandung huruf besar, huruf kecil, angka"
Dapat Diverifikasi (Verifiable)	Setiap persyaratan dapat dinilai lulus/gagal melalui pengujian otomatis atau pemeriksaan manual	❌ "Kode harus elegan" → ✅ "Kompleksitas siklomatik fungsi ≤ 10, tidak ada blok kode duplikat"
Tidak Ambigu (Unambiguous)	Istilah yang sama memiliki arti yang konsisten di seluruh teks, berikan glossary jika perlu	❌ "Jika pengguna tidak ada, kembalikan error" → ✅ "Pengguna tidak ada → kembalikan `404` dengan `{code: 'USER_NOT_FOUND'}`"
Lengkap (Complete)	Mencakup happy path, semua jalur pengecualian, persyaratan non-fungsional	❌ Hanya menulis skenario sukses → ✅ Termasuk batas waktu basis data, izin tidak mencukupi, dll.
Atomik (Atomic)	Satu spec hanya mendeskripsikan satu fitur yang dapat dikirim secara independen (memudahkan AI menyelesaikan dalam satu langkah)	❌ Menggunakan satu spec untuk menulis "seluruh sistem pembayaran" → ✅ Dipecah menjadi "buat pesanan pembayaran", "verifikasi tanda tangan callback", "pengembalian dana"

3. Alur Spec Coding saat Berkolaborasi dengan AI

Manusia menulis spec (struktur di atas, terutama menulis kasus uji dan tanda tangan fungsi).
Beri spec sekaligus ke AI (jangan tambahkan kebutuhan secara dialog, hindari 'vibe pollution').
AI menghasilkan kode + uji unit (AI harus menghasilkan pengujian yang dapat dieksekusi sesuai dengan kasus uji dalam spec).
Jalankan tes: Jika semua lulus, lanjut ke langkah berikutnya; jika tidak, ubah spec atau perbaiki kode langsung (pada titik ini dapat masuk ke siklus kecil, tetapi catat perubahannya).
Tinjauan manual: Periksa apakah ada fungsi di luar spec (scope creep), periksa keamanan/kinerja.
Pembekuan: Kirim dokumen spec dan kode akhir bersama ke repositori sebagai dokumentasi permanen.

Praktik Kunci: Spec menjadi kode — gunakan spec.md + test_spec.py, di mana file tes langsung berasal dari contoh dalam spec, sehingga saat mengubah kode di masa mendatang, cukup jalankan tes untuk memverifikasi apakah spec rusak.

4. Efek dari Spec yang Baik (dapat digunakan sebagai kriteria penerimaan)

Determinisme: Spec yang sama diberikan ke AI (atau orang) berbeda menghasilkan implementasi yang serupa.
Testabilitas: Setelah kode selesai, 90% kebenaran dapat diverifikasi secara otomatis segera.
Maintainabilitas: Setengah tahun kemudian, siapa pun yang melihat spec dapat memahami maksud desain awal.
Biaya komunikasi rendah: Diskusi tim hanya fokus pada spec, bukan pada baris kode spesifik.
Keamanan/kualitas built-in: Persyaratan keamanan (seperti query parameter) dan kondisi batas ditulis dalam spec, AI harus mematuhinya.

5. Contoh Spec yang Baik (versi sangat sederhana)

# Spec: API Pendaftaran Pengguna

## Ruang Lingkup
- Menerima email, password
- Tidak mengirim email verifikasi, tidak memeriksa keaslian email

## Kontrak
POST /register
Content-Type: application/json
Request: { "email": string, "password": string }
Response 201: { "user_id": string }
Response 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Response 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Perilaku
- email harus memenuhi format dasar RFC 5322 (a@b.c)
- password: panjang 8-20, setidaknya berisi satu angka dan satu huruf kapital
- Simpan dengan enkripsi bcrypt, biaya garam 10
- Jika ditemukan email sudah ada sebelum menyimpan ke basis data → 409

## Kasus Uji (Input -> Kode Status + Field Respons yang Diharapkan)
| Input email | password | Harapan |
|-------------|----------|---------|
| test@x.com | Pass1234 | 201, user_id ada |
| test@x.com | pass | 400, INVALID_PASSWORD |
| bad | Pass1234 | 400, INVALID_EMAIL |
| (email sudah ada) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Non-fungsional
- SQL harus menggunakan parameterized query (cegah injeksi)
- Log mencatat IP asal pendaftaran, tidak mencatat password
- Waktu respons 95% permintaan < 100ms (tidak termasuk bcrypt)

## Ketergantungan
- Python 3.10+, FastAPI, bcrypt, asyncpg

Spec Coding yang baik = menulis 'keputusan desain' manusia menjadi 'kasus uji + tanda tangan tipe + batasan perilaku' mesin, sehingga AI hanya bertanggung jawab untuk mengisi implementasi, sementara manusia selalu mengendalikan kualitas dan arah.