vibe-5 - Motrjim Academy S
المحاضرة ٠٥ — من «بيشتغل» إلى «بيتسلّم» | كورس Vibe Coding · أكاديمية مُترجم
lecture_05 · المهارات المتقدمة | Vibe Coding · أكاديمية مُترجم
lecture_02.html lecture_03.html assignment_04.html ● lecture_05.html ✕
student@motrjim:~/vibe-coding $ git log --oneline | head -4
/* lecture 05 · advanced agent engineering */

الوكيل بقى بيسمع كلامك —
دلوقتي هنشوف إنت بتقوله إيه

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

--skills 7 --level advanced --duration ~150min --files 7 قبل الكود --project مِرصاد --lab patient_zero + bug_hunt ×2 --prereq lectures 02 · 03 · 04
// ── ٠ · التمهيد

ليه شغلك واقف عند نفس المستوى؟

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

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

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

  • محاضرة ٠٢: معايير التصميم — الهرمية، التباين، السلالم، لعبة المسح
  • محاضرة ٠٣: بيئة الشغل — Cursor، الموديلات، الـ diff، الـ checkpoints
  • أساينمنت ٠٤: مشروع كامل من رسالة عميل غامضة لصفحة شغّالة

اللي هناخده النهارده

  • تهندس السياق بدل ما تشرح كل مرة من الأول
  • تخلي قواعدك دايمة في الملف مش في المحادثة
  • تكتب مواصفة قبل الكود وتخلي الوكيل يتحاسب عليها
  • تبني حلقة تحقق تخلي الوكيل يثبت شغله
  • تشخّص قبل ما تصلّح، وتراجع الـ diff كمهارة
  • تعرف إمتى توقّف الوكيل وتكتب بإيدك
// ── المهارات السبع

سبعة تحوّلات في طريقة شغلك

كل مهارة فيها: القاعدة، الفرق بين الطريقة القديمة والجديدة، وملف أو برومبت جاهز تمشي بيه.

skill_01

هندسة السياق — إنت بتتحكم في اللي الوكيل بيشوفه

١٥ دقيقة

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

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

السياق مورد بتديره، مش خانة بتملاها. القليل المنقّى أقوى من الكتير المكوّم.
❌ الطريقة القديمة محادثة واحدة طولها ٤٠ رسالة، فيها ٣ مشاريع مختلفة، ومحاولتين فاشلين، ونسخة قديمة من الكود — وبعدين: «طب ممكن تظبط الزرار ده؟»
✅ الطريقة المهندسة محادثة جديدة لكل مهمة مستقلة، بتبدأ بـ @ملف محدد + المواصفة + المطلوب في سطرين. الوكيل شايف اللي يخصه بس.

// practice

  • استخدم @ دايماً: أشِر للملف أو الجزء المقصود بدل ما تقول «الملف اللي فات».
  • الصق الجزء المعطوب فقط لما تسأل عن باج — مش الملف كله.
  • ابدأ محادثة جديدة عند تغيير المهمة — مش عند تغيير السؤال. المهمة الجديدة = سياق جديد.
  • غيّرت الموديل؟ أعِد لصق المواصفات. الموديل الجديد مشافش المحادثة بنفس الشكل.
  • علامة التلوّث: الوكيل رجّع خطأ إنت صلّحته قبل كده ← اقفل وافتح جديدة، متجادلوش.
skill_02

قواعد المشروع — اكتب مرة، تسري على كل محادثة

١٥ دقيقة

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

Cursor بيقرا ملف قواعد من المشروع تلقائياً ويحقنه في كل طلب. الاسم والمكان بيختلفوا حسب الإصدار — النسخ الحديثة بتقرا AGENTS.md في جذر المشروع، وفيه كمان نظام .cursor/rules، والنسخ الأقدم بتستخدم .cursorrules. افتح الإعدادات عندك وشوف نسختك بتقرا إيه — المبدأ واحد مهما اتغير الاسم.

أي كلام بتكرره في أكتر من محادثة، مكانه ملف قواعد — مش ذاكرتك.
AGENTS.md — قالب جاهز عدّله على مشروعك
# قواعد مشروع: ___ اسم المشروع

## اللغة والاتجاه
- كل المحتوى بالعربية الفصحى، والصفحة dir="rtl" و lang="ar".
- المصطلحات الإنجليزية داخل النص توضع في عنصر dir="ltr" محاذٍ مع سياقه.

## نظام التصميم — لا يُخالَف
- الألوان: كحلي ___ · ذهبي ___ · كريمي ___ · وتُعرَّف كمتغيرات في :root ولا تُكتب مباشرة.
- الخط: Cairo فقط، بسلّم أحجام ثابت، وبلا أي خط ثانٍ.
- المسافات: مضاعفات 8px حصراً.
- نصف قطر واحد للبطاقات وواحد للأزرار، وظل واحد في المشروع كله.
- الذهبي للأفعال فقط: زرار أساسي واحد ممتلئ في كل شاشة والباقي outline.
- ممنوع: التدرجات اللونية، والإيموجي في الواجهة، والحركة المستمرة.

