مقابلة سلسلة الذكاء الاصطناعي 16: كيف يجب أن يكون الترميز المواصفاتي الجيد؟

الترميز المواصفاتي الجيد (Spec Coding) يتمحور حول تحويل "الأفكار الغامضة" إلى "عقود دقيقة وقابلة للتحقق والتنفيذ". إنه ليس مجرد كتابة وثيقة، بل بناء لغة تواصل لا لبس فيها بين الإنسان والذكاء الاصطناعي (أو بين البشر). سأقدم أدناه شكل المواصفات الجيدة من أربعة أبعاد: هيكل المحتوى، مبادئ الكتابة، سير العمل مع الذكاء الاصطناعي، والتحقق من الجودة.

١. الهيكل القياسي لوثيقة المواصفات (مثال لوحدة وظيفية)

القسم	المحتوى الإلزامي	مثال
١. الهدف والنطاق	جملة واحدة توضح ما نفعله، وتحدد بوضوح ما لا نفعله	"تنفيذ واجهة برمجة تطبيقات لتسجيل المستخدم، بدون تضمين التحقق من البريد الإلكتروني"
٢. عقد الإدخال/الإخراج	بنية البيانات، الأنواع، الحقول الإلزامية/الاختيارية، قيم أمثلة	طلب `POST /register` `{email: string, password: string}`، استجابة `201` أو `400` مع رمز خطأ
٣. السلوك والمنطق	قواعد العمل، الشروط الحدودية، تحويلات الحالة	"يجب أن يكون طول كلمة المرور 8-20 حرفًا، تحتوي على رقم واحد على الأقل؛ إذا كان البريد الإلكتروني موجودًا بالفعل، أعد `409`"
٤. معالجة الأخطاء	جميع سيناريوهات الاستثناء الممكنة ورموز/رسائل الأخطاء المقابلة	"فشل اتصال قاعدة البيانات → أعد `503`، لا تُظهر تتبع الكومة"
٥. المتطلبات غير الوظيفية	الأداء (وقت الاستجابة < ٢٠٠ مللي ثانية)، الأمان (الاستعلامات المُعلمة)، السجلات، قابلية المراقبة	"يجب استخدام SQL مُجمّع مسبقًا؛ سجل `email` ولكن لا تسجل `password`"
٦. حالات الاختبار (حرجة)	على الأقل ٣ مدخلات نموذجية + ٢ مدخلات حدية/استثنائية، مع إعطاء المخرجات المتوقعة	انظر الجدول أدناه
٧. التبعيات والقيود	المكتبات المستخدمة، الإصدارات، المتغيرات البيئية	"Python 3.10+، FastAPI، متغير البيئة `DB_URL`"

مثال لحالات الاختبار (مضمنة في المواصفات)

السيناريو	الإدخال	المخرجات المتوقعة
تسجيل عادي	email: `a@b.com`, pwd: `Pass1234`	`201`، إرجاع `user_id`
كلمة مرور قصيرة جدًا	pwd: `Ab1`	`400`، رمز الخطأ `WEAK_PASSWORD`
البريد الإلكتروني موجود بالفعل	نفس email أعلاه	`409`، رمز الخطأ `EMAIL_EXISTS`

المواصفات الجيدة يجب أن تكتب حالات الاختبار أولاً، لأن الذكاء الاصطناعي يمكنه توليد اختبارات الوحدة منها مباشرة، والتحقق منها تلقائيًا بعد الانتهاء.

٢. المبادئ الأساسية لكتابة المواصفات (متغير SMART)

المبدأ	الشرح	مثال مضاد
الدقة (Precise)	استخدم أرقامًا محددة، أنواعًا، شروطًا منطقية، تجنب "قدر الإمكان"، "عادةً"	❌ "يجب أن تكون كلمة المرور آمنة بما فيه الكفاية" → ✅ "كلمة المرور على الأقل ٨ أحرف، تحتوي على حرف كبير، حرف صغير، رقم"
قابلية التحقق (Verifiable)	يمكن الحكم على كل مطلب بالنجاح/الفشل من خلال اختبار آلي أو مراجعة يدوية	❌ "يجب أن يكون الكود أنيقًا" → ✅ "تعقيد الدالة ≤ ١٠، لا توجد كتل مكررة"
عدم الغموض (Unambiguous)	استخدام المصطلحات بشكل متسق في النص بأكمله، مع تقديم مسرد مصطلحات عند الضرورة	❌ "إذا لم يكن المستخدم موجودًا، أعد خطأ" → ✅ "المستخدم غير موجود → أعد `404` مع `{code: 'USER_NOT_FOUND'}`"
الشمولية (Complete)	تغطية المسار السعيد، جميع مسارات الاستثناء، والمتطلبات غير الوظيفية	❌ تمت كتابة سيناريو النجاح فقط → ✅ يشمل مهلة قاعدة البيانات، نقص الصلاحيات، إلخ.
الذرية (Atomic)	تصف مواصفة واحدة نقطة وظيفية واحدة قابلة للتسليم بشكل مستقل (لتسهيل إنجاز الذكاء الاصطناعي في مرة واحدة)	❌ استخدام مواصفة واحدة لكتابة "نظام الدفع بالكامل" → ✅ تقسيمه إلى "إنشاء أمر الدفع"، "التحقق من التوقيع عند الاستدعاء"، "استرداد الأموال"

