ذاكرة مشروعنا كانت ثقباً أسود: كيف أنقذتنا ‘سجلات القرارات المعمارية’ (ADRs) من جحيم الأسئلة المنسية

السلام عليكم يا جماعة الخير، معكم أخوكم أبو عمر.

قبل كم سنة، كنا شغالين على مشروع ضخم، وكان الفريق يكبر ويتغير. في يوم من الأيام، انضم إلنا مطور جديد، شب شاطر ومتحمس، خلينا نسميه “خالد”. بعد كم يوم من انضمامه، وإجا خالد يسألني سؤال بسيط ومنطقي جداً: “يا أبو عمر، ليش إحنا بنستخدم RabbitMQ كوسيط للرسائل (Message Broker) في خدمة الطلبات، وبنستخدم Kafka في خدمة المستخدمين؟ ليش ما وحدنا التقنية؟”

والله يا جماعة، سؤاله كان زي الكف. سكتت شوي، وحاولت أتذكر. أنا ما كنت الشخص اللي أخذ القرار الأصلي. لفيت على باقي الشباب في الفريق، واحد يرفع كتافه، والثاني يقول “هيك استلمنا المشروع”. دخلنا في دوامة من البحث في سجلات الـ Git، وقنوات Slack القديمة، والـ-wikis المنسية. ضيعنا يومين كاملين، فريق كامل مش عارف يجاوب على سؤال “ليش؟”. حسينا إنه ذاكرة مشروعنا عبارة عن ثقب أسود بيبتلع كل القرارات المهمة وسببها، وبيتركنا في حالة ضياع مع كل تغيير جديد. كانت لحظة مؤلمة، لكنها كانت نقطة التحول اللي خلتنا نكتشف الحل: سجلات القرارات المعمارية (Architecture Decision Records).

ما هي سجلات القرارات المعمارية (ADRs)؟

ببساطة شديدة، الـ ADR هو ملف نصي قصير، زي مذكرة في دفتر يوميات، بيسجل قرار معماري مهم تم اتخاذه في المشروع. الفكرة مش توثيق كل شاردة وواردة، لا. الفكرة هي توثيق القرارات اللي إلها تأثير كبير على النظام، القرارات اللي ممكن يجي حدا بعد سنة ويسأل “ليش عملتوا هيك؟”.

كل سجل (ADR) لازم يجاوب على أسئلة أساسية وبسيطة:

• شو القصة؟ (Context): ما هي المشكلة اللي بنحاول نحلها أو السياق اللي دفعنا لاتخاذ قرار؟
• شو قررنا؟ (Decision): ما هو الحل التقني أو النهج الذي اخترناه؟
• شو رح يترتب على هالقرار؟ (Consequences): ما هي الآثار الإيجابية والسلبية لهذا القرار؟ كل قرار إله ثمن (trade-off)، وهنا لازم نكون شفافين ونسجلها.

هذه هي الأعمدة الثلاثة لأي قرار سليم وموثق.

لماذا كانت ذاكرة مشروعنا ثقباً أسود؟ (المشكلة بالتفصيل)

قبل ما نتبنى الـ ADRs، كنا عايشين في جحيم تقني صامت. المشاكل ما كانت تظهر مرة وحدة، كانت تتراكم شوي شوي زي الغبار، لحد ما صار التنفس في المشروع صعب. هذه بعض الأعراض اللي كنا نعاني منها:

جحيم الموظف الجديد (Onboarding Hell)

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

فقدان ذاكرة الـ “لماذا”

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

عامل الحافلة (The Bus Factor)

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

كيف أنقذتنا الـ ADRs؟ (الحل العملي)

بعد قصة خالد وسؤاله المحوري، قررنا نتبنى الـ ADRs. العملية كانت أبسط مما توقعنا، وهذا سر نجاحها.

الخطوة الأولى: البساطة ثم البساطة

ما احتجنا برامج معقدة أو أدوات غالية. كل اللي عملناه هو إنشاء مجلد جديد في مستودع الـ Git تبعنا اسمه docs/adrs. اتفقنا على صيغة بسيطة باستخدام Markdown. أي حدا بيقدر يقرأها ويكتبها.

نصيحة من أبو عمر: ابعد عن التعقيد. كل ما كانت الأداة أبسط، زاد احتمال استخدام الفريق إلها. ملفات Markdown في Git هي الخيار الأمثل لأنها بتخضع لنفس عملية المراجعة (Code Review) زيها زي الكود.

هذا هو القالب البسيط اللي بدأنا فيه:

# [رقم ADR]. [عنوان القرار]

**التاريخ:** YYYY-MM-DD

**الحالة:** مقترح / مقبول / مرفوض / تم استبداله بـ [رقم ADR آخر]

## السياق (Context)

ما هي المشكلة التي نواجهها؟ ما هي القيود والمتطلبات؟ اشرح القصة وراء الحاجة لاتخاذ هذا القرار.

## القرار (Decision)

ما هو الحل الذي اخترناه؟ كن واضحاً ومحدداً. اشرح الخيار التقني الذي تم اعتماده.