## معايير الكود الإلزامية
- ملف HTML واحد self-contained بلا أي مكتبة خارجية عدا خط Cairo.
- HTML دلالي: header/main/section/form، وbutton حقيقي لكل عنصر تفاعلي، وh1 واحد بتسلسل سليم.
- كل حقل له label مربوط، وحلقة تركيز ظاهرة عبر :focus-visible.
- بناء العناصر بـ textContent وcreateElement، وممنوع innerHTML لأي قيمة من المستخدم.
- كل قائمة لها حالة فارغة مرشدة، وكل عملية لها حالة تحميل، وكل نتيجة لها تأكيد مرئي.
- mobile-first: صفر تمرير أفقي على 390px، وأهداف لمس 48px.
- ممنوع alert نهائياً؛ الرسائل تظهر داخل الصفحة.

## أسلوب العمل معي
- عند أي غموض في الطلب: اسأل قبل أن تفترض.
- قبل التنفيذ في المهام الكبيرة: اكتب خطة بلا كود وانتظر موافقتي.
- بعد كل تعديل: اذكر باختصار ما غيّرته ولماذا.
- لا تنشئ ملفات جديدة ما لم أطلب ذلك صراحةً.

// note

القاعدة الذهبية في كتابة الملف ده: اكتب القيود مش التمنيات. «خلي التصميم حلو» مش قاعدة. «الذهبي للأفعال فقط، وزرار ممتلئ واحد في الشاشة» قاعدة — لأنها قابلة للفحص، وأي مخالفة ليها تتشاف بالعين.

skill_03

المواصفة قبل الكود — المستند اللي بيتحاسب عليه

٢٠ دقيقة

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

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

أي قرار مش مكتوب في المواصفة، الوكيل هياخده مكانك — وإنت هتكتشفه متأخر.
❌ طلب غامض «اعمل صفحة حجز فيها مواعيد متاحة، والعميل يختار ويأكد.»
← نتيجة تشتغل، وفيها ١٠ قرارات إنت مشفتهاش.
✅ مواصفة محدَّدة «ساعات العمل ١٠ص–٨م، وآخر ميعاد ينتهي قبل الإقفال بمدة الخدمة. الجمعة معطّلة. تغيير الخدمة يعيد توليد المواعيد ويصفّر الاختيار السابق.»
← نتيجة قابلة للمحاسبة.
specs.md — الهيكل الإلزامي
# مواصفة: ___ اسم الشاشة

## ١ · الهدف في جملة
من يستخدمها، ولماذا، وما الفعل الوحيد الناجح.

## ٢ · المدخلات
لكل حقل: الاسم · النوع · إلزامي أم لا · النطاق المسموح · رسالة الخطأ عند المخالفة.

## ٣ · المعادلات وترتيب العمليات
اكتب المعادلة كاملة بالترتيب حرفياً، وحدّد التقريب: أين يحدث ولأي خانة.
مثال: المجموع ← ناقص الخصم ← الصافي ← الضريبة على الصافي ← الإجمالي.
الحساب على القيم الكاملة، والتقريب عند العرض فقط.

## ٤ · القواعد وأولوياتها عند التعارض
اكتبها مرقّمة بالأولوية، لأن الحالات ستتعارض حتماً.
مثال: الحالة "مسلَّم" تلغي أي حساب للتأخير مهما كان التاريخ.

## ٥ · الحالات الأربع
- فارغة: ماذا يظهر ومع أي خطوة تالية؟
- تحميل: ما الذي يتعطّل وماذا يُعرض؟
- خطأ: ما نصّ الرسالة وما البديل المقترح؟
- نجاح: كيف يتأكد المستخدم ولكم من الوقت؟

## ٦ · الحالات الحدية المحسومة مسبقاً
القيمة صفر · القيمة عند الحد بالضبط · نص عربي طويل جداً · ضغط متكرر سريع ·
تاريخ فائت · قائمة فارغة · مدخل غير متوقع.

## ٧ · معايير القبول
قائمة جُمل قابلة للاختبار، كل واحدة إما تحققت أو لا — بلا رأي.
مثال: "اكتب 10 وحدات فقط ← السعر يساوي الحد الأدنى لا القيمة المحسوبة."

## ٨ · خارج النطاق
ما لن تفعله هذه الشاشة صراحةً — لمنع توسّع الوكيل من تلقاء نفسه.

// workflow

  1. اكتب specs.md بإيدك — دي أهم ٢٠ دقيقة في المشروع كله.
  2. ابدأ المحادثة بـ: «اقرأ @specs.md واكتب خطة تنفيذ بلا كود».
  3. راجع الخطة وصلّح فيها. أرخص تصحيح هو اللي بيحصل قبل الكود.
  4. وبعدين: «نفّذ المواصفة بنداً بنداً، ولو وجدت بنداً غامضاً اسألني قبل أن تفترض».
skill_04

حلقة التحقق — خلّي الوكيل يثبت شغله

٢٠ دقيقة

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

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

«تم» مش نتيجة. النتيجة هي: أي بند اتحقق، وفين في الكود، وإيه اللي لسه ناقص.
verification_prompt.txt
راجع تنفيذك مقابل معايير القبول في @specs.md بنداً بنداً.
لكل بند اكتب سطراً واحداً بهذه الصيغة حصراً:

