“Besok aja deh ditulisnya. Masih inget ini mah.”
Dua minggu kemudian: “Ini siapa sih yang mutusin pakai RabbitMQ?”

Meme dan quotes di atas bisa saja terjadi di organisasi atau tempat kita bekerja. Keputusan teknis penting diambil pada rapat ad-hoc, channel Slack, bahkan di meja pantry. Semuanya terdengar masuk akal at that time, tapi begitu sistem berkembang, ada perombakan tim, resign, atau bahkan di-layoff, kita semua jadi arkeolog dadakan, menggali masa lalu dari commit message dan berandai-andai berasaskan prasangka. Biar nggak terus-terusan jadi Indiana Jones di sistem sendiri, dari situlah muncul konsep bernama Architecture Decision Record (ADR).

ADR pertama kali diperkenalkan oleh Michael Nygard, penulis buku Release It! dan software architect yang sepak terjangnya tidak perlu diragukan lagi. Ide dasarnya sederhana, dokumentasikan keputusan arsitektur dalam format yang ringan, bukan dalam format makalah akademis atau kitab suci. Beliau memperkenalkan konsep ini sekitar tahun 2011 lewat sebuah repositori GitHub.

Format ADR

Karena ADR bukan skripsi, tesis atau disertasi, penulisan ADR harus dibuat seminimalisir mungkin namun tetap berbobot. Michael Nygard menyarankan buat dalam format file .md atau .txt dan simpan pada git. Isinya kurang lebih seperti ini:

• Judul keputusan
• Status (misalnya: proposed, accepted, deprecated)
• Konteks: apa masalah yang dihadapi
• Keputusan: apa yang dipilih dan kenapa
• Konsekuensi: baik positif maupun negatif

Contohnya:

• Judul keputusan: Menyimpan konfigurasi di Git
• Status: Accepted
• Konteks: Tim butuh mekanisme versioning dan kolaborasi untuk konfigurasi
• Keputusan: Simpan file konfigurasi dalam repository Git yang sama dengan aplikasinya
• Konsekuensi: Konfigurasi bisa dilacak per commit, namun perubahan membutuhkan waktu melalui proses deployment pipeline

ADR ada bukan untuk mencari keputusan yang paling benar, namun agar keputusan yang diambil hari ini tetap masuk akal dan bisa dimengerti esok atau lusa, baik oleh orang baru, tim lain, atau diri sendiri yang mudah lupa seiring bertambahnya usia.

Kapan sebaiknya ADR ditulis?

Momen terbaik untuk nulis ADR adalah saat keputusan masih hangat, belum hilang konteksnya, seperti:

• Saat memilih antara dua atau lebih pilihan teknis
• Setelah diskusi teknis berupa pemilihan stack dan arsitektur yang signifikan
• Saat perubahan bisa menimbulkan pertanyaan di masa depan

Perlu diingat. Tidak semua keputusan butuh ADR. Ganti warna tombol? Refactor kecil? Fix typo di log? Enggak usah. Singkatnya, tulislah ADR saat kamu merasa “ini keputusan yang bakal dipertanyakan orang suatu saat nanti.” atau saat kamu sendiri mungkin akan lupa di dua bulan ke depan 🙂