1.6 निर्णय अभिलेख

अवलोकन और प्रेरणा

निर्णय अभिलेख (डिसीज़न रिकॉर्ड) एक दस्तावेज़ है जो किसी महत्वपूर्ण फ़ैसले को उसके संदर्भ और परिणामों के साथ क़ैद करता है। सबसे जाना-पहचाना रूप है आर्किटेक्चर डिसीज़न रिकॉर्ड (एडीआर), एक छोटा, तरज़ीही तौर पर अपरिवर्तनीय नोट जो एक आर्किटेक्चरल रूप से महत्वपूर्ण चुनाव, यह क्यों लिया गया, और इससे क्या निकलता है, दर्ज करता है। किसी परियोजना के अभिलेखों के पूरे सेट को उसका निर्णय-लॉग (एडीएल) कहते हैं, और इन्हें बनाए रखने का अनुशासन आर्किटेक्चर नॉलेज मैनेजमेंट (एकेएम) का हिस्सा है। यह अध्याय अध्याय 1.5 के निर्णय-लेने और शासन के अभ्यासों पर बनता है, इस पर केंद्रित है कि आप बड़े पैमाने पर निर्णय अभिलेख कैसे लिखें, संग्रहीत करें, और बनाए रखें।

प्रेरणा सरल है, और इसे कठिन तरीक़े से सीखना दर्दनाक है। किसी भी लंबे समय तक चलने वाली प्रणाली पर, सबसे महँगा सवाल है “आख़िर यह इस तरह क्यों बनाया गया था?”, जो महीनों या वर्षों बाद उन लोगों द्वारा पूछा जाता है जो उस कमरे में नहीं थे। कोड दिखाता है कि प्रणाली क्या करती है। परीक्षण दिखाते हैं कि यह काम करती है। पर कोई भी यह नहीं बताता कि आपने विचारे गए और अस्वीकृत विकल्पों की तुलना में यह रास्ता क्यों चुना। निर्णय अभिलेखों के बिना, वह तर्क स्टाफ़ के बदलने के साथ वाष्पित हो जाता है। टीमें तय हो चुके सवालों को फिर से लड़ती हैं, ग़लत कारणों से अच्छे फ़ैसले पलट देती हैं, या डर से बुरे फ़ैसले बनाए रखती हैं। निर्णय अभिलेख भविष्य के नाम एक सस्ता पत्र है जो तर्क को सुरक्षित रखता है।

बड़ी टीमों के लिए, यह उतना ही समन्वय-उपकरण है जितना स्मृति-सहायक। उद्यम दर्जनों टीमें चलाते हैं जो अतिव्यापी चुनाव करती हैं। एक साझा निर्णय-लॉग किसी एक टीम की कड़ी मेहनत से अर्जित तर्क को एक पुनःउपयोगी संपत्ति में बदल देता है, और भिन्न, असंगत फ़ैसलों को रोकता है। सरकारी और विनियमित परिवेश में, निर्णय अभिलेख लगभग अनिवार्य हैं। ऑडिटर, निगरानी-निकाय, और उत्तराधिकारी ठेकेदार, सभी को आर्किटेक्चरल रूप से महत्वपूर्ण आवश्यकताओं को उनके ख़िलाफ़ किए गए चुनावों से जोड़ने वाला एक ट्रेस-योग्य तर्क चाहिए। एक अच्छी तरह रखा गया निर्णय-लॉग अक्सर उस प्रणाली के बीच का अंतर होता है जिसे आप सुनिश्चित और ऑडिट कर सकते हैं और उस प्रणाली के बीच जिसे आप नहीं कर सकते।

मुख्य सिद्धांत

• सिर्फ़ क्या नहीं, क्यों दर्ज करें। संदर्भ और अस्वीकृत विकल्प ही मुख्य बात हैं।
• हर अभिलेख में एक फ़ैसला। हर अभिलेख को विशिष्ट और स्वतः-निहित रखें।
• छोटा और हल्का, व्यापक और अप्रयुक्त से बेहतर। एक-पन्ने का अभिलेख जो मौजूद है, उस रिपोर्ट से बेहतर है जो कभी लिखी ही नहीं जाती।
• सब कुछ समय-मुद्रित करें। लागतें, बाधाएँ, और विक्रेता बदलते हैं; हर दावे की तारीख़ दें।
• व्यावहारिक रूप से एक जीवंत लॉग को प्राथमिकता दें। अपरिवर्तनीयता आदर्श है; व्यवहार में, दिनांकित नोटों से संशोधित करें।
• संक्षिप्ताक्षरों से ज़्यादा शब्द। “एडीआर” से ज़्यादा “निर्णय” योगदान को न्योता देता है।
• फ़ैसलों को खोजने-योग्य और, जहाँ संभव हो, परीक्षण-योग्य बनाएँ। सही अभिलेख को सही पल पर सामने लाएँ; फ़िटनेस फ़ंक्शनों से इसे सुनिश्चित करें।

सिफ़ारिशें

आवश्यक संरचना क़ैद करें

एक अच्छे निर्णय अभिलेख में कुछ ज़रूरी खंड होते हैं। ख़ुद कोई ईजाद करने के बजाय किसी जाने-पहचाने टेम्पलेट को अपनाएँ:

