1.6 سجلات القرار

نظرة عامة والدافع

سجل القرار وثيقة تلتقط قرارًا مهمًا مع سياقه وعواقبه. الشكل الأكثر شهرة هو سجل قرار العمارة (ADR)، ملاحظة قصيرة وثابتة تفضيليًا تسجّل اختيارًا واحدًا مهمًا معماريًا، ولماذا اتُّخذ، وماذا يترتب عليه. مجموعة سجلات المشروع الكاملة هي سجل قراراته (ADL)، وانضباط الاحتفاظ بها جزء من إدارة معرفة العمارة (AKM). يبني هذا الفصل على ممارسات صنع القرار والحوكمة في الفصل 1.5، ويركز على كيفية كتابة سجلات القرار وتخزينها والحفاظ عليها على نطاق واسع.

الدافع بسيط، ومؤلم تعلمه بالطريقة الصعبة. في أي نظام طويل الأمد، السؤال الأكثر تكلفة هو “لماذا بحق السماء بُني هذا هكذا؟”، يُطرَح بعد أشهر أو سنوات من قِبل أشخاص لم يكونوا في الغرفة. تُظهر الشيفرة ماذا يفعل النظام. تُظهر الاختبارات أنه يعمل. لكن لا شيء منهما يلتقط لماذا اخترت هذا المسار على البدائل التي درستها ورفضتها. بدون سجلات القرار، يتبخر ذلك المنطق مع دوران الموظفين. تعيد الفرق التقاضي بشأن أسئلة محسومة، أو تعكس قرارات جيدة لأسباب سيئة، أو تبقي على قرارات سيئة خوفًا. سجل القرار رسالة رخيصة للمستقبل تحفظ المنطق.

بالنسبة للفرق الكبيرة، هذه أداة تنسيق بقدر ما هي أداة ذاكرة. تشغّل المؤسسات عشرات الفرق التي تتخذ اختيارات متداخلة. سجل قرارات مشترك يحوّل منطق فريق واحد المكتسب بشق الأنفس إلى أصل قابل لإعادة الاستخدام، ويمنع قرارات متباينة وغير متوافقة. في الحكومة والبيئات الخاضعة للتنظيم، سجلات القرار قريبة من الإلزام. يحتاج المدققون، وهيئات الرقابة، والمتعاقدون الخلفاء جميعًا إلى منطق قابل للتتبع يربط المتطلبات المهمة معماريًا بالاختيارات المُتخذة مقابلها. سجل قرارات محفوظ جيدًا غالبًا ما يكون الفرق بين نظام يمكنك تأمينه وتدقيقه وآخر لا يمكنك.

المبادئ الأساسية

• سجّل لماذا، لا ماذا فقط. السياق والبدائل المرفوضة هي الهدف.
• قرار واحد لكل سجل. أبقِ كل سجل محددًا ومكتفيًا بذاته.
• الصغير والخفيف يتفوق على الشامل غير المستخدَم. سجل من صفحة واحدة موجود يتفوق على تقرير لا يُكتَب أبدًا.
• ضع طابعًا زمنيًا على كل شيء. التكاليف والقيود والموردون تتغير؛ أرّخ كل ادعاء.
• فضّل سجلًا حيًا، بشكل عملي. الثبات هو المثالي؛ عمليًا، عدّل بملاحظات مؤرخة.
• الكلمات على الاختصارات. “قرارات” تدعو إلى مساهمة أكثر من “ADRs”.
• اجعل القرارات قابلة للاكتشاف، وحيثما أمكن، قابلة للاختبار. أظهر السجل المناسب في اللحظة المناسبة؛ أكّده بدوال اللياقة.

التوصيات

التقط البنية الأساسية

سجل قرار جيد له بضعة أقسام أساسية. كيّف قالبًا معروفًا بدلًا من ابتكار واحد:

• العنوان: عبارة أمرية قصيرة بصيغة المضارع (“استخدم بوستجرس‌كيو‌إل لدفتر الأستاذ”).
• الحالة: مقترح، مقبول، مُستبدَل، متروك.
• السياق: الموقف، القوى، أولويات العمل، والقيود التي تجعل هذا القرار ضروريًا؛ ضمّن المتطلب المهم معماريًا الذي يعالجه.
• القرار: الاختيار المُتَّخذ، معلَنًا ببساطة.
• العواقب: ما يصبح أسهل وما يصبح أصعب، القرارات التالية المُحفَّزة، والمخاطر المقبولة.

