Catatan keputusan arsitektur (ADR)
Templat, contoh, dan panduan untuk mencatat keputusan arsitektur.
Catatan keputusan arsitektur (ADR) adalah dokumen yang merekam keputusan arsitektur penting yang diambil beserta konteks dan konsekuensinya.
Terjemahan: العربية, বাংলা, Cymraeg, Dansk, Deutsch, English, Ελληνικά, Română, Polski, Español, Eesti, Suomi, Français, हिन्दी, Bahasa Indonesia, Íslenska, Italiano, 日本語, 한국어, Nederlands, Português, Русский, Svenska, Kiswahili, ไทย, Türkçe, اردو, Tiếng Việt, 中文
- Apa itu catatan keputusan arsitektur?
Catatan keputusan arsitektur (architecture decision record, ADR) adalah dokumen yang menangkap sebuah keputusan arsitektur penting yang dibuat beserta konteks dan…
- Cara mulai menggunakan ADR
Untuk mulai menggunakan ADR, bicarakan area-area berikut dengan rekan tim Anda.
- Saran menulis ADR yang baik
Alasan: Jelaskan alasan melakukan AD tertentu tersebut. Ini dapat mencakup konteks (lihat di bawah), kelebihan dan kekurangan berbagai pilihan yang mungkin, perbandingan…
- Templat contoh ADR
Templat ADR oleh Michael Nygard (sederhana dan populer)
- Saran kerja sama tim untuk ADR
Jika Anda mempertimbangkan untuk menggunakan catatan keputusan bersama tim Anda, berikut beberapa saran yang kami pelajari dari bekerja dengan banyak tim.
- Fitness function untuk keputusan sebagai kode
Fitness function adalah pemeriksaan otomatis yang objektif, ditulis dengan kode pemrograman, yang memverifikasi bahwa keputusan tetap dipertahankan.
Lakukan uji tuntas Anda sendiri terhadap sumber daya ini sebelum menggunakannya di sistem kritis apa pun.
Daftar isi:
- Apa itu catatan keputusan arsitektur?
- Cara mulai menggunakan ADR
- Cara mulai menggunakan ADR dengan alat
- Cara mulai menggunakan ADR dengan git
- Skill Claude Code untuk ADR
- Konvensi nama file
- Saran menulis ADR yang baik
- Templat contoh ADR
- Saran kerja sama tim untuk ADR
- Pertanyaan kerja sama tim untuk ADR
- Konsep langkah berikutnya untuk ADR
- Diagram, tampilan, dan sudut pandang arsitektur
- Fitness function untuk keputusan sebagai kode
- Pagar pengaman keputusan untuk pull request
- Untuk informasi lebih lanjut
Templat:
- Templat catatan keputusan oleh Jeff Tyree dan Art Akerman
- Templat catatan keputusan oleh Michael Nygard
- Templat catatan keputusan oleh EdgeX
- Templat catatan keputusan oleh arc42
- Templat catatan keputusan untuk pola Alexandrian
- Templat catatan keputusan untuk kasus bisnis
- Templat catatan keputusan proyek MADR
- Templat catatan keputusan menggunakan Planguage
- Templat catatan keputusan oleh Paulo Merson
- Templat catatan keputusan oleh Olaf Zimmermann
- Templat catatan keputusan oleh Gareth Morgan
- Templat catatan keputusan oleh GIG Cymru NHS Wales
- Templat catatan keputusan untuk Keputusan Teknis Penting (ITD) oleh Ignacio Larrañaga
Contoh:
- Kerangka CSS
- Konfigurasi variabel lingkungan
- Metrik, monitor, peringatan
- Microsoft Azure DevOps
- Monorepo vs multirepo
- Bahasa pemrograman
- Penyimpanan rahasia
- Format stempel waktu
- Masih banyak lagi...
Apa itu catatan keputusan arsitektur?
Catatan keputusan arsitektur (architecture decision record, ADR) adalah dokumen yang menangkap sebuah keputusan arsitektur penting yang dibuat beserta konteks dan konsekuensinya.
Keputusan arsitektur (architecture decision, AD) adalah pilihan desain perangkat lunak yang menjawab persyaratan yang signifikan.
Log keputusan arsitektur (architecture decision log, ADL) adalah kumpulan semua ADR yang dibuat dan dipelihara untuk proyek (atau organisasi) tertentu.
Persyaratan yang signifikan secara arsitektur (architecturally-significant requirement, ASR) adalah persyaratan yang memiliki efek terukur pada arsitektur sistem perangkat lunak.
Semua ini berada dalam topik manajemen pengetahuan arsitektur (architecture knowledge management, AKM).
Tujuan dokumen ini adalah memberikan gambaran umum yang cepat tentang ADR, cara membuatnya, dan di mana mencari informasi lebih lanjut.
Singkatan:
AD: keputusan arsitektur
ADL: log keputusan arsitektur
ADR: catatan keputusan arsitektur
AKM: manajemen pengetahuan arsitektur
ASR: persyaratan yang signifikan secara arsitektur
Cara mulai menggunakan ADR
Untuk mulai menggunakan ADR, bicarakan area-area berikut dengan rekan tim Anda.
Identifikasi keputusan:
Seberapa mendesak dan seberapa penting AD tersebut?
Apakah harus dibuat sekarang, atau dapat menunggu sampai lebih banyak hal diketahui?
Baik pengalaman pribadi maupun kolektif, serta metode dan praktik desain yang diakui, dapat membantu identifikasi keputusan.
Idealnya pertahankan daftar tugas keputusan yang melengkapi daftar tugas produk.
Pengambilan keputusan:
Ada sejumlah teknik pengambilan keputusan, baik yang umum maupun yang khusus untuk arsitektur perangkat lunak, misalnya dialogue mapping.
Pengambilan keputusan secara berkelompok adalah topik penelitian yang aktif.
Pemberlakuan dan penegakan keputusan:
AD digunakan dalam desain perangkat lunak; karena itu AD harus dikomunikasikan kepada, dan diterima oleh, para pemangku kepentingan sistem yang mendanai, mengembangkan, dan mengoperasikannya.
Gaya penulisan kode yang jelas secara arsitektur dan tinjauan kode yang berfokus pada isu dan keputusan arsitektur adalah dua praktik yang terkait.
AD juga harus (kembali) dipertimbangkan ketika memodernisasi sistem perangkat lunak dalam evolusi perangkat lunak.
Berbagi keputusan (opsional):
Banyak AD berulang di berbagai proyek.
Karena itu, pengalaman dengan keputusan masa lalu, baik yang baik maupun buruk, dapat menjadi aset yang berharga dan dapat digunakan kembali ketika menerapkan strategi manajemen pengetahuan yang eksplisit.
Dokumentasi keputusan:
Banyak templat dan alat untuk mencatat keputusan tersedia.
Lihat komunitas agile, misalnya ADR dari M. Nygard.
Lihat proses rekayasa perangkat lunak dan desain arsitektur tradisional, misalnya tata letak tabel yang disarankan oleh IBM UMF dan oleh Tyree dan Akerman dari CapitalOne.
Untuk informasi lebih lanjut:
- Langkah-langkah di atas diadopsi dari entri Wikipedia tentang Architectural Decision
Cara mulai menggunakan ADR dengan alat
- MySpec — Platform spesifikasi dan keputusan arsitektur otomatis yang menyusun konstitusi proyek, arsitektur teknis, dan ADR ke dalam Markdown yang bersih yang disajikan melalui MCP.
Anda dapat mulai menggunakan ADR dengan alat apa pun sesuai keinginan Anda.
Contohnya:
Jika Anda suka menggunakan Google Drive dan penyuntingan daring, Anda dapat membuat Google Doc atau Google Sheet.
Jika Anda suka menggunakan kontrol versi kode sumber, seperti git, Anda dapat membuat satu file untuk setiap ADR.
Jika Anda suka menggunakan alat perencanaan proyek, seperti Atlassian Jira, Anda dapat menggunakan pelacak perencanaan dari alat tersebut.
Jika Anda suka menggunakan wiki, seperti MediaWiki, Anda dapat membuat wiki ADR.
Cara mulai menggunakan ADR dengan git
Jika Anda suka menggunakan kontrol versi git, berikut cara kami memulai penggunaan ADR dengan git untuk proyek perangkat lunak umum yang memiliki kode sumber.
Buat direktori untuk file ADR:
$ mkdir adr
Untuk setiap ADR, buat file teks, seperti database.txt:
$ vi database.txt
Tulis apa pun yang Anda inginkan di dalam ADR. Lihat templat di repositori ini untuk mendapatkan ide.
Commit ADR tersebut ke repositori git Anda.
Skill Claude Code untuk ADR
Repositori ini menyertakan dua skill Claude Code di bawah skills/, agar agen pengodean AI dapat menulis dan memelihara ADR sesuai anjuran proyek ini:
architecture-decision-record-skill— serbaguna, untuk siapa pun yang menulis ADR di proyek mana pun. Membantu memutuskan apakah suatu keputusan memerlukan ADR, menyiapkan direktoriadr/ataudecisions/, menamai berkas, memilih templat dari sebelas kerangka yang disertakan, dan menulis bagian Konteks/Keputusan/Konsekuensi yang solid.architecture-decision-record-maintainer-skill— khusus untuk pemelihara repositori ini. Mendokumentasikan tata letak repositori, konvensi pencerminan README/locales, dan langkah-langkah persis untuk menambahkan templat, contoh, atau tautan alat baru.
Untuk menggunakan sebuah skill, salin foldernya ke .claude/skills/ di akar repositori yang sedang Anda kerjakan (atau ke ~/.claude/skills/ agar tersedia di setiap proyek), lalu minta Claude Code menulis atau meninjau ADR.
Konvensi nama file
Jika Anda memilih membuat ADR menggunakan file teks biasa, Anda mungkin ingin menetapkan konvensi nama file ADR Anda sendiri.
Kami lebih suka menggunakan konvensi nama file yang memiliki format tertentu.
Contoh:
choose-database.md
format-timestamps.md
manage-passwords.md
handle-exceptions.md
Konvensi nama file kami:
Nama berisi frasa kata kerja imperatif dalam bentuk kini. Hal ini membantu keterbacaan dan sesuai dengan format pesan commit kami.
Nama menggunakan huruf kecil dan tanda hubung (sama seperti repositori ini). Ini adalah keseimbangan antara keterbacaan dan kegunaan sistem.
Ekstensinya adalah markdown. Hal ini berguna untuk pemformatan yang mudah.
Saran menulis ADR yang baik
Ciri-ciri ADR yang baik:
Alasan: Jelaskan alasan melakukan AD tertentu tersebut. Ini dapat mencakup konteks (lihat di bawah), kelebihan dan kekurangan berbagai pilihan yang mungkin, perbandingan fitur, pembahasan biaya/manfaat, dan lainnya.
Spesifik: Setiap ADR sebaiknya membahas satu AD, bukan beberapa AD.
Stempel waktu: Tandai kapan setiap butir dalam ADR ditulis. Ini sangat penting untuk aspek yang dapat berubah dari waktu ke waktu, seperti biaya, jadwal, penskalaan, dan sejenisnya.
Tidak dapat diubah: Jangan mengubah informasi yang ada dalam ADR. Sebagai gantinya, ubah ADR dengan menambahkan informasi baru, atau gantikan ADR dengan membuat ADR baru.
Ciri-ciri bagian "Konteks" yang baik dalam ADR:
Jelaskan situasi organisasi Anda dan prioritas bisnisnya.
Sertakan alasan dan pertimbangan berdasarkan komposisi sosial dan keterampilan tim Anda.
Sertakan kelebihan dan kekurangan yang relevan, dan jelaskan dengan istilah yang selaras dengan kebutuhan dan tujuan Anda.
Ciri-ciri bagian "Konsekuensi" yang baik dalam ADR:
Jelaskan apa yang terjadi setelah keputusan dibuat. Ini dapat mencakup dampak, hasil, keluaran, tindak lanjut, dan lainnya.
Sertakan informasi tentang ADR berikutnya. Cukup umum bahwa satu ADR memicu kebutuhan akan ADR lain, misalnya ketika satu ADR membuat pilihan besar yang menyeluruh, yang pada gilirannya menimbulkan kebutuhan akan keputusan-keputusan yang lebih kecil.
Sertakan proses tinjauan pascatindakan apa pun. Biasanya tim meninjau setiap ADR satu bulan kemudian, untuk membandingkan informasi ADR dengan apa yang terjadi dalam praktik sebenarnya, agar dapat belajar dan berkembang.
ADR baru dapat menggantikan ADR sebelumnya:
- Ketika sebuah AD dibuat yang menggantikan atau membatalkan ADR sebelumnya, maka ADR baru harus dibuat
Templat contoh ADR
Templat contoh ADR yang kami kumpulkan dari internet:
Templat ADR oleh Michael Nygard (sederhana dan populer)
Templat ADR oleh Jeff Tyree dan Art Akerman (lebih canggih)
Templat ADR untuk pola Alexandrian (sederhana dengan rincian konteks)
Templat ADR untuk studi kelayakan bisnis (lebih berorientasi MBA, dengan biaya, SWOT, dan lebih banyak opini)
Templat ADR proyek Markdown Any Decision Records (MADR) (versi sederhana dan versi lengkap; yang terakhir menekankan opsi beserta kelebihan dan kekurangannya)
Templat ADR yang menggunakan Planguage (lebih berorientasi penjaminan mutu)
Templat untuk Keputusan Teknis Penting (ITD) oleh Ignacio Larrañaga (ramping dan mengutamakan keputusan, dioptimalkan untuk tinjauan eksekutif yang cepat)
Saran kerja sama tim untuk ADR
Jika Anda mempertimbangkan untuk menggunakan catatan keputusan bersama tim Anda, berikut beberapa saran yang kami pelajari dari bekerja dengan banyak tim.
Anda memiliki kesempatan untuk memimpin rekan tim Anda dengan membicarakan "mengapa" bersama-sama, alih-alih mewajibkan "apa". Misalnya, catatan keputusan adalah cara bagi tim untuk berpikir lebih cerdas dan berkomunikasi lebih baik; catatan keputusan tidak bernilai jika hanya menjadi kewajiban administrasi yang dipaksakan setelah kejadian.
Beberapa tim jauh lebih menyukai nama "keputusan" (decisions) daripada singkatan "ADR". Ketika beberapa tim menggunakan nama direktori "decisions", seolah-olah sebuah lampu menyala, dan tim mulai memasukkan lebih banyak informasi ke dalam direktori tersebut, seperti keputusan vendor, keputusan perencanaan, keputusan penjadwalan, dan sebagainya. Semua jenis informasi ini dapat menggunakan templat yang sama. Kami berhipotesis bahwa orang belajar lebih cepat dengan kata ("keputusan") daripada singkatan ("ADR"), dan orang lebih termotivasi untuk menulis dokumen yang sedang dikerjakan ketika kata "catatan" dihilangkan, dan juga sebagian pengembang dan sebagian manajer tidak menyukai kata "arsitektur".
Secara teori, sifat tidak dapat diubah adalah yang ideal. Dalam praktik, sifat dapat diubah bekerja lebih baik untuk tim kami. Kami menyisipkan informasi baru ke dalam ADR yang ada, dengan stempel tanggal, dan catatan bahwa informasi tersebut datang setelah keputusan. Pendekatan semacam ini menghasilkan "dokumen hidup" yang dapat kami perbarui bersama. Pembaruan yang umum terjadi ketika kami memperoleh informasi berkat rekan tim baru, atau penawaran baru, atau hasil nyata dari penggunaan kami, atau perubahan pihak ketiga setelah kejadian seperti kemampuan vendor, paket harga, perjanjian lisensi, dan sebagainya.
Pertanyaan kerja sama tim untuk ADR
Siapa yang dapat membuat ADR?
Pertimbangkan area seperti orang tertentu, atau peran tertentu, atau tim tertentu, atau departemen tertentu; pertimbangkan juga apakah ada orang, peran, tim, atau departemen yang dapat memesan sebuah ADR, artinya mereka meminta satu ADR yang akan ditulis oleh orang lain.
Contoh jawaban: Siapa pun di organisasi kami yang telah membaca halaman README catatan keputusan arsitektur dapat mengusulkan ADR, artinya orang tersebut dapat mulai menulisnya, dan membagikannya kepada tim.
Apa yang membenarkan pembuatan ADR?
Pertimbangkan area seperti cara kerja tim organisasi Anda, struktur sistem perangkat lunak Anda, koordinasi lintas tim, kemudahan pemeliharaan jangka panjang, antarmuka eksternal, siapa yang ingin Anda beri manfaat, dan sejenisnya.
Contoh jawaban: Kami ingin membuat ADR ketika kami ingin pengembang di masa depan memahami "mengapa" dari apa yang kami lakukan.
Apa yang membenarkan tidak membuat ADR?
Pertimbangkan area seperti keputusan yang bukan tentang arsitektur, atau yang sangat kecil seperti berisiko minimal atau mandiri atau untuk satu pengembang, atau yang sudah sepenuhnya tercakup di tempat lain seperti oleh standar atau kebijakan atau dokumentasi, atau yang bersifat sementara seperti solusi sementara atau bukti konsep atau eksperimen.
Contoh jawaban: Kami ingin melewatkan ADR ketika sebuah keputusan terbatas dalam lingkup dan waktu dan risiko dan biaya, atau sudah tercakup di tempat lain.
Apa siklus hidup sebuah ADR?
Pertimbangkan area seperti proses pembuatan, proses riset, proses pengambilan keputusan, proses implementasi, dan proses penghentian. Pertimbangkan bagaimana melacak siklus hidup ADR dari waktu ke waktu, seperti bagaimana memindahkan ADR dari satu status ke status berikutnya, dan juga bagaimana mengomunikasikannya kepada para pemangku kepentingan.
Contoh jawaban: Kami ingin ADR memiliki lima tahap siklus hidup: Memulai (Initiating) → Meneliti (Researching) → Mengevaluasi (Evaluating) → Mengimplementasikan (Implementing) → Memelihara (Maintaining) → Menghentikan (Sunsetting).
Apa kriteria untuk langkah-langkah siklus hidup sebuah ADR?
Pertimbangkan area seperti kriteria penerimaan untuk sebuah ADR, artinya bagaimana Anda tahu ADR sudah cukup baik untuk maju dari satu langkah siklus hidup ke langkah berikutnya? Apakah masalahnya telah diartikulasikan dengan jelas? Apakah alternatif telah dipertimbangkan? Apakah trade-off sudah cukup dipahami dan didokumentasikan? Apakah semua konteks yang relevan sudah tersedia? Apakah semua pemangku kepentingan yang relevan terlibat? Apakah semua umpan balik sudah dimasukkan?
Contoh jawaban: Kami ingin ADR dipilih melalui pemungutan suara oleh para pemangku kepentingan ketika tim aktif telah 1) menyelesaikan riset mereka, 2) menyelesaikan evaluasi mereka, 3) mempublikasikan usulan ADR kepada para pemangku kepentingan dengan permintaan komentar dan batas waktu satu minggu, 4) semua komentar pemangku kepentingan telah dimasukkan dan ditanggapi.
Peran dan tanggung jawab apa yang berinteraksi dengan sebuah ADR?
Pertimbangkan peran seperti pengusul, peneliti, evaluator, peninjau, penyetuju, pemelihara, dan sejenisnya. Pertimbangkan tanggung jawab seperti komunikasi dengan pemangku kepentingan, memastikan ekspektasi terpenuhi, berbagi di situs web atau intranet, dan meninjau pekerjaan secara berkala dan terutama ketika terjadi perubahan yang relevan.
Contoh jawaban: Kami ingin setiap ADR selalu memiliki satu orang kontak utama, satu orang kontak sekunder, dan satu tim yang akuntabel; mereka bertanggung jawab atas komunikasi, publikasi, pemeliharaan, tinjauan berkala minimal setahun sekali, dan penghentian akhir jika diperlukan.
Bagaimana tata kelola berinteraksi dengan sebuah ADR?
Pertimbangkan area seperti cara kerja organisasi Anda, kebutuhan kepatuhan khusus seperti untuk aspek hukum atau aspek sumber daya manusia, bagaimana Anda ingin menangani konsensus versus konflik versus eskalasi. Apakah ada area atau orang atau tim yang dapat memiliki pengaruh lebih besar daripada yang lain terkait sebuah ADR, seperti dapat menyetujuinya, atau memberikan suara atasnya, atau memvetonya?
Contoh jawaban: Tata kelola sebuah ADR mengikuti urutan prioritas ini: CEO, CTO, CLO, tim yang mengimplementasikan ADR, para ahli di tim yang paling berpengetahuan tentang ADD. Tidak ada orang lain yang memiliki tata kelola kecuali dijelaskan dalam ADR.
Prinsip apa yang berinteraksi dengan sebuah ADR?
Pertimbangkan area seperti cara kerja organisasi Anda yang mencakup bergerak cepat versus bergerak lambat, untuk konsensus keputusan versus konflik keputusan, dan untuk preferensi risiko versus preferensi keselamatan, diskusi publik versus diskusi privat, dan sejenisnya.
Contoh jawaban: Kami menggunakan prinsip kepemimpinan bias for action, disagree-and-commit, estimasi 70% sudah cukup baik untuk keputusan yang mudah dibatalkan dan mudah diisolasi, dan cara kerja publik kecuali untuk informasi rahasia seperti dijelaskan dalam perjanjian kerahasiaan organisasi kami.
Konsep langkah berikutnya untuk ADR
Arc42 menjawab dua pertanyaan secara pragmatis dan dapat disesuaikan dengan kebutuhan Anda. Apa yang sebaiknya Anda dokumentasikan/komunikasikan tentang arsitektur Anda? Bagaimana sebaiknya mendokumentasikan/mengomunikasikannya? Arc42 mencakup catatan keputusan arsitektur serta panduan tentang tujuan, batasan, konteks, kualitas, risiko, dan lainnya.
Model C4 adalah pendekatan yang mudah dipelajari dan ramah pengembang untuk membuat diagram arsitektur perangkat lunak. C4 adalah kumpulan diagram hierarkis untuk konteks, kontainer, komponen, dan kode, ditambah diagram pendukung untuk lanskap sistem, dinamis, dan penerapan.
Diagram, tampilan, dan sudut pandang arsitektur
Diagram arsitektur disebut "tampilan arsitektur".
"Tampilan arsitektur" adalah contoh dari "sudut pandang arsitektur".
"Sudut pandang arsitektur" memperhatikan audiens tertentu dengan kepedulian tertentu.
Contoh sudut pandang, tampilan, dan diagram arsitektur:
Kapabilitas bisnis
Proses bisnis tingkat tinggi
Fungsi perangkat lunak yang dipetakan ke komponen aplikasi
C4 Model Diagram konteks (TO-BE / AS-IS)
C4 Model Diagram kontainer (TO-BE / AS-IS)
Diagram entitas-relasi (ERD) untuk memetakan entitas data ke komponen aplikasi
Diagram urutan untuk menggambarkan alur fungsional di dalam sistem dan untuk integrasi
Business Process Model and Notation (BPMN) diagram untuk menggambarkan aliran data antarkomponen aplikasi
Business Process Model and Notation (BPMN) diagram untuk menggambarkan proses bisnis / skenario pengguna
Manajemen Identitas dan Akses (IAM) diagram
Kontrol Akses Berbasis Peran (RBAC) diagram dengan peran per komponen aplikasi
Kontrol Akses Berbasis Atribut (ABAC) diagram dengan atribut per komponen aplikasi
Diagram privasi
Diagram terkait:
Diagram kasus penggunaan menunjukkan kasus penggunaan kepada manajemen/pelanggan, yang mendahului kebutuhan, yang mendahului arsitektur perangkat lunak.
Diagram penerapan menunjukkan perangkat keras/komputer fisik tempat komponen perangkat lunak diterapkan.
Diagram alir data menunjukkan bagaimana data bergerak melalui sistem dan diubah.
Diagram urutan digunakan untuk menunjukkan cara kerja protokol seperti HTTP pada sumbu waktu.
Diagram aktivitas menggambarkan alur kerja aktivitas yang dilakukan sistem perangkat lunak, seperti AI NPC.
Fitness function untuk keputusan sebagai kode
Fitness function adalah pemeriksaan otomatis yang objektif, ditulis dengan kode pemrograman, yang memverifikasi bahwa keputusan tetap dipertahankan.
Fitness function membuat keputusan dapat diuji dan terjamin.
Fitness function untuk keputusan dapat sangat membantu penjaminan mutu, proses regulasi, dan tujuan tata kelola.
Bagaimana fitness function terhubung dengan keputusan
Catatan keputusan mendokumentasikan keputusan, sedangkan fitness function menjamin keputusan tersebut.
Contoh keputusan: Kami menggunakan event sourcing untuk memenuhi persyaratan audit.
Contoh fitness function: Kami menggunakan server integrasi berkelanjutan untuk menguji bahwa semua perubahan status harus menghasilkan event.
Mengapa fitness function membantu keputusan
Pengukuran objektif: Fitness function lulus atau gagal, sehingga pekerjaan terlihat dan jelas.
Penggunaan berkelanjutan: Fitness function adalah aturan hidup Anda, dijalankan pada setiap commit dan build.
Percaya diri untuk melakukan refactoring: Fitness function secara otomatis menangkap kesalahan aturan keputusan.
Tata kelola yang dapat diskalakan: Fitness function menjamin standar tanpa menciptakan hambatan.
Dapatkah fitness function menggunakan AI?
Fitness function dapat memanfaatkan LLM AI untuk keputusan dengan mengajukan pertanyaan tentang pekerjaan Anda, seperti rencana, kode, skema, API, dan lainnya:
IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning.
IMPORTANT: Turn on extended thinking. Turn on expert advice. Turn on search.
This is a fitness function to evaluate if our work is
using all our decisions, and is correct and accurate.
- Our decisions are here: {url}
- Our work to evaluate is here: {url}
Explain any errors, problems, gaps, weaknesses. Be direct. Be decisive.
Pengujian unit arsitektur
ArchUnit: memeriksa aturan arsitektur kode Java dengan menggunakan kerangka pengujian unit Java biasa apa pun.
ArchUnitTS: memeriksa aturan arsitektur kode TypeScript dan kode JavaScript dengan menggunakan Jest, Vitest, Jasmine, dan sebagainya.
Pagar pengaman keputusan untuk pull request
Decision Guardian otomatis memunculkan catatan keputusan yang tepat pada saat yang tepat, yaitu ketika pengembang sedang mengubah kode yang dicakup keputusan tersebut. Alih-alih berharap pengembang membaca folder dokumen sebelum menggabungkan, konteks yang relevan muncul langsung di pull request.
Ini berlaku untuk semua jenis catatan keputusan: keputusan arsitektur, keputusan data, keputusan kepatuhan, keputusan klinis dan medis, keputusan keamanan, dan lainnya.
Bekerja dengan sistem CI apa pun (GitLab, Jenkins, CircleCI) dan sebagai hook pre-commit. Sumber terbuka. Lisensi MIT.
ADR Guard adalah GitHub
Action yang menggagalkan pull request ketika jalur kode yang dipantau berubah tanpa catatan keputusan arsitektur yang ditambahkan atau diperbarui. Pengecualian bersifat eksplisit: baris
ADR-Exempt: beserta alasan meloloskan gerbang dan ditulis ke ringkasan job. Tidak terikat templat, tanpa dependensi. Sumber terbuka. Lisensi MIT.
Untuk informasi lebih lanjut
Pengantar:
Templat:
Documenting architecture decisions - Michael Nygard (thinkrelevance.com)
Template for documenting architecture alternatives and decisions (stackoverflow.com)
Mendalam:
The Decision View's Role in Software Architecture Practice (computer.org)
Documenting Software Architectures: Views and Beyond (resources.sei.cmu.edu)
Architecture Decisions: Demystifying Architecture (utdallas.edu)
ThoughtWorks Technology Radar: Lightweight Architecture Decision Records (thoughtworks.com)
A Skeptic’s Guide to Software Architecture Decisions (infoq.com)
Architectural Retrospectives: the Key to Getting Better at Architecting
Software Architecture Monday with Mark Richards - pelajaran arsitektur perangkat lunak bulanan gratis
"Keep the Why: Code Becomes Legacy When Nobody Remembers Why"
Alat:
Command-line tools for working with Architecture Decision Records
kgai - append-only decision log for AI coding agents, a machine-readable companion to ADR files
Panduan khusus perusahaan:
Contoh:
Video:
Podcast:
Buku:
Software Architecture in Practice (SEI Series in Software Engineering)
Documenting Software Architectures: Views and Beyond (SEI Series in Software Engineering)
The Software Architect Elevator: Redefining the Architect's Role in the Digital Enterprise
Fundamentals of Software Architecture: An Engineering Approach - by Mark Richards and Neal Ford
Building Evolutionary Architectures - by Neal Ford, Rebecca Parsons, Patrick Kua, Pramod Sadalage
Foundations of Decision Analysis by Ronald Howard and Ali Abbas
Head First Software Architecture - by Raju Gandhi, Neal Ford and Mark Richards
Communication Patterns: A Guide for Developers and Architects - by Jacqui Read
Lihat juga:
REMAP (Representation and Maintenance of Process Knowledge)
DRL (Decision Representation Language)
IBIS (Issue-Based Information System)
QOC (Questions, Options, and Criteria)
IBM’s e-Business Reference Architecture Framework
Decision Reasoning Format (DRF) - Format YAML/JSON yang netral terhadap vendor dan dapat dibaca mesin untuk merepresentasikan keputusan dengan penalaran eksplisit, asumsi, keadaan kognitif, dan pertukaran. Melengkapi ADR dengan menambahkan penalaran terstruktur yang dapat divalidasi ke dokumentasi keputusan.