Menulis Spesifikasi yang Baik

Anda jarang menulis spesifikasi dari halaman kosong. Anda mendeskripsikan perubahan dalam bahasa sederhana, /opsx:propose menyusun persyaratan dan skenario, lalu Anda memperbaikinya agar menjadi baik. Halaman ini membahas bagian terakhir tersebut — bagaimana tampilan "yang baik" dan cara mengarahkan AI ke arah sana.

Halaman ini adalah pendamping dari Meninjau Perubahan: peninjauan adalah menemukan titik lemah dalam draf, sedangkan penulisan adalah mengetahui apa saja yang membentuk spesifikasi yang kuat.

Spesifikasi adalah perilaku, bukan kode

Spesifikasi menyatakan apa yang dilakukan sistem Anda, dalam istilah yang dapat diperiksa oleh siapa pun — bukan bagaimana sistem itu dibangun. Spesifikasi terdiri dari persyaratan (pernyataan perilaku) dan skenario (contoh konkret yang membuktikan persyaratan tersebut).

### Persyaratan: Waktu Tunggu Sesi
Sistem HARUS kedaluwarsa sesi setelah 30 menit tidak aktif.

#### Skenario: Waktu tunggu diam
- DIBERIKAN sebuah sesi yang terautentikasi
- JIKA 30 menit berlalu tanpa aktivitas
- MAKA sesi tidak valid dan pengguna harus melakukan autentikasi ulang

Simpan aspek bagaimana — antrian, pustaka, skema tabel — di design.md atau dalam kode. Ketika perilaku dan implementasi dicampur menjadi satu persyaratan, persyaratan tersebut berhenti dapat diuji dan mulai usin begitu kode berubah.

Apa yang membuat persyaratan menjadi baik

Persyaratan yang baik adalah satu perilaku, dinyatakan dengan sangat lugas sehingga Anda bisa menyerahkannya kepada orang lain untuk diuji.

• Satu pernyataan, satu SHALL/MUST. Jika sebuah persyaratan memiliki tiga klausa "dan juga", sebenarnya itu adalah tiga persyaratan. Pisahkanlah.

• Dapat diamati. Seseorang di luar kode harus dapat menentukan apakah persyaratan tersebut terpenuhi. "Sistem HARUS menampilkan banner kesalahan ketika unggahan melebihi 10 MB" dapat diamati. "Sistem HARUS menangani unggahan besar dengan lancar" tidak dapat diamati.

• Kekuatan yang tepat. OpenSpec menggunakan kata kunci RFC 2119, dan masing-masing memiliki makna berbeda:

  Kata Kunci	Makna
  MUST / SHALL	Persyaratan keras. Tidak dapat dinegosiasikan.
  SHOULD	Rekomendasi kuat, dengan ruang untuk pengecualian yang dibenarkan.
  MAY	Benar-benar opsional.

  Gunakan MUST/SHALL sebagai pilihan default. Gunakan SHOULD hanya ketika Anda benar-benar bermaksud "kecuali ada alasan bagus untuk tidak melakukannya."

Uji bagi sebuah persyaratan: bisakah seorang penguji yang belum pernah melihat kode memberitahu apakah persyaratan tersebut lulus? Jika tidak, persyaratan tersebut perlu dipertajamkan.

Apa yang membuat skenario menjadi baik

Skenario adalah tempat di mana sebuah persyaratan membuktikan nilainya. Setiap skenario adalah GIVEN / WHEN / THEN yang konkret yang dapat menjadi uji otomatis.

• Melatih persyaratannya. Skenario yang hanya mengulang persyaratan dengan kata-kata lain tidak menguji apa pun. Jadikan situasi spesifik dengan hasil spesifik.
• Cakup kasus yang penting, bukan hanya jalur sukses. Login yang valid itu mudah. Input kosong, token yang kedaluwarsa, klik kedua, hal-hal yang salah — di situlah bug berada, dan di situlah skenario paling berharga.
• Namai kasusnya dalam judul. "Skenario: Tolak token yang kedaluwarsa" memberi tahu peninjau apa yang dicakup sekilas; "Skenario: Uji 2" tidak.

Kebiasaan yang berguna: sebelum menyetujui, tanyakan kasus apa yang akan membuat saya kesal jika rusak? — dan pastikan ada skenario yang menamainya.

Pilih jenis delta yang tepat

Sebuah perubahan mendeskripsikan suntingannya terhadap spesifikasi dengan tiga jenis bagian. Menggunakan yang tepat menjaga kejujuran spesifikasi yang diarsipkan:

• ## ADDED Requirements — perilaku baru yang sebelumnya tidak ada.
• ## MODIFIED Requirements — perilaku yang sudah ada dan sedang berubah. Sertakan versi baru secara lengkap; catatan singkat tentang apa yang berubah membantu peninjau.
• ## REMOVED Requirements — perilaku yang dihapus, disertai penjelasan alasannya.

