Vibe 5 - Motrjim Academy S
تدريب المحاضرة ٠٥ — معايير الجودة غير المرئية | Vibe Coding · أكاديمية مُترجم
training_05 · معايير الجودة غير المرئية | Vibe Coding
lecture_04.html ● training_05.html ✕ patient_zero.html
student@motrjim:~/training-05 $ open patient_zero.html --diagnose
/* live training · 6 rounds */

الصفحة دي شكلها كويس —
وفيها ١٧ عطل

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

--file patient_zero.html --criteria 6 --rounds 6 × 12min --ide cursor --mode إصلاح مش بناء
// ── التمهيد · ليه المعايير دي دلوقتي بالذات

الـ AI بيكتب كود «شغّال» — والشغّال مش المحترف

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

المعايير الستة دي هي «الظروف التانية». وأهم حاجة فيها إنها قابلة للاختبار في ٣٠ ثانية — مش أذواق ولا آراء. كل معيار تحت ليه: قاعدة، اختبار سريع تعمله بنفسك، وبرومبت جاهز تديه للوكيل.

قبل ما نبدأ — حمّل الملف وافتحه في Cursor

  1. حمّل patient_zero.html وحطه في فولدر لوحده باسم training-05.
  2. افتح الفولدر من Cursor: File → Open Folder.
  3. افتح الملف في المتصفح وجرّب تسجّل اسم — وبعدين استنى، لأننا هنشخّص الأول.
  4. اعمل نسخة احتياطية باسم patient_zero_original.html عشان تقارن في الآخر.
// ── جولة ٠ · التشخيص — ١٠ دقايق، من غير Cursor

شوف بعينك قبل ما تسأل الوكيل

أول قاعدة في مراجعة الجودة: مينفعش تطلب إصلاح حاجة مشوفتهاش بنفسك. اعمل الخمس تجارب دي واكتب اللي حصل.

خمس تجارب — كل واحدة ثانيتين

وسجّل إجاباتك في ملف

اعمل ملف bugs.md واكتب فيه كل عطل لاقيته بصيغة: «اللي عملته → اللي توقعته → اللي حصل فعلاً».

الملف ده هو اللي هتديه للوكيل في الجولات الجاية. ولاحظ: البرومبت المبني على ملاحظة بتاعتك دايماً أقوى من برومبت مبني على «راجع الصفحة وشوف فيها إيه».

// ── المعايير الستة · جولة لكل معيار

ست جولات — نصلّح معيار في كل جولة

في كل جولة: اقرا القاعدة، اعمل الاختبار، شوف الأعطال في الملف، وبعدين ادّي البرومبت للوكيل واقرا الـ diff قبل ما تقبل.

criterion_01

البنية الدلالية — العنصر الصح للوظيفة الصح

الجولة ١ · ١٢ دقيقة

<div> عنصر بلا معنى. لما تستخدمه كزرار أو كعنوان، إنت بتشيل المعنى من الصفحة: محركات البحث مش فاهمة، وقارئ الشاشة مش شايف، والكيبورد مش واصل. الفرق بين <div class="btn"> و<button> مش شكلي — التاني بييجي بسلوك كامل مجاناً.

📏 القاعدةكل شيء تفاعلي يبقى <button> أو <a>، وكل قسم في مكانه: header، main، section، form. عنوان <h1> واحد في الصفحة، وترتيب العناوين متسلسل.
🔬 الاختبارعطّل الـ CSS كله (في المتصفح: Inspect ← امسح ستايل الصفحة). لو المحتوى فضل مفهوم ومترتب كمستند، بنيتك سليمة. لو بقى كومة نصوص متساوية، بنيتك ديكور مش هيكل.

// bugs_in_file

  • <div class="h1"> وclass="h2" وclass="h3" بدل عناوين حقيقية — والترتيب مقلوب (h3 قبل h2)
  • زراير «تسجيل» و«مسح» والفلاتر كلها <div> و<span> بـ onclick
  • مفيش <main> ولا <form> — والحقول عايمة في <div>
  • عنوان الصفحة Document ومفيش meta description
  • الاتجاه متظبط بـ direction:rtl في CSS بدل خاصية dir="rtl" على العنصر