[البند] — متحقق / غير متحقق / متحقق جزئياً — الموقع في الكود (اسم الدالة أو رقم السطر) — ملاحظة في عشر كلمات.

قواعد إلزامية عليك:
- لا تصلح أي شيء في هذا الرد؛ التقرير فقط.
- إن كان بند غير متحقق فاذكره صراحةً ولا تبرّره.
- إن كنت غير قادر على التحقق من بند برمجياً فاكتب "يحتاج اختباراً يدوياً" واذكر خطوات الاختبار.
- في نهاية التقرير: اذكر أي حالة حدية في المواصفة لم تعالجها.

// self_test_prompt

والصيغة الأقوى: خليه يهاجم شغله بنفسه قبل ما تهاجمه إنت.

adversarial_prompt.txt
تصرّف الآن كمختبِر جودة مهمته كسر هذه الصفحة، لا كمطوّر يدافع عنها.
اكتب لي عشر حالات اختبار يُرجَّح أن تفشل فيها هذه الصفحة، مرتبة من الأخطر إلى الأقل.
لكل حالة: ما الذي سيفعله المستخدم بالضبط، وما النتيجة المتوقعة، وما النتيجة الفعلية المرجّحة في الكود الحالي.
ركّز على: القيم عند الحدود تماماً · القيم الصفرية والسالبة · النصوص العربية الطويلة جداً ·
الضغط المتكرر السريع · التواريخ الفائتة · القوائم الفارغة · تغيير اختيار سابق بعد بناء ما يليه عليه.
لا تصلح شيئاً الآن — القائمة فقط، وسأختار منها.
skill_05

التشخيص قبل العلاج — منهج إصلاح الأعطال

٢٠ دقيقة

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

المنهج الصح ثلاث مراحل مفصولة: عَرَض ← فرضية ← إصلاح. وممنوع تعدّي مرحلة قبل ما تخلص اللي قبلها. الفصل ده هو الفرق بين «صلّحتها» و«فهمتها».

متطلبش إصلاح لحاجة مفهمتش سببها. الوكيل هيرضيك بإخفاء العَرَض.

١ · العَرَض

اللي عملته ← اللي توقعته ← اللي حصل فعلاً. بالأرقام والخطوات، بدون تفسير ولا تخمين.

٢ · الفرضية

السبب المرجّح في سطر محدد، وإزاي نثبته أو ننفيه. من غير أي تعديل لسه.

٣ · الإصلاح

أضيق تعديل ممكن يعالج السبب، وبعده إعادة اختبار للعَرَض ولما حواليه.

diagnosis_prompt.txt
لا تعدّل أي شيء في هذا الرد.

العَرَض:
- ما فعلته: ___
- ما توقعته: ___
- ما حدث فعلاً: ___

المطلوب منك:
١ · اذكر ثلاثة أسباب محتملة مرتبة بالاحتمالية، ولكل سبب السطر أو الدالة المسؤولة.
٢ · لكل سبب: كيف أتحقق منه بنفسي في أقل من دقيقة؟
٣ · اختر السبب الأرجح واشرح لماذا ترجّحه على الاثنين الآخرين.
٤ · صف الإصلاح المقترح بالكلمات فقط، واذكر ما الذي قد ينكسر بسببه في مكان آخر.

سأراجع تحليلك ثم أطلب التنفيذ. لا تكتب كوداً الآن.

// lab

هنطبّق المنهج ده عملياً النهارده على تلات ملفات معطوبة: patient_zero.html (٣٠ عطل في الشكل والبنية)، bug_hunt_02.html (سلة طلب — أعطال في الحسابات)، وbug_hunt_03.html (لوحة تسليمات — أعطال في الحالة والوقت). الملفين التانيين شكلهم سليم تماماً وشغالين — وده اللي بيخليهم أخطر.

skill_06

مراجعة الفروق — أخطر مهارة وأكتر واحدة بتتسرّع فيها

١٥ دقيقة

الـ diff هو آخر خط دفاع بينك وبين كود مش فاهمه. وأغلب الطلبة بيدوسوا «قبول» بعد نظرة سريعة — وده بيبني مشروع في الضلمة. المهارة هنا مش إنك تقرا كل سطر؛ المهارة إنك تعرف تدوّر على إيه.

// review_checklist — خمس أسئلة قبل أي قبول

  • حجم التعديل معقول للطلب؟ طلبت تغيير لون وجايلك ٨٠ سطر ← ارفض واطلب أضيق.
  • فيه حاجة اتشالت مقصدتش تشيلها؟ الأحمر أخطر من الأخضر. دوّر على تحقق أو حالة اتحذفت.
  • فيه أرقام أو ألوان جديدة برّه النظام؟ قيمة مكتوبة مباشرة بدل المتغير = بداية تفكك النظام.
  • فيه مكتبة أو ملف اتضاف؟ ممنوع في مشروع self-contained إلا لو إنت طلبته.
  • الجزء اللي كان شغال، لسه شغال؟ الإصلاح اللي بيكسر حاجة تانية مش إصلاح.