تشمل القوالب الشائعة قالب Michael Nygard (بسيط ومعتمد على نطاق واسع)، وقالب Tyree و Akerman (أكثر تفصيلًا، ببدائل موزونة)، وMADR (سجلات قرار ماركداون لأي قرار، قوي في الخيارات وإيجابياتها/سلبياتها)، وعبارات Y (شكل بجملة واحدة منظمة). وحّد على قالب واحد لكل منظمة، حتى تكون السجلات قابلة للمقارنة. انظر الفصل 12.3 لقالب جاهز للنسخ واللصق.

اكتب سجلات محددة، مؤرخة، وشبه ثابتة

أبقِ كل سجل حول قرار واحد بالضبط. أرّخ الادعاءات الفردية، خاصة أي شيء ينجرف: التسعير، أرقام التوسع، قدرات الموردين، شروط الترخيص. نظريًا، ينبغي أن يكون السجل ثابتًا. عندما يتغير قرار، تكتب سجلًا جديدًا يستبدل القديم، محافظًا على التاريخ. عمليًا، تجد فرق كثيرة أن نهج الوثيقة الحية يعمل بشكل أفضل: أدخل معلومات جديدة في السجل الحالي بختم تاريخ وملاحظة بأنها وصلت بعد القرار. كلاهما مشروع. النمط الثابت أقوى لمسارات التدقيق؛ النمط الحي أفضل للمعرفة اليومية للفريق. اختر عن قصد، وكن متسقًا.

خزّن السجلات حيث يحدث العمل

ضع سجلات القرار في التحكم بالإصدار جنبًا إلى جنب مع الشيفرة: دليل decisions/ (أو adr/) من ملفات ماركداون، واحد لكل قرار، مسمّى بعبارة فعل أمرية بأحرف صغيرة مفصولة بشرطات (choose-database.md، format-timestamps.md). هذا يمنحك تاريخًا ومراجعة ومقارنة اختلافات مجانًا، ويبقي المنطق بجانب ما يشرحه. إذا كان فريقك يفضل الويكي، أو مستندات جوجل، أو متعقب على طراز جيرا، استخدم تلك بدلًا من ذلك. الأداة تهم أقل بكثير من العادة. أداة سطر أوامر خفيفة (مثل adr-tools) يمكن أن تُنشئ وتُفهرس السجلات.

سمِّها “قرارات”، ووسّع أبعد من العمارة

بصيرة عملية من فرق كثيرة: التسمية مهمة. يمتعض بعض المطورين والمديرين من كلمة “عمارة”، ويمكن أن يشعر “سجل” بأنه أوراق بعد الحقيقة. إعادة تسمية الدليل ببساطة إلى “قرارات” غالبًا ما يقلب مفتاحًا. تبدأ الفرق بتسجيل اختيارات الموردين، وقرارات التخطيط، وقرارات الجدولة، وقرارات البيانات والامتثال، كلها بنفس القالب. يتعلم الناس أسرع من الكلمات مقارنة بالاختصارات، ويساهمون أكثر عندما يكون الإطار “ساعد زملاءك المستقبليين على التفكير” بدلًا من “املأ النموذج الإلزامي”.

حدد دورة الحياة والحوكمة

لتوسيع سجلات القرار، اتفق على العملية المحيطة (هنا تلتقي حوكمة الفصل 1.5 بالممارسة):

• من يستطيع طرح واحد، وما يبرره: عادة أي مساهم مطّلع؛ اطرح سجلًا عندما سيحتاج المطورون المستقبليون لماذا، وتخطَّه للاختيارات منخفضة المخاطر، المكتفية بذاتها، أو الموثقة بالفعل.
• دورة الحياة: تدفق بسيط مثل البدء ← البحث ← التقييم ← التنفيذ ← الصيانة ← الإنهاء التدريجي، مع معايير قبول للانتقال بين المراحل (المشكلة موضحة، البدائل مدروسة، المفاضلات موثقة، أصحاب المصلحة مستشارون).
• الأدوار: المقترِح، الباحث، المراجِع، المُوافِق، وقائم على الصيانة مسؤول يراجع السجل دوريًا (سنويًا على الأقل) ويقود الإنهاء التدريجي النهائي.
• الحوكمة: كيف يعمل الإجماع، والنزاع، والتصعيد، والنقض، وأي قيود امتثال. اعتمد على مبادئ مثل الانحياز للفعل والاختلاف والالتزام، واحفظ العملية الأثقل للقرارات غير القابلة للعكس وواسعة الأثر (“الباب ذو الاتجاه الواحد”).

