ينبغي أن يضع قالب المواصفات التقنية القرارات المحفوفة بالمخاطر في الصفحة الأولى: المشكلة وقيودها، والتصميم المقترح، والبدائل التي رفضتها، وما قد يسوء، وذلك في صفحة إلى ثلاث صفحات لمعظم التغييرات. تتبع وثائق التصميم في Google وطلبات التعليق (RFC) في Uber هذا الشكل. يضيف القالب القابل للنسخ أدناه ملخصاً من جملة واحدة وجدول قرارات، ليجد المراجعون القرارات الصعبة في أقل من دقيقة.
أهم النقاط
تتألف وثائق التصميم في Google من خمسة أقسام أساسية وتبلغ 10 إلى 20 صفحة في المشاريع الكبيرة، لكنها 1 إلى 3 صفحات في العمل التدريجي (Malte Ubl، 2020).
يقرأ القراء نحو 20% من كلمات صفحة الويب المتوسطة، وبحد أقصى 28% (Nielsen Norman Group، 2008). وتُقرأ المواصفات بالطريقة نفسها: تُمسح بحثاً عن الأجزاء التي قد تكون خاطئة.
يقضي 61% من المطورين أكثر من 30 دقيقة يومياً في البحث عن إجابات (Stack Overflow، 2024). المواصفات التي تسجّل القرارات تجيب عن هذه الأسئلة مرة واحدة.
الفرق ذات التوثيق عالي الجودة أرجح بـ 3.8 مرة لتطبيق أفضل ممارسات الأمان (DORA، 2021).
«البدائل المدروسة» هو القسم الذي يثق به المراجعون أكثر من غيره، لأنه يُظهر أنك بحثت عن سبب لعدم البناء بهذه الطريقة.
ما المواصفات التقنية وكيف تختلف عن PRD؟
المواصفات التقنية (تُسمى أيضاً وثيقة التصميم أو design doc) تشرح كيف سيبني الفريق شيئاً ما وما المفاضلات التي يقبلها. أما PRD فيشرح أي مشكلة تستحق الحل، ولمن، وكيف سيُقاس النجاح. يأتي PRD أولاً، وتأتي المواصفات التقنية جواباً عنه.
تستخدم الفرق أربع وثائق متقاربة. الخلط بينها هو السبب الأشيع في أن تتضخم المواصفات إلى 15 صفحة لا يُنهيها أحد.
هل تتفق المؤسسة الأوسع مع هذه الخطة قبل بدء العمل؟
الكاتب مع معتمدين مسمّين
مثل المواصفات، مع موعد نهائي للمراجعة
ADR (سجل قرار معماري)
لماذا اتخذنا هذا القرار بالذات، وما الذي يترتب عليه؟
المهندس الذي اتخذ القرار
1–2 صفحة
يصف دليل Google وثيقة التصميم بأنها المكان الذي تُوثَّق فيه استراتيجية التنفيذ العامة وقرارات التصميم الرئيسية، مع التركيز على المفاضلات. أما صيغة ADR التي نشرها Michael Nygard عام 2011 فتحصرها في قرار واحد بخمسة أجزاء: العنوان والسياق والقرار والحالة والعواقب (Michael Nygard، 2011). وإن أردت البدء بجانب المنتج، فابدأ بـدليل كتابة PRD.
لماذا يتجاوز المهندسون معظم المواصفات التقنية؟
يتجاوز المهندسون المواصفات التي تجيب عن أسئلة لم يطرحها أحد وتخفي الأسئلة المهمة. ثلاثة أنماط تفسّر معظم ذلك.
تُكتب من أجل الاكتمال لا من أجل القرارات. وجد تحليل Jakob Nielsen عام 2008 أن القراء في صفحة متوسطة من 593 كلمة كان لديهم وقت لقراءة 28% من الكلمات على الأكثر، وكان 20% أرجح. ولم يصل القراء إلى نصف المحتوى إلا في الصفحات التي تبلغ 111 كلمة أو أقل. والمراجع الذي لديه ست مواصفات في قائمته يقرأ بالطريقة نفسها: الملخص، ثم المخطط، ثم النص العريض، ثم القسم الذي يختلف معه.
تخبّئ القرار الخطِر في نثر متجانس. إذا كان القرار غير القابل للتراجع في الفقرة التاسعة، فعلى كل مراجع أن يستنتجه من جديد. وهذا بالضبط الهدر الذي يُفترض بالمواصفات أن تمنعه.
تتقادم. وجد استطلاع Stack Overflow Developer Survey لعام 2024 أن 61% من المشاركين يقضون أكثر من 30 دقيقة يومياً في البحث عن إجابات، وأن 30% يقولون إن صوامع المعرفة تضر بإنتاجيتهم 10 مرات أسبوعياً أو أكثر. والمواصفات التي تتوقف عن مطابقة الشيفرة تصبح مصدراً آخر للإجابات الخاطئة.
وعائد إتقان ذلك قابل للقياس. فقد وجدت أبحاث DORA لعام 2021 أن الفرق ذات التوثيق عالي الجودة كانت أرجح بـ 3.8 مرة لتطبيق أفضل ممارسات الأمان وبـ 2.5 مرة للاستفادة من السحابة بكامل إمكاناتها.
ماذا ينبغي أن تتضمن المواصفات التقنية؟
ضمّن فقط ما يغيّر طريقة بناء العمل أو مراجعته. وتوفر ممارستان منشورتان أساساً جيداً.
أقسام وثيقة التصميم في Google
يسرد نص Malte Ubl لعام 2020 عن وثائق التصميم في Google الأقسام التي تشترك فيها معظم الوثائق:
السياق والنطاق: البيئة التي يعيش فيها النظام، في بضع فقرات.
الأهداف وغير الأهداف: ما يجب أن يفعله النظام، وما لن يفعله صراحةً.
التصميم الفعلي: مخطط النظام وواجهات API وتخزين البيانات، والشيفرة أو الشيفرة الزائفة فقط حيث توضّح خوارزمية جديدة.
نما نظام RFC في Uber مع الشركة من عشرات المهندسين إلى بضعة آلاف، بحسب Gergely Orosz الذي عمل هناك (The Pragmatic Engineer، 2018). كان قالب الواجهة الخلفية يبدأ بـقائمة المعتمدين، ثم يغطي تغييرات المعمارية واتفاقيات مستوى الخدمة (SLA) والاعتماديات واختبارات الحمل وقضايا مراكز البيانات المتعددة والأمان والاختبار والإطلاق والمقاييس والمراقبة ودعم العملاء. وأضاف قالب الجوال واجهة المستخدم وإمكانية الوصول. وكانت الأقسام تُضاف كلما تعلّمت الشركة ما كانت تغفله مراراً.
الدرس من الاثنين: قالب المواصفات التقنية قائمة تحقق بأخطاء الماضي. ابدأ صغيراً، ولا تضف قسماً إلا حين يتسبب غيابه في مشكلة حقيقية.
قالب المواصفات التقنية (انسخه وعدّله)
يجمع هذا القالب أقسام Google وعادة Uber في وضع المعتمدين أولاً وصيغة القرار عند Nygard. احذف أي قسم سيقول «غير منطبق».
# [اسم الميزة أو النظام]: المواصفات التقنية
**الملخص:** نفعل [X] لتحقيق [Y]، ونقبل مفاضلة [Z].
**الكاتب:** [الاسم] · **المعتمدون:** [2–3 أسماء] · **المراجعة قبل:** [التاريخ]
**الحالة:** مسودة | قيد المراجعة | معتمدة | حلّت محلها [رابط]
**PRD / التذكرة المرتبطة:** [رابط]
## 1. المشكلة والقيود
- ما المعطّل، ومن يشعر به، وما الذي يصبح ممكناً بعد إصلاحه.
- قيود صارمة: ميزانية زمن الاستجابة، وموقع البيانات، والتوافق
مع الإصدارات السابقة، واتفاقية مستوى الخدمة التي لا يجوز كسرها.
## 2. الأهداف وغير الأهداف
- الأهداف (قابلة للقياس حيث أمكن).
- غير الأهداف: أشياء قد يتوقعها قارئ معقول ولن نفعلها.
## 3. القرارات الرئيسية (اقرأ هذا أولاً)
| # | القرار | هل يمكن التراجع؟ | الخطر إن كان خاطئاً | الثقة |
|---|----------|-------------|---------------|------------|
| 1 | | باب باتجاه واحد / باتجاهين | | عالية / متوسطة / منخفضة |
## 4. التصميم المقترح
- مخطط واحد. تغييرات واجهات API ونموذج البيانات. شيفرة زائفة فقط
لما هو جديد.
## 5. البدائل المدروسة
- الخيار A: لماذا خسر.
- الخيار B: لماذا خسر.
- عدم فعل شيء: ماذا يحدث إن لم نبنِ هذا.
## 6. المخاطر والأسئلة المفتوحة
- الافتراضات الجوهرية وكيف سنتحقق منها.
- أسئلة نحتاج إجاباتها قبل البناء أو خلاله.
## 7. الاعتبارات الشاملة
- الأمان والخصوصية · قابلية الرصد · إمكانية الوصول · التكلفة.
## 8. الإطلاق والتحقق والتراجع
- Feature flag / خطة إطلاق على مراحل.
- المقاييس التي تثبت أنه يعمل، والعتبة التي تفعّل التراجع.
## 9. سجل القرارات
- [التاريخ] تغيّر [القرار] لأن [السبب]. (حدّث هنا، لا في تعليق على PR.)
جدول القرارات في القسم 3 هو الجزء الذي يبرر وجود القالب. فتمييز كل قرار بأنه باب باتجاه واحد أو باتجاهين يخبر المراجعين أين يركّزون انتباههم. ويشرح إطار القرارات القابلة للتراجع وغير القابلة كيف تحكم على كل منها.
ما الطول المناسب للمواصفات التقنية؟
بقدر ما يسمح به أخطر قرار. يضع دليل Google وثائق التصميم للمشاريع الكبيرة عند نحو 10 إلى 20 صفحة، ويعدّ «وثائق التصميم المصغّرة» من 1 إلى 3 صفحات مناسبة للعمل التدريجي. وسجلات ADR عند Nygard صفحة أو صفحتان. وتستبدل Amazon الشرائح بـ«مذكرات من ست صفحات ببنية سردية» تُقرأ بصمت في بداية كل اجتماع، وكتب Jeff Bezos أن المذكرة الممتازة تستغرق على الأرجح أسبوعاً أو أكثر لكتابتها (Amazon، 2018).
قاعدة عملية بحسب حجم التغيير:
التغيير
الصيغة
الطول
المراجعة
إصلاح خلل، أو تغيير نص، أو تعديل إعداد
وصف التذكرة
فقرة
مراجعة الشيفرة فقط
نقطة نهاية أو مكوّن جديد داخل خدمة واحدة
مواصفات مصغّرة
صفحة واحدة
معتمد واحد، بشكل غير متزامن
ميزة تمس 2–3 خدمات أو واجهة API عامة
مواصفات تقنية (القالب أعلاه)
2–3 صفحات
2–3 معتمدين، نافذة 2–3 أيام
نظام جديد أو ترحيل بيانات أو حد أمني
وثيقة تصميم كاملة أو RFC
5–20 صفحة
اجتماع مراجعة رسمي
ويقول دليل Google أيضاً متى لا تكتبها: حين يكون الحل لا لبس فيه وتكون الوثيقة مجرد دليل تنفيذ بلا مفاضلات للنقاش.
كيف تكتب مواصفات يقرؤها المهندسون فعلاً؟
اكتبها بهذا الترتيب. معظم العمل هو أن تقرر ما تتركه خارجها.
اكتب الملخص من جملة واحدة أولاً. «نفعل X لتحقيق Y، ونقبل مفاضلة Z.» إن لم تستطع كتابتها فلست جاهزاً لكتابة المواصفات، ولن يستطيع مراجعوك تلخيصها أيضاً.
ابدأ بالمشكلة لا بالحل. لا يستطيع المهندسون الحكم على تصميم قبل أن يعرفوا القيود التي يخدمها. اذكر ما لا يقبل التفاوض قبل مخطط المعمارية.
املأ جدول القرارات. اذكر كل قرار قد يختلف معه مراجع بشكل معقول. اجعل الأبواب ذات الاتجاه الواحد بخط عريض.
اكتب البدائل بصدق. أدرج «عدم فعل شيء». المواصفات بلا خيارات مرفوضة تبدو كقرار اتُّخذ مسبقاً.
سمِّ اثنين أو ثلاثة معتمدين وموعداً نهائياً للمراجعة. كانت Uber تدرج المعتمدين في أعلى كل RFC. والمواصفات بلا صاحب قرار ولا تاريخ تميل إلى البقاء في المراجعة بلا نهاية.
راجع بشكل غير متزامن، واجتمع فقط عند الخلاف. التعليقات على الوثيقة تتولى معظم الملاحظات. وإن اجتمعتم فاحذُ حذو Amazon وخصصوا أول عشر دقائق للقراءة الصامتة.
حدّث المواصفات حين يغيّرها البناء. تعامل دورة حياة Google الوثيقة كشيء يُنقَّح أثناء التنفيذ. سجّل التغييرات في سجل القرارات، لا في تعليق على pull request لن يجده أحد.
يلاحظ Orosz أنه حين يتفق الفريق على خطة، فإن كتابتها تستغرق عادةً بضع ساعات. وإن استغرقت أياماً فالخلاف هو الاكتشاف.
مثال تطبيقي (للتوضيح)
لنفترض أن فريقاً من ست أشخاص يحتاج إلى منع webhooks العملاء البطيئة من تعطيل صفحة الدفع بسبب انتهاء المهلة. جملة الملخص عندهم: «ننقل تسليم webhooks إلى طابور حتى لا ينتظر الدفع خادم أي عميل، ونقبل تأخيراً في التسليم يصل إلى 60 ثانية.»
#
القرار
هل يمكن التراجع؟
الخطر إن كان خاطئاً
الثقة
1
التحول إلى التسليم مرة واحدة على الأقل؛ وعلى العملاء إزالة التكرار بمعرّف الحدث
باب باتجاه واحد (عقد عام)
طلبات مكررة في أنظمة العملاء
متوسطة
2
استخدام قاعدة Postgres الحالية كطابور بدل وسيط جديد
باب باتجاهين
سقف للإنتاجية وقت الذروة؛ الترحيل لاحقاً
عالية
3
إعادة المحاولة خمس مرات خلال 24 ساعة، ثم وسمها بالفشل
باب باتجاهين
يفوّت بعض العملاء أحداثاً أثناء الانقطاعات الطويلة
عالية
يرى المراجعون خلال 30 ثانية أن القرار 1 يستحق النقاش: فهو يغيّر عقد API عاماً، ويحتاج ملاحظة ترحيل للعملاء، ولا يمكن التراجع عنه بهدوء. أما القراران 2 و3 فيمكن اعتمادهما بتعليق.
ما الأخطاء الشائعة في المواصفات التقنية؟
كتابة المواصفات بعد الشيفرة. المواصفات المكتوبة لتبرير pull request منتهٍ بلا بدائل ولا تلتقط شيئاً.
خمسة مخططات بدل واحد. مخطط واحد للنظام مع إبراز التغيير يتفوق على خمسة تعرض كل شيء.
التعامل مع القالب كأنه استمارة. الأقسام الفارغة «غير منطبق» تعلّم القراء التصفح السريع. احذفها.
لا مالك للأسئلة المفتوحة. كل سؤال مفتوح يحتاج اسماً وتاريخاً، وإلا صار حادثة إنتاج.
تجميد الوثيقة. المواصفات التي تتوقف عن مطابقة البناء أسوأ من انعدامها، لأن الناس يثقون بها.
استخدام مواصفات حيث يجيب نموذج أولي أسرع. إن كان السؤال الخطِر هو «هل ستتحمل هذه المكتبة حملنا؟»، فتجربة سريعة (spike) ليوم واحد تتفوق على جدال من خمس صفحات.
كيف تتغير المواصفات التقنية مع وكلاء البرمجة بالذكاء الاصطناعي؟
يقرأ وكلاء البرمجة المواصفات حرفياً. والغموض الذي كان المهندس البشري سيحسمه في Slack يصبح شيفرة يكتبها الوكيل خاطئة بثقة. والأجزاء الأهم في القالب بالنسبة إلى الوكيل هي غير الأهداف والقيود ومعايير القبول القابلة للاختبار. ويوضح قالب PRD لوكلاء البرمجة بالذكاء الاصطناعي كيف تجعلها صريحة. وبعد اعتماد المواصفات، تكون الخطوة التالية تقسيم PRD إلى قصص مستخدم، ويختبر pre-mortem الإطلاق خطة الإطلاق تحت الضغط قبل الإصدار.
أين يتموضع Specky؟
تنفتح الفجوة بين النية الموثّقة والواقع المُسلَّم عادةً حين تعيش المتطلبات والقرارات والتذاكر في أدوات مختلفة. يصوغ Specky وثائق PRD في محرر مع اقتباسات مضمّنة تعود إلى أدلة العملاء، وينشئ تذاكر بمعايير قبول قابلة للاختبار، ويسجّل القرارات في Product Graph كي يبقى «السبب» مرتبطاً بالعمل. ويمكن لوكلاء البرمجة قراءة ذلك السياق عبر خادم MCP. ولا يزال المهندس هو من يكتب التصميم التقني، بينما يبقى سياق المنتج المحيط به محدَّثاً. وإن كان إيجاد وقت للكتابة هو العائق، فإن مثال جدول أسبوع الـ PM يحمي كتلة تركيز لذلك.
الأسئلة الشائعة
ما الفرق بين PRD والمواصفات التقنية؟
يحدد PRD المشكلة والمستخدمين وكيفية قياس النجاح؛ وتحدد المواصفات التقنية كيف سيبني الفريق الحل وما المفاضلات التي يقبلها. يملك الـ product manager عادةً PRD، ويملك الـ tech lead المواصفات. اكتب PRD أولاً ثم اربطه من المواصفات ليتمكن المراجعون من مقارنة التصميم بالهدف الأصلي.
من ينبغي أن يكتب المواصفات التقنية؟
ينبغي أن يكتب المواصفات التقنية المهندس أو الـ tech lead الذي سيتولى البناء، ويراجعها الـ product manager مقابل PRD. الكاتب مسؤول عن القرارات، لا عن كتابة كل قسم بنفسه. وفي الفريق الصغير يمكن للـ PM صياغة أقسام المشكلة والأهداف وغير الأهداف، ويكمل المهندس التصميم والبدائل وخطة الإطلاق.
ما الطول المناسب لوثيقة التصميم التقني؟
ينبغي أن تكون معظم وثائق التصميم التقني من صفحة إلى ثلاث صفحات. تعدّ ممارسة Google وثائق التصميم المصغّرة من 1 إلى 3 صفحات أمراً عادياً للتغييرات التدريجية، وتحجز 10 إلى 20 صفحة للأنظمة الجديدة الكبيرة. وإن تجاوزت مواصفاتك ثلاث صفحات لميزة داخل خدمات قائمة، فهي على الأرجح تخلط عدة قرارات ينبغي أن تكون سجلات ADR منفصلة.
ما RFC في هندسة البرمجيات؟
RFC (طلب تعليقات) خطة مكتوبة تُشارَك مع مؤسسة الهندسة الأوسع قبل بدء العمل، ليشير الآخرون إلى المخاطر. استخدمت Uber وثائق RFC وهي تنمو من عشرات المهندسين إلى بضعة آلاف، وكانت تدرج المعتمدين بأسمائهم في أعلى كل وثيقة. الـ RFC هو مواصفات تقنية مضافاً إليها عملية مراجعة وموعد نهائي وصاحب قرار.
متى لا ينبغي أن تكتب مواصفات تقنية؟
تجاوز المواصفات حين يكون الحل لا لبس فيه ولا توجد مفاضلات مهمة للنقاش، وهذا هو الخط الذي يرسمه دليل Google. إصلاحات الأخطاء وتغييرات الواجهة الصغيرة وتحديثات الإعدادات مكانها التذكرة. وإن كان عدم اليقين الرئيسي هو الجدوى التقنية، فأجرِ spike محدوداً بوقت أولاً، ثم اكتب المواصفات حين تعرف ما الذي يعمل.
ما سجل القرار المعماري (ADR)؟
ADR سجل من صفحة أو صفحتين لقرار معماري واحد. وصيغة Michael Nygard لعام 2011 من خمسة أجزاء: العنوان والسياق والقرار والحالة والعواقب. تحتفظ كثير من الفرق بسجلات ADR في مستودع الشيفرة، ليرى المهندسون في المستقبل لماذا بُني شيء بطريقة معينة. استخدم ADR للقرارات التي تعيش أطول من مواصفات واحدة.
GDPR-aligned. EU workspace data is stored in Frankfurt, Germany. GDPR and EU data Built in Vienna, Austria. A product of influence solutions fm GmbH (FN 675374y). Imprint 14-day trial. Card required, and nothing is charged until day 14. 30-day refund after subscribing. See pricing