Wawancara Siri AI 16: Bagaimanakah spec coding yang baik?

Spec Coding yang baik (pengaturcaraan berasaskan spesifikasi) berfokus pada mengubah "idea kabur" menjadi "kontrak yang tepat, boleh disahkan, dan boleh dilaksana". Ia bukan sekadar menulis dokumen, tetapi membina bahasa komunikasi tanpa kekaburan antara manusia dan AI (atau antara manusia). Di bawah, saya akan memberikan gambaran spec yang baik dari empat dimensi: struktur kandungan spesifikasi, prinsip penulisan, aliran kerjasama dengan AI, dan pengesahan kualiti.

Satu: Struktur Piawai Dokumen Spesifikasi (Contoh Modul Fungsi)

Bahagian	Kandungan Wajib	Contoh
1. Matlamat & Skop	Satu ayat terangkan apa yang dilakukan, nyatakan apa yang tidak dilakukan	"Membangunkan API pendaftaran pengguna, tidak termasuk pengesahan e-mel"
2. Kontrak Input/Output	Struktur data, jenis, medan wajib/pilihan, nilai contoh	`POST /register` body permintaan `{email: string, password: string}`, respon `201` atau `400` dengan kod ralat
3. Tingkah Laku & Logik	Peraturan perniagaan, keadaan sempadan, perubahan keadaan	"Panjang kata laluan 8-20 aksara, mesti mengandungi sekurang-kurangnya satu digit; e-mel sudah wujud → pulangkan `409`"
4. Pengendalian Ralat	Semua senario luar biasa yang mungkin serta kod/ mesej ralat yang sepadan	"Sambungan pangkalan data gagal → pulangkan `503`, jangan dedahkan timbunan"
5. Keperluan Bukan Fungsian	Prestasi (masa respon < 200ms), keselamatan (pertanyaan berparameter), log, kebolehcerapan	"Semua SQL mesti menggunakan prapenyusunan; catat `email` tetapi jangan catat `password`"
6. Kes Ujian (Penting)	Sekurang-kurangnya 3 input tipikal + 2 input sempadan/luar biasa, berikan output jangkaan	Lihat jadual di bawah
7. Kebergantungan & Kekangan	Perpustakaan apa digunakan, versi, pembolehubah persekitaran	"Python 3.10+, FastAPI, pembolehubah persekitaran `DB_URL`"

Contoh Kes Ujian (Disisipkan dalam spec)

Senario	Input	Output Jangkaan
Pendaftaran biasa	e-mel: `a@b.com`, pwd: `Pass1234`	`201`, pulangkan `user_id`
Kata laluan terlalu pendek	pwd: `Ab1`	`400`, kod ralat `WEAK_PASSWORD`
E-mel sudah wujud	e-mel sama seperti di atas	`409`, kod ralat `EMAIL_EXISTS`

Spec yang baik mesti menulis kes ujian terlebih dahulu, kerana AI boleh menjana ujian unit secara langsung daripadanya, dan mengesahkan secara automatik selepas selesai.

Dua: Prinsip Teras Penulisan Spec (Varian SMART)

Prinsip	Penjelasan	Contoh Buruk
Tepat (Precise)	Gunakan nombor, jenis, keadaan boolean yang spesifik, elakkan "seboleh mungkin", "biasanya"	❌ "Kata laluan mesti cukup selamat" → ✅ "Kata laluan sekurang-kurangnya 8 aksara, mengandungi huruf besar, huruf kecil, digit"
Boleh Disahkan (Verifiable)	Setiap keperluan boleh dinilai lulus/gagal melalui ujian automatik atau pemeriksaan manual	❌ "Kod mesti elegan" → ✅ "Kompleksiti bulatan fungsi ≤ 10, tiada blok kod berulang"
Tanpa Kekaburan (Unambiguous)	Istilah yang sama digunakan dengan makna yang konsisten sepanjang dokumen, beri glosari jika perlu	❌ "Jika pengguna tidak wujud, pulangkan ralat" → ✅ "Pengguna tidak wujud → pulangkan `404` dan `{code: 'USER_NOT_FOUND'}""
Lengkap (Complete)	Merangkumi laluan gembira, semua laluan luar biasa, keperluan bukan fungsian	❌ Hanya menulis senario berjaya → ✅ Termasuk tamat masa pangkalan data, kebenaran tidak mencukupi, dll.
Atomik (Atomic)	Satu spec hanya menerangkan satu titik fungsi yang boleh dihantar secara bebas (memudahkan AI selesaikan sekali gus)	❌ Gunakan satu spec untuk menulis "keseluruhan sistem pembayaran" → ✅ Pecah kepada "jana pesanan pembayaran", "pengesahan tandatangan panggil balik", "bayaran balik"