round_01_prompt.txt
حوّل بنية الصفحة إلى HTML دلالي بدون أي تغيير في الشكل النهائي: استبدل div الترويسة بـ header، والمحتوى بـ main، والأقسام بـ section، وحقول التسجيل بـ form. حوّل كل عنصر تفاعلي (تسجيل، مسح، أزرار الفلترة) إلى button حقيقي بنوع type مناسب. استبدل div.h1/h2/h3 بعناوين h1/h2/h3 فعلية بترتيب هرمي متسلسل بحيث لا تُتخطى مرتبة، وh1 واحد فقط. أضف dir="rtl" و lang="ar" على عنصر html، وعنوان title وصفي وmeta description. لا تغيّر أي قيمة لون أو مسافة — الشكل يجب أن يبقى كما هو. اشرح لي في نهاية ردك قائمة العناصر التي غيّرتها ولماذا.
criterion_02

إمكانية الوصول — الكيبورد والتسميات والإعلان

الجولة ٢ · ١٢ دقيقة

مش كل مستخدم معاه ماوس، ومش كل مستخدم شايف. وحتى المستخدم العادي بيستعمل الكيبورد في الفورمات. المعيار ده مالوش علاقة بالنية الحسنة — ده شرط قانوني في أسواق كتير، وفي مصر بقى مطلوب في مناقصات المواقع الحكومية والشركات الكبيرة.

📏 القاعدةكل حقل له <label> مربوط بـ for/id — والـ placeholder مش تسمية. حلقة تركيز ظاهرة على كل عنصر تفاعلي. الخطأ يتقال بالنص مش باللون بس. وأي تغيير بيحصل من غير ما الصفحة تتحمّل (زي عدد النتايج) لازم يتعلن بـ aria-live.
🔬 الاختباراضغط Tab من أول الصفحة لآخرها. لازم تعرف في كل لحظة إنت فين، وتوصل لكل زرار، وتشغّله بـ Enter أو Space. لو ضعت أو وقفت — رسبت.

// bugs_in_file

  • outline:none مفروض على كل الحقول والأزرار — حلقة التركيز مقتولة
  • مفيش أي <label> — الاعتماد كله على placeholder اللي بيختفي أول ما تكتب
  • الخطأ بيتعرض بحدود حمرا بس، من غير نص يقول المشكلة إيه
  • عدّاد المسجلين بيتغير في صمت — قارئ الشاشة مش هيعرف حاجة اتغيرت
  • نص رمادي #b9b9b9 و#bbbbbb على خلفية فاتحة — تباين تحت الحد بكتير
round_02_prompt.txt
اجعل الصفحة قابلة للاستخدام بالكيبورد وقارئ الشاشة: أضف label مرئياً لكل حقل مربوطاً بـ for/id مع الإبقاء على placeholder كمثال فقط لا كتسمية. احذف كل outline:none واستبدلها بحلقة تركيز واضحة عبر :focus-visible بلون ذهبي وسمك 2px مع offset. حوّل رسائل الخطأ إلى نص عربي صريح أسفل كل حقل يشرح المشكلة والمطلوب، ولا تعتمد على اللون وحده، واربطه بالحقل عبر aria-describedby مع aria-invalid. ضع عدّاد المسجلين وأي رسالة حالة داخل عنصر aria-live="polite". ارفع تباين كل النصوص الرمادية إلى 4.5:1 على الأقل مع خلفيتها. لا تغيّر التخطيط ولا الوظائف.
criterion_03

الحالات الأربع — كل واجهة ليها أربع أوجه

الجولة ٣ · ١٢ دقيقة

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

📏 القاعدةكل قايمة لازم لها حالة فارغة فيها الخطوة التالية مش مجرد «لا توجد بيانات». كل عملية بتاخد وقت لازم مؤشر تحميل وتعطيل للزرار أثناءها. كل نتيجة لازم تأكيد مرئي يفضل كفاية عشان يتقرا.
🔬 الاختبارامسح كل البيانات ← إيه اللي بيظهر؟ اضغط الزرار عشر مرات بسرعة ← بيتنفذ كام مرة؟ اقفل النت وجرّب ← الصفحة بتقول حصل إيه ولا بتسكت؟

