سجل قرارات تصميم يشرح لماذا اختير هذا المسار البرمجي

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

وثّق اختياراً مهماً في ملف مستقل

ابدأ بملفات Markdown تحمل معرفاً وعنواناً وتاريخاً وحالة، ثم أقساماً للسياق والقرار والبدائل والعواقب. «استخدم PostgreSQL» وحدها ليست ملاحظة مفيدة؛ يحتاج القارئ معرفة متطلبات النسخة التي قادت للفكرة وما الذي لم يحله الاختيار. لا تسجل كل قرار صغير في الكود. اختر التغيير الذي يؤثر في حدود المكونات أو يصعب عكسه، واكتب مَن راجعه إذا كان الفريق يعتمد هذا الحقل. تبقى النصوص قابلة للتعديل في Git بدلاً من أن تختفي خلف خدمة مغلقة.

يعرف MADR سجل القرار المعماري بوصفه توثيقاً موجزاً لاختيار مبرر ويقدم قالباً بموضوع واحد. ويناقش Michael Nygard في مقاله عن توثيق القرارات الاحتفاظ بالسياق والنتيجة في وحدات صغيرة يسهل تحديثها. يمكن للفريق اختيار قالب مختلف، لكنه يثبت الإصدار أو الحقول كي لا يفسر المحلل عناويناً غير متوقعة بصمت.

اجعل الحالة والعلاقة صريحتين

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

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

مثال اختيار بين تخزينين

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

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

اعرض العلاقات دون شبكة مربكة

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

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

تحقق من سلامة السجل والفهرس

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

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

مخرجات قابلة للنقل بين الفرق

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

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