Menulis Sejarah Keputusan Teknis Anda: Pengenalan Architectural Decision Records (ADRs)

1. Pendahuluan

Pernahkah Anda bergabung dengan proyek baru dan bertanya-tanya, “Mengapa mereka memilih teknologi X ini, bukan Y?” Atau, setelah beberapa bulan, Anda sendiri lupa alasan di balik keputusan arsitektural penting yang Anda buat? 🤷‍♂️ Ini adalah masalah umum di banyak tim pengembangan. Seiring berjalannya waktu, konteks keputusan bisa hilang, developer baru kesulitan memahami “warisan” kode, dan bahkan tim inti bisa terjebak dalam diskusi berulang tentang hal yang sudah diputuskan.

Dalam dunia web development yang serba cepat, di mana tumpukan teknologi dan pola arsitektur terus berkembang, membuat keputusan teknis yang tepat adalah krusial. Namun, yang tidak kalah penting adalah mendokumentasikan keputusan tersebut. Di sinilah Architectural Decision Records (ADRs) berperan.

ADRs adalah dokumen singkat yang mencatat keputusan arsitektural yang signifikan, konteksnya, pilihan yang dipertimbangkan, dan alasannya. Mereka berfungsi sebagai “sejarah” keputusan teknis proyek Anda, membantu tim menjaga konsistensi, mempercepat onboarding, dan menghindari mengulang kesalahan atau diskusi yang sama.

Artikel ini akan membawa Anda menyelami dunia ADRs: apa itu, mengapa sangat penting, bagaimana strukturnya, dan praktik terbaik untuk mengimplementasikannya di tim Anda. Mari kita mulai menulis sejarah keputusan teknis Anda! 🚀

2. Apa Itu Architectural Decision Record (ADR)?

Secara sederhana, Architectural Decision Record (ADR) adalah dokumen yang mencatat satu keputusan arsitektural yang signifikan. ADR menjawab pertanyaan fundamental: mengapa keputusan tertentu dibuat, bukan hanya apa keputusannya.

Bayangkan ADR sebagai “log commit” untuk keputusan arsitektur. Sama seperti Anda mencatat perubahan kode dan alasannya di Git, ADR mencatat perubahan atau penambahan pada arsitektur sistem Anda. Setiap ADR fokus pada satu keputusan, memberikan gambaran lengkap tentang:

Konteks: Masalah atau tantangan apa yang ingin dipecahkan? Apa batasan atau tujuan yang relevan?
Keputusan: Pilihan spesifik apa yang diambil?
Konsekuensi: Apa dampak positif dan negatif dari keputusan ini?
Alternatif: Pilihan lain apa yang dipertimbangkan dan mengapa ditolak?

📌 Intinya: ADR bukan tentang mendokumentasikan setiap detail teknis. Ini tentang mendokumentasikan keputusan yang signifikan dan memiliki dampak jangka panjang pada struktur, perilaku, dan evolusi sistem Anda.

Misalnya, memilih framework frontend (React vs Vue), jenis database (SQL vs NoSQL), strategi deployment (monolit vs microservices), atau pola komunikasi antar layanan (REST vs gRPC) adalah contoh keputusan yang ideal untuk ADR.

3. Mengapa ADR Penting untuk Tim Anda?

Mungkin Anda berpikir, “Bukankah dokumentasi itu merepotkan dan sering usang?” Betul, tapi ADR dirancang untuk menjadi lean dan living documentation yang memberikan nilai besar dengan usaha yang relatif kecil. Berikut beberapa alasan mengapa ADR sangat penting:

✅ 3.1. Konsistensi & Kohesi Arsitektur

Tanpa catatan yang jelas, arsitektur sistem bisa “drift” seiring waktu. Developer yang berbeda mungkin membuat keputusan yang bertentangan atau tidak selaras dengan visi awal. ADR memastikan semua orang memiliki pemahaman yang sama tentang prinsip dan keputusan inti, menjaga arsitektur tetap kohesif.

✅ 3.2. Mempercepat Onboarding Developer Baru

Bayangkan developer baru bergabung dengan proyek Anda. Alih-alih harus menggali kode atau bertanya kepada anggota tim satu per satu, mereka bisa membaca ADRs untuk memahami sejarah dan alasan di balik struktur sistem. Ini sangat mempercepat proses adaptasi dan membuat mereka lebih produktif lebih cepat.

✅ 3.3. Auditabilitas & Akuntabilitas

ADRs menyediakan jejak rekam keputusan. Jika ada masalah di kemudian hari, tim dapat melihat kembali ADR untuk memahami konteks dan alasan di balik keputusan yang mungkin berkontribusi pada masalah tersebut. Ini juga mendorong akuntabilitas dalam pengambilan keputusan.

✅ 3.4. Menghindari Mengulang Diskusi yang Sama