• शीर्षक: एक छोटा, वर्तमान-काल का आदेशात्मक वाक्यांश (“लेज़र के लिए PostgreSQL इस्तेमाल करें”)।
• स्थिति: प्रस्तावित, स्वीकृत, अधिक्रमित, अप्रचलित।
• संदर्भ: वह स्थिति, बल, व्यावसायिक प्राथमिकताएँ, और बाधाएँ जो इस फ़ैसले को ज़रूरी बनाती हैं; वह आर्किटेक्चरल रूप से महत्वपूर्ण आवश्यकता शामिल करें जिसे यह संबोधित करता है।
• फ़ैसला: किया गया चुनाव, सीधे-सीधे बताया गया।
• परिणाम: क्या आसान हो जाता है और क्या कठिन, ट्रिगर हुए अनुवर्ती फ़ैसले, और स्वीकृत जोख़िम।

लोकप्रिय टेम्पलेटों में माइकल नाइगार्ड का (सरल और व्यापक रूप से अपनाया गया), टायरी और एकरमैन का (अधिक विस्तृत, भारित विकल्पों के साथ), एमएडीआर (मार्कडाउन एनी डिसीज़न रिकॉर्ड्स, विकल्पों और उनके फ़ायदे-नुक़सान में मज़बूत), और वाई-स्टेटमेंट (एक-वाक्य संरचित रूप) शामिल हैं। हर संगठन में एक पर मानकीकृत करें, ताकि अभिलेख तुलना-योग्य हों। कॉपी-पेस्ट टेम्पलेट के लिए अध्याय 12.3 देखें।

विशिष्ट, दिनांकित, और लगभग-अपरिवर्तनीय अभिलेख लिखें

हर अभिलेख को बिल्कुल एक फ़ैसले के बारे में रखें। अलग-अलग दावों को समय-मुद्रित करें, ख़ासतौर पर वह सब कुछ जो बहता है: क़ीमत, स्केलिंग-संख्याएँ, विक्रेता-क्षमताएँ, लाइसेंस-शर्तें। सिद्धांततः, अभिलेख अपरिवर्तनीय होना चाहिए। जब कोई फ़ैसला बदलता है, आप एक नया अभिलेख लिखते हैं जो पुराने को अधिक्रमित करता है, इतिहास को सुरक्षित रखते हुए। व्यवहार में, कई टीमें पाती हैं कि जीवंत-दस्तावेज़ दृष्टिकोण बेहतर काम करता है: मौजूदा अभिलेख में नई जानकारी को एक दिनांक-मुद्रा और एक नोट के साथ डालना कि यह फ़ैसले के बाद आई। दोनों वैध हैं। अपरिवर्तनीय शैली ऑडिट-ट्रेल के लिए मज़बूत है; जीवंत शैली रोज़मर्रा के टीम-ज्ञान के लिए बेहतर है। जान-बूझकर चुनें, और संगत रहें।

अभिलेख वहाँ रखें जहाँ काम होता है

निर्णय अभिलेखों को कोड के साथ वर्शन-नियंत्रण में रखें: decisions/ (या adr/) निर्देशिका में मार्कडाउन फ़ाइलें, हर फ़ैसले के लिए एक, लोअरकेस, डैश-अलग किए आदेशात्मक क्रिया-वाक्यांश से नामित (choose-database.md, format-timestamps.md)। यह आपको मुफ़्त में इतिहास, समीक्षा, और डिफ़िंग देता है, और तर्क को उसके पास रखता है जिसे यह समझाता है। अगर आपकी टीम विकी, गूगल डॉक्स, या जीरा-शैली ट्रैकर पसंद करती है, तो उनका इस्तेमाल करें। टूल आदत से कहीं कम मायने रखता है। एक हल्का कमांड-लाइन टूल (जैसे adr-tools) अभिलेखों को ढाँचा और सूचीबद्ध कर सकता है।

इन्हें “निर्णय” नाम दें, और आर्किटेक्चर से परे विस्तार करें

कई टीमों से एक व्यावहारिक समझ: लेबल मायने रखता है। कुछ डेवलपर और प्रबंधक “आर्किटेक्चर” शब्द से चिढ़ते हैं, और “रिकॉर्ड” बाद-की-काग़ज़ी-कार्रवाई जैसा महसूस हो सकता है। निर्देशिका को बस “decisions” नाम देना अक्सर एक स्विच पलट देता है। टीमें विक्रेता-चुनाव, योजना-फ़ैसले, समय-निर्धारण-फ़ैसले, डेटा और अनुपालन-फ़ैसले, सब कुछ उसी टेम्पलेट के साथ दर्ज करने लगती हैं। लोग संक्षिप्ताक्षरों से ज़्यादा शब्दों से तेज़ी से सीखते हैं, और जब फ़्रेमिंग “अपने भविष्य के साथियों को सोचने में मदद करो” होती है, न कि “अनिवार्य फ़ॉर्म भरो”, तो वे ज़्यादा योगदान करते हैं।

जीवनचक्र और शासन परिभाषित करें

निर्णय अभिलेखों को पैमाने पर काम करने के लिए, आस-पास की प्रक्रिया पर सहमत हों (यहीं अध्याय 1.5 का शासन अभ्यास से मिलता है):