لو مش فاهم سطر في الـ diff، متقبلوش — اسأل عنه. القبول إقرار بالفهم.
❌ الرد المتسرّع قبول ← الصفحة اتكسرت ← «رجّعها زي ما كانت» ← الوكيل بيصلّح فوق الكارثة ← الملف بقى أسوأ من الأول.
✅ الرد المنضبط رفض ← Restore checkpoint ← برومبت أضيق نطاقاً بمواصفة أدق ← تنفيذ ← مراجعة ← قبول.
skill_07

إدارة النطاق — إمتى توقّف الوكيل وتكتب بإيدك

١٥ دقيقة

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

الحالةالأفضلليه
بناء أول نسخة من شاشة كاملة بمواصفة جاهزةAgentمهمة واسعة ومتكررة الطابع — أعلى عائد
تغيير قيمة أو لون أو نص إنت شايف سطرهيدويالكتابة أسرع من كتابة البرومبت نفسه
تعديل محدود على جزء إنت حدّدتهInlineنطاق مقفول = خطر أقل وتكلفة أقل
باج غامض مش عارف مصدرهChatالتشخيص محادثة، مش تعديل
توحيد قيم متكررة في الملف كلهAgentتعديل متعدد المواضع — بالظبط اللي بيتفوّق فيه
محاولتين متتاليتين فشلوا في نفس الحاجةقفالمشكلة في المواصفة مش في التنفيذ — ارجع اكتبها
قاعدة المحاولتين: فشل مرتين على نفس النقطة ← مفيش محاولة تالتة. ارجع للمواصفة.

والقاعدة الأهم في الباب ده: متسلّمش كود إنت مش فاهمه. مش لازم تعرف تكتبه من الأول، لكن لازم تعرف كل جزء بيعمل إيه وليه موجود — لأنك إنت اللي هتترد عليك في التعديل الجاي، ومش هيكون الوكيل قاعد جنبك ساعتها.

// ── ملفات المشروع · التجهيز قبل Cursor

سبعة ملفات — تبني منها المشروع قبل أول سطر كود

الفرق بين اللي بيفتح Cursor ويكتب طلب واللي بيفتحه وعنده الملفات دي جاهزة هو الفرق بين نصف يوم شغل ونص ساعة. أربعة منها بتتكتب قبل ما تبدأ، واتنين بيتكتبوا أثناء الشغل، وواحد عند التسليم.

my-project/ ├── AGENTS.md # القواعد الدائمة — تسري على كل محادثة ├── specs.md # المواصفة — القرارات قبل الكود ├── content.ar.md # المحتوى والبيانات الحقيقية ├── test-cases.md # القيم الشريرة وحالات الاختبار ├── prompt_log.md # سجل المحاولات — يُكتب أثناء الشغل ├── diagnosis.md # سجل الأعطال — يُكتب أثناء الشغل ├── handoff.md # رسالة التسليم والقرارات └── index.html # الناتج — آخر ملف يظهر في المجلد

لاحظ ترتيب المجلد: ملف الكود آخر واحد. ده مش شكل — ده ترتيب التفكير. الطالب اللي بيبدأ بـ index.html بيقضي بقية اليوم بيصلّح قرارات اتاخدت من غيره.

// ── ملف بملف

كل ملف: بيحل إيه، وبيتكتب إزاي

لكل ملف: غرضه في جملة، اللي يتحط فيه، اللي ممنوع يتحط فيه، وقالب تنسخه.

file_01

AGENTS.md — القواعد الدائمة

قبل الشغل

الغرض: يمنعك من إعادة لصق نظام التصميم والمعايير في أول كل محادثة — القواعد بتتحقن تلقائياً في كل طلب.

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

القالب الكامل موجود فوق في المهارة ٠٢. بيتكتب مرة واحدة للمشروع كله، وبيتعدّل نادراً.

file_02

specs.md — المواصفة

قبل الشغل

الغرض: ياخد القرارات اللي الوكيل هياخدها مكانك لو سكتّ — ترتيب العمليات، التقريب، الأولويات عند التعارض.

يتحط فيهالمدخلات بنطاقاتها · المعادلات بترتيبها حرفياً · القواعد مرقّمة بالأولوية · الحالات الأربع · الحالات الحدية · معايير القبول · خارج النطاق.
ممنوع فيهكود · أسماء أصناف CSS · أي قرار تنفيذي. المواصفة بتقول إيه وليه — مش إزاي.

القالب الكامل بأقسامه الثمانية موجود فوق في المهارة ٠٣. ملف لكل شاشة، مش ملف للمشروع كله.

file_03

content.ar.md — المحتوى والبيانات الحقيقية

قبل الشغل

الغرض: يمنع «عنوان تجريبي» و«Lorem ipsum». التصميم اللي بينجح مع محتوى مثالي بس تصميم فاشل — والعميل بيكتشف ده أول ما يحط كلامه الحقيقي.

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