Tiga: Aliran Spec Coding dalam Kerjasama dengan AI

Manusia menulis spec (struktur di atas, terutamanya kes ujian dan tandatangan fungsi).
Beri spec sekali gus kepada AI (jangan tambah keperluan secara dialog untuk elakkan pencemaran vibe).
AI output kod + ujian unit (AI mesti menjana ujian yang boleh dilaksana berdasarkan kes ujian dalam spec).
Jalankan ujian: Jika semua lulus, terus ke langkah seterusnya; jika tidak, ubah spec atau betulkan kod terus (boleh masuk gelung kecil, tetapi catat perubahan).
Semakan manusia: Periksa sama ada terdapat fungsi di luar spec (scope creep), periksa keselamatan/prestasi.
Kukuhkan: Hantar dokumen spec dan kod akhir bersama ke repositori sebagai dokumentasi kekal.

Amalan Penting: Spec dikodkan — gunakan spec.md + test_spec.py, di mana fail ujian datang terus daripada contoh dalam spec, supaya apabila kod diubah kemudian, hanya perlu jalankan ujian untuk mengesahkan spec tidak rosak.

Empat: Kesan Spec yang Baik (Boleh Digunakan sebagai Kriteria Penerimaan)

Kepastian: Spec yang sama diberikan kepada AI berbeza (atau orang berbeza) menghasilkan pelaksanaan yang serupa.
Kebolehujian: Selepas kod selesai, 90% ketepatan boleh disahkan secara automatik dengan segera.
Kebolehselenggaraan: Enam bulan kemudian, sesiapa yang melihat spec dapat memahami niat reka bentuk asal.
Kos Komunikasi Rendah: Semasa perbincangan pasukan, hanya bincang spec, bukan baris kod tertentu.
Keselamatan/Kualiti Terbina dalam: Keperluan keselamatan (seperti pertanyaan berparameter) dan keadaan sempadan dinyatakan dalam spec, AI mesti mematuhinya.

Lima: Contoh Spec yang Baik (Versi Ringkas)

# Spec: API Pendaftaran Pengguna

## Skop
- Menerima e-mel, kata laluan
- Tidak menghantar e-mel pengesahan, tidak memeriksa kesahihan e-mel

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

## Tingkah Laku
- E-mel mesti mematuhi format asas RFC 5322 (a@b.c)
- Kata laluan: panjang 8-20, mesti mengandungi sekurang-kurangnya satu digit dan satu huruf besar
- Gunakan bcrypt untuk penyimpanan dienkripsi, kos garam 10
- Jika sebelum menyimpan ke pangkalan data didapati e-mel sudah wujud → 409

## Kes Ujian (input -> kod status jangkaan+medan respon)
| Input e-mel | kata laluan | Jangkaan |
|------------|----------|----------|
| test@x.com | Pass1234  | 201, user_id wujud |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (e-mel sudah wujud) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## Bukan Fungsian
- SQL mesti menggunakan pertanyaan berparameter (cegah suntikan)
- Log catat IP sumber pendaftaran, jangan catat kata laluan
- Masa respon 95% permintaan < 100ms (tidak termasuk bcrypt)

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

Spec Coding yang baik = mengubah "keputusan reka bentuk" manusia menjadi "kes ujian + tandatangan jenis + kekangan tingkah laku" mesin, membolehkan AI hanya mengisi pelaksanaan, manakala manusia sentiasa mengawal kualiti dan hala tuju.