• कौन कोई अभिलेख उठा सकता है, और क्या इसे उचित ठहराता है: आमतौर पर कोई भी सूचित योगदानकर्ता; तब अभिलेख उठाएँ जब भविष्य के डेवलपरों को क्यों चाहिए होगा, और कम-जोख़िम, स्वतः-निहित, या पहले से दस्तावेज़ित चुनावों के लिए इसे छोड़ दें।
• जीवनचक्र: एक सरल प्रवाह जैसे आरंभ → शोध → मूल्यांकन → कार्यान्वयन → रखरखाव → अवसान, चरणों के बीच बढ़ने के लिए स्वीकृति-मापदंडों के साथ (समस्या स्पष्ट की गई, विकल्प विचारे गए, ट्रेड-ऑफ़ दस्तावेज़ित, हितधारकों से सलाह ली गई)।
• भूमिकाएँ: प्रस्तावक, शोधकर्ता, समीक्षक, अनुमोदक, और एक जवाबदेह मेंटेनर जो अभिलेख की समय-समय पर (कम से कम सालाना) समीक्षा करे और अंततः अवसान की दिशा दे।
• शासन: सहमति, टकराव, वृद्धि (एस्कलेशन), और वीटो कैसे काम करते हैं, और कोई भी अनुपालन-बाधाएँ। क्रिया के लिए पूर्वाग्रह और असहमत-और-प्रतिबद्ध जैसे सिद्धांतों पर टिकें, और भारी प्रक्रिया को न-उलट-सकने-योग्य, बड़े-प्रभाव-दायरे वाले (“एक-तरफ़ा दरवाज़ा”) फ़ैसलों के लिए रखें।

फ़ैसलों को परीक्षण-योग्य और खोजने-योग्य बनाएँ

एक निर्णय अभिलेख किसी फ़ैसले को दस्तावेज़ित करता है; एक फ़िटनेस फ़ंक्शन इसे सुनिश्चित करता है: एक स्वचालित जाँच, सतत एकीकरण (सीआई) में चलाई जाती है, जो सत्यापित करती है कि फ़ैसला अब भी क़ायम है (“सभी स्थिति-परिवर्तनों को इवेंट उत्सर्जित करने चाहिए,” “कोई मॉड्यूल इन सीमाओं के आर-पार आयात नहीं कर सकता”, ArchUnit जैसे टूल इस्तेमाल करते हुए)। यह शासन को समय-समय पर मैनुअल समीक्षा से निरंतर, स्केल-योग्य प्रवर्तन में बदल देता है, जो नियामक और ऑडिट लक्ष्यों (अध्याय 3.1, 4.6, 8.5) के लिए ख़ासतौर पर मूल्यवान है। फिर सही अभिलेख को सही पल पर सामने लाएँ। ऐसी टूलिंग जो किसी पुल-रिक्वेस्ट से प्रासंगिक फ़ैसले जोड़ती है, जब कोई डेवलपर उस कोड को छूता है जिसे वे शासित करते हैं, इस उम्मीद से बेहतर है कि लोग किसी डॉक्स-फ़ोल्डर को पढ़ें।

ट्रेड-ऑफ़: फ़ायदे और नुक़सान

चुनाव	फ़ायदे	नुक़सान
हल्के एडीआर (नाइगार्ड/एमएडीआर)	लिखने में तेज़, वाक़ई लिखे जाते हैं; कम औपचारिकता	ऊँचे-दाँव, विवादित फ़ैसलों के लिए कम कठोरता
भारी टेम्पलेट (टायरी-एकरमैन)	भारित विकल्प; बड़े, महँगे चुनावों के लिए मज़बूत	धीमे; नियमित दर्ज करने को हतोत्साहित कर सकते हैं
अपरिवर्तनीय + अधिक्रमण	स्वच्छ ऑडिट-ट्रेल; इतिहास सुरक्षित	ज़्यादा अभिलेख; पाठकों को शृंखलाएँ ट्रेस करनी पड़ती हैं
जीवंत दस्तावेज़ (दिनांकित संशोधन)	सत्य का एक वर्तमान स्रोत; बनाए रखना आसान	कमज़ोर ऑडिट-कहानी; चुपचाप संपादन का जोख़िम
रिपो-में मार्कडाउन	वर्शन्ड, समीक्षा-योग्य, कोड के पास	ग़ैर-डेवलपरों के लिए कम अनुकूल
विकी / डॉक्स टूल	सभी भूमिकाओं के लिए सुलभ	इतिहास और समीक्षा कमज़ोर; कोड से बहता है

मूल तनाव है कठोरता बनाम अपनाई। सबसे कठोर प्रणाली जिसे कोई इस्तेमाल नहीं करता, कुछ भी दर्ज नहीं करती। सबसे हल्की प्रणाली जिसे सब इस्तेमाल करते हैं, मूल्य में चक्रवृद्धि होती है। डिफ़ॉल्ट रूप से हल्का रखें, और भारी प्रक्रिया उन गिनती के फ़ैसलों के लिए रखें जो महँगे और उलटने में कठिन हैं।

अपनी टीम के साथ चर्चा के लिए प्रश्न

1. सही निर्णय अभिलेख किसी डेवलपर तक उस पल पहुँचेगा जब वे वह कोड छूते हैं जिसे यह शासित करता है, न कि किसी ऐसे फ़ोल्डर में बैठा रहेगा जिसे कोई नहीं खोलता? एक सिर्फ़-लिखने-वाला लॉग ऐसा तर्क दर्ज करता है जो कभी व्यवहार नहीं बदलता, जो निर्णय अभिलेखों के विफल होने का सबसे आम तरीक़ा है: वे मौजूद हैं, और जब मायने रखता है तो कोई उन्हें पढ़ता नहीं। प्रतिस्पर्धी विचार है प्रयास, क्योंकि अभिलेखों को स्वचालित रूप से सामने लाना (जब कोई शासित कोड संपादित करे तो उन्हें पुल-रिक्वेस्ट से जोड़ना) टूलिंग-निवेश माँगता है जो कोई विकी या डॉक्स-फ़ोल्डर नहीं माँगता। चर्चा में प्रमाण लाएँ: जब हाल ही में किसी ने तय हो चुके सवाल को पलटा या फिर से लड़ा, तो क्या उस पल प्रासंगिक अभिलेख खोजने-योग्य था, या दबा हुआ था? दर्जनों टीमें चलाने वाले बड़े संगठन के लिए, खोजने-योग्यता ही वह चीज़ है जो किसी एक टीम की कड़ी मेहनत से अर्जित तर्क को निजी संग्रह के बजाय पुनःउपयोगी संपत्ति में बदलती है। तय करें कि क्या अभिलेखों को कोड के पास वर्शन-नियंत्रण में रखना है और उन्हें पुल-रिक्वेस्ट प्रवाह में जोड़ना है, ताकि अभिलेख वहाँ दिखे जहाँ काम होता है।