يتحط فيهكل نص هيظهر في الواجهة بصيغته النهائية · بيانات تجريبية واقعية بأسماء وأسعار وتواريخ حقيقية · وعمداً: أطول عنوان متوقع، وأقصر واحد، واسم إنجليزي، ورقم كبير.
ممنوع فيهنصوص وهمية · «اكتب هنا» · بيانات كلها بنفس الطول (دي بتخفي مشاكل التخطيط بدل ما تكشفها).
content.ar.md — قالب
# محتوى: ___ اسم الشاشة

## النصوص الثابتة
- العنوان الرئيسي: ___
- العنوان الفرعي: ___
- نص الزرار الأساسي: ___
- نصوص الحالة الفارغة / التحميل / النجاح / الخطأ: ___

## رسائل الأخطاء (نص كل رسالة كما ستظهر)
- حقل فارغ: ___
- صيغة غير صحيحة: ___
- تجاوز الحد: ___

## البيانات التجريبية — واقعية ومتفاوتة عمداً
| ___ | ___ | ___ |
|---|---|---|
| أقصر مدخل ممكن | | |
| مدخل متوسط طبيعي | | |
| أطول عنوان عربي متوقع في الواقع | | |
| مدخل يحتوي اسماً إنجليزياً وسط العربي | | |
| مدخل برقم كبير أو تاريخ فائت | | |

## مصطلحات لا تُترجم ولا تُغيَّر
___
file_04

test-cases.md — القيم الشريرة

قبل الشغل

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

يتحط فيهلكل حالة: الفعل بالضبط · النتيجة المتوقعة · النتيجة الفعلية (تُملأ بعد الاختبار) · الحالة (نجح/فشل).
ممنوع فيه«اختبر الصفحة» · «شوف لو فيه أخطاء». الحالة اللي مش قابلة للحكم عليها بنعم/لا مش حالة اختبار.
test-cases.md — قالب بالحالات المتكررة
# حالات الاختبار: ___ اسم الشاشة

| # | الفعل بالضبط | المتوقع | الفعلي | ✅/❌ |
|---|---|---|---|---|
| 1 | إرسال والحقول كلها فارغة | رسالة عربية أسفل كل حقل مطلوب، والتركيز ينتقل لأول حقل | | |
| 2 | إدخال مسافات فقط في حقل مطلوب | يُرفض كأنه فارغ | | |
| 3 | إدخال قيمة سالبة أو صفر | تُرفض برسالة تشرح النطاق المسموح | | |
| 4 | إدخال حروف في حقل رقمي | تُرفض بلا ظهور NaN في أي مكان | | |
| 5 | القيمة عند الحد بالضبط (مثال: 500) | تُعامَل بحسب القاعدة المكتوبة لا بالتخمين | | |
| 6 | القيمة أقل بواحد وأكثر بواحد من الحد | السلوك مختلف ومتوقع في الحالتين | | |
| 7 | لصق نص عربي طويل جداً (300 حرف) | التخطيط لا ينكسر ولا يخرج عن الحاوية | | |
| 8 | لصق وسم HTML في حقل نصي | يظهر كنص عادي ولا يُنفَّذ | | |
| 9 | الضغط على زرار الإرسال 10 مرات سريعاً | تنفيذ واحد فقط | | |
| 10 | فلترة تُرجع صفر نتائج | حالة فارغة مرشدة لا جدول مقطوع | | |
| 11 | تغيير اختيار سابق بُني عليه ما بعده | كل ما بُني عليه يُصفَّر ويُعاد بناؤه | | |
| 12 | تاريخ فائت / تاريخ اليوم بالضبط | "متأخر" و"اليوم" لا رقم سالب ولا صفر | | |
| 13 | فتح الصفحة على عرض 390px | صفر تمرير أفقي وكل الأزرار 48px | | |
| 14 | التنقل بالكيبورد حتى إتمام العملية | ممكن بالكامل بدون ماوس | | |
| 15 | إعادة تحميل الصفحة بعد إدخال بيانات | السلوك متوقع ومعلَن (تُحفظ أو تُفقد بوضوح) | | |
file_05

prompt_log.md — سجل المحاولات

أثناء الشغل

الغرض: ده الملف اللي بيخلّي مهارتك تتراكم بدل ما تتبخّر. البرومبت اللي نجح النهارده هتنساه بعد أسبوع — إلا لو مكتوب، ومكتوب معاه ليه نجح.

يتحط فيهالبرومبت بنصه · الموديل · النتيجة في سطر · التعديل اللي عملته في المحاولة اللي بعدها ولماذا.
ممنوع فيهالكتابة في آخر اليوم من الذاكرة. السجل اللي بيتكتب بأثر رجعي بيبقى قصة، مش سجل.
prompt_log.md — قالب
# سجل البرومبتات: ___ المشروع

## المحاولة 1 — [المهمة]
- **الموديل:** ___
- **البرومبت:** ___
- **النتيجة:** ___
- **المشكلة في الناتج:** ___
- **التعديل في المحاولة التالية والسبب:** ___

## المحاولة 2 — [نفس المهمة، نطاق أضيق]
- **الموديل:** ___
- **ما غيّرته في الصياغة:** ___
- **النتيجة:** ___

