عبدالله الكندي: كيف تكتب مواصفات مهمة لوكيل ذكاء اصطناعي ينفّذها صح؟

أعطيت الوكيل مهمة في سطر، ورجع لك بعد عشر دقائق بشغل كثير: عدّل ملفات ما طلبتها، وأضاف مكتبة ما تبيها، وقال «تم بنجاح». والمشكلة إنه فعلاً سوّى شي يشتغل، بس مو الشي اللي في راسك. عبدالله الكندي يشتغل مع وكلاء برمجة في مشاريعه، وتعلّم إن جودة الناتج تتقرر غالباً قبل ما يبدأ الوكيل، في الورقة اللي تكتبها له. هنا نبني هالورقة مع بعض، قسماً قسماً، على مثال واحد.

المثال: موقع متجر مبني بـ Next.js، وفيه صفحة فاتورة تعرض المبالغ بأرقام إنجليزية بدون فواصل. الطلب الخام اللي يكتبه أغلب الناس: «خل الأرقام في الفاتورة بالعربي ومرتبة».

الوكيل هنا لازم يخمّن خمسة أشياء على الأقل: «بالعربي» يعني أرقام هندية ٠١٢٣ أو بس فواصل عربية؟ «مرتبة» يعني فواصل الآلاف؟ كم خانة عشرية؟ وين يكتب «ر.س»؟ ويغيّر الفاتورة بس، أو كل الموقع؟ كل تخمين فيه احتمال يطلع عكس اللي تبي. المواصفات اللي جاية تشيل التخمين.

الهدف بسببه، ثم السياق اللي ما يقدر يكتشفه

اكتب النتيجة، مو الطريقة، وأضف ليش تبيها. «المبالغ في صفحة الفاتورة تُعرض بصيغة عربية سعودية مألوفة للعميل، لأن عملاء اشتكوا إن الأرقام الطويلة صعبة القراءة». السبب مو ترف: لما يواجه الوكيل قراراً ما ذكرته، يرجع للسبب ويختار اللي يخدمه. مثلاً بيفهم إن الوضوح أهم من الشكل.

بعدها السياق. الوكيل يقدر يقرأ الكود، فلا تشرح له وش موجود في الملفات. اشرح له اللي مو مكتوب في أي ملف: «فيه دالة تنسيق للتواريخ في مجلد المساعدات، اتبع نفس أسلوبها. الفواتير تنطبع أحياناً PDF، فالتغيير لازم يظهر في الطباعة. لوحة التحكم الداخلية يستخدمها فريق يفضّل الأرقام الإنجليزية، فلا تلمسها». هذي معلومات لو ما قلتها، ما فيه طريقة يعرفها.

الحدود والممنوعات

• النطاق: صفحة الفاتورة ونسختها المطبوعة فقط.
• لا تضيف مكتبات جديدة؛ استخدم واجهة Intl.NumberFormat المدمجة في المتصفح.
• لا تغيّر طريقة تخزين المبالغ في قاعدة البيانات؛ التنسيق للعرض فقط.
• لا تعدّل ملفات الإعدادات أو الاختبارات الموجودة لتنجح؛ لو اختبار فشل، وقّف وقل لي.

البند الأخير بالذات مهم. الوكيل اللي هدفه «خلّ الاختبارات تنجح» ممكن يوصل للهدف بأقصر طريق: يعدّل الاختبار نفسه. هذا مو سوء نية، هذا تحسين لهدف ما كان مكتوب صح.

معايير قبول تقدر تتحقق منها

هنا يفرق المحترف عن غيره. «مرتب» ما تنقاس. اللي ينقاس:

• مبلغ ١٢٥٠٠ يظهر هكذا: ١٢٬٥٠٠٫٠٠ ر.س، بأرقام عربية وفاصل آلاف وخانتين عشريتين.
• المبلغ صفر يظهر «٠٫٠٠ ر.س»، مو فراغ ومو شرطة.
• المبالغ السالبة في المرتجعات تظهر بعلامة سالب واضحة ولون مختلف.
• اتجاه السطر يبقى سليماً في صفحة RTL، والرمز ما ينقلب لبداية الرقم.
• النسخة المطبوعة تطابق الشاشة.

لاحظ إن كل بند فيه مثال بقيمة محددة. الأمثلة الحدّية، مثل الصفر والسالب، هي اللي تكشف الحل الناقص، لأن الحالة العادية تنجح في أي حل تقريباً.

كيف يتحقق، ومتى يتوقف، وكيف يسلّم

قل له الأوامر بالاسم: «بعد التعديل شغّل فحص الأنواع وأمر البناء والاختبارات، وأضف اختباراً للحالات الخمس فوق». الوكيل اللي يقدر يتحقق من شغله بنفسه يصلح أخطاءه قبل ما توصلك. وبعدها حدد نقاط التوقف: «لو لقيت إن التنسيق مكرر في أكثر من مكان خارج الفاتورة، لا توحّده؛ اكتب لي قائمة بالأماكن واسألني». بدون هالجملة، الوكيل المتحمس بيعيد هيكلة نص المشروع.

وأخيراً شكل التسليم: «في النهاية اكتب ملخصاً: الملفات اللي تغيّرت، وليش، ووش اللي ما قدرت تسويه أو ما كنت متأكد منه». هالسطر الأخير يخلّي الوكيل يعترف بالنقاط الضعيفة بدل ما يدفنها تحت «تم بنجاح».

أخطاء تخرّب مواصفات مكتوبة بنية طيبة

• كتابة الكود داخل المواصفات: لو كتبت الحل سطراً سطراً، ألغيت فائدة الوكيل، وغالباً بتفوّت حالة كان بيلقاها لو فهم الهدف.
• دفن القيد الأهم في الفقرة الخامسة: الممنوعات الحرجة تجي في قسم واضح باسمها، مو وسط شرح طويل.
• تعليمات متعارضة: «لا تلمس ملفات الإعدادات» ثم «تأكد إن البناء ينجح» والبناء يحتاج تعديل إعداد. الوكيل بيختار واحدة، وغالباً مو اللي تبيها.
• افتراض إنه يتذكر الجلسة اللي قبل: كل مهمة جديدة تبدأ من الصفر إلا اللي كتبته أو حفظته في ملف تعليمات المشروع.
• ثلاث مهام في ورقة وحدة: «وعدّل كمان صفحة الدفع، وشوف ليش البحث بطيء». كل مهمة تستاهل مواصفاتها وتحقّقها.

قائمة سريعة قبل ما ترسل أي مهمة

• هل كتبت الهدف بنتيجة يقدر شخص ثالث يحكم عليها؟
• هل ذكرت المعلومة اللي ما هي موجودة في الكود؟
• هل حددت وش ممنوع يلمس؟
• هل كل معيار قبول فيه مثال بقيمة؟
• هل قلت له كيف يتحقق؟ ومتى يوقف ويسأل؟
• هل المهمة صغيرة بما يكفي لجلسة وحدة؟ لو لا، قسّمها.

هالطريقة ما جات من فراغ. عبدالله عبدالرحيم بن سنكر الكندي درس في دورتي Claude Code in Action و Introduction to subagents من Anthropic كيف يُقسّم العمل ويُسلَّم لوكلاء، والدرس المتكرر: الوكيل الفرعي يبدأ بسياق فاضي، وما يعرف إلا اللي كتبته له. فالمواصفات هي كل عالمه.

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