2. हर अभिलेख का जवाबदेह मेंटेनर कौन है, और आपके लॉग को आत्मविश्वासी ग़लत-सूचना में सड़ने से क्या रोकता है? निर्णय-लॉग का ख़तरनाक विफलता-तरीक़ा ख़ाली फ़ोल्डर नहीं है, यह ऐसे अभिलेखों से भरा फ़ोल्डर है जिनकी लागतें, विक्रेता-क्षमताएँ, और बाधाएँ चुपचाप वर्षों पहले बासी हो गईं। हर अभिलेख को एक जवाबदेह मालिक चाहिए जो इसे एक लय पर (कम से कम सालाना) समीक्षा करे और अधिक्रमण या अवसान की दिशा दे, वरना लॉग ऐसी लोककथा में सड़ जाता है जिसे लोग चुनिंदा रूप से उद्धृत करते हैं और थोड़ा भरोसा करते हैं। प्रमाण लाएँ: आपके कितने अभिलेख अदिनांकित हैं, कितने किसी ऐसे विक्रेता या क़ीमत का वर्णन करते हैं जो तब से बदल चुकी है, और हर एक की आख़िरी समीक्षा कब हुई। सरकारी और विनियमित परिवेश में यह ज़्यादा तेज़ चलता है, क्योंकि एक अपरिवर्तनीय, अधिक्रमित शृंखला ठीक वही है जिस पर ऑडिटर और उत्तराधिकारी ठेकेदार ट्रेस-योग्य तर्क के लिए निर्भर करते हैं। अपना जीवनचक्र स्पष्ट रूप से तय करें, बहने वाले अलग-अलग दावों को समय-मुद्रित करें, और मेंटेनर सौंपें, ताकि लॉग क़ब्रिस्तान के बजाय जीवंत संपत्ति बना रहे।

3. क्या आपको सभी टीमों में एक टेम्पलेट पर मानकीकृत होना चाहिए, और आपके सबसे ऊँचे-दाँव वाले फ़ैसलों को वाक़ई कितनी कठोरता चाहिए? तुलना-योग्यता एक वास्तविक फ़ायदा है: जब हर टीम एक ही आकार (नाइगार्ड, एमएडीआर, या ऐसा ही) इस्तेमाल करती है, तो एक नई टीम तीन पूर्व अभिलेख ढूँढ सकती है और एक महीने की बहस के बजाय एक दोपहर में तर्क अपना सकती है। मूल तनाव है कठोरता बनाम अपनाई, क्योंकि सबसे भारी टेम्पलेट जिसे कोई इस्तेमाल नहीं करता, कुछ भी दर्ज नहीं करता, जबकि सबसे हल्का जिसे सब इस्तेमाल करते हैं, मूल्य में चक्रवृद्धि होता है। प्रमाण लाएँ: क्या अभिलेख वाक़ई लिखे जा रहे हैं, और अलग से, क्या कोई बड़ा, विवादित, महँगा फ़ैसला कम-विश्लेषित रह गया क्योंकि हल्के रूप ने विकल्प तौलना छोड़ दिया? टीमों में अतिव्यापी चुनाव समन्वित करने वाले उद्यमों के लिए, एक साझा टेम्पलेट और खोजने-योग्य सूचकांक भिन्न, असंगत फ़ैसलों को रोकता है। सामान्य मामले के लिए डिफ़ॉल्ट रूप से हल्का रखें, और पहले से सहमत हों कि कौन-से एक-तरफ़ा-दरवाज़ा फ़ैसलों को भारित विकल्पों वाला भारी रूप चाहिए।

4. कोई निर्णय अभिलेख उठाना वाक़ई क्या उचित ठहराता है, और किसे यह कहने का अधिकार है कि किसी चुनाव को अभिलेख नहीं चाहिए? बार बहुत ऊँचा रखें और गंभीर चुनावों के पीछे का तर्क वाष्पित हो जाता है; बहुत नीचे रखें और लॉग तुच्छ बातों से भर जाता है जो उन अभिलेखों को दबा देती हैं जिनकी लोगों को वाक़ई ज़रूरत है। बड़े संगठन के लिए, अस्पष्ट सीमा का मतलब है कि हर टीम अपनी ख़ुद की सुधारती है, इसलिए कवरेज असमान हो जाता है और कोई भरोसा नहीं कर सकता कि गायब अभिलेख किसी महत्वहीन फ़ैसले का संकेत है। चर्चा में प्रमाण लाएँ: मुट्ठी भर हाल के फ़ैसले जो दर्ज हुए पर होने की ज़रूरत नहीं थी, और दर्दनाक फ़ैसले जो अदर्ज रह गए और बाद में आपको फिर-खोज की क़ीमत चुकानी पड़ी। एक सीधा परीक्षण तय करें, जैसे कि जब भविष्य के किसी डेवलपर को क्यों चाहिए होगा तो दर्ज करें और कम-जोख़िम, स्वतः-निहित, या पहले से दस्तावेज़ित चुनावों को छोड़ दें। विनियमित और सरकारी परिवेश में गणना बदल जाती है, क्योंकि कोई ऑडिट-अधिदेश हर आर्किटेक्चरल रूप से महत्वपूर्ण आवश्यकता के लिए अभिलेख माँग सकता है चाहे टीम इसे लिखने लायक़ समझे या नहीं, इसलिए पहले से नाम दें कि कौन-से फ़ैसले गैर-परक्राम्य हैं।

