سجلّات قرارات المعمارية

الـ ADR يوثّق لماذا اتخذنا قرارًا مكلف التراجع. نكتب ADR للقرارات المكلفة فقط (database أو auth model أو framework أو حدّ ملكية بيانات)، ولا نكتبه لتغيير رخيص — إن كان التراجع عنه PR صغيراً فلا ADR له. اختبار التفصيل: إن كان التعديل التالي سيغيّر رقماً فهذا معايرة لا قرار، مكانه وثيقة تصميم الميزة؛ وإصلاحات الأخطاء ليست ADRs أبداً. الـ ADRs تعيش داخل كل repo في /docs/adr مع ملف README.md كفهرس إلزامي. الـ ADRs قابلة للإضافة لا للتعديل: تُلحق قسم Amendment مؤرّخاً عند التنقيح، ويُكتب ADR جديد يَنسخ القديم عند العكس فقط. حقل Enforcement يجب أن يذكر فحصاً موجوداً فعلاً على الـ branch، أو كلمة Review-only بصراحة. الـ ADR يُدمج في نفس الـ PR الذي ينفّذه.

stateDiagram-v2
  [*] --> Proposed
  Proposed --> Accepted
  Proposed --> Rejected
  Accepted --> Accepted: amended (dated, append-only)
  Accepted --> Superseded: decision reversed
  Accepted --> Deprecated
  Superseded --> [*]
  Deprecated --> [*]

للتفاصيل الكاملة والأمثلة انظر النسخة الإنجليزية: Architecture Decision Records.