اجعل القرارات قابلة للاختبار والاكتشاف

سجل القرار يوثّق قرارًا؛ دالة اللياقة تؤكده: فحص آلي، يعمل في التكامل المستمر (CI)، يتحقق من أن القرار لا يزال قائمًا (“يجب أن تصدر كل تغييرات الحالة أحداثًا”، “لا يجوز لأي وحدة الاستيراد عبر هذه الحدود”، باستخدام أدوات مثل ArchUnit). هذا يحوّل الحوكمة من مراجعة يدوية دورية إلى إنفاذ مستمر وقابل للتوسع، وهو قيّم بشكل خاص لأهداف التنظيم والتدقيق (الفصول 3.1، 4.6، 8.5). ثم أظهر السجل المناسب في اللحظة المناسبة. أدوات ترفق قرارات ذات صلة بطلب سحب، عندما يلمس مطور الشيفرة التي تحكمها، تتفوق على الأمل في أن يقرأ الناس مجلد وثائق.

المفاضلات: الإيجابيات والسلبيات

الاختيار	الإيجابيات	السلبيات
سجلات قرار خفيفة (Nygard/MADR)	سريعة الكتابة، تُكتَب فعليًا؛ شعائر قليلة	صرامة أقل للقرارات عالية المخاطر والمتنازع عليها
قوالب ثقيلة (Tyree-Akerman)	بدائل موزونة؛ قوية للاختيارات الكبيرة والمكلفة	أبطأ؛ يمكن أن تثبط التسجيل الروتيني
الثابت + الاستبدال	مسار تدقيق نظيف؛ تاريخ محفوظ	سجلات أكثر؛ يجب على القراء تتبع السلاسل
الوثيقة الحية (تعديلات مؤرخة)	مصدر واحد حالي للحقيقة؛ سهل الصيانة	قصة تدقيق أضعف؛ خطر تعديلات صامتة
ماركداون داخل المستودع	مُصدَّر، قابل للمراجعة، بجانب الشيفرة	أقل ودية لغير المطورين
أداة ويكي / وثائق	متاحة لكل الأدوار	التاريخ والمراجعة أضعف؛ ينجرف عن الشيفرة

التوتر الأساسي هو الصرامة مقابل التبني. النظام الأكثر صرامة الذي لا يستخدمه أحد لا يسجل شيئًا. النظام الأخف الذي يستخدمه الجميع يتراكم في القيمة. الجأ افتراضيًا إلى الخفيف، واحفظ العملية الأثقل للقرارات القليلة المكلفة والصعبة العكس.

أسئلة للنقاش مع فريقك

1. كيف سيصل سجل القرار الصحيح إلى مطور في لحظة لمسه الشيفرة التي يحكمها، بدلًا من الجلوس في مجلد لا يفتحه أحد؟ السجل الذي يُكتَب فقط ولا يُقرَأ يسجل منطقًا لا يغيّر السلوك أبدًا، وهذه هي الطريقة الأكثر شيوعًا لفشل سجلات القرار: توجد، ولا يقرأها أحد عندما يهم ذلك. الاعتبار المتنافس هو الجهد، لأن إظهار السجلات تلقائيًا (إرفاقها بطلب سحب عندما يعدّل شخص ما الشيفرة المحكومة) يتطلب استثمارًا في الأدوات لا يقدمه ويكي أو مجلد وثائق. اجلب دليلًا إلى النقاش: عندما عكس أحدهم مؤخرًا سؤالًا محسومًا أو أعاد التقاضي بشأنه، هل كان السجل ذو الصلة قابلًا للاكتشاف في تلك اللحظة، أم مدفونًا؟ بالنسبة لمنظمة كبيرة تشغّل عشرات الفرق، القابلية للاكتشاف هي ما يحوّل منطق فريق واحد المكتسب بشق الأنفس إلى أصل قابل لإعادة الاستخدام بدلًا من أرشيف خاص. قرر ما إذا كنت ستخزن السجلات في التحكم بالإصدار بجانب الشيفرة وتربطها بتدفق طلب السحب، حتى يظهر السجل حيث يحدث العمل.