5. क्या आपके अभिलेख फ़ैसले के पल में क़ैद किया गया असली तर्क हैं, या किसी अधिदेश को संतुष्ट करने के लिए बाद में लिखी गई काग़ज़ी कार्रवाई? किसी टिकट बंद करने के लिए बाद में बना अभिलेख चुने गए विकल्प को धोने और उन विकल्पों को चुपचाप छोड़ने की प्रवृत्ति रखता है जिन्हें वाक़ई तौला गया था, जो ठीक वह जानकारी है जिसकी भविष्य के पाठक को सबसे ज़्यादा ज़रूरत है। प्रतिस्पर्धी दबाव वास्तविक है: फ़ैसले से पहले या दौरान क्यों लिखना शिप करने से धीमा महसूस होता है, और अस्वीकृत रास्तों को लिखित रूप में स्वीकार करना ऐसी मनोवैज्ञानिक सुरक्षा माँगता है जिसकी कुछ टीमों में कमी है। हाल के अभिलेखों का एक नमूना मेज़ पर लाएँ और ईमानदारी से पूछें कि क्या संदर्भ और अस्वीकृत विकल्प असली विचार जैसे पढ़ते हैं या बाद में फ़िट किए गए औचित्य जैसे। बड़ी टीम के लिए, खोखले अभिलेख कोई न होने से बदतर हैं, क्योंकि वे लोगों को सिखाते हैं कि लॉग पर भरोसा नहीं किया जा सकता। उद्यम और सरकारी ऑडिट में यह अंतर तीखा है: निगरानी-निकाय और उत्तराधिकारी ठेकेदार उस तर्क पर निर्भर करते हैं जो वाक़ई विचार किए गए को दर्शाता है, और नाटक जैसा पढ़ने वाला अभिलेख उस सुनिश्चितता को कमज़ोर करता है जिसके लिए लॉग मौजूद है।

6. आपके किन सबसे ऊँचे-दाँव वाले फ़ैसलों को आप एक स्वचालित फ़िटनेस फ़ंक्शन से सुनिश्चित कर सकते हैं, बजाय इस भरोसे के कि समय-समय पर मैनुअल समीक्षा किसी उल्लंघन को पकड़ लेगी? निर्णय अभिलेख किसी चुनाव को दस्तावेज़ित करता है, पर सिर्फ़ सतत एकीकरण में चलाई गई एक स्वचालित जाँच ही उस चुनाव को वर्षों में दर्जनों डेवलपरों द्वारा कोड छूने के साथ चुपचाप घिसने से रोकती है। ट्रेड-ऑफ़ है निवेश, क्योंकि फ़िटनेस फ़ंक्शन (ArchUnit जैसे टूल के साथ) लिखना और बनाए रखना इंजीनियरिंग-समय ख़र्च करता है, और कई फ़ैसले, ख़ासतौर पर प्रक्रिया या विक्रेता-चुनाव, यांत्रिक रूप से परीक्षण-योग्य ही नहीं हैं। प्रमाण लाएँ: किन सीमा-फ़ैसलों (मॉड्यूल-निर्भरता, इवेंट-उत्सर्जन, डेटा-पहुँच-नियम) का उल्लंघन चुपचाप हुआ और सिर्फ़ समीक्षा में या उत्पादन में देर से पकड़ा गया। कई टीमें चलाने वाले उद्यम के लिए, फ़िटनेस फ़ंक्शन शासन को केंद्रीय बाधा से निरंतर प्रवर्तन में बदल देते हैं जो सबको धीमा किए बिना स्केल करता है। विनियमित और सरकारी संदर्भों में, स्वचालित, हमेशा-चालू जाँच किसी समीक्षा पर हस्ताक्षर से कहीं मज़बूत ऑडिट-प्रमाण है, क्योंकि यह साबित करती है कि फ़ैसला आज भी क़ायम है, न कि सिर्फ़ यह कि किसी ने कभी इसे मंज़ूर किया था।

क्षेत्र-लेंस

स्टार्टअप। इसे सिर्फ़ आदत तक और कुछ नहीं तक रखें: अपने मुख्य रिपो में एक decisions/ फ़ोल्डर, और जब भी आप ऐसा फ़ैसला लें जिस पर आपका भविष्य का ख़ुद सवाल उठाएगा, एक दो-खंड वाला नोट (संदर्भ और चुनाव)। जीवनचक्र, भूमिकाएँ, और अनुमोदकों को पूरी तरह छोड़ दें, क्योंकि जो प्रक्रिया आप बनाए नहीं रख सकते वह प्रक्रिया है जिसे आप छोड़ देंगे। वह अकेला अभिलेख जो आपकी पहली भर्ती को यह पूछने से बचाता है कि प्रणाली इस तरह क्यों बनी है, पूरे अभ्यास की क़ीमत पहले ही चुका देता है।