---
## خلاصة الجلسة
- **أنجح صيغة استخدمتها:** ___
- **أسوأ صيغة ولماذا فشلت:** ___
- **متى بدأت محادثة جديدة ولماذا:** ___
- **قاعدة أضيفها إلى AGENTS.md بعد اليوم:** ___
file_06

diagnosis.md — سجل الأعطال

أثناء الشغل

الغرض: يفرض عليك منهج المهارة ٠٥ — عَرَض ثم فرضية ثم إصلاح. الكتابة في الملف ده هي اللي بتمنعك من إنك تقول للوكيل «صلّحه» وخلاص.

يتحط فيهالعَرَض بالخطوات · السبب في سطر محدد · الإصلاح · والدرس المستفاد — وده أهم سطر لأنه اللي بيمنع تكرار العطل في المشروع الجاي.
ممنوع فيه«الصفحة مش شغالة» · «فيه مشكلة في الجدول». العَرَض من غير خطوات إعادة إنتاج مش عَرَض.
diagnosis.md — قالب
# سجل الأعطال: ___ المشروع

## عطل 1
- **العَرَض:** ما فعلته ___ / ما توقعته ___ / ما حدث فعلاً ___
- **خطوات إعادة الإنتاج:** 1) ___ 2) ___ 3) ___
- **الفرضية:** السبب المرجّح في ___ (الدالة/السطر)
- **كيف تحققت منها:** ___
- **الإصلاح:** ___
- **ما كان يمكن أن ينكسر بسببه وفحصته:** ___
- **الدرس المستفاد (بصيغة قاعدة عامة):** ___
file_07

handoff.md — رسالة التسليم

عند التسليم

الغرض: ده الملف اللي بيفرّق بين حد بيبعت ملف وحد بيسلّم شغل. العميل مش هيقرا كودك — هيقرا الرسالة دي، وعليها هيحكم عليك.

يتحط فيهإيه اللي اتعمل · القرارات اللي أخدتها في النقاط الغامضة · إيه اللي محتاج قرار منه · حدود الشغل الحالي بصراحة.
ممنوع فيهمصطلحات تقنية · اعتذارات · «الصفحة كاملة ومفيهاش أي مشاكل». الوضوح بيبني ثقة أكتر من الكمال المزعوم.
handoff.md — قالب
# تسليم: ___ اسم الشاشة

## ما تم تنفيذه
___ في فقرة واحدة بلغة العميل لا بلغة المطوّر.

## قرارات اتخذتها نيابةً عنك
كان في طلبك نقاط تحتمل أكثر من تفسير، وهذه اختياراتي وسببها:
1. ___ — اخترت ___ لأن ___. لو كان المقصود غير ذلك فالتعديل بسيط.
2. ___

## يحتاج قراراً منك
- ___
- ___

## حدود النسخة الحالية
___ بصراحة ووضوح (مثال: البيانات محفوظة في متصفحك أنت فقط ولا تُشارَك بين الأجهزة).

## كيف تستخدمها
1. ___ 2. ___ 3. ___

قاعدة المجلد

لو ملف من السبعة فاضي وإنت بتشتغل، ده مش «كسل» — ده إشارة. specs.md فاضي يعني إنت بتخمّن. content.ar.md فاضي يعني هتكتشف مشاكل التخطيط قدام العميل. test-cases.md فاضي يعني هتسلّم شغل مااتجربش.

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

المهارات السبع في مسار واحد

ده الروتين اللي المفروض تمشي عليه في أي مشروع بعد النهارده — من فتح الفولدر للتسليم.

تجهيز البيئة

فولدر مستقل · ملف قواعد المشروع فيه نظام التصميم والمعايير الإلزامية · فتح الفولدر من Cursor. القواعد بقت في الملف — مش هتلصقها تاني.

كتابة المواصفة

specs.md بإيدك: المدخلات بنطاقاتها، المعادلات بترتيبها، القواعد بأولوياتها، الحالات الأربع، الحالات الحدية، معايير القبول، وخارج النطاق.

خطة بلا كود

«اقرأ @specs.md واكتب خطة تنفيذ بلا كود». راجع الخطة وصلّحها. التصحيح هنا بيكلّف دقيقة؛ بعد الكود بيكلّف ساعة.

تنفيذ بسياق نظيف

محادثة مخصصة للمهمة دي، بالموديل المناسب، بإشارة @ للملفات المعنية. مفيش كلام زيادة في النافذة.

مراجعة الفروق

الخمس أسئلة قبل أي قبول. أي سطر مش فاهمه ← اسأل عنه. أي تعديل أوسع من الطلب ← ارفض واطلب أضيق.

حلقة التحقق

برومبت التحقق بنداً بنداً مقابل معايير القبول، وبعده البرومبت العدائي عشان يهاجم شغله بنفسه. وإنت تختبر بإيدك اللي هو قال عليه «يحتاج اختباراً يدوياً».

مراجعة الجودة الستة

البنية الدلالية · إمكانية الوصول · الحالات الأربع · تحصين المدخلات · الاستجابة الحقيقية · رموز التصميم. ده اللي بيحوّل «شغّال» لـ«قابل للتسليم».

التسليم والتوثيق