2. من هو القائم على الصيانة المسؤول عن كل سجل، وما الذي يمنع سجلك من التدهور إلى معلومات مضللة واثقة؟ وضع الفشل الخطير لسجل القرارات ليس مجلدًا فارغًا، إنه مجلد مليء بسجلات تكاليفها وقدرات مورديها وقيودها أصبحت قديمة بصمت منذ سنوات. يحتاج كل سجل إلى مالك مسؤول يراجعه على وتيرة (سنويًا على الأقل) ويقود الاستبدال أو الإنهاء التدريجي، وإلا فإن السجل يتعفن إلى فلكلور يستشهد به الناس انتقائيًا ويثقون به قليلًا. اجلب دليلًا: كم من سجلاتك غير مؤرخ، كم منها يصف موردًا أو سعرًا تغير منذ ذلك الحين، ومتى رُوجِع كل واحد آخر مرة. في الإعدادات الحكومية والخاضعة للتنظيم، يصبح هذا أكثر حدة، لأن سلسلة ثابتة ومستبدلة هي بالضبط ما يعتمد عليه المدققون والمتعاقدون الخلفاء لمنطق قابل للتتبع. حدد دورة حياتك صراحة، وأرّخ الادعاءات الفردية التي تنجرف، وعيّن قائمين على الصيانة، حتى يبقى السجل أصلًا حيًا بدلًا من مقبرة.

3. هل ينبغي أن توحّد على قالب واحد عبر كل الفرق، وكم من الصرامة تحتاجها قراراتك الأعلى مخاطرة فعليًا؟ قابلية المقارنة فائدة حقيقية: عندما يستخدم كل فريق نفس الشكل (Nygard، أو MADR، أو مشابه)، يمكن لفريق جديد إيجاد ثلاثة سجلات سابقة وتبني المنطق في بعد ظهر واحد بدلًا من شهر من النقاش. التوتر الأساسي هو الصرامة مقابل التبني، لأن القالب الأثقل الذي لا يستخدمه أحد لا يسجل شيئًا، بينما الأخف الذي يستخدمه الجميع يتراكم في القيمة. اجلب دليلًا: هل تُكتَب السجلات فعليًا، وبشكل منفصل، هل قُلِّل تحليل أي قرارات كبيرة ومتنازع عليها ومكلفة لأن الشكل الخفيف تخطى وزن البدائل؟ بالنسبة للمؤسسات التي تنسق اختيارات متداخلة عبر الفرق، قالب مشترك بالإضافة إلى فهرس قابل للبحث يمنع قرارات متباينة وغير متوافقة. الجأ افتراضيًا إلى الخفيف للحالة الشائعة، واتفق مسبقًا على أي قرارات ذات باب اتجاه واحد تستحق شكلًا أثقل ببدائل موزونة.

4. ما الذي يبرر فعليًا طرح سجل قرار، ومن له السلطة ليقول إن اختيارًا لا يحتاج واحدًا؟ حدد السقف عاليًا جدًا وسيتبخر المنطق وراء الاختيارات المهمة؛ حدده منخفضًا جدًا وسيمتلئ السجل بتفاهات تدفن السجلات التي يحتاجها الناس فعليًا. بالنسبة لمنظمة كبيرة، عتبة غير واضحة تعني أن كل فريق يرتجل عتبته الخاصة، فتصبح التغطية غير متساوية ولا يستطيع أحد الثقة بأن سجلًا مفقودًا يشير إلى قرار غير مهم. اجلب دليلًا إلى النقاش: حفنة من القرارات الحديثة التي سُجّلت لكن لم تكن بحاجة لذلك، وأخرى مؤلمة لم تُسجَّل وكلّفتك لاحقًا إعادة اكتشاف. اتفق على اختبار بسيط، مثل التسجيل كلما احتاج مطور مستقبلي لماذا وتخطي الاختيارات منخفضة المخاطر، المكتفية بذاتها، أو الموثقة بالفعل. في الإعدادات الخاضعة للتنظيم والحكومية، يتحول الحساب، لأن تفويض تدقيق قد يتطلب سجلًا لكل متطلب مهم معماريًا سواء حكم الفريق بأنه يستحق الكتابة أم لا، لذا سمِّ أي القرارات غير قابلة للتفاوض مقدمًا.

