من RFC إلى ADR: الوصول إلى القرار والحفاظ على المنطق

القرار الذي لم يستطع أحد إعادة بنائه

يسأل قائد التقنية الجديد سؤالاً معقولاً: لماذا تتحدث كل خدمة إلى نظام الفوترة من خلال تلك الطابور؟ هناك سجل قرار معماري — ADR-014، أربع جمل، كُتبت قبل أحد عشر شهراً. السياق: "كنا بحاجة إلى تكامل موثوق للفوترة." القرار: "استخدم الطابور." العواقب: "بعض التأخير الإضافي." من الناحية الفنية، هو سجل. لا يجيب على شيء.

كنت هناك، لذا تعرف ما لا يقوله ADR-014: الجدل الذي استمر ثلاثة أسابيع عبر قناتين في Slack وسلسلة من المناقشات الحادة حول PR؛ خيار API المتزامن الذي خسر بسبب حد معدل تم رفعه منذ ذلك الحين؛ اعتراض المهندس الموظف الذي تم الرد عليه بمعيار لا يمكن لأحد العثور عليه الآن. حدث النقاش. تم كتابة السجل بعد ذلك، من الذاكرة، بواسطة شخص واحد، في يوم الجمعة.

هذه هي وضعية الفشل الموثقة، شبه العالمية، لممارسة جيدة حقًا. توصي إرشادات AWS الإرشادية ووثائق Microsoft Well-Architected كلاهما بـ ADRs — وكلاهما يشير إلى الألم: الحفاظ عليها محدثة يستغرق وقتًا، وإدارتها تصبح معقدة مع تزايد الفرق والخيارات. السبب الجذري هو هيكلي: النقاش والسجل يعيشان في أماكن مختلفة، لذا فإن السجل دائمًا ما يكون نسخًا غير كامل. الحل هو جعلهما في نفس المكان. كما أن هذه الممارسة ليست محددة بالهندسة، أو حتى محددة بـ ADR. تتطلب Google وثيقة تصميم — المشكلة، الاقتراح المقترح، البدائل المدروسة، الموازنة — مكتوبة ومراجعة قبل بدء العمل الفني الكبير، وهي ممارسة موضحة في هندسة البرمجيات في Google. إنها نفس الانضباط مثل ADR، ولكن يتم تطبيقها خطوة واحدة في وقت سابق: يسجل ADR الخيار الذي جادلت فيه وثيقة التصميم. يفشل الاثنان بنفس الطريقة لنفس السبب، وكلاهما يتم إصلاحه بنفس الخطوة — الاحتفاظ بالنقاش حيث يعيش السجل، بدلاً من نسخ أحدهما إلى الآخر بعد ذلك. اقرأ كل خطوة أدناه على أنها تغطي كلا الأثرين.

لماذا تتعفن شهادات الإيداع الأمريكية

تحمل جملة واحدة من مواد مجتمع ADR التشخيص الكامل: عادة ما يتعلق RFC بالوصول إلى اتفاق؛ يسجل ADR الاتفاق بمجرد الوصول إليه. عنصران، لحظتان — وكل شيء بينهما يتسرب. البدائل التي كانت "واضحة" بشكل "بديهي" تظل غير مسجلة (حتى تتوقف عن كونها واضحة). الاعتراض الذي شكل التصميم النهائي يبقى فقط كتعليق PR على موضوع مغلق. يتم كتابة قسم السياق في النهاية، وبأسوأ شكل، من قبل من خسر لعبة "ليس هو". الاجتماعات التي كان ينبغي أن تنتج قرارات تنتج ملخصات بدلاً من ذلك، والتفكير الذي يجعل القرار دائمًا — الشيء الذي تعتمد عليه سلسلة جودة القرار بأكملها — هو بالضبط ما تسقطه النسخ.

الخطوة 1–3: الاقتراح، السياق، الخيارات

1. 1حدد الاقتراح كالمطالبة الأساسية — القرار المقترح، وليس سؤالاً: "سنقوم بتوجيه جميع كتابات الفواتير من خلال قائمة انتظار دائمة." هذه الجملة هي عنوان ADR المستقبلي. نقطة تفتيش: الجذر موجود، جملة واحدة، كتبها المقترح.
2. 2السياق كحجج منفصلة. كل قوة تجعل القرار ضروريًا - متطلبات الموثوقية، حد معدل نظام الفوترة، تفويض التدقيق - هي حجة خاصة بها تحت الجذر. لا يمكن الطعن في فقرة "السياق" الأحادية؛ يمكن أن يتم استجواب أو تأكيد أو دحض ثلاث ادعاءات سياقية منفصلة بشكل فردي. نقطة التحقق: ≥2 حجج سياقية، كل واحدة قوة.
3. 3كل خيار يحصل على عقدته الخاصة. الطابور، واجهة برمجة التطبيقات المتزامنة، وظيفة الدفعة - حجج شقيقة، كل منها لها مزاياها وعيوبها الخاصة. المزايا/العيوب نسبية بالنسبة للأب، لذا فإن عيوب الخيار تتعلق بـ ذلك الخيار، وليس بالقرار. قم بتضمين الخيارات التي تتوقع رفضها: الشقيق المرفوض هو ما يجيب على "لماذا لم نقم فقط..." في العام المقبل. نقطة تفتيش: كل خيار قد يسأل عنه القارئ موجود.

الخطوة 4-6: جولة RFC التي تترك سجلاً

