Dari RFC ke ADR: Mencapai Keputusan dan Menjaga Alasan

Keputusan yang tidak bisa direkonstruksi oleh siapa pun

Pemimpin teknologi baru mengajukan pertanyaan yang masuk akal: mengapa setiap layanan berkomunikasi dengan sistem penagihan melalui antrean itu? Ada sebuah ADR — ADR-014, empat kalimat, ditulis sebelas bulan yang lalu. Konteks: "kami membutuhkan integrasi penagihan yang dapat diandalkan." Keputusan: "gunakan antrean." Konsekuensi: "beberapa penundaan tambahan." Secara teknis, ini adalah sebuah catatan. Ini tidak menjawab apa-apa.

Anda ada di sana, jadi Anda tahu apa yang tidak dikatakan ADR-014: argumen tiga minggu di dua saluran Slack dan utas PR yang memanas; opsi API-sinkron yang kalah karena batas laju yang sejak itu telah dinaikkan; keberatan insinyur staf yang dijawab dengan tolok ukur yang sekarang tidak bisa ditemukan oleh siapa pun. Perdebatan itu terjadi. Catatan ditulis setelahnya, dari ingatan, oleh satu orang, pada hari Jumat.

Ini adalah mode kegagalan yang terdokumentasi dan hampir universal dari praktik yang benar-benar baik. Panduan preskriptif AWS dan dokumen Well-Architected Microsoft keduanya merekomendasikan ADR — dan keduanya mencatat rasa sakitnya: menjaga agar mereka tetap terkini memerlukan waktu, dan mengelolanya menjadi kompleks seiring tim dan pilihan bertambah. Penyebab utamanya adalah struktural: perdebatan dan catatan berada di tempat yang berbeda, sehingga catatan selalu merupakan transkripsi yang kehilangan informasi. Solusinya adalah membuatnya menjadi tempat yang sama. Praktik ini juga tidak spesifik untuk rekayasa, atau bahkan spesifik untuk ADR. Google mengharuskan adanya dokumen desain — masalah, pendekatan yang diusulkan, alternatif yang dipertimbangkan, trade-off — yang ditulis dan ditinjau sebelum pekerjaan teknis yang signifikan dimulai, praktik yang diatur dalam Rekayasa Perangkat Lunak di Google. Ini adalah disiplin yang sama dengan ADR, diterapkan satu langkah lebih awal: ADR mencatat pilihan yang diperjuangkan oleh dokumen desain. Keduanya gagal dengan cara yang sama karena alasan yang sama, dan keduanya diperbaiki dengan langkah yang sama — pegang argumen di tempat catatan berada, daripada mentranskripsikan satu ke yang lain setelahnya. Bacalah setiap langkah di bawah ini sebagai mencakup kedua artefak.

Mengapa ADR membusuk

Satu kalimat dari materi komunitas ADR sendiri membawa seluruh diagnosis: RFC biasanya tentang mencapai kesepakatan; ADR mencatat kesepakatan setelah dicapai. Dua artefak, dua momen — dan segala sesuatu di antara mereka bocor. Alternatif yang "jelas" salah tidak tercatat (sampai mereka berhenti menjadi jelas). Keberatan yang membentuk desain akhir hanya bertahan sebagai komentar PR di thread yang ditutup. Bagian konteks ditulis terakhir, paling buruk, oleh siapa pun yang kalah dalam permainan tidak-itu. Pertemuan yang seharusnya menghasilkan keputusan justru menghasilkan ringkasan sebagai gantinya, dan alasan yang membuat keputusan tahan lama — hal yang menjadi dasar seluruh rantai kualitas keputusan — adalah tepat apa yang hilang dalam transkripsi.

Langkah 1–3: Proposal, konteks, opsi