5. هل سجلاتك منطق حقيقي التُقط في لحظة القرار، أم أوراق كُتبت بعد ذلك لإرضاء تفويض؟ السجل المُنتَج بعد الحقيقة لإغلاق تذكرة يميل إلى تبييض الخيار المُتخذ وإغفال البدائل التي وُزنت فعليًا بصمت، وهذا بالضبط المعلومات التي يحتاجها القارئ المستقبلي أكثر. الضغط المتنافس حقيقي: كتابة لماذا قبل أو أثناء قرار تبدو أبطأ من التسليم، والاعتراف بالمسارات المرفوضة كتابةً يتطلب أمانًا نفسيًا يفتقر إليه بعض الفرق. اجلب عينة من السجلات الحديثة إلى الطاولة واسأل بصدق ما إذا كان السياق والبدائل المرفوضة تُقرأ كتمحيص حقيقي أم كتبرير مُلفَّق لاحقًا. بالنسبة لفريق كبير، السجلات الجوفاء أسوأ من عدمها، لأنها تعلّم الناس أن السجل لا يمكن الوثوق به. في التدقيق المؤسسي والحكومي هذا التمييز حاد: تعتمد هيئات الرقابة والمتعاقدون الخلفاء على منطق يعكس ما جرى النظر فيه حقًا، والسجل الذي يُقرَأ كمسرحية يقوّض التأكيد الذي وُجد السجل لتوفيره.

6. أي قراراتك الأعلى مخاطرة يمكنك تأكيدها بدالة لياقة آلية، بدلًا من الثقة بأن المراجعة اليدوية الدورية ستكتشف انتهاكًا؟ يوثّق سجل القرار اختيارًا، لكن فقط الفحص الآلي الذي يعمل في التكامل المستمر يمنع ذلك الاختيار من التآكل بصمت مع لمس عشرات المطورين للشيفرة على مدى سنوات. المفاضلة هي الاستثمار، لأن كتابة وصيانة دوال اللياقة (بأدوات مثل ArchUnit) تكلف وقت هندسة، والكثير من القرارات، خاصة اختيارات العملية أو المورد، غير قابلة للاختبار الآلي على الإطلاق. اجلب دليلًا: أي قرارات حدودية (اعتماديات الوحدات، إصدار الأحداث، قواعد الوصول للبيانات) انتُهكت بصمت واكتُشفت فقط متأخرًا في المراجعة أو الإنتاج. بالنسبة لمؤسسة تشغّل فرقًا كثيرة، تحوّل دوال اللياقة الحوكمة من اختناق مركزي إلى إنفاذ مستمر يتوسع دون إبطاء الجميع. في السياقات الخاضعة للتنظيم والحكومية، فحص آلي دائم التشغيل هو دليل تدقيق أقوى بكثير من توقيع على مراجعة، لأنه يثبت أن القرار لا يزال قائمًا اليوم بدلًا من أن أحدهم وافق عليه ذات مرة.

المنظور القطاعي

الشركة الناشئة. أبقِه على العادة ولا شيء آخر: مجلد decisions/ في مستودعك الرئيسي، وملاحظة من قسمين (السياق والاختيار) كلما اتخذت قرارًا ستشكك فيه ذاتك المستقبلية. تخطَّ دورة الحياة، والأدوار، والمُوافِقين تمامًا، لأن العملية التي لا يمكنك الاستمرار فيها هي عملية ستتخلى عنها. السجل الواحد الذي يجنّب موظفك الأول سؤال لماذا بُني النظام هكذا يعوّض بالفعل الممارسة كلها.