الآن جولة المراجعة — عادةً الجزء الذي يتناثر عبر الدردشة، التعليقات والممرات. هنا يتم تشغيلها كنوعين من التبادل المنظم، كل منها حوار من أربع دورات بين المراجع ومؤلف الخيار:

الخطوة 7: اتخاذ القرار — وما ليس عليه التقييم

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

الخطوة 8-9: الـ ADR الذي لم يكن عليك كتابته

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

1. 1سجل العواقب التي تقبلها. العيوب المعروفة - التأخير الإضافي، العبء التشغيلي للطابور - تستمر كأطفال غير مرغوب فيهم للخيار المختار، معترف بها من قبل صانع القرار. كتابة هذه العواقب هو ما يجعلها قرارًا بدلاً من تفضيل. نقطة تفتيش: ≥1 عاقبة مقبولة مسجلة.
2. 2قم بالتصدير إذا كانت منظمتك تتطلب ADRs متعقبة في المستودع. العديد منها يتطلب ذلك، بشكل صحيح — يبقى ADR بتنسيق markdown بجوار الكود هو الأثر التوافقي. اكتب ملخص الأقسام الأربعة من الشجرة (خمس دقائق، وليس يوم الجمعة)، واربط النقاش للعودة إلى المناقشة الكاملة. نقطة تفتيش: ADR المستودع يشير إلى الشجرة؛ الشجرة تحتوي على الأسباب.

اختلاف الرأي والالتزام، على السجل

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

الخطوة 10: الاستبدال دون الحذف

عمر القرارات. عندما يتم رفع الحد الأقصى للسرعة الذي أدى إلى إلغاء الخيار المتزامن، فإن الخطوة الصحيحة هي قرار جديد يشير إلى القرار الذي يحل محله — حجة جديدة مرتبطة بعقد ADR-014، توضح ما الذي تغير. يبقى القرار القديم قابلاً للقراءة؛ فسبب وجوده هو بالضبط ما يجعل القرار الجديد يعرف ما الذي يقوم بإلغائه.

فجوة واحدة صادقة يجب إدارتها بشكل صريح: لا يوجد حقل حالة ADR مدمج. مقترح / مقبول / ملغى ليست حالة من الدرجة الأولى في الحجة — يتم نمذجة الإلغاء من خلال الربط، والاتفاقية هي مسؤوليتك للحفاظ عليها. اذكرها في اتفاقية العمل الخاصة بفريقك بدلاً من افتراض أن المنتج يفرضها.

القيود الصادقة

• ✗هذا لا يحل محل ADRs في مستودعك إذا كانت منظمتك تتطلب أن تكون تحت التحكم في النسخ بجوار الكود. قم بتصدير وتسجيل الملخص؛ استخدم الشجرة للجزء الذي يكون فيه markdown ضعيفًا — النقاش.
• ✗لا يوجد حقل حالة ADR. الاقتراح/القبول/الإلغاء هو تقليد ربط تحافظ عليه، وليس شيئًا يفرضه المنتج.
• ✗السلسلة تتكون من أربع لفات. سيتطلب الخلاف المعماري العميق إجراء مكالمة؛ السلسلة هي سجل لما تم تجربته بالفعل من قبل.
• ✗التقييمات هي قيمة واحدة معلمة، وليست تسجيلات متعددة المعايير موزونة.
• ✗لا يجعل أي شخص يكتب سياقًا جيدًا. الهيكل يقلل من تكلفة سجل جيد؛ لكنه لا يوفر الحكم.

دروس عملية

• ✓RFC واحد، نقاش واحد. قاوم الشجرة العملاقة التي تغطي عمارة الربع بأكمله — روابط الاستبدال تربط القرارات بشكل أفضل من التعشيش.
• ✓زرع مما هو موجود. نص مليء بالقرارات أو مجلد ADR القديم الخاص بك، المستخرج، يمنح النقاش انطلاقة قوية - مع وضع علامة على أنه مستورد، بحيث تظل الحجج الحية قابلة للتمييز.
• ✓ضع أسماء المراجعين على سلاسلهم واتركهم هناك. النسبة هي المساءلة؛ الاعتراضات المعمارية المجهولة تتحول مع مرور الوقت إلى فولكلور.
• ✓قسم العواقب هو خاص بالقرار، وليس لأحد آخر. العيوب المقبولة التي كتبها الشخص الذي قبلها تحمل وزنًا مختلفًا عن تحذيرات المراجع.

ADR-014، النسخة التي تجيب

عودة إلى سؤال قائد التقنية الجديد. في النسخة المعاد بناؤها، ADR-014 هو عقدة: قرار الطابور مع مبرراته، ثلاث قوى سياقية (واحدة الآن قديمة - بشكل واضح)، شقيق مرفوض من واجهة برمجة التطبيقات المتزامنة whose fatal con names the old rate limit، أربع سلاسل مراجعة مكتملة بما في ذلك سلسلة المهندس الفني، والمعيار المرفق كدليل. يقرأ قائد التقنية لمدة عشر دقائق، يرى أن حد المعدل قد تغير، ويفتح اقتراحًا جديدًا مرتبطًا بالعقدة القديمة. لا أحد يبحث في Slack. هذه هي الوعد بالكامل: السلاسل تصل إلى الاتفاق، والشجرة تسجل ذلك - والسجل يجيب على أسئلة لم تكن تعرف أنه سيتم طرحها.