Spesifikasi Tereksekusi: Arsip Keputusan, Bukan Sampah
Spesifikasi yang sudah dieksekusi adalah catatan keputusan: pindahkan ke arsip sebagai perubahan status, jaga imutabilitas ala ADR.
Pohon dokumen di sebuah project portal terlihat sesak. Spesifikasi yang sudah selesai dieksekusi masih bercampur dengan dokumen yang sedang dikerjakan. Mencari dokumen hidup jadi lambat, dan referensi silang antarspesifikasi mudah keliru.
Reaksi pertama yang umum: pemindahan berkas lama hanyalah housekeeping. Tujuannya sekadar merapikan direktori, atau lebih hemat lagi, riwayat yang dianggap basi cukup dihapus begitu saja.
Fungsi Sebenarnya: Catatan Keputusan
Cara pandang itu melewatkan fungsi fundamental dokumen tersebut. Spesifikasi yang sudah dieksekusi adalah catatan keputusan. Ia menjelaskan mengapa sistem berbentuk sekarang, alternatif mana yang ditolak, dan trade-off apa yang diterima saat itu. Memindahkannya ke folder arsip bukan pembuangan, melainkan perubahan status formal dari aktif menjadi historis.
Risikonya nyata di dua arah. Spesifikasi lama yang tertinggal di direktori aktif sering dibaca pengembang baru sebagai panduan terkini, dan implementasi yang mengikuti jadi tidak konsisten. Sebaliknya, arsip yang dihapus menghilangkan jejak rasionalisasi. Tim terpaksa menebak alasan di balik konfigurasi yang sudah berjalan.
Contoh yang sering terjadi: satu spesifikasi menetapkan format slug tertentu pada batas API. Setahun kemudian keputusan itu dicabut karena laporan bug. Tanpa arsip, pengembang yang membaca spesifikasi lama akan membangun fitur baru dengan aturan yang sudah tidak berlaku, lalu menghabiskan satu sesi debugging untuk menemukan bahwa dia mengikuti dokumen yang salah.
Folder arsip menyelesaikan kedua masalah itu sekaligus. Dokumen tidak hilang, tetapi statusnya jelas terpisah dari dokumen hidup. Siapa pun yang membaca arsip tahu ia sedang membaca sejarah, bukan instruksi terkini.
Doktrin Architecture Decision Record memberi kerangka yang pas untuk perpindahan status ini. Panduan AWS menegaskan sebuah ADR yang telah diterima bersifat immutable; kalau wawasan baru menuntut keputusan berbeda, tim menyusun ADR baru dan ADR baru itulah yang menyatakan menggantikan yang lama [7].
Azure Well-Architected Framework memperkuat dengan prinsip append-only log: jangan mengedit catatan yang sudah diterima. Tulis catatan baru yang menyatakan supersede, lalu tautkan keduanya agar sejarah alur pikir tetap terbaca dan terlihat kapan arah berubah [8].
Penerapannya di level berkas sederhana. Dokumen aktif tinggal di folder rencana, dokumen yang sudah dieksekusi pindah ke folder arsip, dan setiap spesifikasi pengganti menyebutkan dokumen arsip mana yang digantikannya beserta tautannya. Riwayat utuh, status terkini selalu jelas.
Prinsip imutabilitas ini juga yang membuat arsip aman dari kebingungan versi. Karena dokumen arsip tidak pernah diedit, pembaca tidak perlu memeriksa riwayat revisi untuk tahu isi dokumen itu saat keputusannya dibuat. Satu berkas, satu keadaan, tanpa kemungkinan isi berubah diam-diam di belakang tautan yang sudah disebar ke tempat lain.
Dua Kriteria Pindah ke Arsip
Satu praktik pembantu yang memperlancar pemisahan ini adalah tinjauan direktori aktif secara berkala, misalnya tiap akhir sprint: tanyakan untuk setiap spesifikasi apakah ia masih memandu pekerjaan berjalan. Dokumen yang sudah menjawab satu implementasi biasanya langsung terlihat janggal di antara dokumen hidup, dan pemindahannya ke arsip tidak perlu menunggu besarnya tumpukan. Kebiasaan ringan ini mencegah pohon dokumen mencapai titik sesak seperti yang memicu perpindahan di awal cerita.
Ambang pemisahannya harus objektif, bukan perasaan. Dua kondisi menentukan. Pertama, implementasi spesifikasi itu selesai dan berjalan. Kedua, tidak ada rencana modifikasi aktif terhadap dokumen itu pada siklus pengembangan berjalan.Kriteria kedua sama pentingnya dengan yang pertama. Spesifikasi yang sudah dieksekusi tetapi masih menjadi sasaran revisi berikutnya sebaiknya tetap di folder aktif; perpindahannya menunggu sampai gelombang revisi reda. Dengan begitu folder arsip benar-benar hanya berisi dokumen yang sudah stabil, dan status arsip tidak pernah menyesatkan.
Eksekusi perpindahannya sendiri bisa seringan memindahkan berkas ke folder arsip dalam satu commit, asalkan pesan commit menyebut daftar dokumen yang berubah status. Tim dengan kebutuhan audit lebih ketat menambahkan satu baris status di kepala dokumen, misalnya menandai arsip sebagai superseded oleh dokumen tertentu, mengikuti pola ADR yang sama.
Kedua kondisi terpenuhi berarti dokumen berubah peran menjadi referensi historis. Membiarkannya di direktori aktif hanya menambah kebisingan. Arsip bukan tempat pembuangan akhir, melainkan rak referensi yang menjamin setiap keputusan sistem bisa dilacak sampai ke akar logikanya.