الملف + specs.md + سجل البرومبتات + رسالة تسليم مهنية فيها القرارات اللي أخدتها في النقاط الغامضة.

// ── المشروع المتقدم · مشروع المحاضرة

«مِرصاد» — فاحص جودة ترجمة يشتغل في المتصفح

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

الفكرة في جملة

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

ليه المشروع ده بالذات

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

محرّك الفحص — ثمانية فحوص

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

#الفحصالخطورةالمنطق المطلوب
1مقطع غير مترجمخطيرالهدف فارغ بعد trim، أو مطابق للمصدر حرفياً
2عدم تطابق الأرقامخطيراستخراج كل الأرقام من الطرفين ومقارنتها كمجموعات — مع تطبيع الأرقام الهندية ٠١٢٣ إلى 0123 قبل المقارنة
3مخالفة المسردخطيرلو مصطلح المسرد موجود في المصدر، لازم ترجمته المعتمدة تكون في الهدف — بمطابقة مطبَّعة
4عدم اتساق داخليتحذيرنفس المقطع المصدر مترجم بأكتر من صيغة مختلفة في الملف
5رموز نائبة مفقودةخطيررموز زي {0} أو %s موجودة في المصدر وناقصة في الهدف
6أقواس غير متوازنةتحذيرعدّ الأقواس وعلامات التنصيص في الهدف والتأكد من إغلاقها
7مشاكل مسافات وترقيمملاحظةمسافة مزدوجة · مسافة قبل علامة ترقيم · غياب المسافة بعدها
8طول غير متناسبملاحظةالهدف أطول من المصدر بأكثر من نسبة يحددها المستخدم

الواجهة المطلوبة

  • الإدخال: عمودان للصق (مقطع في كل سطر) + خانة مسرد بصيغة مصطلح = ترجمة في كل سطر + إعدادات الحدود.
  • مؤشرات علوية: عدد المقاطع · عدد المشاكل بكل درجة · نسبة سلامة محسوبة بمعادلة تكتبها إنت في المواصفة.
  • جدول المشاكل: رقم المقطع · نوع الفحص · الخطورة · الوصف · المصدر والهدف جنب بعض مع تمييز الجزء المشكوك فيه.
  • فلاتر: بالخطورة وبنوع الفحص — يشتغلوا مع بعض.
  • تجاهل مشكلة: زرار «مقبول» يشيلها من العد ويسيبها موسومة.
  • تصدير: زرار طباعة بتقرير A4 نضيف + زرار تنزيل التقرير CSV.

الفخاخ المدفونة — دي اللي هتفرق

فخاخ منطقية

فخاخ تقنية

خطة المحاضرة — خمس مراحل

المواصفة — بنكتبها سوا (١٥ دقيقة)

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

الهيكل والإدخال والجدول (٢٠ دقيقة)

الشكل الكامل بنظام التصميم من AGENTS.md، وتقسيم المدخل لمقاطع، وعرض الجدول ثنائي اللغة بـ dir مستقل لكل عمود. من غير أي فحص لسه.

محرّك الفحص — أول ثلاثة (٢٥ دقيقة)

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

باقي الفحوص والفلاتر والمؤشرات (٢٠ دقيقة)

الخمسة الباقيين، والفلاتر المتزامنة، والحالات الأربع، وفصل الفحص عن العرض عشان الفلترة متعيدش الفحص كل مرة.

التصدير والتحقق (٢٠ دقيقة)

طباعة A4 وتصدير CSV، وبعدين برومبت التحقق بنداً بنداً والبرومبت العدائي — والوكيل يقولنا هو نفسه إيه اللي ناقص.

بيانات العرض — فيها أخطاء مزروعة

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

