Pertanyaan dan konteks
Pertanyaan ini menguji apakah Anda dapat mengubah trade-off teknis yang penting menjadi memori tim yang dapat dicari, ditinjau, dan dikembangkan. Bahas kapan ADR diperlukan, cara mencatat opsi yang ditolak, bagaimana catatan tersebut mendukung tinjauan kode dan pemecahan masalah, serta cara menangani keputusan yang digantikan oleh keputusan baru.
Ini cocok untuk peran backend, platform, SRE, staff engineer, dan peran lintas fungsi. Asumsikan tim memiliki repositori dan proses peninjauan tetapi tidak memiliki konvensi catatan keputusan bersama; pilihan tersebut mungkin melibatkan keandalan, keamanan, antarmuka, dependensi, atau trade-off biaya yang tidak dapat dibatalkan.
Hal yang dievaluasi oleh pewawancara
Pertama, dapatkah Anda mengidentifikasi keputusan yang signifikan secara arsitektur alih-alih mendokumentasikan setiap detail implementasi? Kedua, dapatkah Anda menjelaskan pilihan tersebut dengan konteks, batasan, opsi, dan konsekuensi yang netral? Ketiga, dapatkah Anda menempatkan ADR dalam siklus hidup proposed, reviewed, accepted, dan superseded? Keempat, dapatkah Anda membuat catatan tersebut berguna dalam tinjauan kode, orientasi anggota baru (onboarding), dan respons insiden?
Pertanyaan klarifikasi yang perlu diajukan
- Apakah keputusan ini memengaruhi struktur sistem, atribut kualitas utama, antarmuka publik, atau hanya implementasi lokal?
- Batasan mutlak apa yang berlaku: latensi, ketersediaan, kepatuhan, keterampilan, jendela migrasi, atau biaya?
- Apakah opsi tersebut sudah diterapkan, atau apakah ADR masih berstatus Proposed? Siapa yang dapat menerima atau menolaknya?
- Apakah ADR akan berada di repositori, sistem dokumentasi, atau keduanya? Bagaimana tim yang terdampak menemukan pembaruan?
- Sinyal apa yang akan memicu evaluasi ulang: lalu lintas, tingkat kegagalan, biaya, atau perubahan regulasi?
Kerangka jawaban 30 detik
“Pertama-tama saya memeriksa apakah pilihan tersebut mengubah struktur sistem, atribut kualitas utama, atau antarmuka yang sulit dibatalkan. Jika ya, saya membuat ADR yang ringkas. Dokumen ini mencatat konteks, batasan, opsi yang dipertimbangkan, alternatif yang ditolak, keputusan, trade-off, risiko, dan status, kemudian tim yang terdampak meninjaunya saat berstatus Proposed. Setelah diterima, saya memperlakukannya sebagai riwayat yang tidak dapat diubah (immutable); ketika persyaratan berubah, saya membuat ADR pengganti, menautkan catatan lama, dan memperbarui indeks. Saya menyimpan catatan tersebut dalam repositori berversi yang mudah diakses dan mereferensikannya dalam tinjauan desain, tinjauan kode, orientasi anggota baru, dan pemecahan masalah.”
Jawaban langkah demi langkah
Langkah 1: Tetapkan ambang batas pencatatan
Buat ADR ketika suatu pilihan memengaruhi struktur sistem, atribut kualitas utama, antarmuka publik, dependensi penting, atau biaya yang sulit dibatalkan. Penamaan, detail refaktor sekali pakai, atau pilihan yang sudah diatur oleh standar yang jelas biasanya tidak memerlukan catatannya sendiri. Ambang batas ini mempertahankan keputusan yang akan mengubah pertimbangan di masa depan tanpa menimbulkan kebisingan dokumentasi.
Langkah 2: Jelaskan masalah secara netral
Nyatakan masalah, dampak bagi pengguna atau bisnis, persyaratan fungsional dan non-fungsional, tenggat waktu, serta batasan yang tidak dapat dinegosiasikan. Jangan menyelipkan opsi yang disukai ke dalam konteks atau mengganti fakta dengan "tim X bersikeras." Kontributor baru harus memahami mengapa suatu keputusan diperlukan sekarang.
Langkah 3: Bandingkan opsi dan trade-off
Buat daftar opsi yang benar-benar dipertimbangkan, termasuk pilihan yang ditolak dan alasan penolakannya. Bandingkan latensi, ketersediaan, radius dampak (blast radius), keamanan, biaya migrasi, beban operasional, dan kapabilitas tim; jika nilainya belum pasti, sebutkan asumsi dan tingkat keyakinannya. Jaga agar ADR tetap fokus pada keputusan dan tautkan detail spike atau desain secara terpisah.
Langkah 4: Nyatakan keputusan dan konsekuensinya
Tulis keputusan yang jelas dan berdiri sendiri, seperti “Kami akan menggunakan antrean regional dan menerima persetujuan manual untuk failover lintas wilayah.” Kemudian catat manfaat yang diharapkan, biaya, risiko, kendali yang diperlukan, dan komponen yang terdampak. “Pilih opsi A” tidaklah cukup karena peninjau di masa depan tidak dapat melihat alasan atau konsekuensi biaya yang harus dibayar.
Langkah 5: Tetapkan status, kepemilikan, dan tinjauan
Gunakan status seperti Proposed, Accepted, Rejected, Deprecated, dan Superseded. Tetapkan pemilik dan undang tim yang terdampak untuk membaca serta berkomentar saat statusnya Proposed; setelah diterima, tambahkan tanggal, pemangku kepentingan, dan versi. Tinjauan bertujuan memverifikasi bahwa fakta, batasan, opsi, dan konsekuensi sudah jelas, bukan memastikan semua orang akan setuju selamanya.
Langkah 6: Masukkan ADR ke dalam alur kerja rekayasa
Simpan versi ADR bersama repositori atau sistem dokumentasi dan kelola indeks yang dapat dicari. Ketika tinjauan desain atau kode menemukan perubahan yang bertentangan dengan keputusan yang telah diterima, tautkan ADR tersebut dan wajibkan catatan perubahan yang eksplisit. Orientasi anggota baru, serah terima tugas, dan respons insiden juga harus menggunakan ADR untuk menjawab "mengapa dilakukan dengan cara ini", guna mengurangi perdebatan yang berulang.
Langkah 7: Tambahkan catatan baru saat keputusan berubah
Pertahankan ADR yang telah diterima atau ditolak agar tidak diubah (immutable). Jika bukti baru, skala, biaya, atau regulasi mengubah kesimpulan, tulis ADR baru yang menjelaskan konteks baru, keterbatasan lama, dan trade-off yang baru. Setelah diterima, tandai catatan lama sebagai Superseded dan tautkan kedua catatan tersebut. Hal ini menjaga riwayat sembari mempermudah penemuan keputusan saat ini.
Contoh jawaban yang kuat
“Pertama-tama saya memeriksa apakah hal ini memengaruhi struktur sistem, atribut kualitas utama, antarmuka, atau biaya yang tidak dapat dibatalkan; jika ini hanya implementasi lokal, saya tidak akan menambahkan ADR. Begitu memenuhi ambang batas, saya menulis catatan Proposed yang memuat konteks masalah, persyaratan pengguna dan non-fungsional, batasan, opsi, alternatif yang ditolak, keputusan, trade-off, risiko, dan keyakinan.
Saya mengundang tim yang terdampak untuk membaca sebelum diskusi peninjauan, serta mencatat status, pemilik, tanggal, dan pemangku kepentingan. Setelah diterima, saya menyimpan ADR tersebut dalam repositori berversi yang dapat dicari dan mereferensikannya dalam tinjauan desain, tinjauan kode, orientasi anggota baru, dan pemecahan masalah. Dokumen ini tetap ringkas dan faktual daripada menggantikan dokumen desain yang lengkap.
Jika persyaratan atau bukti berubah, saya tidak mengedit catatan yang sudah diterima. Saya membuat ADR baru yang menjelaskan mengapa keputusan lama tidak lagi sesuai, opsi-opsi baru, dan konsekuensinya. Setelah diterima, saya menandai catatan lama sebagai Superseded dan menautkan keduanya, sehingga tim dapat melihat pilihan saat ini tanpa kehilangan riwayat penalarannya.”
Kesalahan umum
- Menulis panduan desain lengkap → keputusan menjadi sulit ditemukan → pertahankan konteks, opsi, keputusan, dan konsekuensi; tautkan detailnya.
- Hanya mencatat opsi yang menang → perdebatan akan berulang di kemudian hari → sertakan opsi yang ditolak beserta batasan pada saat itu.
- Mengganti batasan dengan preferensi pribadi → catatan tidak dapat ditinjau secara objektif → gunakan fakta dan asumsi yang netral serta dapat diamati.
- Mengedit catatan yang sudah diterima secara langsung → riwayat menghilang → tambahkan catatan baru dan tandai catatan lama sebagai Superseded.
- Menghilangkan status dan pemilik → tidak ada yang tahu apakah keputusan itu masih berlaku → lacak siklus hidup, pemilik, dan tanggal penerimaan.
- Tidak pernah mengutip ADR → dokumentasi tidak memiliki nilai operasional → hubungkan dengan tinjauan desain, tinjauan kode, orientasi anggota baru, dan respons insiden.
Pertanyaan lanjutan dan jawaban
Pertanyaan lanjutan 1: Bisakah tim menerima ADR ketika ada anggota yang tidak setuju?
Ya. Catat keberatan yang belum terselesaikan, risiko, dan siapa yang berwenang menerima keputusan tersebut. Peninjauan membuat pilihan dan biayanya menjadi transparan; peninjauan tidak bertujuan memaksakan konsensus permanen. Jika bukti pendukung masih kurang, pertahankan ADR dalam status Proposed dan jadwalkan tugas validasi.
Pertanyaan lanjutan 2: Kapan Anda harus mengisi kembali (backfill) ADR yang terlewat?
Lakukan backfill ketika struktur, antarmuka, atau trade-off kualitas yang ada bersifat penting tetapi tidak ada yang dapat menjelaskannya. Gunakan riwayat commit, data insiden, dan wawancara dengan pengelola, serta beri label hasilnya sebagai catatan retrospektif agar kesimpulan deduksi tidak disajikan sebagai fakta kontemporer.
Pertanyaan lanjutan 3: Repositori atau wiki?
Lebih disukai repositori berversi di dekat kode yang terdampak agar catatan tersebut ditinjau bersamaan dengan implementasinya. Jika pemangku kepentingan bisnis atau keamanan memerlukan akses yang lebih luas, buat salinan (mirror) indeks atau ringkasan sembari mempertahankan satu sumber otoritatif tunggal untuk mencegah perbedaan data.
Pertanyaan lanjutan 4: Bagaimana cara menunjukkan nilai dari ADR?
Pantau waktu yang dibutuhkan anggota baru untuk memahami pilihan-pilihan utama, frekuensi perdebatan yang berulang, pelanggaran keputusan yang telah diterima yang ditemukan saat peninjauan, dan seberapa cepat petugas respons insiden menemukan konteks. Metrik mengungkap celah yang ada; jumlah dokumen bukanlah tujuannya.