// bugs_in_file

  • افلتر على مستوى مفيهوش حد ← جدول فاضي وسطر رؤوس معلّق في الفراغ
  • التسجيل بياخد ١٢٠٠ مللي ثانية من غير أي مؤشر — المستخدم بيفتكرها اتعلقت
  • الزرار مبيتعطلش أثناء الإرسال ← ضغطة زيادة = تسجيل مكرر
  • بعد النجاح مفيش أي رسالة — الفورم بيتمسح وخلاص، والمستخدم مش عارف اتسجل ولا اتمسح
  • مفيش أي مسار للخطأ أصلاً في الكود
round_03_prompt.txt
أضف الحالات الأربع لكل واجهة في الصفحة. الحالة الفارغة: عندما لا توجد نتائج بعد الفلترة أو التسجيل، أخفِ الجدول واعرض بطاقة فيها سبب الفراغ والخطوة التالية بصيغة إرشادية عربية. حالة التحميل: أثناء عملية التسجيل عطّل زرار الإرسال وغيّر نصه إلى "جارٍ التسجيل..." وامنع أي ضغط إضافي حتى انتهاء العملية. حالة النجاح: بعد التسجيل اعرض رسالة تأكيد واضحة تبقى 4 ثوانٍ على الأقل داخل عنصر aria-live، وأبرز الصف الجديد في الجدول لحظياً. حالة الخطأ: أضف مساراً للفشل يعرض رسالة عربية تشرح ما حدث وكيف يعيد المحاولة، بدون كسر بقية الصفحة. لا تعتمد على alert في أي حالة منها.
criterion_04

تحصين المدخلات — مدخل المستخدم بيانات مش كود

الجولة ٤ · ١٢ دقيقة

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

📏 القاعدةالنص اللي جاي من المستخدم يتحط بـ textContent — مش innerHTML. والتحقق يتعمل على القيمة الفعلية: النوع، الطول، النطاق، والصيغة. الحقل المطلوب متحقق منه في الكود مش في العين.
🔬 الاختباراكتب في خانة الاسم: <b>تجربة</b> وسجّل. لو ظهر الاسم بخط عريض بدل ما يظهر بالأقواس زي ما كتبته — الصفحة عندك ثغرة. جرّب كمان: اسم فاضي بمسافات، رقم من ٣ أرقام، اسم ٥٠٠ حرف.

// bugs_in_file

  • الجدول بيتبني كله بـ innerHTML من قيم المستخدم مباشرة — ثغرة حقن كاملة
  • التحقق بيقارن بـ == "" بس ← «مسافة» تعتبر اسم صحيح
  • رقم الموبايل مقبول بأي شكل: حروف، ٣ أرقام، رموز
  • حقل المستوى ممكن يفضل فاضي والتسجيل بيعدي
  • مفيش حد أقصى لطول الاسم أو الملاحظات — ٥٠٠ حرف بيكسر الجدول
round_04_prompt.txt
حصّن الصفحة ضد مدخلات المستخدم. أولاً: أعد بناء صفوف الجدول باستخدام createElement وtextContent بدلاً من innerHTML، بحيث لا يُنفَّذ أي HTML يكتبه المستخدم إطلاقاً، وأبقِ نفس الشكل الحالي للجدول. ثانياً: أضف تحققاً حقيقياً قبل التسجيل — الاسم بعد trim لا يقل عن 3 أحرف ولا يزيد عن 60، رقم الموبايل 11 رقماً يبدأ بـ 01 وأرقاماً فقط، المستوى إلزامي، والملاحظات بحد أقصى 200 حرف مع عدّاد أحرف. كل خطأ يظهر كنص عربي أسفل حقله يشرح الصحيح، والتركيز ينتقل تلقائياً لأول حقل خاطئ. لا تستخدم alert.
criterion_05

الاستجابة الحقيقية — الشاشة الصغيرة مش نسخة مصغّرة

الجولة ٥ · ١٢ دقيقة

«متجاوب» مش يعني الصفحة بتصغر. يعني التخطيط بيتغير عشان يخدم شاشة تانية وإيد بتلمس. الجدول اللي بيتسحب يمين وشمال، والزرار اللي ارتفاعه ٢٨ بكسل، والحاوية اللي عرضها ثابت — كلها بتقول للزائر إن الصفحة دي مش معمولة له.