1. 1Nyatakan proposal sebagai klaim utama — keputusan yang diusulkan, bukan pertanyaan: "Kami akan mengarahkan semua penulisan penagihan melalui antrean yang tahan lama." Kalimat ini adalah judul ADR di masa depan. Checkpoint: akar ada, satu kalimat, ditulis oleh pengusul.
2. 2Konteks sebagai argumen pro terpisah. Setiap kekuatan yang membuat keputusan itu diperlukan — persyaratan keandalan, batas tarif sistem penagihan, mandat audit — adalah argumen tersendiri di bawah akar. Sebuah paragraf "Konteks" monolitik tidak dapat dipertanyakan; tiga klaim konteks terpisah dapat masing-masing dipertanyakan, dikonfirmasi, atau dibantah secara individu. Checkpoint: ≥2 argumen konteks, masing-masing satu kekuatan.
3. 3Setiap opsi mendapatkan nodenya sendiri. Antrian, API sinkron, pekerjaan batch — argumen saudara, masing-masing dengan anak pro dan kontra sendiri. Pro/kontro adalah relatif terhadap induk, jadi kelemahan suatu opsi tergantung pada opsi itu, bukan pada keputusan. Sertakan opsi yang Anda harapkan untuk ditolak: saudara yang ditolak adalah apa yang menjawab "mengapa kita tidak hanya…". Titik pemeriksaan: setiap opsi yang mungkin ditanyakan pembaca ada.

Langkah 4–6: Putaran RFC yang meninggalkan catatan

Sekarang tahap tinjauan — biasanya bagian yang tersebar di obrolan, komentar, dan lorong. Di sini, ini berjalan sebagai tiga jenis pertukaran terstruktur, masing-masing merupakan dialog empat putaran antara peninjau dan penulis opsi:

Langkah 7: Memutuskan — dan apa yang bukan penilaian

Pengambil keputusan menilai opsi: satu diberi label penilaian masing-masing. Distribusi adalah bukti yang sah — di mana ruangan berdiri, tercatat, sebelum panggilan. Tetapi penilaian bukanlah keputusan. Seorang manusia yang disebutkan masih memutuskan, dan jika panggilan bertentangan dengan distribusi, simpul keputusan adalah tempat itu dijelaskan. (Siapa manusia yang disebutkan itu, dan bagaimana menetapkan peran sebelum debat daripada setelahnya, adalah disiplin tersendiri — lihat tutorial hak keputusan.)

Langkah 8–9: ADR yang tidak perlu Anda tulis

Inilah hasilnya. Catatan tersebut bukanlah dokumen yang Anda tulis setelahnya — itu adalah node dari opsi yang dipilih ditambah semua yang sudah terlampir padanya: argumen konteks (Context), saudara yang ditolak (Options Considered), rantai yang telah diselesaikan (diskusi, dengan penulis), penilaian (di mana posisi ruangan), dan argumen keputusan beserta alasannya (Decision). Tidak ada yang ditranskripsikan, jadi tidak ada yang hilang dalam transkripsi.

1. 1Catat konsekuensi yang Anda terima. Kekurangan yang diketahui — latensi tambahan, beban operasional dari antrean — terus berlanjut sebagai anak-anak dari opsi yang dipilih, diakui oleh pengambil keputusan. Menuliskannya adalah apa yang menjadikannya sebuah keputusan daripada sekadar preferensi. Checkpoint: ≥1 konsekuensi yang diterima tercatat.
2. 2Ekspor jika organisasi Anda memerlukan ADR yang dilacak oleh repositori. Banyak yang memang memerlukannya, dengan benar — ADR markdown di samping kode tetap menjadi artefak kepatuhan. Tulis ringkasan empat bagian dari pohon (lima menit, bukan hari Jumat), tautkan kembali ke diskusi untuk perdebatan lengkap. Checkpoint: ADR repositori mengacu pada pohon; pohon menyimpan alasan.

Tidak setuju dan berkomitmen, secara resmi