الشركة الصغيرة. بدون معماري مخصص ووقت قليل، ضع السجلات حيثما يعمل فريقك بالفعل، سواء ويكي، أو مستند مشترك، أو المستودع، بدلًا من شراء أداة مخصصة. العادة تهم أكثر بكثير من الأدوات، لذا اخفض الحاجز: سمِّ الدليل decisions بدلًا من adr، والتقط اختيارات الموردين والشراء مقابل البناء في نفس النفَس مثل التقنية. عندما تعتمد على متعاقدين خارجيين، سجل قصير ومؤرخ لماذا اخترت موردًا أو منصة تأمين رخيص ضد الوقوع في اختيار لا يستطيع أحد شرحه لاحقًا.

المؤسسة الكبرى. العمل هو التنسيق عبر فرق كثيرة: وحّد على قالب واحد، انشر فهرسًا قابلًا للبحث بين الفرق، وادعم القرارات الحدودية الرئيسية بدوال لياقة حتى تفشل الانتهاكات البناء بدلًا من انتظار المراجعة. عيّن قائمًا على الصيانة مسؤولًا لكل سجل بوتيرة مراجعة، حتى يبقى السجل أصلًا حيًا بدلًا من التدهور إلى فلكلور. بشكل جيد، يصبح منطق فريق واحد بشأن اختيار صعب أصلًا يتبناه الفريق التالي في بعد ظهر واحد بدلًا من إعادة التقاضي.

الحكومة. تجعل قواعد المشتريات، والشفافية، والمساءلة العامة سجلات القرار قريبة من الإلزام. اطلب سجلًا ثابتًا ومستبدلًا لكل متطلب مهم معماريًا، يربط كل واحد الاختيار بالتفويض أو ضابط الامتثال الذي يلبيه، حتى تجد هيئات الرقابة منطقًا قابلًا للتتبع بدلًا من إعادة بناء. ولأن الأنظمة العامة تمتد عبر أعمار متعددة السنوات ومتعددة الموردين، سجل محفوظ جيدًا غالبًا ما يكون ما يتيح لمتعاقد خلف فهم لماذا شُكّل النظام كما هو ومواصلة العمل دون إعادة التقاضي بشأن أرض محسومة.

أمثلة

الشركة الناشئة. تضيف شركة ناشئة من خمسة أشخاص مجلد decisions/ بسيطًا إلى مستودعها الرئيسي، مع ملاحظة من قسمين (السياق والاختيار) كلما اتخذ أحدهم قرارًا ستشكك فيه ذواتهم المستقبلية. لا توجد دورة حياة، ولا أدوار، ولا مُوافِقون: فقط عادة كتابة لماذا بجانب الشيفرة. عندما تنضم أول موظفة لديهم بعد ستة أشهر، تقرأ المجلد بأكمله في ساعة وتتوقف عن سؤال “لماذا بُني هذا هكذا؟” السجل الخفيف يكلف دقائق لكل إدخال ويجنّبهم ضريبة إعادة الاكتشاف التي تعض قبل أن يكبر الفريق بكثير.

المؤسسة الكبرى. يوحّد تاجر تجزئة بثلاثين فريق هندسة على سجلات بصيغة MADR في كل مستودع، بالإضافة إلى فهرس مركزي قابل للبحث. عندما يواجه فريق جديد ”مونوريبو مقابل متعدد المستودعات”، يجدون ثلاثة سجلات سابقة بسياق وعواقب، ويتبنون المنطق في بعد ظهر واحد بدلًا من شهر من النقاش. القرارات الحدودية الرئيسية (ملكية الخدمة، قواعد الوصول للبيانات) مدعومة بدوال لياقة ArchUnit، حتى تفشل الانتهاكات البناء بدلًا من أن تُكتشَف في المراجعة. تلك حوكمة تتوسع دون اختناق مركزي.

الحكومة. تطلب وكالة تحدّث نظام مزايا سجل قرار عمارة لكل متطلب مهم معماريًا، يربط كل واحد القرار بالتفويض أو ضابط الامتثال الذي يلبيه (الوصولية، إقامة البيانات، قابلية التدقيق). السجلات ثابتة ومستبدلة، منتجة سجلًا قابلًا للتتبع يلبي مراجعة الرقابة. وبشكل حاسم، يتيح أيضًا لمتعاقد خلف فهم لماذا شُكّل النظام كما هو، محافظًا على الاستمرارية عبر أعمار متعددة السنوات ومتعددة الموردين النموذجية للبرامج العامة (الفصول 4.6، 10.4).