Seringkali, tim menghabiskan waktu berharga untuk mendiskusikan kembali hal yang sama. Dengan ADR, Anda memiliki referensi yang jelas. Jika ada yang mengusulkan kembali solusi yang pernah ditolak, Anda bisa merujuk ke ADR terkait yang menjelaskan mengapa opsi tersebut tidak dipilih sebelumnya.

✅ 3.5. Memfasilitasi Diskusi yang Lebih Baik

Proses menulis ADR itu sendiri mendorong tim untuk berpikir lebih kritis tentang keputusan yang akan diambil. Ini memaksa Anda untuk mengartikulasikan masalah, mempertimbangkan alternatif, dan menganalisis konsekuensinya secara objektif, yang mengarah pada keputusan yang lebih matang.

✅ 3.6. Sebagai Sumber Kebenaran (Source of Truth)

ADR menjadi sumber kebenaran tunggal untuk keputusan arsitektural. Ketika ada keraguan atau perdebatan, ADR adalah tempat pertama untuk mencari jawaban. Ini mengurangi ambiguitas dan spekulasi.

4. Struktur Dasar Sebuah ADR

ADR umumnya berbentuk sederhana, seringkali dalam format Markdown, dan disimpan bersama kode proyek di sistem kontrol versi. Berikut adalah struktur dasar yang banyak digunakan, berdasarkan format dari Michael Nygard:

# [Nomor] [Judul Keputusan]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Tanggal
[YYYY-MM-DD]

## Deciders
[Nama-nama individu atau tim yang terlibat dalam keputusan]

## Konteks
[Jelaskan masalah atau tantangan yang perlu dipecahkan.
Apa situasi saat ini?
Apa batasan-batasan yang ada?
Apa tujuan yang ingin dicapai dengan keputusan ini?
Gunakan poin-poin atau paragraf singkat.]

## Keputusan
[Nyatakan keputusan yang diambil secara jelas dan ringkas.
Misalnya: "Kami akan menggunakan teknologi X untuk Y."]

## Konsekuensi
### Positif
*   [Dampak positif dari keputusan ini.]
*   [Dampak positif lainnya.]
### Negatif
*   [Dampak negatif atau trade-off dari keputusan ini.]
*   [Dampak negatif lainnya.]

## Alternatif yang Dipertimbangkan (Opsional, tapi Sangat Direkomendasikan)
*   **[Alternatif A]**: [Alasan mengapa alternatif ini tidak dipilih atau memiliki kekurangan.]
*   **[Alternatif B]**: [Alasan mengapa alternatif ini tidak dipilih atau memiliki kekurangan.]

💡 Tips: Gunakan nomor urut untuk setiap ADR (misalnya, 0001-memilih-database-utama.md) agar mudah diatur dan direferensikan.

5. Contoh Konkret ADR: Memilih Database untuk Microservice Baru

Mari kita buat contoh ADR untuk skenario umum: memilih jenis database untuk microservice baru.

# 0005. Memilih Database untuk Microservice Manajemen Pengguna

## Status
Accepted

## Tanggal
2023-10-27

## Deciders
Tim Backend, Lead Arsitek

## Konteks
Microservice "Manajemen Pengguna" yang baru akan dibangun. Microservice ini bertanggung jawab untuk menyimpan dan mengelola data pengguna (nama, email, password hash, peran, dll.). Data ini bersifat relasional, membutuhkan integritas data yang tinggi, dan akan sering diakses dengan query berdasarkan ID pengguna atau email. Skalabilitas horizontal akan menjadi pertimbangan di masa depan, tetapi prioritas utama saat ini adalah konsistensi data dan kemudahan pengelolaan transaksi.

## Keputusan
Kami memutuskan untuk menggunakan **PostgreSQL** sebagai database utama untuk microservice Manajemen Pengguna.

## Konsekuensi
### Positif
*   **Integritas Data Tinggi**: PostgreSQL menyediakan ACID compliance penuh, memastikan konsistensi data yang krusial untuk informasi pengguna.
*   **Dukungan Relasional Kuat**: Skema yang terstruktur dengan baik cocok untuk data pengguna yang memiliki hubungan jelas (misalnya, pengguna memiliki peran).
*   **Ekosistem Matang**: Banyak tool, library, dan komunitas yang mendukung PostgreSQL di berbagai bahasa pemrograman.
*   **Fleksibilitas Data**: Dukungan JSONB di PostgreSQL memungkinkan fleksibilitas untuk menyimpan data semi-terstruktur jika diperlukan di masa depan tanpa harus bermigrasi total ke NoSQL.
*   **Familiaritas Tim**: Mayoritas tim sudah familiar dengan SQL dan PostgreSQL, mengurangi kurva pembelajaran.

### Negatif
*   **Skalabilitas Horizontal**: Skalabilitas tulis (write scalability) PostgreSQL secara native lebih menantang dibandingkan NoSQL murni, mungkin membutuhkan sharding di masa depan.
*   **Overhead Manajemen**: Membutuhkan manajemen skema dan migrasi database yang lebih terstruktur dibandingkan NoSQL.