छोटा व्यवसाय। बिना समर्पित आर्किटेक्ट और कम समय के, अभिलेख वहीं रखें जहाँ आपकी टीम पहले से काम करती है, चाहे कोई विकी हो, साझा दस्तावेज़ हो, या रिपो, कोई समर्पित टूल ख़रीदने के बजाय। टूलिंग से कहीं ज़्यादा आदत मायने रखती है, इसलिए बाधा घटाएँ: निर्देशिका को adr के बजाय decisions नाम दें, और विक्रेता व ख़रीदना-बनाम-बनाना चुनावों को तकनीकी चुनावों के साथ उसी साँस में क़ैद करें। जब आप बाहरी ठेकेदारों पर निर्भर हों, आपने कोई विक्रेता या प्लेटफ़ॉर्म क्यों चुना इसका एक छोटा दिनांकित अभिलेख, किसी ऐसे चुनाव में फँस जाने के ख़िलाफ़ सस्ता बीमा है जिसे बाद में कोई समझा नहीं सकता।

उद्यम। काम है कई टीमों में समन्वय: एक टेम्पलेट पर मानकीकृत करें, एक खोजने-योग्य क्रॉस-टीम सूचकांक प्रकाशित करें, और मुख्य सीमा-फ़ैसलों को फ़िटनेस फ़ंक्शनों से समर्थित करें ताकि उल्लंघन समीक्षा का इंतज़ार करने के बजाय बिल्ड फेल कर दें। हर अभिलेख को समीक्षा-लय वाला एक जवाबदेह मेंटेनर सौंपें, ताकि लॉग लोककथा में सड़ने के बजाय जीवंत संपत्ति बना रहे। अच्छी तरह किया गया, किसी कठिन चुनाव पर एक टीम का तर्क वह संपत्ति बन जाता है जिसे अगली टीम फिर से लड़ने के बजाय एक दोपहर में अपना लेती है।

सरकार। ख़रीद-नियम, पारदर्शिता, और सार्वजनिक जवाबदेही निर्णय अभिलेखों को लगभग अनिवार्य बनाते हैं। हर आर्किटेक्चरल रूप से महत्वपूर्ण आवश्यकता के लिए एक अपरिवर्तनीय, अधिक्रमित अभिलेख माँगें, हर एक चुनाव को उस अधिदेश या अनुपालन-नियंत्रण से जोड़ते हुए जिसे यह संतुष्ट करता है, ताकि निगरानी-निकायों को पुनर्निर्माण के बजाय एक ट्रेस-योग्य तर्क मिले। चूँकि सार्वजनिक प्रणालियाँ बहु-वर्षीय, बहु-विक्रेता जीवन-अवधि तक फैली होती हैं, एक अच्छी तरह रखा गया लॉग अक्सर वह चीज़ है जो किसी उत्तराधिकारी ठेकेदार को यह समझने देती है कि प्रणाली जैसी है वैसी क्यों है और तय ज़मीन को फिर से लड़े बिना काम जारी रखने देती है।

उदाहरण

स्टार्टअप। एक पाँच-सदस्यीय स्टार्टअप अपने मुख्य रिपो में एक सादा decisions/ फ़ोल्डर जोड़ता है, जब भी कोई ऐसा फ़ैसला लेता है जिस पर उनका भविष्य का ख़ुद सवाल उठाएगा, एक दो-खंड वाले नोट (संदर्भ और चुनाव) के साथ। कोई जीवनचक्र नहीं, कोई भूमिकाएँ नहीं, कोई अनुमोदक नहीं: बस कोड के पास क्यों लिखने की आदत। छह महीने बाद जब उनकी पहली भर्ती जुड़ती है, वह पूरा फ़ोल्डर एक घंटे में पढ़ लेती है और “यह इस तरह क्यों बना है?” पूछना बंद कर देती है। हल्का लॉग हर प्रविष्टि पर मिनट ख़र्च करता है और उन्हें उस फिर-खोज-कर से बचाता है जो टीम के बड़ा होने से बहुत पहले काटता है।

उद्यम। 30 इंजीनियरिंग टीमों वाला एक रिटेलर हर रिपो में एमएडीआर-प्रारूप वाले अभिलेखों पर मानकीकृत करता है, साथ ही एक खोजने-योग्य केंद्रीय सूचकांक। जब कोई नई टीम ”मोनोरिपो बनाम मल्टीरिपो” का सामना करती है, वे संदर्भ और परिणामों वाले तीन पूर्व अभिलेख पाते हैं, और एक महीने की बहस के बजाय एक दोपहर में तर्क अपना लेते हैं। मुख्य सीमा-फ़ैसले (सेवा-स्वामित्व, डेटा-पहुँच-नियम) ArchUnit फ़िटनेस फ़ंक्शनों से समर्थित हैं, इसलिए उल्लंघन समीक्षा में पकड़े जाने के बजाय बिल्ड फेल कर देते हैं। यह ऐसा शासन है जो बिना केंद्रीय बाधा के स्केल करता है।

सरकार। कोई एजेंसी किसी लाभ-प्रणाली को आधुनिक बनाते हुए हर आर्किटेक्चरल रूप से महत्वपूर्ण आवश्यकता के लिए एक एडीआर माँगती है, हर एक फ़ैसले को उस अधिदेश या अनुपालन-नियंत्रण से जोड़ते हुए जिसे यह संतुष्ट करता है (सुगम्यता, डेटा-निवास, ऑडिटेबिलिटी)। अभिलेख अपरिवर्तनीय और अधिक्रमित हैं, जो एक ट्रेस-योग्य लॉग बनाता है जो निगरानी-समीक्षा को संतुष्ट करता है। महत्वपूर्ण रूप से, यह किसी उत्तराधिकारी ठेकेदार को यह समझने भी देता है कि प्रणाली जैसी है वैसी क्यों है, सार्वजनिक कार्यक्रमों की सामान्य बहु-वर्षीय, बहु-विक्रेता जीवन-अवधि में निरंतरता सुरक्षित रखते हुए (अध्याय 4.6, 10.4)।