٣. سير عمل الترميز المواصفاتي عند التعاون مع الذكاء الاصطناعي

يكتب الإنسان المواصفة (الهيكل أعلاه، خاصة كتابة حالات الاختبار وتوقيع الدوال).
يُغذّى الذكاء الاصطناعي بالمواصفة مرة واحدة (لا تُضاف متطلبات بشكل حواري، لتجنب التلوث بالمزاج).
يُخرج الذكاء الاصطناعي الكود + اختبارات الوحدة (يجب أن يتبع الذكاء الاصطناعي حالات الاختبار في المواصفة لإنشاء اختبارات قابلة للتنفيذ).
تشغيل الاختبارات: إذا نجحت جميعها، انتقل إلى الخطوة التالية؛ إذا فشلت، قم بتعديل المواصفة أو تصحيح الكود مباشرة (يمكن الدخول في حلقة صغيرة، ولكن يجب تسجيل التغييرات).
المراجعة البشرية: التحقق من عدم إضافة وظائف خارج المواصفة (توسع النطاق)، والتحقق من الأمان/الأداء.
التثبيت: إرسال وثيقة المواصفة مع الكود النهائي إلى المستودع كوثيقة دائمة.

الممارسة الأساسية: جعل المواصفة قابلة للترميز — استخدام spec.md + test_spec.py، حيث يأتي ملف الاختبار مباشرة من الأمثلة في المواصفة، بحيث يمكن عند تعديل الكود لاحقًا تشغيل الاختبارات للتحقق من عدم انتهاك المواصفة.

٤. تأثيرات المواصفة الجيدة (يمكن استخدامها كمعايير قبول)

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

٥. مثال لمواصفة جيدة (نسخة مبسطة)

# المواصفة: واجهة برمجة تطبيقات تسجيل المستخدم

## النطاق
- استقبال email، password
- لا إرسال بريد إلكتروني للتحقق، لا التحقق من صحة البريد الإلكتروني

## العقد
POST /register
Content-Type: application/json
الطلب: { "email": string, "password": string }
الاستجابة 201: { "user_id": string }
الاستجابة 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
الاستجابة 409: { "code": "EMAIL_ALREADY_EXISTS" }

## السلوك
- يجب أن يتوافق البريد الإلكتروني مع التنسيق الأساسي RFC 5322 (a@b.c)
- كلمة المرور: الطول 8-20، تحتوي على رقم واحد وحرف كبير واحد على الأقل
- استخدم bcrypt للتشفير والتخزين، مع تكلفة الملح 10
- إذا تم اكتشاف أن البريد الإلكتروني موجود قبل التخزين في قاعدة البيانات → 409

## حالات الاختبار (الإدخال -> رمز الحالة المتوقع + حقل الاستجابة)
| البريد الإلكتروني | كلمة المرور | المتوقع |
|-------------------|-------------|--------|
| test@x.com | Pass1234  | 201, user_id موجود |
| test@x.com | pass      | 400, INVALID_PASSWORD |
| bad        | Pass1234  | 400, INVALID_EMAIL |
| (بريد موجود بالفعل) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## غير وظيفي
- يجب استخدام SQL باستعلامات مُعلمة (لمنع الحقن)
- تسجيل عنوان IP المصدر للتسجيل، وعدم تسجيل كلمة المرور
- وقت الاستجابة لـ 95% من الطلبات < 100 مللي ثانية (باستثناء bcrypt)

## التبعيات
- Python 3.10+، FastAPI، bcrypt، asyncpg

الترميز المواصفاتي الجيد = تحويل "قرارات التصميم البشرية" إلى "حالات اختبار + توقيعات أنواع + قيود سلوكية" للآلة، مما يسمح للذكاء الاصطناعي بملء التنفيذ فقط، بينما يظل الإنسان مسيطرًا على الجودة والاتجاه.