سجل قرار البنية المعمارية (ADR)
قوالب وأمثلة وإرشادات لتوثيق قرارات البنية المعمارية.
سجل قرار البنية المعمارية (ADR) وثيقة تدوّن قرارًا معماريًا مهمًا اتُّخذ مع سياقه ونتائجه.
اللغة: العربية, Български, भोजपुरी, বাংলা, Čeština, Cymraeg, Dansk, Deutsch, Ελληνικά, English, Español, Eesti, Euskara, فارسی, Suomi, Français, Gaeilge, Gàidhlig, ગુજરાતી, Hausa, עברית, हिन्दी, Hrvatski, Magyar, Bahasa Indonesia, Íslenska, Italiano, 日本語, Basa Jawa, ខ្មែរ, ಕನ್ನಡ, 한국어, kernewek, Lëtzebuergesch, ລາວ, Lietuvių, Latviešu, मराठी, Bahasa Melayu, Malti, Norsk bokmål, Nederlands, ਪੰਜਾਬੀ, Naijá, Polski, Português, Română, Русский, Scots, Slovenčina, Slovenščina, Svenska, Kiswahili, தமிழ், తెలుగు, ไทย, Filipino, Türkçe, Українська, اردو, Tiếng Việt, 吴语, 粵語, 中文
- ما هو سجل قرار البنية المعمارية؟
سجل قرار البنية المعمارية (architecture decision record، ويُختصر ADR) هو وثيقة تدوّن قرارًا معماريًا مهمًا مع سياقه وعواقبه.
- كيف تبدأ باستخدام سجلات ADR
لتبدأ باستخدام سجلات ADR، ناقش مع زملائك في الفريق المجالات التالية.
- اقتراحات لكتابة سجلات ADR جيدة
المبرّر (Rationale): اشرح أسباب اتخاذ قرار AD المعيّن. وقد يشمل ذلك السياق (انظر أدناه)، ومزايا الخيارات المحتملة المختلفة وعيوبها، ومقارنات الميزات، ومناقشات التكلفة…
- قوالب أمثلة ADR
قالب ADR من Michael Nygard (بسيط وشائع)
- نصائح العمل الجماعي لسجلات ADR
إذا كنت تفكر في استخدام سجلات القرارات مع فريقك، فهذه بعض النصائح التي تعلمناها من العمل مع فرق كثيرة.
- دوال الملاءمة للقرارات بوصفها شيفرة
دوال الملاءمة (fitness functions) هي فحوص آلية موضوعية، مكتوبة بشيفرة برمجية، تتحقق من أن القرارات يجري الالتزام بها.
أجرِ العناية الواجبة بنفسك على هذه الموارد قبل استخدامها في أي أنظمة حرجة.
المحتويات:
- ما هو سجل قرار البنية المعمارية؟
- كيف تبدأ باستخدام سجلات ADR
- كيف تبدأ باستخدام سجلات ADR مع الأدوات
- كيف تبدأ باستخدام سجلات ADR مع git
- مهارات Claude Code لسجلات ADR
- اصطلاحات تسمية الملفات
- اقتراحات لكتابة سجلات ADR جيدة
- قوالب أمثلة ADR
- نصائح العمل الجماعي لسجلات ADR
- أسئلة العمل الجماعي لسجلات ADR
- مفاهيم الخطوة التالية لسجلات ADR
- مخططات البنية المعمارية والمناظير ووجهات النظر
- دوال الملاءمة للقرارات بوصفها شيفرة
- حواجز حماية القرارات لطلبات السحب
- لمزيد من المعلومات
القوالب:
- قالب سجل القرار من Jeff Tyree وArt Akerman
- قالب سجل القرار من Michael Nygard
- قالب سجل القرار من EdgeX
- قالب سجل القرار من arc42
- قالب سجل القرار للنمط الإسكندري
- قالب سجل القرار لدراسة الجدوى
- قالب سجل القرار لمشروع MADR
- قالب سجل القرار باستخدام Planguage
- قالب سجل القرار من Paulo Merson
- قالب سجل القرار من Olaf Zimmermann
- قالب سجل القرار من Gareth Morgan
- قالب سجل القرار من GIG Cymru NHS Wales
- قالب سجل القرار للقرارات التقنية المهمة (ITD) من Ignacio Larrañaga
الأمثلة:
- إطار CSS
- الإعداد بمتغيرات البيئة
- المقاييس والمراقبة والتنبيهات
- Microsoft Azure DevOps
- مستودع واحد مقابل مستودعات متعددة
- لغات البرمجة
- تخزين الأسرار
- صيغة الطابع الزمني
- المزيد...
ما هو سجل قرار البنية المعمارية؟
سجل قرار البنية المعمارية (architecture decision record، ويُختصر ADR) هو وثيقة تدوّن قرارًا معماريًا مهمًا مع سياقه وعواقبه.
قرار البنية المعمارية (architecture decision، ويُختصر AD) هو خيار تصميمي برمجي يعالج متطلبًا جوهريًا.
سجل قرارات البنية المعمارية (architecture decision log، ويُختصر ADL) هو مجموعة كل سجلات ADR التي أُنشئت وصُينت لمشروع (أو مؤسسة) معيّن.
المتطلب ذو الأثر المعماري (architecturally-significant requirement، ويُختصر ASR) هو متطلب له أثر قابل للقياس في البنية المعمارية للنظام البرمجي.
وكل ذلك يندرج تحت موضوع إدارة المعرفة المعمارية (architecture knowledge management، ويُختصر AKM).
الغاية من هذه الوثيقة تقديم نظرة سريعة على سجلات ADR، وكيفية إنشائها، وأين تجد مزيدًا من المعلومات.
الاختصارات:
AD: قرار البنية المعمارية
ADL: سجل قرارات البنية المعمارية
ADR: سجل قرار البنية المعمارية
AKM: إدارة المعرفة المعمارية
ASR: المتطلب ذو الأثر المعماري
كيف تبدأ باستخدام سجلات ADR
لتبدأ باستخدام سجلات ADR، ناقش مع زملائك في الفريق المجالات التالية.
تحديد القرارات:
ما مدى استعجال قرار البنية المعمارية (AD) وما مدى أهميته؟
هل يجب اتخاذه الآن، أم يمكن أن ينتظر حتى يُعرف المزيد؟
يمكن للخبرة الشخصية والجماعية، إضافةً إلى أساليب التصميم وممارساته المعترف بها، أن تساعد في تحديد القرارات.
من الأفضل الاحتفاظ بقائمة مهام للقرارات تكمّل قائمة مهام المنتج.
اتخاذ القرارات:
توجد تقنيات عديدة لاتخاذ القرارات، منها العامة ومنها الخاصة بالبنية المعمارية للبرمجيات، مثل رسم خرائط الحوار.
اتخاذ القرارات الجماعي موضوع بحثي نشط.
تنفيذ القرارات وإنفاذها:
تُستخدم قرارات AD في تصميم البرمجيات؛ ولذلك يجب إبلاغها إلى أصحاب المصلحة في النظام ممن يموّلونه ويطوّرونه ويشغّلونه، وأن يقبلوها.
أساليب الترميز الواضحة معماريًا ومراجعات الشيفرة التي تركّز على الاعتبارات والقرارات المعمارية ممارستان ذواتا صلة.
ويجب أيضًا (إعادة) النظر في قرارات AD عند تحديث نظام برمجي أثناء تطوره.
مشاركة القرارات (اختياري):
تتكرر كثير من قرارات AD عبر المشاريع.
ومن ثمّ يمكن لخبرات القرارات السابقة، الجيدة منها والسيئة، أن تكون أصولًا قيّمة قابلة لإعادة الاستخدام عند اعتماد استراتيجية صريحة لإدارة المعرفة.
توثيق القرارات:
توجد قوالب وأدوات كثيرة لتدوين القرارات.
انظر المجتمعات الرشيقة، مثل سجلات ADR لدى M. Nygard.
انظر عمليات هندسة البرمجيات وتصميم البنية المعمارية التقليدية، مثل تخطيطات الجداول التي اقترحتها IBM UMF وكلٌّ من Tyree وAkerman من CapitalOne.
لمزيد من المعلومات:
- الخطوات أعلاه مقتبسة من مدخل ويكيبيديا عن القرار المعماري
كيف تبدأ باستخدام سجلات ADR مع الأدوات
- MySpec — منصة آلية للمواصفات والقرارات المعمارية تنظّم دستور المشروع والبنية التقنية وسجلات ADR في Markdown نظيف يُقدَّم عبر MCP.
يمكنك البدء باستخدام سجلات ADR مع الأدوات بأي طريقة تشاء.
على سبيل المثال:
إذا كنت تحب استخدام Google Drive والتحرير عبر الإنترنت، يمكنك إنشاء مستند Google Docs أو جدول بيانات Google Sheets.
إذا كنت تحب استخدام التحكم في إصدارات الشيفرة المصدرية، مثل git، يمكنك إنشاء ملف لكل سجل ADR.
إذا كنت تحب استخدام أدوات تخطيط المشاريع، مثل Atlassian Jira، يمكنك استخدام متتبّع التخطيط في الأداة.
إذا كنت تحب الويكي، مثل MediaWiki، يمكنك إنشاء ويكي لسجلات ADR.
كيف تبدأ باستخدام سجلات ADR مع git
إذا كنت تحب استخدام نظام التحكم في الإصدارات git، فهذه هي الطريقة التي نفضّلها للبدء باستخدام سجلات ADR مع git في مشروع برمجي نموذجي له شيفرة مصدرية.
أنشئ مجلدًا لملفات ADR:
$ mkdir adr
لكل سجل ADR، أنشئ ملفًا نصيًا، مثل database.txt:
$ vi database.txt
اكتب في السجل ما تشاء. راجع القوالب الموجودة في هذا المستودع للاستلهام.
أودِع السجل (commit) في مستودع git الخاص بك.
مهارات Claude Code لسجلات ADR
يوفّر هذا المستودع مهارتين من Claude Code ضمن skills/، ليتمكن وكيل برمجة بالذكاء الاصطناعي من كتابة سجلات ADR وصيانتها بالطريقة التي يوصي بها هذا المشروع:
architecture-decision-record-skill— للأغراض العامة، لكل من يكتب سجل ADR في أي مشروع. تساعد في تقرير ما إذا كان القرار يحتاج إلى سجل ADR، وتنشئ مجلدadr/أوdecisions/، وتسمّي الملف، وتختار قالبًا من الهياكل الأحد عشر المرفقة، وتكتب أقسام السياق/القرار/النتائج بإحكام.architecture-decision-record-maintainer-skill— لمشرفي هذا المستودع تحديدًا. توثّق بنية المستودع واصطلاح مطابقة README/locales، والخطوات الدقيقة لإضافة قالب أو مثال أو رابط أداة جديد.
لاستخدام مهارة، انسخ مجلدها إلى .claude/skills/ في جذر المستودع الذي تعمل عليه (أو إلى ~/.claude/skills/ لإتاحتها في كل مشروع)، ثم اطلب من Claude Code كتابة سجل ADR أو مراجعته.
اصطلاحات تسمية الملفات
إذا اخترت إنشاء سجلات ADR باستخدام ملفات نصية عادية، فقد ترغب في وضع اصطلاحك الخاص لتسمية ملفات ADR.
نفضّل اصطلاحًا لتسمية الملفات له صيغة محددة.
أمثلة:
choose-database.md
format-timestamps.md
manage-passwords.md
handle-exceptions.md
اصطلاحنا في تسمية الملفات:
يتضمن الاسم عبارة فعلية بصيغة الأمر في زمن المضارع. هذا يحسّن قابلية القراءة ويتوافق مع صيغة رسائل الإيداع (commit) لدينا.
يستخدم الاسم الأحرف الصغيرة والشرطات (مثل هذا المستودع). وهذا توازن بين قابلية القراءة وسهولة الاستخدام في النظام.
الامتداد هو markdown. وقد يفيد هذا في تنسيق سهل.
اقتراحات لكتابة سجلات ADR جيدة
خصائص سجل ADR الجيد:
المبرّر (Rationale): اشرح أسباب اتخاذ قرار AD المعيّن. وقد يشمل ذلك السياق (انظر أدناه)، ومزايا الخيارات المحتملة المختلفة وعيوبها، ومقارنات الميزات، ومناقشات التكلفة والفائدة، وغير ذلك.
المحدَّد (Specific): ينبغي أن يتناول كل سجل ADR قرار AD واحدًا، لا عدة قرارات.
الطوابع الزمنية (Timestamps): بيّن متى كُتب كل عنصر في السجل. وهذا مهم خصوصًا للجوانب التي قد تتغير بمرور الوقت، مثل التكاليف والجداول الزمنية والتوسّع وما شابه.
غير القابل للتعديل (Immutable): لا تغيّر المعلومات الموجودة في السجل. بل عدِّل السجل بإضافة معلومات جديدة، أو استبدله بإنشاء سجل ADR جديد.
خصائص قسم «السياق» الجيد في سجل ADR:
اشرح وضع مؤسستك وأولوياتها التجارية.
ضمّن المبررات والاعتبارات المبنية على التركيبة الاجتماعية والمهارية لفرقك.
ضمّن المزايا والعيوب ذات الصلة، وصفها بعبارات تتوافق مع احتياجاتك وأهدافك.
خصائص قسم «العواقب» الجيد في سجل ADR:
اشرح ما يترتب على اتخاذ القرار. وقد يشمل ذلك الآثار والنتائج والمخرجات والمتابعات وغير ذلك.
ضمّن معلومات عن أي سجلات ADR لاحقة. من الشائع نسبيًا أن يستدعي سجل ADR واحد الحاجة إلى سجلات أخرى، كأن يتخذ سجل قرارًا عامًا كبيرًا ينشئ بدوره الحاجة إلى قرارات أصغر.
ضمّن أي عمليات مراجعة بعد التنفيذ. من المعتاد أن تراجع الفرق كل سجل ADR بعد شهر، لمقارنة معلومات السجل بما حدث فعليًا في الممارسة، بغرض التعلم والنمو.
يمكن لسجل ADR جديد أن يحلّ محل سجل سابق:
- عندما يُتخذ قرار AD يستبدل سجل ADR سابقًا أو يُبطله، ينبغي إنشاء سجل ADR جديد
قوالب أمثلة ADR
قوالب أمثلة ADR التي جمعناها من الإنترنت:
قالب ADR من Michael Nygard (بسيط وشائع)
قالب ADR من Jeff Tyree وArt Akerman (أكثر تطورًا)
قالب ADR لنمط Alexandrian (بسيط مع تفاصيل السياق)
قالب ADR لحالة العمل (أقرب إلى منظور إدارة الأعمال، مع التكاليف وتحليل SWOT وآراء أكثر)
قالب ADR لمشروع Markdown Any Decision Records (MADR) (نسختان بسيطة ومفصلة؛ وتؤكد الثانية الخيارات ومزاياها وعيوبها)
قالب ADR باستخدام Planguage (أقرب إلى ضمان الجودة)
قالب القرارات التقنية المهمة (ITD) من Ignacio Larrañaga (مختصر ويبدأ بالقرار، ومُحسَّن للمراجعة التنفيذية السريعة)
نصائح العمل الجماعي لسجلات ADR
إذا كنت تفكر في استخدام سجلات القرارات مع فريقك، فهذه بعض النصائح التي تعلمناها من العمل مع فرق كثيرة.
أمامك فرصة لقيادة زملائك بالحديث معًا عن «السبب»، بدلًا من فرض «الماهية». فمثلًا، سجلات القرارات وسيلة للفرق كي تفكر بذكاء أكبر وتتواصل بصورة أفضل؛ ولا قيمة لها إن كانت مجرد متطلب ورقي مفروض بعد وقوع الأمر.
تفضّل بعض الفرق اسم «القرارات» (decisions) كثيرًا على الاختصار «ADR». وحين تستخدم بعض الفرق اسم المجلد «decisions» يكون الأمر كمن أُضيء له مصباح، فيبدأ الفريق بوضع مزيد من المعلومات في المجلد، مثل قرارات الموردين وقرارات التخطيط وقرارات الجدولة وغيرها. وكل هذه الأنواع من المعلومات يمكن أن تستخدم القالب نفسه. ونفترض أن الناس يتعلمون أسرع بالكلمات («القرارات») منهم بالاختصارات («ADR»)، وأنهم أكثر حماسًا لكتابة وثائق العمل الجارية عند إزالة كلمة «سجل»، وأن بعض المطورين وبعض المديرين يكرهون أيضًا كلمة «بنية معمارية».
من الناحية النظرية، عدم قابلية التعديل مثالية. أما في الممارسة، فقد نجحت قابلية التعديل أكثر مع فرقنا. فنحن ندرج المعلومات الجديدة في سجل ADR القائم، مع ختم تاريخ وملاحظة بأن المعلومات وصلت بعد القرار. ويؤدي هذا النهج إلى «وثيقة حية» يمكننا جميعًا تحديثها. وتحدث التحديثات النموذجية عندما نحصل على معلومات بفضل زملاء جدد، أو عروض جديدة، أو نتائج واقعية لاستخداماتنا، أو بعد تغييرات لاحقة لدى أطراف ثالثة، مثل قدرات الموردين وخطط التسعير واتفاقيات الترخيص وغيرها.
أسئلة العمل الجماعي لسجلات ADR
من يستطيع إنشاء سجل ADR؟
فكّر في جوانب مثل أشخاص بعينهم، أو أدوار بعينها، أو فرق بعينها، أو أقسام بعينها؛ وفكّر أيضًا فيما إذا كان هناك أشخاص أو أدوار أو فرق أو أقسام يمكنها تكليف إنشاء سجل ADR، أي أن تطلب سجلًا يكتبه شخص آخر.
مثال على إجابة: يمكن لأي شخص في مؤسستنا قرأ صفحة README الخاصة بسجل قرار البنية المعمارية أن يقترح سجل ADR، أي أن يبدأ بكتابته ويشاركه مع الفريق.
ما الذي يبرّر إنشاء سجل ADR؟
فكّر في جوانب مثل طرائق عمل الفرق في مؤسستك، وبنية نظامك البرمجي، والتنسيق بين الفرق، وقابلية الصيانة على المدى البعيد، والواجهات الخارجية، ومن تريد أن تفيده، وما شابه.
مثال على إجابة: نريد إنشاء سجل ADR عندما نريد أن يفهم المطورون في المستقبل «لماذا» نفعل ما نفعله.
ما الذي يبرّر عدم إنشاء سجل ADR؟
فكّر في جوانب مثل القرارات التي لا تتعلق بالبنية المعمارية، أو الصغيرة مثل قليلة المخاطر أو المستقلة بذاتها أو الخاصة بمطور واحد، أو المغطاة كليًا في مكان آخر مثل المعايير أو السياسات أو التوثيق، أو المؤقتة مثل الحلول البديلة أو إثباتات المفهوم أو التجارب.
مثال على إجابة: نريد تخطي سجل ADR عندما يكون القرار محدودًا في النطاق والوقت والمخاطر والتكلفة، أو مغطى بالفعل في مكان آخر.
ما دورة حياة سجل ADR؟
فكّر في جوانب مثل عملية الإنشاء، وعملية البحث، وعملية اتخاذ القرار، وعملية التنفيذ، وعملية الإنهاء. وفكّر في كيفية تتبّع دورة حياة السجل عبر الزمن، مثل كيفية نقل السجل من حالة إلى الحالة التالية، وكيفية إبلاغ أصحاب المصلحة بذلك.
مثال على إجابة: نريد أن يكون لسجل ADR خمس مراحل في دورة حياته: البدء ← البحث ← التقييم ← التنفيذ ← الصيانة ← الإنهاء.
ما معايير مراحل دورة حياة سجل ADR؟
فكّر في جوانب مثل معايير قبول السجل، أي كيف تعرف أنه جيد بما يكفي للانتقال من مرحلة في دورة الحياة إلى التالية؟ هل صيغت المشكلة بوضوح؟ هل نُظر في البدائل؟ هل المفاضلات مفهومة وموثقة بما يكفي؟ هل السياق ذو الصلة كله موجود؟ هل أصحاب المصلحة المعنيون كلهم مشاركون؟ هل أُدرجت كل الملاحظات؟
مثال على إجابة: نريد أن يصوّت أصحاب المصلحة على سجل ADR عندما يكون الفريق النشط قد 1) أكمل بحثه، 2) أكمل تقييمه، 3) نشر مقترح السجل على أصحاب المصلحة مع طلب تعليقات ومهلة أسبوع، 4) أدرج كل تعليقات أصحاب المصلحة وعالجها.
ما الأدوار والمسؤوليات المتفاعلة مع سجل ADR؟
فكّر في أدوار مثل المقترِح والباحث والمقيّم والمراجع والمعتمِد والمشرف على الصيانة وما شابه. وفكّر في مسؤوليات مثل التواصل مع أصحاب المصلحة، وضمان تلبية التوقعات، والنشر على الموقع الإلكتروني أو الشبكة الداخلية، ومراجعة العمل دوريًا وخصوصًا عند حدوث تغييرات ذات صلة.
مثال على إجابة: نريد أن يكون لكل سجل ADR دائمًا شخص اتصال أساسي وشخص اتصال ثانوي وفريق مسؤول؛ وهؤلاء مسؤولون عن الاتصالات والنشر والصيانة والمراجعة الدورية مرة في السنة على الأقل والإنهاء النهائي عند الحاجة.
كيف تتفاعل الحوكمة مع سجل ADR؟
فكّر في جوانب مثل طرائق العمل في مؤسستك، وأي احتياجات امتثال خاصة مثل الجوانب القانونية أو جوانب الموارد البشرية، وكيف تريد التعامل مع التوافق مقابل الخلاف مقابل التصعيد. هل هناك مجالات أو أشخاص أو فرق يمكن أن يكون لها تأثير أكبر من غيرها فيما يخص سجل ADR، كأن تستطيع اعتماده أو التصويت عليه أو نقضه؟
مثال على إجابة: تكون حوكمة سجل ADR بهذا الترتيب من الأولوية: الرئيس التنفيذي (CEO)، والمدير التقني (CTO)، والمدير القانوني (CLO)، والفريق الذي ينفّذ السجل، والخبراء في الفريق الأكثر معرفة بالسجل ADD. ولا يملك أحد غيرهم حوكمة ما لم ينص السجل على ذلك.
ما المبادئ المتفاعلة مع سجل ADR؟
فكّر في جوانب مثل طرائق العمل في مؤسستك التي تشمل التحرك بسرعة مقابل التحرك ببطء، وتوافق القرارات مقابل تضارب القرارات، وتفضيلات المخاطرة مقابل تفضيلات الأمان، والنقاش العلني مقابل النقاش الخاص، وما شابه.
مثال على إجابة: نستخدم مبادئ القيادة التالية: الانحياز إلى الفعل، والاختلاف ثم الالتزام (disagree-and-commit)، وكفاية تقديرات بنسبة 70% للقرارات التي يسهل التراجع عنها وعزلها، وطرائق العمل العلنية باستثناء المعلومات السرية كما هو موضح في اتفاقية السرية الخاصة بمؤسستنا.
مفاهيم الخطوة التالية لسجلات ADR
يجيب Arc42 عن سؤالين بطريقة عملية ويمكن تكييفه مع احتياجاتك. ماذا ينبغي أن توثّق/تنقل عن بنيتك المعمارية؟ وكيف ينبغي أن توثّق/تنقل؟ يتضمن Arc42 سجلات قرارات البنية المعمارية إضافةً إلى إرشادات حول الأهداف والقيود والسياقات والجودة والمخاطر وغيرها.
نموذج C4 نهج سهل التعلّم ومناسب للمطورين لرسم مخططات البنية المعمارية للبرمجيات. C4 مجموعة من المخططات الهرمية للسياق والحاويات والمكوّنات والشيفرة، إضافةً إلى مخططات داعمة لمشهد الأنظمة والديناميكية والنشر.
مخططات البنية المعمارية والمناظير ووجهات النظر
يُسمّى مخطط البنية المعمارية "منظورًا معماريًا".
والـ"منظور المعماري" هو مثيل لـ"وجهة نظر معمارية".
ولكل "وجهة نظر معمارية" جمهور محدد له اهتمامات محددة.
أمثلة على وجهات النظر المعمارية والمناظير والمخططات:
القدرات التجارية
العمليات التجارية عالية المستوى
الوظائف البرمجية المرتبطة بمكوّنات التطبيق
C4 Model مخطط السياق (TO-BE / AS-IS)
C4 Model مخطط الحاويات (TO-BE / AS-IS)
مخطط الكيانات والعلاقات (ERD) لربط كيانات البيانات بمكوّنات التطبيق
مخططات التسلسل لوصف التدفقات الوظيفية داخل الأنظمة وفي التكاملات
نمذجة وتدوين العمليات التجارية (BPMN) مخططات لوصف تدفقات البيانات عبر مكوّنات التطبيق
نمذجة وتدوين العمليات التجارية (BPMN) مخططات لوصف العمليات التجارية / سيناريوهات المستخدم
إدارة الهوية والوصول (IAM) مخططات
التحكم في الوصول القائم على الأدوار (RBAC) مخططات بأدوار لكل مكوّن تطبيق
التحكم في الوصول القائم على السمات (ABAC) مخططات بسمات لكل مكوّن تطبيق
مخططات الخصوصية
مخططات ذات صلة:
يعرض مخطط حالات الاستخدام حالات الاستخدام للإدارة/العملاء، وهو يسبق المتطلبات التي تسبق البنية المعمارية للبرمجيات.
يعرض مخطط النشر الأجهزة/الحواسيب المادية التي تُنشر عليها مكوّنات البرمجيات.
يعرض مخطط تدفق البيانات كيف تنتقل البيانات عبر النظام وتُحوَّل.
يُستخدم مخطط التسلسل لإظهار كيفية عمل بروتوكولات مثل HTTP على محور زمني.
يصوّر مخطط النشاط سير عمل الأنشطة التي ينفذها نظام برمجي، مثل ذكاء NPC الاصطناعي.
دوال الملاءمة للقرارات بوصفها شيفرة
دوال الملاءمة (fitness functions) هي فحوص آلية موضوعية، مكتوبة بشيفرة برمجية، تتحقق من أن القرارات يجري الالتزام بها.
تجعل دوال الملاءمة القرارات قابلة للاختبار والتأكيد.
يمكن لدوال الملاءمة الخاصة بالقرارات أن تساعد كثيرًا في ضمان الجودة والعمليات التنظيمية وأهداف الحوكمة.
كيف ترتبط دوال الملاءمة بالقرارات
يوثّق سجل القرار القرار، بينما تؤكّد دالة الملاءمة القرار.
مثال على قرار: نستخدم توثيق الأحداث (event sourcing) لمتطلبات التدقيق.
مثال على دالة ملاءمة: نستخدم خادم التكامل المستمر لاختبار أن كل تغييرات الحالة يجب أن تنتج أحداثًا.
لماذا تساعد دوال الملاءمة القرارات
قياسات موضوعية: تنجح دوال الملاءمة أو تفشل، فيكون العمل مرئيًا وواضحًا.
استخدام مستمر: دوال الملاءمة هي قواعدك الحية، تعمل مع كل إيداع (commit) وكل بناء (build).
ثقة في إعادة الهيكلة: تلتقط دوال الملاءمة تلقائيًا أخطاء قواعد القرارات.
حوكمة قابلة للتوسّع: تؤكّد دوال الملاءمة المعايير دون خلق اختناقات.
هل يمكن لدوال الملاءمة استخدام الذكاء الاصطناعي؟
يمكن لدوال الملاءمة الاستفادة من نماذج اللغة الكبيرة (LLM) للذكاء الاصطناعي في القرارات بطرح أسئلة عن عملك، مثل خططك وشيفرتك ومخططاتك وواجهاتك البرمجية وغير ذلك:
IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning.
IMPORTANT: Turn on extended thinking. Turn on expert advice. Turn on search.
This is a fitness function to evaluate if our work is
using all our decisions, and is correct and accurate.
- Our decisions are here: {url}
- Our work to evaluate is here: {url}
Explain any errors, problems, gaps, weaknesses. Be direct. Be decisive.
اختبار وحدة البنية المعمارية
ArchUnit: يفحص القواعد المعمارية لشيفرة Java باستخدام أي إطار اختبار وحدات عادي في Java.
ArchUnitTS: يفحص القواعد المعمارية لشيفرة TypeScript وJavaScript باستخدام Jest وVitest وJasmine وغيرها.
حواجز حماية القرارات لطلبات السحب
Decision Guardian يُظهر تلقائيًا سجلات القرارات المناسبة في اللحظة المناسبة، أي عندما يعدّل المطوّر فعليًا الشيفرة التي تغطيها تلك القرارات. فبدلًا من الأمل في أن يقرأ المطورون مجلد وثائق قبل الدمج، يظهر السياق ذو الصلة مباشرةً في طلب السحب.
يعمل هذا مع أي نوع من سجلات القرارات: قرارات البنية المعمارية، وقرارات البيانات، وقرارات الامتثال، والقرارات السريرية والطبية، وقرارات الأمان، وغيرها.
يعمل مع أي نظام تكامل مستمر (GitLab وJenkins وCircleCI) وكخطّاف pre-commit. مفتوح المصدر. ترخيص MIT.
ADR Guard إجراء GitHub
يُفشل طلب السحب عندما تتغير مسارات الشيفرة المراقَبة دون إضافة سجل قرار معماري أو تحديثه. الاستثناءات صريحة: سطر
ADR-Exempt: مع سبب يجتاز البوابة ويُسجَّل في ملخص المهمة. لا يرتبط بقالب معين ولا يحتاج إلى تبعيات. مفتوح المصدر. ترخيص MIT.
لمزيد من المعلومات
مقدمة:
القوالب:
Documenting architecture decisions - Michael Nygard (thinkrelevance.com)
Template for documenting architecture alternatives and decisions (stackoverflow.com)
بتعمق:
The Decision View's Role in Software Architecture Practice (computer.org)
Documenting Software Architectures: Views and Beyond (resources.sei.cmu.edu)
Architecture Decisions: Demystifying Architecture (utdallas.edu)
ThoughtWorks Technology Radar: Lightweight Architecture Decision Records (thoughtworks.com)
A Skeptic’s Guide to Software Architecture Decisions (infoq.com)
Architectural Retrospectives: the Key to Getting Better at Architecting
Software Architecture Monday with Mark Richards - درس شهري مجاني في هندسة البرمجيات المعمارية
"Keep the Why: Code Becomes Legacy When Nobody Remembers Why"
الأدوات:
Command-line tools for working with Architecture Decision Records
kgai - append-only decision log for AI coding agents, a machine-readable companion to ADR files
إرشادات خاصة بالشركات:
الأمثلة:
مقاطع الفيديو:
البودكاست:
الكتب:
Software Architecture in Practice (SEI Series in Software Engineering)
Documenting Software Architectures: Views and Beyond (SEI Series in Software Engineering)
The Software Architect Elevator: Redefining the Architect's Role in the Digital Enterprise
Fundamentals of Software Architecture: An Engineering Approach - by Mark Richards and Neal Ford
Building Evolutionary Architectures - by Neal Ford, Rebecca Parsons, Patrick Kua, Pramod Sadalage
Foundations of Decision Analysis by Ronald Howard and Ali Abbas
Head First Software Architecture - by Raju Gandhi, Neal Ford and Mark Richards
Communication Patterns: A Guide for Developers and Architects - by Jacqui Read
انظر أيضًا:
REMAP (Representation and Maintenance of Process Knowledge)
DRL (Decision Representation Language)
IBIS (Issue-Based Information System)
QOC (Questions, Options, and Criteria)
IBM’s e-Business Reference Architecture Framework
Decision Reasoning Format (DRF) - صيغة YAML/JSON محايدة تجاه الموردين وقابلة للقراءة آليًا لتمثيل القرارات مع المنطق الصريح والافتراضات والحالة المعرفية والمقايضات. تكمّل سجلات ADR بإضافة منطق منظَّم يمكن التحقق منه إلى توثيق القرارات.