व्यवसाय-मामला: प्रेरणाएँ, आरओआई, और टीसीओ

निर्णय अभिलेख लिखने में मिनट लगते हैं और समीक्षा में कुछ और। रिटर्न है टाली गई पुनर्निर्णय लागत और टाली गई ग़लत-पलटाव लागत, दोनों लंबे समय तक चलने वाली प्रणालियों पर बड़ी और बार-बार आने वाली हैं। हर बार जब कोई टीम तय हो चुके सवाल को फिर से लड़ती है, या किसी सही चुनाव को पलट देती है क्योंकि किसी को उसके पीछे की बाधा याद नहीं थी, वे वरिष्ठ-इंजीनियर के समय में और अक्सर किसी घटना में चुकाते हैं। एक निर्णय-लॉग उस बार-बार आने वाले कर को एक-बारगी लेखन में बदल देता है।

स्वामित्व की कुल लागत पर, निर्णय अभिलेख आपके पास रखने-योग्य सबसे ऊँची-उत्तोलन वाली दस्तावेज़ीकरण में से हैं, क्योंकि वे सबसे टर्नओवर-संवेदनशील संपत्ति को निशाना बनाते हैं: तर्क। ऑनबोर्डिंग तेज़ होती है (नई भर्तियाँ सिर्फ़ कोड नहीं, क्यों पढ़ती हैं)। आधुनिकीकरण सुरक्षित होता है (अध्याय 3.6: आप आवश्यक फ़ैसलों को आकस्मिक फ़ैसलों से बता सकते हैं)। ऑडिट सस्ते होते हैं (प्रमाण पहले से मौजूद है)। इन्हें न रखने की लागत किसी डैशबोर्ड पर अदृश्य है, और यह हर प्रस्थान के साथ चुपचाप चक्रवृद्धि होती है। नेतृत्व के सामने मामला बनाने के लिए, किसी हालिया महँगी फिर-खोज, या किसी ऐसे पलटे गए फ़ैसले की ओर इशारा करें जिसने कोई घटना पैदा की, और नोट करें कि इसे संस्थागत बनाने की लागत लगभग कुछ भी नहीं है।

एंटी-पैटर्न और नुक़सान

• क्यों के बिना क्या दर्ज करना: संदर्भ और अस्वीकृत विकल्प छोड़ना, जो कि पूरी बात है।
• बाद-की काग़ज़ी कार्रवाई: ऐसे अभिलेख जो अधिदेश संतुष्ट करने के लिए लिखे गए, सोचने के लिए नहीं; वे खोखले पढ़ते हैं और कोई उन पर भरोसा नहीं करता।
• बहु-फ़ैसला मेगा-दस्तावेज़: एक विशाल पन्ना जिसे कोई साफ़-साफ़ नेविगेट या अधिक्रमित नहीं कर सकता।
• अदिनांकित दावे: लागतें और बाधाएँ जो कभी सच थीं, कालातीत के रूप में पेश।
• चुपचाप संपादन: बिना दिनांकित नोट के किसी फ़ैसले का इतिहास बदलना, ऑडिट-ट्रेल नष्ट करना।
• सिर्फ़-लिखने-वाले लॉग: ऐसे अभिलेख जो बनाए जाते हैं और जिस पल वे प्रासंगिक हों उस पल कभी सामने नहीं आते, इसलिए वे व्यवहार को प्रभावित नहीं करते।
• संक्षिप्ताक्षर-द्वारपाली: “एडीआर” और “आर्किटेक्चर” पर ज़ोर देकर योगदान को हतोत्साहित करना।
• कोई जीवनचक्र नहीं: ऐसे अभिलेख जिनकी कभी समीक्षा, अधिक्रमण, या अवसान नहीं होता, ग़लत-सूचना में सड़ते हुए।

परिपक्वता मॉडल

• स्तर 1 (आरंभ): फ़ैसले लोगों के दिमाग़, चैट-थ्रेड, और कमिट-संदेशों में रहते हैं; क़ैद प्रतिक्रियात्मक और तदर्थ है, और तर्क नियमित रूप से स्टाफ़ के बदलने के साथ खो जाता है।
• स्तर 2 (विकास): कुछ टीमें भिन्न प्रारूपों और टेम्पलेटों में अभिलेख रखती हैं, जब भी किसी व्यक्ति को याद रहे; अभ्यास टीमों में असंगत है, कोई साझा लॉग, नामकरण, या प्रक्रिया नहीं।
• स्तर 3 (मानकीकरण): एक अकेला टेम्पलेट, रिपो-में भंडारण, और एक परिभाषित जीवनचक्र व शासन (उठाने/छोड़ने के मापदंड, भूमिकाएँ, समीक्षा-लय) पूरे संगठन में दस्तावेज़ित और संगत रूप से लागू हैं; अभिलेखों की समीक्षा और अधिक्रमण होता है, चुपचाप संपादन नहीं।
• स्तर 4 (प्रबंधन): निर्णय-लॉग को आधार-रेखाओं के मुक़ाबले मापा जाता है: कवरेज (आर्किटेक्चरल रूप से महत्वपूर्ण फ़ैसलों का वह हिस्सा जो अभिलेख रखता है), ताज़गी (उनकी लय के भीतर समीक्षित अभिलेखों का हिस्सा, साथ ही अदिनांकित या बासी दावों की गिनती), और खोजने-योग्यता (कितनी बार कोई प्रासंगिक अभिलेख वाक़ई उस डेवलपर तक पहुँचा जिसने शासित कोड बदला)। जवाबदेह मेंटेनर इन मेट्रिक्स पर कार्रवाई करते हैं, बासी अभिलेखों को अधिक्रमित करते हुए और कवरेज-अंतरालों को किस्सों के बजाय प्रमाण पर बंद करते हुए।
• स्तर 5 (संयोजन): एक खोजने-योग्य क्रॉस-टीम निर्णय-लॉग रोज़ के काम में एकीकृत है: प्रासंगिक अभिलेख उन बदलावों पर स्वचालित रूप से सामने आते हैं जिन्हें वे शासित करते हैं, मुख्य फ़ैसले सतत एकीकरण में फ़िटनेस फ़ंक्शनों से सुनिश्चित होते हैं, और लॉग ऑनबोर्डिंग, आधुनिकीकरण, और ऑडिट को जीवंत संपत्ति के रूप में सींचता है। संगठन अभ्यास को ही लगातार सुधारता है, प्रणाली और उसकी बाधाएँ बदलने के साथ अभिलेखों को सेवानिवृत्त, अधिक्रमित, और फिर से दायरा देता है, और फ़ैसलों का पोर्टफ़ोलियो बढ़ने के साथ कठोरता में निवेश को फिर से संतुलित करता है।

