
Enam bulan selepas sistem dilancarkan, seorang pembangun baharu membuka repositori kod dan bertanya dalam saluran pasukan: “Kenapa kita simpan artikel sebagai fail Markdown dalam Git dan bukan dalam pangkalan data MySQL?” Atau soalan klasik lain: “Kenapa modul bil masih menggunakan worker berasingan daripada API utama?”
Jika tiada siapa pernah mencatat sebab di sebalik pilihan itu, jawapan yang paling kerap keluar ialah: “Entahlah, masa mula-mula projek dulu memang buat macam tu.” Akibatnya, pasukan menghabiskan dua jam dalam mesyuarat mengulang perdebatan yang sama dari sifar—atau lebih teruk, terus merombak seni bina sedia ada tanpa sedar ia dulu dibina begitu untuk mengelakkan had kuota penyedia awan, kekangan kos pelayan, atau syarat audit tertentu.
Tulis ADR ringkas dalam 15 baris sahaja
Anda tidak perlukan dokumen spesifikasi 20 muka surat dalam Word yang tiada siapa sanggup membaca apabila tarikh pelancaran semakin dekat. Untuk keputusan teknikal yang memberi kesan jangka panjang, cukup satu fail Markdown ringkas—yang biasa dipanggil Architecture Decision Record (ADR)—dan disimpan terus dalam folder seperti docs/decisions/0003-guna-markdown-untuk-blog.md bersebelahan kod sumber.
Contoh format yang paling mudah dikekalkan hanya mengambil beberapa minit untuk ditulis:
# 0003: Simpan kandungan blog sebagai Markdown dalam Git
- **Tarikh & Status:** 2026-10-13 — Diterima
- **Konteks:** Tapak statik dikendalikan oleh seorang pembangun dan dua penulis teknikal. Bajet pelayan terhad dan prestasi paparan perlu pantas tanpa pangkalan data berasingan.
- **Pilihan lain:** WordPress self-hosted (perlu penyelenggaraan tampalan PHP/plugin), Headless CMS berbayar (kos bulanan tambahan).
- **Keputusan:** Gunakan fail Markdown dalam Git bersama binaan statik ke Cloudflare Pages supaya versi artikel boleh dijejak melalui Pull Request.
- **Bila perlu semak semula:** Jika bilangan editor bukan teknikal melebihi lima orang atau aliran kerja memerlukan penjadualan artikel tanpa akses Git.
Kunci utama format ini ialah dua bahagian terakhir: menyatakan pilihan yang ditolak secara jujur, dan menetapkan syarat jelas bila keputusan itu patut disemak semula. Apabila anda menulis “Bila perlu semak semula”, anda sebenarnya membuang rasa bersalah pembangun masa depan yang ingin menukar arah apabila skala sistem berubah.
Dalam projek agensi atau sistem dalaman syarikat Malaysia, konteks kekangan itu selalunya berkait rapat dengan realiti operasi—contohnya pelanggan hanya sanggup bayar bajet VPS RM80 sebulan, atau pasukan hanya ada seorang pembangun yang menjaga lima modul serentak. Tanpa catatan bertulis, pembangun baharu yang masuk setahun kemudian akan menyangka keputusan lama itu dibuat kerana kurang ilmu, sedangkan ia sebenarnya kompromi paling waras pada waktu itu.
Simpan dekat dengan tempat kerja harian
Kesilapan paling biasa selepas mula menulis nota keputusan ialah menyimpannya di tempat yang terasing—contohnya satu folder Google Drive baharu yang pautannya hanya diketahui oleh ketua projek lama. Dalam masa tiga bulan, orang baharu tidak tahu dokumen itu wujud dan masalah lupa konteks berulang semula.
Simpan keputusan teknikal di dalam repositori Git supaya ia muncul terus dalam sejarah komit dan boleh dirujuk dalam Pull Request. Untuk keputusan produk atau operasi yang melibatkan pasukan bukan teknikal (seperti polisi pemulangan wang atau struktur harga pakej), simpan di dalam tiket Jira, Linear, atau ruang dokumentasi utama yang memang dibuka setiap hari oleh pasukan.
Nota keputusan bukan batu bersurat
Ada pembangun yang enggan menulis ADR kerana risau ia akan mengikat pasukan daripada berubah pada masa depan. Sebenarnya tujuan ADR adalah yang sebaliknya: ia memberi konteks yang adil supaya pembangun seterusnya berani membuat keputusan baharu dengan yakin.
Apabila seseorang membaca nota lama dan nampak alasan asal—“Oh, dulu mereka pilih begini sebab trafik masih rendah dan pasukan hanya ada dua orang”—perbincangan untuk berhijrah ke sistem baharu menjadi jauh lebih tenang dan objektif. Anda tidak lagi membuang masa meneka niat pasukan terdahulu, dan anda boleh menukar halatuju berdasarkan realiti semasa tanpa rasa ragu-ragu.