حالة العمل: الدوافع والعائد على الاستثمار وتكلفة الملكية الإجمالية

يكلف سجل قرار دقائق للكتابة وبضع دقائق أخرى للمراجعة. العائد هو تكلفة إعادة القرار المتجنَّبة وتكلفة العكس الخاطئ المتجنَّبة، وكلاهما كبيران ومتكرران على الأنظمة طويلة الأمد. في كل مرة يعيد فيها فريق التقاضي بشأن سؤال محسوم، أو يعكس اختيارًا سليمًا لأن لا أحد تذكّر القيد وراءه، يدفعون في وقت مهندس أول وغالبًا في حادث. سجل القرارات يحوّل تلك الضريبة المتكررة إلى كتابة لمرة واحدة.

من حيث تكلفة الملكية الإجمالية، سجلات القرار من بين أعلى الوثائق تأثيرًا التي يمكنك الاحتفاظ بها، لأنها تستهدف الأصل الأكثر حساسية لدوران الموظفين: المنطق. الإلحاق أسرع (يقرأ الموظفون الجدد لماذا، لا الشيفرة فقط). التحديث أكثر أمانًا (الفصل 3.6: يمكنك التمييز بين القرارات الجوهرية والعرضية). التدقيقات أرخص (الدليل موجود بالفعل). تكلفة عدم الاحتفاظ بها غير مرئية على أي لوحة، وتتراكم بصمت مع كل رحيل. لتقديم الحجة للقيادة، أشِر إلى إعادة اكتشاف مكلفة حديثة، أو قرار عُكس تسبب في حادث، ولاحظ أن الإصلاح لا يكلف تقريبًا شيئًا لتأسيسه.

الأنماط المضادة والمزالق

• تسجيل ماذا دون لماذا: إغفال السياق والبدائل المرفوضة، الهدف بأكمله.
• أوراق بعد الحقيقة: سجلات كُتبت لإرضاء تفويض، لا للتفكير؛ تُقرَأ كجوفاء ولا يثق بها أحد.
• وثائق ضخمة متعددة القرارات: صفحة عملاقة واحدة لا يستطيع أحد التنقل فيها أو استبدالها بنظافة.
• ادعاءات غير مؤرخة: تكاليف وقيود كانت صحيحة مرة، معروضة كأنها أبدية.
• تعديلات صامتة: تغيير تاريخ قرار دون ملاحظة مؤرخة، مدمرًا مسار التدقيق.
• سجلات تُكتَب فقط: سجلات أُنشئت ولم تُظهَر أبدًا في اللحظة ذات الصلة، لذا لا تؤثر على السلوك.
• حراسة الاختصارات: الإصرار على “ADR” و”عمارة” وبالتالي إحباط المساهمة.
• بدون دورة حياة: سجلات لا تُراجَع أبدًا، أو تُستبدَل، أو تُنهى تدريجيًا، متدهورة إلى معلومات مضللة.

نموذج النضج