📏 القاعدةالحاويات بـ max-width مش width ثابت. أهداف اللمس ٤٤–٤٨ بكسل ارتفاع كحد أدنى. الجدول على الموبايل يتحوّل لبطاقات. صفر تمرير أفقي — و100vw ممنوعة لأنها بتحسب عرض شريط التمرير.
🔬 الاختبارافتح على عرض 390px وحاول تسحب الصفحة يمين وشمال بإصبع واحد. أي حركة أفقية = عطل. وبعدين جرّب تضغط كل زرار بإبهامك مش بالماوس.

// bugs_in_file

  • .container{width:900px} عرض ثابت — بيسبب تمرير أفقي على أي موبايل
  • .top{width:100vw} بتزوّد عرض الصفحة عن الشاشة
  • الجدول بـ white-space:nowrap و٥ أعمدة — بيخرج برا الشاشة
  • ارتفاع الأزرار ٢٨ بكسل — أقل من نص هدف اللمس المطلوب
  • أحجام خط ثابتة صغيرة (١٣ بكسل للحقول) على كل المقاسات
round_05_prompt.txt
اجعل الصفحة متجاوبة فعلياً بمنهج mobile-first. استبدل العرض الثابت للحاوية بـ max-width مع padding جانبي، واحذف أي استخدام لـ 100vw. اضبط ارتفاع كل الأزرار والحقول عند 48px على الأقل مع مساحة لمس مريحة. عند عرض أقل من 700px حوّل صفوف الجدول إلى بطاقات، كل بطاقة تعرض التسميات بجوار القيم، مع إزالة white-space:nowrap. اجعل أحجام الخطوط سائلة عبر clamp بحيث يكون النص مقروءاً على 390px دون تكبير. الهدف النهائي: صفر تمرير أفقي على عرض 390px — تحقق من ذلك وأخبرني بما عدّلته لتحقيقه.
criterion_06

رموز التصميم — مصدر واحد للحقيقة

الجولة ٦ · ١٢ دقيقة

في المحاضرة ٠٢ اتفقنا على الاتساق كمعيار جمالي. دلوقتي هنفرضه تقنياً: قيمة واحدة متعرّفة في مكان واحد، والباقي بيشير ليها. ده مش ترتيب للكود — ده اللي بيخلي طلب زي «غيّر الذهبي كله» يتنفذ في سطر واحد بدل ما الوكيل يلف على ٤٠ مكان وينسى تلاتة.

📏 القاعدةكل لون ومسافة ونصف قطر وظل يتعرّف مرة واحدة كـ CSS variable في :root. صفر أرقام سحرية مبعثرة، وصفر ستايلات inline. والحركة تحترم prefers-reduced-motion.
🔬 الاختبارغيّر قيمة اللون الذهبي في مكان واحد. لو الصفحة كلها اتغيرت — نظامك سليم. لو فضل ذهبي في مكانين — عندك نسخ مكررة بقيم متقاربة والعين مش شايفة الفرق بس النظام مكسور.

// bugs_in_file

  • الكحلي متكتب بتلات قيم متقاربة: #1a2b4c و#1b2c4e و#19294a
  • الذهبي متكرر بقيمتين: #C9A961 و#c8a860
  • أربع قيم مختلفة لنصف القطر (٤ / ٦ / ١٦ / ٢٠) بدون سبب، وظلّان مختلفان
  • ستايلات inline على العناصر بدل الأصناف
  • أنيميشن nudge شغال باستمرار وبيتجاهل prefers-reduced-motion
  • مفيش أي استعداد للطباعة رغم إن الصفحة قايمة مسجلين هتتطبع
round_06_prompt.txt
وحّد نظام الصفحة تقنياً. عرّف في :root متغيرات CSS لكل الألوان والمسافات وأنصاف الأقطار والظل، ثم استبدل كل قيمة مكررة في الملف بالمتغير المناسب — ووحّد التدرجات المتقاربة في قيمة واحدة (الكحلي واحد والذهبي واحد). اجعل المسافات كلها من سلّم مضاعفات 8px، ونصفي قطر فقط: واحد للبطاقات وواحد للأزرار، وظل واحد. انقل كل الستايلات inline إلى أصناف. أوقف الحركة المستمرة واجعلها استجابة للتفاعل فقط بمدة 200ms، وأضف كتلة prefers-reduced-motion تلغي الحركة. أضف بلوك @media print ينظّف الصفحة للطباعة: يخفي النموذج والأزرار ويطبع جدول المسجلين فقط بألوان اقتصادية. في نهاية ردك اذكر عدد القيم المكررة التي وحّدتها.
// ── إدارة الوقت في المحاضرة

