Anda tidak bisa menekan tombol jeda pada pengembangan. Itulah hal pertama yang harus diterima. Tiket terus berdatangan, pelanggan mengharapkan pengiriman, dan kode Anda yang sudah ada tidak akan berhenti berjalan hanya karena Anda memutuskan untuk mendokumentasikannya. Tidak ada manajer teknik yang akan memberikan lampu hijau untuk pembekuan pengembangan selama sebulan penuh agar tim dapat menulis spesifikasi yang seharusnya sudah ada sejak hari pertama. OpenSpec dibangun untuk realitas, bukan untuk fantasi greenfield. OpenSpec bekerja paling baik saat Anda menerapkannya pada apa yang sudah Anda miliki, lengkap dengan pelanggan Anda.
Tujuannya di sini bukanlah menulis ulang. Ini adalah arkeologi yang jujur. Anda menggali apa yang sebenarnya berjalan di produksi, mendeskripsikannya secara akurat, dan membiarkan deskripsi tersebut berkembang seiring dengan perkembangan kode Anda. Ketika spesifikasi Anda sesuai dengan sistem Anda, Anda mempermudah hidup para engineer yang bergabung di kuartal berikutnya dan alat AI yang kini berada di IDE Anda. Berikut adalah cara melakukannya tanpa melewatkan satu rilis pun.
Mulai dengan Apa yang Benar-benar Anda Lakukan
Buka repositori Anda dan Anda akan melihat folder bernama controllers, models, services, dan utils. Itu adalah lapisan teknis, dan mereka menipu Anda. Mereka tidak mendeskripsikan apa yang dilakukan sistem Anda untuk bisnis. Sebuah folder berisi file JavaScript tidak menjelaskan bagaimana sebuah pesanan menjadi sebuah pengiriman. Untuk menerapkan OpenSpec secara retroaktif, Anda perlu berpikir dalam hal kapabilitas.
Carilah operasi bisnis stabil yang akan tetap bertahan bahkan jika Anda menulis ulang seluruh stack dalam bahasa yang berbeda. Di kebanyakan perusahaan produk, hal ini muncul berulang kali: Orders, Billing, Inventory, Customers, dan Notifications. Sebutkan lima hingga delapan kapabilitas inti ini.
Untuk setiap kapabilitas, paksa diri Anda untuk menjawab lima pertanyaan spesifik. Masalah dunia nyata apa yang diselesaikan oleh kapabilitas ini? Di mana kode tersebut sebenarnya berada—satu layanan, tiga microservices, atau modul legacy yang tidak ingin disentuh siapa pun? Apa yang memicunya: klik pengguna, cron job terjadwal, atau inbound webhook? Data apa yang masuk dan data apa yang keluar? Dan terakhir, sistem lain mana yang bergantung padanya, artinya apa yang akan rusak jika bagian ini berhenti berfungsi?
Bersikaplah jujur apa adanya. Jika kapabilitas "Customers" Anda tersebar di seluruh monolith Rails, API Node, dan CRM eksternal, tuliskan hal itu apa adanya. Peta Anda harus terlihat seperti wilayah aslinya, bukan seperti mimpi seorang arsitek.
Tuliskan Kebenaran, Bukan Daftar Keinginan
Kalimat paling berbahaya dalam upaya dokumentasi apa pun adalah, "Sambil kita menulis ini, sekalian saja kita perbaiki." Berhenti. Anda tidak sedang merancang ulang alur checkout. Anda sedang mendeskripsikan alur checkout yang sedang memproses kartu kredit asli saat ini.
Jika melakukan pemesanan memicu penangkapan pembayaran segera dan kemudian mengirimkan email melalui background worker, dokumentasikan urutan tepat tersebut. Jangan memasukkan antrean event yang berencana Anda tambahkan di kuartal berikutnya. Jangan berpura-pura bahwa validasi terjadi di edge API jika sebenarnya ia berada jauh di dalam sebuah service class. Akurasi jauh lebih penting daripada aspirasi.
Dokumentasi yang salah lebih buruk daripada tidak ada sama sekali. Dokumentasi yang salah melatih karyawan baru untuk mengharapkan perilaku yang tidak ada. Hal ini mengarahkan asisten coding AI ke jalur imajiner berdasarkan angan-angan. Ketika spesifikasi Anda sesuai dengan produksi, Anda menciptakan baseline yang andal. Debugging menjadi lebih cepat karena Anda berhenti menebak-nebak alur yang "dimaksudkan". Refactoring menjadi lebih aman karena Anda tahu titik awalnya adalah nyata.
Ekstrak Kontrak dari API Anda
Endpoint API Anda sudah menegakkan aturan. Mereka hanya menyimpannya secara implisit. Menerapkan OpenSpec berarti menarik aturan-aturan tersebut ke permukaan.
Mulailah dengan input dan validasi. Apa yang sebenarnya diterima oleh endpoint tersebut? Dokumentasikan tipe datanya, kolom yang wajib diisi, panjang maksimum, dan ketergantungan antar-kolom. Kemudian deskripsikan perilaku bisnisnya. Apakah panggilan ini membuat sebuah record, memicu side effect, atau sekadar memvalidasi status terhadap layanan lain? Bersikaplah spesifik.
Terakhir, katalogkan responsnya. Apa yang dikembalikan saat berhasil? Apa kode error tepatnya dan dalam kondisi apa kode tersebut muncul? Jangan menulis "mengembalikan error." Tulislah "mengembalikan 422 saat alamat penagihan hilang dan 409 saat inventaris sudah dipesan oleh proses lain." Tingkat presisi seperti itu mengubah rute yang samar menjadi kontrak yang dapat dipercaya oleh tim frontend, engineer QA, dan alat otomatisasi.
Buru Aturan-Aturan yang Tersembunyi
Sebagian besar pengetahuan paling mahal dalam sistem Anda tersembunyi di celah-celah yang tidak terlihat. Pengetahuan itu terkubur dalam blok kondisional di dalam service classes, terselip di database triggers, atau tertulis dalam stored procedures yang tidak pernah disentuh selama dua tahun. Ini adalah aturan bisnis Anda, dan biasanya baru ditemukan kembali saat terjadi outage atau dengan cara mencecar satu-satunya engineer yang sudah ada sejak awal.
Bawa mereka ke permukaan. Mulailah dengan aturan yang sudah Anda ketahui. Pesanan di atas nilai tertentu memerlukan persetujuan manajer sebelum diproses. Akun pengguna yang tidak aktif tidak dapat membuat pesanan baru. Pengembalian dana (refund) hanya diizinkan sebelum penyelesaian (settlement) selesai. Tulis setiap aturan di samping kapabilitas yang dikelolanya, dalam bahasa yang cukup jelas sehingga seorang product manager dapat membacanya tanpa perlu penerjemah.
Saat Anda memusatkan aturan-aturan ini, Anda melakukan lebih dari sekadar mendokumentasikannya. Anda mengungkap duplikasi. Anda menunjukkan adanya konflik. Dan Anda memberikan satu tempat bagi seluruh tim untuk memperdebatkan kebijakan sebelum seseorang melakukan commit perubahan satu baris yang secara tidak sengaja melanggar batasan (constraint) yang Anda lupakan keberadaannya.
Petakan Alur Sistem
Sistem modern berjalan berdasarkan event. Sebuah tindakan di satu service akan memberikan dampak berantai ke setengah lusin service lainnya sebelum sesuatu yang terlihat sampai ke pengguna. Anda perlu memetakan dampak tersebut. Petakan alur dari satu event ke event berikutnya untuk alur kerja (workflow) inti Anda. Pesanan dibuat (order created) memicu inventaris dipesan (inventory reserved), yang kemudian menunggu pembayaran dikonfirmasi (payment confirmed). Gambarkan rantai lengkapnya, meskipun beberapa tautan terasa rapuh atau menggunakan protokol yang berbeda.
Jangan berhenti pada trafik internal saja. Layanan eksternal adalah bagian dari sistem Anda, terlepas dari apakah Anda menganggapnya demikian atau tidak. Untuk setiap integrasi, catat tujuannya, bagaimana aplikasi Anda melakukan autentikasi, dan bagaimana ia gagal. Apakah payment gateway mengalami timeout setelah tiga puluh detik dan mengembalikan error 500 generik? Apakah API pengiriman mengembalikan JSON yang malformed pada akhir pekan? Apakah identity provider mencabut refresh token lebih cepat daripada yang diklaim dalam dokumentasinya sendiri? Detail-detail ini tampak sepele