## التبعات (Consequences)

ما هي النتائج المترتبة على هذا القرار؟

*   **الإيجابيات:** (e.g., تحسين الأداء، تقليل التكلفة، سهولة التطوير)
*   **السلبيات:** (e.g., زيادة التعقيد في جزء معين، الاعتماد على تقنية جديدة تحتاج لتدريب)
*   **المقايضات (Trade-offs):** (e.g., ضحينا بسرعة التطوير مقابل استقرار أعلى)

مثال عملي: قرار توحيد وسطاء الرسائل

عشان الصورة تكون أوضح، خلينا نكتب ADR جواباً على سؤال خالد اللي بدأنا فيه القصة.

# 001. توحيد استخدام Kafka كوسيط للرسائل في النظام

**التاريخ:** 2023-10-26

**الحالة:** مقبول

## السياق (Context)

يستخدم نظامنا حالياً تقنيتين لوسطاء الرسائل: RabbitMQ في خدمة الطلبات، و Kafka في خدمة المستخدمين. هذا التباين يؤدي إلى زيادة العبء المعرفي على المطورين الجدد، ويتطلب صيانة وتدريب على نظامين مختلفين، ويزيد من تعقيد البنية التحتية والمراقبة (Monitoring). المطور الجديد "خالد" أثار هذا التساؤل المنطقي، مما دفعنا لمراجعة هذا القرار.

## القرار (Decision)

سنقوم بتوحيد استخدام وسيط الرسائل في كل خدمات المشروع، واعتماد Apache Kafka كالخيار الوحيد. سيتم ترحيل خدمة الطلبات تدريجياً من RabbitMQ إلى Kafka خلال الربع القادم.

## التبعات (Consequences)

*   **الإيجابيات:**
    *   تقليل العبء المعرفي على الفريق. كل المطورين سيركزون على تقنية واحدة.
    *   تبسيط البنية التحتية وعمليات التشغيل (DevOps).
    *   إعادة استخدام الخبرات والحلول المتعلقة بـ Kafka عبر كل المشروع.
    *   Kafka يقدم ضمانات استمرارية (Durability) وأداء أعلى للتعامل مع حجم بيانات كبير، وهو ما نتوقعه مستقبلاً.

*   **السلبيات:**
    *   عملية الترحيل ستتطلب وقتاً وجهداً من الفريق (تقدر بـ 3 أسابيع عمل).
    *   RabbitMQ قد يكون أبسط في بعض حالات الاستخدام (Use Cases) البسيطة، لكن فائدة التوحيد تفوق هذه البساطة.

*   **المقايضات (Trade-offs):**
    *   نحن نضحي بالبساطة التي يوفرها RabbitMQ في بعض السيناريوهات مقابل الحصول على نظام موحد وأكثر قوة وقابلية للتوسع على المدى الطويل.

شايفين كيف؟ بصفحة واحدة، وثقنا قرار مهم، سببه، ونتائجه. الآن لو انضم “سعيد” بعد سنة، وقرأ هذا الملف، سيفهم القصة كاملة بدون ما يسأل حدا.

نصائح من “أبو عمر” لتطبيق الـ ADRs بنجاح

بعد ما طبقنا هاي المنهجية لفترة، جمعت لكم شوية نصائح من خبرتي المتواضعة:

1. ابدأ صغيراً وبالقرارات الجديدة: لا تحاول توثيق كل القرارات القديمة، هاي مهمة مستحيلة ورح تحبطك. “ما ترجع تحرث البحر”. ابدأ بتوثيق أي قرار جديد ومهم من اليوم. مع الوقت، رح تبني مكتبة قيمة.
2. اجعلها عملية جماعية: كتابة الـ ADRs مش وظيفة شخص واحد. لما الفريق يتناقش في قرار، خلوا واحد منهم يكتب مسودة ADR. بعدين الكل يراجعها كجزء من الـ Pull Request. هذا بيضمن إنه الجميع فاهم القرار وموافق عليه.
3. خير الكلام ما قل ودل: الـ ADR لازم يكون مختصر ومباشر. الهدف مش كتابة رواية، الهدف توصيل المعلومة الأساسية. إذا كان طوله أكثر من صفحتين، فغالباً هو معقد أكثر من اللازم.
4. الـ ADR ليس وثيقة تصميم مفصلة: الـ ADR هو عن “لماذا”، وليس عن “كيف” بالتفصيل الممل. تفاصيل التنفيذ مكانها في الكود، والتعليقات، ووثائق التصميم الأخرى إن وجدت.
5. القرارات تتغير، وهذا طبيعي: لا تخاف من تحديث قرار قديم. ممكن تكتشف إنه قرار اتخذته قبل سنة لم يعد مناسباً. في هاي الحالة، اكتب ADR جديد يوضح السياق الجديد والقرار الجديد، وفي خانة الحالة (Status) للـ ADR القديم، اكتب “تم استبداله بـ ADR-00X”. هذا بيخلق سجل تاريخي جميل لتطور بنية نظامك.

الخلاصة: من ثقب أسود إلى ذاكرة حية 💡

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

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