جدول الجلسة

١٠٠ دقيقة تقريباً. كل جولة بنفس الإيقاع: اختبار (٢د) ← برومبت (١د) ← تنفيذ ومراجعة diff (٦د) ← إعادة اختبار ونقاش (٣د).

الجولةالمعياراختبار القبول السريعالوقت
٠التشخيص بالعينخمس تجارب + ملف bugs.md10'
١البنية الدلاليةعطّل الـ CSS ← المستند لسه مفهوم12'
٢إمكانية الوصولتنقّل بالـ Tab لآخر الصفحة وسجّل بالكيبورد12'
٣الحالات الأربعفلتر فاضي + ضغط عشر مرات + رسالة نجاح12'
٤تحصين المدخلاتاكتب وسم HTML في الاسم ← ظهر كنص12'
٥الاستجابة واللمس390px بصفر تمرير أفقي + أزرار 48px12'
٦رموز التصميمغيّر متغيّر الذهبي ← الصفحة كلها اتغيرت12'
٧المراجعة والمقارنةالأصلي جنب المصلَّح + برومبت المراجعة الشامل15'
// ── الخلاصة · البرومبت اللي هتستخدمه في كل مشروع بعد كده

برومبت مراجعة الجودة الشامل

الجولات الستة اتحولت لأمر واحد. ده مش بديل عن إنك تفهم المعايير — ده اختصار بعد ما تكون فهمتها.

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

quality_review_prompt.txt — master
راجع هذه الصفحة على المعايير الستة التالية، وقبل أن تعدّل أي شيء اكتب لي تقريراً بكل مخالفة وجدتها مصنّفة حسب المعيار ودرجة خطورتها، ثم انتظر موافقتي:

١ · البنية الدلالية: عناصر HTML مناسبة لوظائفها، header/main/section/form، أزرار button حقيقية لا div، تسلسل عناوين سليم بـ h1 واحد، وlang وdir وtitle وmeta description.

٢ · إمكانية الوصول: label مربوط لكل حقل، حلقة تركيز ظاهرة عبر :focus-visible، وصول كامل بالكيبورد لكل عنصر تفاعلي، رسائل خطأ نصية لا لونية مربوطة بـ aria-describedby، وaria-live للتغييرات الديناميكية، وتباين 4.5:1 لكل النصوص.

٣ · الحالات الأربع: لكل واجهة حالة فارغة مرشدة، وحالة تحميل تعطّل الزرار، وحالة نجاح مؤكَّدة مرئياً، وحالة خطأ تشرح وتقترح الحل — بدون alert.

٤ · تحصين المدخلات: بناء العناصر بـ textContent وcreateElement لا innerHTML لأي قيمة يكتبها المستخدم، وتحقق فعلي من النوع والطول والنطاق والصيغة مع رسائل عربية واضحة.

٥ · الاستجابة الحقيقية: mobile-first، max-width لا عرض ثابت، صفر تمرير أفقي على 390px، أهداف لمس 48px، جداول تتحول إلى بطاقات على الشاشات الصغيرة، وأحجام خط سائلة.

٦ · رموز التصميم: متغيرات CSS في :root لكل لون ومسافة ونصف قطر وظل، صفر قيم مكررة أو متقاربة، صفر ستايل inline، حركة عند التفاعل فقط مع احترام prefers-reduced-motion، وبلوك @media print إن كان للصفحة محتوى يُطبع.

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

التكليف: طبّق الستة على مشروعك إنت

التدريب النهارده كان على مريض جاهز. التكليف إنك تكتشف إن مشروعك من الأساينمنت اللي فات فيه نفس الأمراض.

سلّم تلات حاجات

واختبارات القبول النهائية

student@motrjim:~/training-05 $ diff patient_zero_original.html patient_zero_fixed.html

أكاديمية مُترجم الترجمة في عصر الذكاء الاصطناعي

© 2026 جميع الحقوق محفوظة

Scroll to Top