ذاكرة الفريق هي التوثيق الوحيد: كيف أنقذتنا ‘سجلات القرارات المعمارية’ (ADRs) من جحيم “لماذا فعلنا ذلك؟”

ليلة الكود المنسي: قصة بدأت بكوب قهوة وانتهت بكارثة

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

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

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

في هذيك الليلة، وأنا راجع عالبيت مهدود حيلي، أقسمت إنه هالأشي ما لازم يتكرر. ذاكرة الفريق، وذاكرتي أنا شخصيًا، مش لازم تكون هي الوثيقة الوحيدة. من هون بدأت رحلتي مع أداة بسيطة لكنها غيّرت طريقة عملنا تمامًا: سجلات القرارات المعمارية (Architectural Decision Records – ADRs).

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

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

أهمية الـ ADRs بتكمن في أنها بتحل مشاكل جوهرية بنعاني منها كلنا كمطورين:

• محاربة “المعرفة القبلية” (Tribal Knowledge): بتنقل المعرفة من عقول الأفراد (مثل صاحبنا خالد) إلى وثيقة ثابتة ومتاحة للجميع، اليوم وبكرا وبعد عشر سنين.
• تسهيل انضمام الأعضاء الجدد: لما يجي مطور جديد على الفريق، بدل ما يسأل ألف سؤال عن تاريخ المشروع، بيقدر يقرأ الـ ADRs ويفهم سياق القرارات الأساسية اللي شكّلت النظام.
• توفير “السياق” للمستقبل: أهم سؤال بتجاوب عليه الـ ADRs هو “لماذا؟”. لما تيجي بعد سنة أو سنتين وتفكر تغير قرار معين، بتقدر ترجع للـ ADR الأصلي وتفهم الظروف اللي تم فيها اتخاذ القرار، وهل هاي الظروف تغيرت اليوم ولا لأ. هالأشي بيمنعك من تكرار أخطاء الماضي.
• الهروب من جحيم “لماذا فعلنا ذلك؟”: هاي هي الفائدة الكبرى. بتنهي تمامًا الاجتماعات الطويلة والنقاشات المحتدمة اللي بنحاول فيها نتذكر ليش عملنا الأشي الفلاني بطريقة معينة.

هيكل الـ ADR: كيف تبني سجلاً فعالاً؟

الجميل في الـ ADRs هو بساطتها. ما في قواعد صارمة، بس في قالب مشهور ومجرّب، اقترحه Michael Nygard، وأنا بنصح فيه بشدة. بيتكون من الأجزاء التالية:

نصيحة من أبو عمر: لا تعقّد الأمور. ابدأ بهذا القالب البسيط. المهم هو المضمون، مش الشكل. الهدف هو التوثيق السريع والفعّال.

1. العنوان (Title)

عنوان قصير وواضح للقرار. عادةً بياخد رقم تسلسلي واسم وصفي. مثلاً: “001 – استخدام PostgreSQL كقاعدة بيانات أساسية”.

2. الحالة (Status)

حالة القرار الحالي. ممكن تكون واحدة من التالي:

• مقترح (Proposed): القرار لسا قيد النقاش.
• مقبول (Accepted): تم الاتفاق على القرار وسيتم تنفيذه.
• مرفوض (Rejected): تم رفض هذا الخيار.
• مهمل (Deprecated): كان مقبولاً، ولكنه لم يعد الخيار المفضل.
• مُستبدَل (Superseded by ADR-XXX): تم استبدال هذا القرار بقرار آخر جديد (مع ذكر رقم الـ ADR الجديد).

3. السياق (Context)

هذا هو أهم جزء تقريبًا. هون بتشرح المشكلة اللي بتحاول تحلها. شو هي الظروف؟ شو هي المتطلبات؟ شو هي القيود (Constraints) اللي أثرت على القرار؟

4. القرار (Decision)

هنا تذكر بوضوح وبشكل مباشر ما هو القرار الذي تم اتخاذه. “قررنا استخدام…”، “سنقوم بتنفيذ…”. خليك مباشر ومختصر.

5. العواقب (Consequences)

ما في قرار بدون عواقب، إيجابية كانت أو سلبية. هذا القسم بيجبرك تفكر في تأثير قرارك على المدى الطويل. اذكر هون:

• النتائج الإيجابية: شو بنكسب من هاد القرار؟ (أداء أفضل، صيانة أسهل، تكلفة أقل…).
• النتائج السلبية أو المقايضات (Trade-offs): شو بنخسر أو بنضحي فيه؟ (تعقيد أكبر في النشر، حاجة لتعلم تقنية جديدة، مرونة أقل…). هذا الجزء يظهر نضج الفريق الهندسي.

مثال عملي: ADR لاختيار قاعدة البيانات

عشان الصورة تكون أوضح، تعالوا نكتب ADR كامل لسيناريو شائع جدًا.

# 001: اختيار PostgreSQL كقاعدة بيانات أساسية للمشروع

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

**السياق:**
يحتاج النظام الجديد (منصة تجارة إلكترونية) إلى تخزين بيانات مترابطة بشكل كبير مثل (المستخدمين، الطلبات، المنتجات، الفئات).
نحن بحاجة إلى ضمانات قوية لسلامة البيانات وتناسقها (ACID compliance).
الفريق لديه خبرة سابقة جيدة في قواعد بيانات SQL و NoSQL.
نتوقع الحاجة إلى استعلامات معقدة وتقارير تحليلية في المستقبل تتطلب عمليات ربط (JOINs) متعددة.

**القرار:**
سنعتمد على قاعدة بيانات PostgreSQL كقاعدة بيانات علائقية أساسية للمشروع.
سيتم استخدام نسخة مُدارة (Managed Service) مثل AWS RDS أو Azure Database for PostgreSQL لتقليل العبء التشغيلي على الفريق.

**العواقب:**
*   **إيجابيات:**
    *   ضمان سلامة وتناسق البيانات بفضل دعم ACID الكامل.
    *   قدرات استعلام قوية جدًا باستخدام لغة SQL القياسية، مما يسهل كتابة التقارير المعقدة.
    *   نظام بيئي (Ecosystem) ناضج جدًا مع دعم ممتاز من المكتبات البرمجية وأدوات المطورين في مختلف اللغات.
    *   أداء ممتاز وموثوقية عالية مثبتة في مشاريع ضخمة.
    *   خبرة الفريق السابقة ستقلل من منحنى التعلم.

*   **سلبيات / مقايضات:**
    *   أي تغيير في مخطط قاعدة البيانات (Schema) يتطلب عملية ترحيل (Migration)، مما قد يضيف خطوة إضافية لعملية النشر (CI/CD pipeline).
    *   أقل مرونة في التعامل مع البيانات غير المهيكلة أو سريعة التغير مقارنة بخيارات NoSQL. (يمكننا التفكير في استخدام قاعدة بيانات NoSQL لخدمات محددة في المستقبل إذا دعت الحاجة، مثل سجلات النشاط أو جلسات المستخدمين).

كيف تبدأ بتطبيق الـ ADRs في فريقك؟ نصائح من الميدان

الحماس حلو، بس التطبيق العملي هو الأهم. بناءً على تجربتي، هاي أفضل الطرق للبدء:

1. اجعلها بسيطة جدًا:** لا تحتاج لأي أداة معقدة. كل ما تحتاجه هو مجلد جديد في مستودع الكود (Git repository) الخاص بك، سمّه مثلاً docs/adrs أو architecture/decisions.
2. ملفات Markdown هي صديقك:** استخدم ملفات Markdown (اللي امتدادها .md) لكتابة الـ ADRs. سهلة القراءة، سهلة الكتابة، وبتندمج بشكل رائع مع منصات مثل GitHub و GitLab.
3. اجعلها جزءًا من الـ Workflow:** هل لديكم اجتماع معماري؟ ممتاز، نتيجة الاجتماع لازم تكون ADR جديد أو تحديث لـ ADR قديم. هل تناقشتم في قرار مهم على Pull Request؟ لخصوا النقاش في ADR واربطوه بالـ PR.
4. لا تخف من كتابة ADR “سيء”:** الهدف هو التوثيق، وليس كتابة مقال أدبي. حتى لو كان الـ ADR قصيرًا وبسيطًا، فهو أفضل بمليون مرة من لا شيء. مع الوقت، ستتحسن جودة كتابتكم.
5. وثّق القرارات المرفوضة أيضًا:** أحيانًا، معرفة “لماذا لم نستخدم الخيار X” لا تقل أهمية عن معرفة “لماذا استخدمنا الخيار Y”. هذا يمنع الفريق من إعادة فتح نفس النقاشات في المستقبل.