كانت قراراتنا أشباحاً تطاردنا: كيف أنقذتنا ‘سجلات القرارات المعمارية’ (ADRs) من جحيم “لماذا فعلنا ذلك؟”

بتذكر قبل كم سنة، كنا شغالين على مشروع كبير ومهم… فريق جديد، حماس عالي، والكل بده يثبت حاله. مرت الشهور، وسلمنا أول نسخة من المنتج، والوضع كان تمام. بعد سنة، دخل معنا مهندس جديد على الفريق، شب شاطر ومحترم. أول أسبوع إله، وهو بقلّب في الكود، إجاني وسألني: “أبو عمر، بس سؤال… ليش مستخدمين RabbitMQ هون بدل Kafka؟ طبيعة البيانات اللي عنا بتناسب Kafka أكثر بكثير”.

سكتت شوي… حاولت أتذكر النقاش اللي صار قبل سنة ونص. مين كان موجود؟ شو كانت الظروف؟ هل كان في مشكلة معينة مع Kafka وقتها؟ هل كانت مسألة خبرة فريق؟ والله يا جماعة ما قدرت أتذكر إشي. صار كل واحد فينا يرمي تخمين من عنده. “يمكن عشان أسهل في الإعداد”، “لا، يمكن عشان المكتبة الفلانية ما كانت تدعمه وقتها”.

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

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

ببساطة شديدة، الـ ADR هو وثيقة قصيرة، ملف نصي بسيط، يسجل قراراً معمارياً واحداً مهماً في مشروعك. الشغلة مش قصة توثيق معقد وممل من مئات الصفحات. لا، هو مجرد سجل للقرارات المهمة التي تؤثر على شكل النظام على المدى الطويل.

الفكرة الجوهرية ليست في توثيق “ماذا” قررنا، فهذا يظهر في الكود غالباً. الأهم هو توثيق “لماذا” قررنا هذا القرار بالذات، في ظل الظروف التي كنا فيها.

“الـ ADR هو رسالة من فريقك الحالي إلى فريقك المستقبلي (والذي قد تكون أنت نفسك بعد ستة أشهر!)”

لماذا يجب أن نهتم بهذا الموضوع؟ أليس الكود كافياً؟

هذا السؤال سمعته كثيراً. والجواب القصير: لا، الكود ليس كافياً أبداً. الكود يخبرك “كيف” يعمل النظام الآن، لكنه لا يخبرك عن:

• البدائل التي تم رفضها: لماذا اخترنا PostgreSQL ولم نختر MongoDB؟ الكود لن يجيبك.
• السياق والقيود (Context & Constraints): هل كان القرار بسبب ضغط الوقت؟ قلة خبرة الفريق بتقنية معينة؟ متطلبات أداء محددة؟ ميزانية محدودة؟
• “عامل الحافلة” (The Bus Factor): ماذا لو الشخص الوحيد الذي يتذكر سبب القرار ترك الشركة (أو، لا سمح الله، صدمته حافلة)؟ تصبح ذاكرة الفريق في خطر.
• تسهيل انضمام الأعضاء الجدد: بدلاً من أن يقضي المطور الجديد أسابيع في طرح الأسئلة، يمكنه قراءة سجلات القرارات وفهم تاريخ المشروع وتطوره المنطقي.
• تجنب إعادة فتح النقاشات القديمة: كم مرة أعدنا النقاش في نفس الموضوع كل ثلاثة أشهر؟ الـ ADR يضع حداً لهذا الأمر.

بنية سجل القرار المعماري (Anatomy of an ADR)

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

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

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

2. الحالة (Status)

يوضح مرحلة القرار. يمكن أن يكون:

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

3. السياق (Context)

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

4. القرار (Decision)

هنا نذكر بوضوح وبشكل مباشر ما هو القرار الذي تم اتخاذه. هذا هو الجزء الذي يجيب على سؤال “ماذا فعلنا؟”.

5. التبعات (Consequences)

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

مثال عملي: من وحي القصة

لنتخيل أننا عدنا بالزمن للحظة النقاش حول RabbitMQ و Kafka، وقررنا كتابة ADR. كان سيبدو كالتالي:

# ADR-001: استخدام RabbitMQ للمراسلات الأولية بين الخدمات

**الحالة:** مقبول (Accepted)

**التاريخ:** 2021-03-15