Pola yang membuat Amazon terkenal — tidak setuju dan berkomitmen — memiliki masalah keterbacaan: bagaimana seseorang tahu kemudian bahwa ketidaksetujuan itu nyata, didengar, dan dijawab, daripada diabaikan? Mekanika rantai menjawabnya. Rantai Tinjauan yang menjalani empat putaran penuh dan diselesaikan tanpa kesepakatan adalah bukti yang tepat: keberatan diajukan, dijawab, ditekan, dan dijawab lagi, secara resmi, sebelum pihak yang tidak setuju berkomitmen. Pihak yang tidak setuju didokumentasikan telah didengar — yang membuat komitmen setelahnya menjadi masuk akal daripada sekadar patuh.

Langkah 10: Menggantikan tanpa menghapus

Keputusan berumur. Ketika batas laju yang membunuh opsi sinkron dinaikkan, langkah yang tepat adalah keputusan baru yang merujuk pada yang digantikan — argumen baru yang terhubung ke node ADR-014, menyatakan apa yang berubah. Keputusan lama tetap dapat dibaca; alasannya adalah tepat mengapa keputusan baru tahu apa yang dibatalkannya.

Satu celah jujur yang perlu dikelola secara eksplisit: tidak ada kolom status ADR bawaan. Diusulkan / diterima / digantikan bukanlah status kelas satu dalam sebuah argumen — penggantian dimodelkan dengan penghubungan, dan konvensi tersebut adalah milik Anda untuk dipertahankan. Nyatakan dalam kesepakatan kerja tim Anda daripada mengasumsikan produk menegakkannya.

Batasan yang jujur

• ✗Ini tidak menggantikan ADR di repositori Anda jika organisasi Anda memerlukan mereka dikendalikan versi di samping kode. Ekspor dan komit ringkasan; gunakan pohon untuk bagian yang buruk dalam markdown — perdebatan.
• ✗Tidak ada kolom status ADR. Diusulkan/diterima/digantikan adalah konvensi penghubung yang Anda pertahankan, bukan sesuatu yang ditegakkan oleh produk.
• ✗Sebuah rantai adalah empat putaran. Ketidaksepakatan arsitektural yang mendalam akan memerlukan panggilan; rantai adalah catatan dari apa yang sudah dicoba sebelumnya.
• ✗Penilaian adalah nilai berlabel tunggal, bukan skor multi-kriteria yang berbobot.
• ✗Itu tidak membuat siapa pun menulis konteks yang baik. Struktur menurunkan biaya catatan yang baik; itu tidak menyediakan penilaian.

Pelajaran praktis

• ✓Satu RFC, satu diskusi. Tahan pohon mega yang menutupi seluruh arsitektur kuartal — tautan supersesi menghubungkan keputusan lebih baik daripada pengelompokan.
• ✓Benih dari apa yang ada. Transkrip yang penuh keputusan atau folder ADR lama Anda, yang diekstrak, memberikan debat awal yang baik — dilabeli sebagai diimpor, sehingga argumen langsung tetap dapat dibedakan.
• ✓Letakkan nama peninjau di rantai mereka dan biarkan di sana. Atribusi adalah akuntabilitas; keberatan arsitektural anonim menjadi folklore.
• ✓Bagian konsekuensi adalah milik pengambil keputusan, bukan milik orang lain. Kerugian yang diterima yang ditulis oleh orang yang menerimanya memiliki bobot yang berbeda dibandingkan dengan peringatan dari peninjau.

ADR-014, versi yang menjawab

Kembali ke pertanyaan pemimpin teknologi yang baru. Dalam versi yang dibangun kembali, ADR-014 adalah sebuah node: keputusan antrean dengan alasannya, tiga kekuatan konteks (satu sekarang sudah usang — terlihat), saudara API sinkron yang ditolak yang nama fatalnya menyebutkan batas laju lama, empat rantai Tinjauan yang telah diselesaikan termasuk milik insinyur staf, dan tolok ukur yang dilampirkan sebagai bukti. Pemimpin teknologi membaca selama sepuluh menit, melihat batas laju telah diubah, dan membuka proposal yang menggantikan yang terhubung ke node lama. Tidak ada yang menggali Slack. Itulah seluruh janji: rantai mencapai kesepakatan, pohon mencatatnya — dan catatan tersebut menjawab pertanyaan yang tidak Anda ketahui akan ditanyakan.