demo_source.txt — المصدر
The agreement shall enter into force on 15 March 2026.
The Contractor shall deliver 3 copies of the report.
Please contact us at support@example.com for assistance.
The total amount is {0} EGP including 14% VAT.
The Party may terminate this Agreement (with notice) at any time.
The Contractor shall deliver 3 copies of the report.
This clause is governed by the laws of the Arab Republic of Egypt.
All rights reserved.
demo_target.txt — الهدف (فيه ٨ أعطال مزروعة)
يدخل الاتفاق حيز النفاذ في ١٥ مارس ٢٠٢٦.
يسلّم المقاول نسختين من التقرير.
Please contact us at support@example.com for assistance.
المبلغ الإجمالي هو ___ جنيهاً شاملاً ضريبة القيمة المضافة بنسبة 14%.
يجوز للطرف إنهاء هذا الاتفاق (بعد إخطار في أي وقت.
يقوم المقاول بتوريد ٣ نسخ من التقرير.
يخضع هذا البند لقوانين جمهورية مصر  العربية ، وذلك على النحو المبيّن في هذا الاتفاق وفي أي ملاحق لاحقة له.
demo_glossary.txt — المسرد
Agreement = اتفاق
Contractor = المقاول
Party = الطرف
report = تقرير
VAT = ضريبة القيمة المضافة

الأعطال المزروعة — للمدرّب

  • سطر ٢: الرقم 3 بقى «نسختين» ← عدم تطابق أرقام
  • سطر ٣: مش مترجم خالص ← مقطع غير مترجم
  • سطر ٤: الرمز النائب {0} اختفى ← رمز نائب مفقود
  • سطر ٥: قوس مفتوح من غير إغلاق ← أقواس غير متوازنة
  • سطر ٦: نفس مصدر سطر ٢ ومترجم بصيغة تانية ← عدم اتساق داخلي
  • سطر ٦: «توريد» بدل «تسليم» و«المقاول» صح ← اختبار للمسرد
  • سطر ٧: مسافة مزدوجة ومسافة قبل الفاصلة ← مشاكل ترقيم
  • سطر ٧: الهدف أطول من المصدر بنسبة كبيرة ← طول غير متناسب
  • سطر ٨: غايب تماماً ← عدد الأسطر مختلف (فخ المحاذاة)
project_kickoff_prompt.txt — برومبت المرحلة الثانية
@AGENTS.md @specs.md @content.ar.md

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

المتطلبات:
- ملف HTML واحد self-contained، بنظام التصميم المعرّف في AGENTS.md حرفياً.
- منطقة إدخال: حقلان نصيان كبيران للمصدر والهدف (كل سطر = مقطع)، وحقل ثالث للمسرد بصيغة "مصطلح = ترجمة".
- عند الضغط على "تحليل": قسّم النصين إلى مقاطع مع تجاهل الأسطر الفارغة، واعرضهما في جدول متقابل مرقّم.
- عمود المصدر داخل عنصر dir="ltr" وعمود الهدف dir="rtl"، وكل خلية محاذية مع عمودها.
- إن اختلف عدد أسطر المصدر عن الهدف فاعرض تنبيهاً واضحاً أعلى الجدول يذكر الرقمين، واعرض المقاطع الزائدة بخلية فارغة موسومة — لا تتجاهلها بصمت.
- ابنِ خلايا الجدول بـ createElement وtextContent فقط، فالنص كله من المستخدم.
- طبّق الحالات الأربع لجدول المقاطع.

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

ملاحظة على وقت الجلسة

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

// ── الورشة العملية · ٦٠ دقيقة

ثلاث ملفات معطوبة — والمنهج اللي اتعلمناه

مش هنبني حاجة جديدة النهارده. هنطبّق المهارة ٥ و٦ على كود موجود — ودي أقرب حاجة للشغل الحقيقي.

patient_zero.html

٣٠ عطل في الشكل والبنية والوصول والاستجابة.

أعطال تتشاف — بتتكشف بالتشخيص البصري وبالتنقل بالكيبورد.

bug_hunt_02.html

١٤ عطل في الحسابات وترتيب العمليات.

سلة طلب شكلها سليم تماماً — والمحل بيخسر فلوس كل يوم.

bug_hunt_03.html

١٣ عطل في الحالة والوقت والتخزين.

لوحة متابعة بتدّي أرقام غلط بثقة — أخطر نوع باج على الإطلاق.

قواعد الورشة

  1. عشر دقايق تشخيص بالعين قبل أي برومبت. اللي بيدي الملف للوكيل على طول بيتعلم أقل بكتير.
  2. ممنوع «صلّح كل الأخطاء». الصيغة المطلوبة: «العَرَض ده — شخّص السبب واشرحهولي قبل ما تعدّل».
  3. ملف diagnosis.md: كل عطل بصيغة عَرَض ← سبب ← إصلاح ← الدرس المستفاد.
  4. بعد كل إصلاح: إعادة اختبار. الإصلاح اللي مااتختبرش مش إصلاح.
// ── التكليف

طبّق المسار كامل على مشروعك

التكليف مش مشروع جديد — التكليف إنك ترجع لمشروع الأساينمنت ٠٤ بتاعك وتعدّيه على المسار ده.

خمس تسليمات

معايير التقييم

🎁 نقطتان إضافيتان

نفّذ نفس المواصفة مرتين: مرة بملف قواعد المشروع مفعّل، ومرة في مشروع فاضي بدونه — وقارن في عشر سطور: كام مخالفة للنظام ظهرت في كل حالة؟ وكام برومبت تصحيحي احتجت؟

// ── الخلاصة

سبع جمل تلخّص المحاضرة

  1. السياق مورد بتديره — القليل المنقّى أقوى من الكتير المكوّم.
  2. أي كلام بتكرره، مكانه ملف قواعد — مش ذاكرتك ولا أول كل محادثة.
  3. أي قرار مش مكتوب في المواصفة، الوكيل هياخده مكانك — والاكتشاف بيبقى متأخر.
  4. «تم» مش نتيجة — النتيجة تقرير بنداً بنداً بمواقعه في الكود.
  5. متطلبش إصلاح لسبب مفهمتوش — الوكيل هيخفي العَرَض ويسيب السبب.
  6. الأحمر في الـ diff أخطر من الأخضر — اللي اتشال بيعدي في صمت.
  7. فشل مرتين على نفس النقطة = المشكلة في المواصفة — مش في التنفيذ.

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

student@motrjim:~/vibe-coding $ git commit -m "lecture_05: from working to shippable"

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

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

Scroll to Top