चर्चा के लिए विचार

1. आपकी टीम ने आख़िरी बार कौन-सा फ़ैसला पलटा या फिर से लड़ा क्योंकि किसी को मूल तर्क याद नहीं था?
2. क्या आपकी adr/ निर्देशिका को decisions/ नाम देना बदल देगा कि कौन योगदान देता है और क्या दर्ज होता है?
3. आपके किन गंभीर फ़ैसलों को आज एक स्वचालित फ़िटनेस फ़ंक्शन से सुनिश्चित किया जा सकता है?
4. अपरिवर्तनीय-और-अधिक्रमण या जीवंत-दस्तावेज़: कौन-सा आपकी ऑडिट-बाध्यताओं और संस्कृति में फ़िट बैठता है, और क्यों?
5. कोई नई भर्ती (या उत्तराधिकारी ठेकेदार) अभी कैसे पता लगाएगी कि आपकी प्रणाली जैसी है वैसी क्यों है?
6. आपकी टीम में निर्णय अभिलेख उठाना क्या उचित ठहराता है, और एक न उठाना क्या उचित ठहराता है?

मुख्य निष्कर्ष

• निर्णय अभिलेख एक महत्वपूर्ण फ़ैसले को उसके संदर्भ और परिणामों के साथ क़ैद करता है: सिर्फ़ क्या नहीं, क्यों।
• अभिलेखों को विशिष्ट, समय-मुद्रित, और हल्का रखें; एक टेम्पलेट (नाइगार्ड, एमएडीआर, या ऐसा ही) पर मानकीकृत करें।
• इन्हें कोड के पास वर्शन-नियंत्रण में रखें; योगदान बढ़ाने के लिए इन्हें “decisions” नाम देने पर विचार करें।
• एक जीवनचक्र और शासन परिभाषित करें (उठाने/छोड़ने के मापदंड, भूमिकाएँ, समीक्षा-लय); एक-तरफ़ा-दरवाज़ा फ़ैसलों के लिए भारी प्रक्रिया रखें।
• फ़ैसलों को बदलाव के पल खोजने-योग्य बनाएँ और जहाँ संभव हो, फ़िटनेस फ़ंक्शनों के ज़रिए परीक्षण-योग्य।
• आरओआई है टाली गई फिर-खोज और ग़लत-पलटाव लागत; टीसीओ-मामला वहाँ सबसे मज़बूत है जहाँ टर्नओवर, आधुनिकीकरण, और ऑडिट सबसे ज़्यादा मायने रखते हैं। अध्याय 1.5 (निर्णय-लेना और शासन) और अध्याय 3.1 (आर्किटेक्चर की बुनियादी बातें) देखें।

संदर्भ और आगे पढ़ने के लिए

• माइकल नाइगार्ड, “डॉक्यूमेंटिंग आर्किटेक्चर डिसीज़न्स” (2011): बुनियादी हल्का एडीआर।
• एमएडीआर: मार्कडाउन एनी डिसीज़न रिकॉर्ड्स परियोजना (adr.github.io/madr)।
• जेफ़ टायरी और आर्ट एकरमैन, “आर्किटेक्चर डिसीज़न्स: डीमिस्टिफ़ाइंग आर्किटेक्चर” (आईईईई सॉफ़्टवेयर, 2005)।
• ओलाफ़ ज़िमरमैन, “वाई-स्टेटमेंट्स” और “आर्किटेक्चरल डिसीज़न मेकिंग” (ozimmer.ch)।
• जोएल पार्कर हेंडरसन, आर्किटेक्चर डिसीज़न रिकॉर्ड (एडीआर): टेम्पलेट, उदाहरण, और टीमवर्क मार्गदर्शन (github.com/joelparkerhenderson/architecture-decision-record)।
• थॉटवर्क्स टेक्नोलॉजी रडार: “लाइटवेट आर्किटेक्चर डिसीज़न रिकॉर्ड्स।”
• नील फ़ोर्ड, रेबेका पार्सन्स, पैट्रिक कुआ, प्रमोद सडालगे, बिल्डिंग इवोल्यूशनरी आर्किटेक्चर्स (फ़िटनेस फ़ंक्शन)।
• एडब्ल्यूएस प्रिस्क्रिप्टिव गाइडेंस, “एडीआर प्रोसेस”; रेड हैट, “व्हाई यू शुड यूज़ एडीआर्स।”
• विकिपीडिया, “आर्किटेक्चरल डिसीज़न” और “आर्किटेक्चरली सिग्निफ़िकेंट रिक्वायरमेंट्स।”