**السياق (Context):**
نحتاج إلى نظام مراسلات غير متزامن (asynchronous messaging) للتواصل بين الخدمات المصغرة (microservices). المتطلبات الأولية تتركز حول أنماط بسيطة مثل طوابير المهام (task queues) و RPC. يمتلك الفريق خبرة قوية ومسبقة في RabbitMQ وبروتوكول AMQP.
البديل الرئيسي كان Apache Kafka، وهو قوي جداً في معالجة تدفق البيانات (stream processing). لكن، حالة الاستخدام الحالية لدينا لا تتطلب هذا الحجم من معالجة التدفقات، كما أن تعلم الفريق لـ Kafka ومكوناته (Zookeeper، الأقسام، إلخ) قد يؤدي إلى تأخير في الجدول الزمني للمشروع. التكلفة التشغيلية لإعداد وصيانة RabbitMQ في هذه المرحلة تعتبر أقل بالنسبة لفريقنا الصغير.

**القرار (Decision):**
سنقوم باستخدام RabbitMQ كوسيط الرسائل (message broker) الأساسي في النظام.

**التبعات (Consequences):**
- **إيجابيات:**
  - سرعة في التطوير والتسليم بفضل خبرة الفريق الحالية.
  - تعقيد تشغيلي أولي أقل.
  - مناسب تماماً لأنماط الاستخدام الحالية (طوابير مهام و RPC).

- **سلبيات:**
  - قد لا يكون الخيار الأمثل إذا تطور نظامنا مستقبلاً ليصبح منصة تعتمد بكثافة على تدفق الأحداث (event streaming).
  - الانتقال إلى نظام آخر مثل Kafka في المستقبل سيتطلب مجهوداً كبيراً.
  - نحن نقبل بهذه المخاطرة من أجل تحقيق أهداف التسليم الحالية.

تخيل لو أن المهندس الجديد وجد هذا الملف. كم كان سيوفر علينا من وقت وجهد وحرج؟ كان سيفهم السياق كاملاً في خمس دقائق فقط.

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

من خبرتي، إليك بعض النصائح لتجعل هذه العملية ناجحة وليست مجرد عبء إضافي:

1. ابدأ ببساطة (Keep it Simple): لا تحتاج لأدوات معقدة. أنشئ مجلداً باسم docs/adrs أو architecture/decisions داخل مستودع Git الخاص بك، وابدأ بإنشاء ملفات Markdown بسيطة. الأداة الأهم هي الالتزام.
2. اجعلها جزءاً من عملية الـ Pull Request: هل القرار كبير؟ اكتب ADR جديد أو قم بتحديث واحد قديم كجزء من الـ Pull Request. هذا يضمن أن تتم مراجعة القرار وتوثيقه في نفس الوقت.
3. متى أكتب ADR؟: ليس لكل تغيير صغير. اكتب ADR للقرارات التي:
   • لها تأثير كبير على بنية النظام (Significant).
   • يصعب تغييرها لاحقاً (Hard to reverse).
   • ليست واضحة من الكود نفسه (Non-obvious).
   • (مثال: اختيار لغة برمجة، إطار عمل، قاعدة بيانات، نمط معماري، خدمة سحابية رئيسية).
4. لا تحذف السجلات القديمة أبداً: إذا تغير قرار ما، لا تحذف الـ ADR القديم. قم بتحديث حالته إلى “مُستبدَل” (Superseded) وأنشئ سجلاً جديداً يشرح القرار الجديد وسياقه. التاريخ مهم جداً لفهم تطور المشروع.

الخلاصة: وثّق رحلتك، وليس فقط وجهتك 📜

في النهاية، يا جماعة، بناء البرمجيات هو رحلة مليئة بالقرارات والمقايضات. الـ ADRs ليست مجرد أوراق بيروقراطية، بل هي “سجل رحلة” مشروعك. هي الذاكرة المؤسسية لفريقك التي تحميك من أشباح الماضي وتساعدك على بناء أنظمة أفضل وأكثر استدامة.

لا تدع تاريخ مشروعك يصبح مجموعة من الهمسات المنسية والقرارات الغامضة. ابدأ اليوم، مع أول قرار مهم قادم. اكتب أول ADR لك. فريقك المستقبلي (وأنت المستقبلي) سيشكرك جزيل الشكر. صدقني، عن تجربة.