• المستوى 1 (البدء): تعيش القرارات في رؤوس الناس، وخيوط الدردشة، ورسائل الالتزام؛ الالتقاط رد فعل ومرتجل، ويُفقَد المنطق روتينيًا مع دوران الموظفين.
• المستوى 2 (التطوير): تحتفظ بعض الفرق بسجلات، بصيغ وقوالب متنوعة، كلما تذكّر فرد ذلك؛ الممارسة غير متسقة عبر الفرق، دون سجل مشترك أو تسمية أو عملية.
• المستوى 3 (التوحيد القياسي): قالب واحد، تخزين داخل المستودع، ودورة حياة وحوكمة محددتان (معايير الطرح/التخطي، الأدوار، وتيرة المراجعة) موثقة ومطبَّقة باتساق على مستوى المنظمة؛ تُراجَع السجلات وتُستبدَل بدلًا من تعديلها صامتًا.
• المستوى 4 (الإدارة): يُقاس سجل القرارات مقابل خطوط أساس: التغطية (نسبة القرارات المهمة معماريًا التي تحمل سجلًا)، الحداثة (نسبة السجلات المُراجَعة ضمن وتيرتها، بالإضافة إلى عدد الادعاءات غير المؤرخة أو البالية)، وقابلية الاكتشاف (كم مرة وصل سجل ذو صلة فعليًا إلى المطور الذي غيّر الشيفرة المحكومة). يتصرف القائمون على الصيانة المسؤولون بناءً على هذه المقاييس، مستبدلين السجلات البالية ومغلقين فجوات التغطية بناءً على الأدلة لا الحكايات.
• المستوى 5 (التنسيق): يُدمَج سجل قرارات قابل للبحث بين الفرق في العمل اليومي: تظهر السجلات ذات الصلة تلقائيًا على التغييرات التي تحكمها، وتُؤكَّد القرارات الرئيسية بدوال لياقة في التكامل المستمر، ويغذي السجل الإلحاق والتحديث والتدقيق كأصل حي. تحسّن المنظمة الممارسة نفسها باستمرار، متقاعدة ومستبدلة ومعيدة تحديد نطاق السجلات مع تغير النظام وقيوده، ومعيدة موازنة أين تستثمر الصرامة مع نمو محفظة القرارات.

أفكار للنقاش

1. ما آخر قرار عكسه فريقك أو أعاد التقاضي بشأنه لأن لا أحد تذكّر المنطق الأصلي؟
2. هل ستغير إعادة تسمية دليل adr/ إلى decisions/ من يساهم وما يُسجَّل؟
3. أي قراراتك الحرجة يمكن تأكيدها بدالة لياقة آلية اليوم؟
4. ثابت-ومستبدَل أو وثيقة حية: أيهما يناسب التزامات التدقيق لديك وثقافتك، ولماذا؟
5. كيف سيكتشف موظف جديد (أو متعاقد خلف) حاليًا لماذا شُكّل نظامك بالطريقة التي هو عليها؟
6. ما الذي يبرر طرح سجل قرار في فريقك، وما الذي يبرر عدم طرح واحد؟

النقاط الرئيسية

• سجل القرار يلتقط قرارًا مهمًا واحدًا مع سياقه وعواقبه: لماذا، لا ماذا فقط.
• أبقِ السجلات محددة، مؤرخة، وخفيفة؛ وحّد على قالب واحد (Nygard، MADR، أو مشابه).
• خزّنها في التحكم بالإصدار بجانب الشيفرة؛ فكّر في تسميتها “قرارات” لتوسيع المساهمة.
• حدد دورة حياة وحوكمة (معايير الطرح/التخطي، الأدوار، وتيرة المراجعة)؛ احفظ العملية الثقيلة لقرارات الباب ذي الاتجاه الواحد.
• اجعل القرارات قابلة للاكتشاف في لحظة التغيير وحيثما أمكن قابلة للاختبار عبر دوال اللياقة.
• العائد هو إعادة الاكتشاف والعكس الخاطئ المتجنَّبان؛ حالة تكلفة الملكية الإجمالية أقوى حيث يهم دوران الموظفين والتحديث والتدقيق أكثر. انظر الفصل 1.5 (صنع القرار والحوكمة) والفصل 3.1 (أسس العمارة).

المراجع والقراءات الإضافية

• Michael Nygard, “Documenting Architecture Decisions” (2011): سجل القرار الخفيف التأسيسي.
• مشروع MADR: Markdown Any Decision Records (adr.github.io/madr).
• Jeff Tyree و Art Akerman, “Architecture Decisions: Demystifying Architecture” (IEEE Software، 2005).
• Olaf Zimmermann, “Y-Statements” و”Architectural Decision Making” (ozimmer.ch).
• Joel Parker Henderson, Architecture Decision Record (ADR): قوالب، أمثلة، وإرشادات عمل جماعي (github.com/joelparkerhenderson/architecture-decision-record).
• ThoughtWorks Technology Radar: “Lightweight Architecture Decision Records.”
• Neal Ford, Rebecca Parsons, Patrick Kua, Pramod Sadalage, Building Evolutionary Architectures (دوال اللياقة).
• AWS Prescriptive Guidance, “ADR process”؛ Red Hat, “Why you should use ADRs.”
• ويكيبيديا، “Architectural decision” و”Architecturally significant requirements.”