Saat pengarsipan, ADDED ditambahkan ke spesifikasi utama, MODIFIED menggantikan versi lama, dan REMOVED dihapus darinya. Hapus persyaratan terakhir dari suatu kemampuan, dan Anda pensiunkan kemampuan tersebut: alih-alih meninggalkan spesifikasi yang kosong, arsip menghapus openspec/specs/<capability>/spec.md. Karena ini adalah satu langkah pengarsipan yang menghapus file, tindakan ini harus diminta secara eksplisit — tambahkan retire_capabilities: true ke .openspec.yaml perubahan tersebut, di samping schema: yang sudah diperlukan oleh file tersebut. Tanpanya, pengarsiban akan dibatalkan dan memberi tahu Anda. Pensiun menghapus seluruh file, sehingga operasi ini juga ditolak jika spesifikasi masih berisi apa pun selain judulnya, ## Purpose, dan blok persyaratannya — seperti bagian ## Notes, atau komentar di bawah sebuah persyaratan. Pembatalan mencantumkan baris-baris tersebut; pindahkan ke ## Purpose atau ke dalam sebuah persyaratan, atau hapus spesifikasi secara manual. Untuk spesifikasi dalam checkout pemanggil, output arsip juga mencantumkan git checkout yang memulihkan file yang telah dikomitmkan; penyimpanan tertentu menerima panduan pemulihan yang terbatas pada cakupan checkout. Jika Anda menandai perubahan nyata sebagai ADDED, Anda berakhir dengan dua persyaratan yang bersaing; jika Anda mendeskripsikan perilaku baru sebagai MODIFIED, tidak ada yang diganti. Jika ragu, buka spesifikasi saat ini dan lihat apakah persyaratannya sudah ada.

Satu bagian lagi yang patut diketahui. Ketika delta Anda menciptakan kemampuan yang belum ada, bukalah dengan ## Purpose — satu atau dua kalimat tentang apa tujuan kemampuan tersebut. Arsip menggunakannya sebagai Tujuan dari spesifikasi utama yang dibuatnya; melewatinya akan menghasilkan placeholder TBD yang harus diisi secara manual. Spesifikasi yang sudah ada memiliki Tujuan, sehingga Tujuan dari delta diabaikan di sana — sunting openspec/specs/<capability-path>/spec.md secara langsung untuk mengubahnya. Di sini, <capability-path> adalah direktori relatif terhadap specs/, seperti user-auth dalam proyek datar atau identity/user-auth dalam proyek yang diatur berdasarkan domain.

Sesuaikan ukuran perubahan

Kesalahan penulisan paling umum bukanlah persyaratan yang ditulis dengan buruk — melainkan perubahan yang mencoba menjadi tiga perubahan sekaligus.

Perubahan yang baik memiliki satu niat yang dapat Anda ungkapkan dalam satu kalimat. "Tambahkan tombol ganti mode gelap." "Batasi laju endpoint login." "Migrasi sesi keluar dari cookie." Jika mendeskripsikan perubahan membutuhkan banyak "dan juga," itu adalah sinyal untuk memisahkannya.

Tanda-tanda perubahan terlalu besar:

• Cakupan proposal terbaca seperti daftar fitur yang tidak terkait.
• Meninjaunya akan memakan waktu setengah hari, sehingga tidak ada yang akan melakukannya.
• Dua orang tidak dapat bekerja padanya tanpa bertabrakan.
• Setengah dari tugas dapat dirilis secara mandiri.

Perubahan yang lebih kecil lebih mudah ditinjau, lebih mudah dibangun dalam satu sesi fokus, dan lebih mudah dipikirkan enam bulan kemudian ketika arsip adalah satu-satunya yang tersisa. Anda selalu dapat menjalankan beberapa perubahan secara paralel — lihat Mengedit & iterasi dan Alur Kerja.

Hal sebaliknya juga terjadi: perbaikan typo satu baris tidak memerlukan tiga persyaratan dan dokumen desain. Sesuaikan upacara dengan tingkat risikonya.

Cara mengarahkan AI menuju draf yang baik

Karena /opsx:propose mengerjakan draf pertama, kualitas apa yang Anda terima mengikuti kualitas apa yang Anda berikan. Anda tidak perlu menulis persyaratan secara manual — Anda harus mengarahkan AI dengan baik:

• Nyatakan niat dan batasnya. "Tambahkan tombol ganti mode gelap yang mengikuti pengaturan OS saat pemuatan pertama — jangan sentuh API tema yang ada." Bagian di luar cakupan sama pentingnya dengan bagian di dalam cakupan.
• Namai kasus yang Anda pedulikan. "Pastikan ada skenario untuk pengguna yang sudah memilih tema secara manual." AI mencakup apa yang Anda tunjuk.
• Lalu edit. Itu adalah Markdown biasa. Ketatkan SHALL yang samar, hapus skenario yang tidak menguji apa pun, tambahkan kasus yang terlewat — atau minta AI untuk melakukannya: "persyaratan waktu tunggu bersifat samar, tetapkan pada 30 menit."

Buat draf, tajamkan, ulangi. Beberapa putaran dari proses itu menghasilkan spesifikasi yang Anda percayai, yang merupakan tujuan utamanya.

Daftar periksa cepat

• Setiap persyaratan adalah satu perilaku yang dapat diamati dengan SHALL/MUST.
• Tidak ada detail implementasi yang tertanam dalam persyaratan.
• Setiap persyaratan memiliki setidaknya satu skenario yang benar-benar melatihnya.
• Kasus tepi dan kesalahan yang penting memiliki skenario, bukan hanya jalur sukses.
• Delta menggunakan ADDED / MODIFIED / REMOVED dengan benar terhadap spesifikasi saat ini.
• Seluruh perubahan memiliki satu niat yang dapat Anda nyatakan dalam satu kalimat.

Langkah selanjutnya

• Meninjau Perubahan — tinjauan cepat dua menit yang menangkap apa yang lolos.
• Konsep — model yang lebih mendalam di balik spesifikasi, perubahan, dan delta.
• Contoh & Resep — perubahan nyata dari awal hingga akhir.