## Alternatif yang Dipertimbangkan
*   **MongoDB**: Dipertimbangkan karena fleksibilitas skema dan skalabilitas horizontal yang lebih mudah untuk data non-relasional. Namun, ditolak karena prioritas utama saat ini adalah integritas data relasional dan konsistensi transaksi yang lebih kuat yang disediakan oleh PostgreSQL. Selain itu, kompleksitas dalam menjaga integritas data relasional di MongoDB (misalnya, dengan menggunakan `$lookup` atau denormalisasi) dianggap terlalu tinggi untuk kebutuhan inti manajemen pengguna.
*   **Redis**: Dipertimbangkan untuk kasus penggunaan cache atau data sesi yang sangat cepat. Ditolak karena Redis bukan database persisten utama yang cocok untuk data pengguna inti yang membutuhkan penyimpanan jangka panjang dan query kompleks.

🎯 Catatan: Contoh di atas menunjukkan bagaimana ADR memberikan konteks, alasan, dan perbandingan, yang sangat berharga di kemudian hari.

6. Praktik Terbaik dalam Mengelola ADR

Agar ADRs benar-benar bermanfaat dan tidak menjadi beban dokumentasi yang usang, penting untuk mengikuti beberapa praktik terbaik:

📌 6.1. Simpan di Version Control (Git) Bersama Kode

Ini adalah praktik paling krusial. ADRs harus hidup bersama kode yang mereka deskripsikan.

Manfaat: Mudah diakses, di-versioning, di-review (seperti code review), dan di-deploy bersama aplikasi.
Lokasi: Buat folder /docs/adr atau /architecture/decisions di root repository Anda.

📌 6.2. Gunakan Format Sederhana (Markdown)

Hindari format proprietary atau tool yang kompleks. Markdown adalah pilihan terbaik karena:

Mudah Dibaca & Ditulis: Sintaks sederhana.
Rendah Friksi: Tidak perlu tool khusus.
Version Control Friendly: Perubahan mudah dilacak.

📌 6.3. Kapan Menulis ADR?

Jangan menulis ADR untuk setiap keputusan kecil. Fokus pada keputusan yang:

Signifikan: Memiliki dampak luas pada arsitektur, kinerja, keamanan, atau biaya.
Sulit Dibatalkan: Perubahan yang mahal jika harus diubah di kemudian hari.
Kontroversial: Keputusan yang melibatkan trade-off penting dan butuh konsensus tim.
Mendasar: Membangun fondasi untuk keputusan di masa depan.

❌ Hindari: Menulis ADR untuk keputusan seperti “memilih warna tombol” atau “struktur folder project”. Itu bukan keputusan arsitektural.

📌 6.4. Libatkan Tim dalam Proses Review

Sama seperti code review, ADR juga perlu di-review. Ini memastikan:

Konsensus: Semua pihak yang relevan setuju dengan keputusan.
Kualitas: ADR ditulis dengan jelas dan lengkap.
Pemahaman Bersama: Tim memiliki pemahaman yang sama.

📌 6.5. Jaga Status ADR Tetap Relevan

ADR bukanlah dokumen statis. Jika suatu keputusan diubah atau digantikan, perbarui status ADR yang lama menjadi Deprecated atau Superseded by ADR-XXX dan buat ADR baru untuk keputusan pengganti. Ini menjaga sejarah tetap akurat.

📌 6.6. Hindari Over-Dokumentasi

Tujuan ADR adalah kejelasan dan efisiensi, bukan menjadi beban. Jaga ADR tetap ringkas dan fokus pada esensi. Jika terlalu banyak detail, itu bisa jadi tanda bahwa Anda mendokumentasikan terlalu banyak atau keputusan tersebut perlu dipecah.

📌 6.7. Gunakan Tooling (Opsional)

Ada beberapa tool sederhana seperti adr-tools yang bisa membantu mengelola ADR (membuat template, memberi nomor otomatis). Ini opsional, tetapi bisa membantu konsistensi jika tim Anda besar.

Kesimpulan

Architectural Decision Records (ADRs) mungkin terlihat seperti tambahan pekerjaan, tetapi manfaat jangka panjangnya jauh melampaui usaha awal. Dengan mendokumentasikan keputusan arsitektural secara sistematis, Anda tidak hanya membangun sistem yang lebih konsisten dan mudah dirawat, tetapi juga menciptakan basis pengetahuan yang tak ternilai bagi tim Anda.

ADRs adalah investasi kecil yang memberikan dividen besar dalam bentuk:

Tim yang lebih berdaya dan mandiri.
Onboarding developer yang lebih cepat.
Pengambilan keputusan yang lebih baik di masa depan.
Arsitektur yang lebih kuat dan tahan lama.

Jadi, tunggu apa lagi? Mulailah menulis sejarah keputusan teknis proyek Anda hari ini. Tim Anda (dan diri Anda di masa depan) akan berterima kasih! 💡